Images, editable projects and archives

Image options and limitations

image_resize supports dimensions, percentage or longest edge, re-encoding, quality/target KB and print DPI. It does not enlarge unless allow_upscale is enabled; enlargement is bounded to 4× and 100 megapixels. image_edit applies an ordered list at full resolution: geometry, filters, adjustments, borders, text, shapes and image/text watermarks.

• Pixels and DPI are different. Changing print DPI does not by itself add detail. Set pixel dimensions for screen requirements and the appropriate print density for physical output.
• Contain, cover and exact resizing differ. Contain retains the whole image, cover fills a box by cropping, and exact dimensions can distort proportions. Discover the selected tool’s enum rather than borrowing another tool’s labels.
• Transparency can be flattened. For convert to JPEG/BMP/GIF, choose background (default white); do not promise continuous alpha in those outputs. Use PNG or another suitable alpha-capable target when transparency matters.
• Size targets need verification. Inspect actual output bytes and any warnings. Target compression support differs by tool and format; do not assume HEIC accepts the JPEG/PNG/WebP target-size API.
• Input support exceeds edit/export support. Camera RAW conversion can use the camera’s embedded JPEG, rather than developing the sensor data. PSD conversion is a flattened representation rather than preservation of Photoshop layers.
• Fonts are operation-specific. image_edit text uses bundled Inter with Latin, Greek and Cyrillic coverage; do not assume it covers every script. Inspect text rendering for the language in use.
• Multi-page or animated sources need an explicit decision. Single-image processing can refuse a sequence rather than silently using only the first page/frame. For a multipage TIFF, choose the TIFF-to-TIFF resize/recompress route to retain all pages. High-depth TIFF conversion can refuse formats that would lose precision; use supported TIFF/PNG paths when depth matters.
• HEIC transparency and layers are separate. Supported alpha can survive HEIC decoding for pixel edits. Layered sources can be refused where a pixel edit would silently discard image items; a successful preview alone does not establish a safe round trip.

For layered work that should remain editable, use an imageEditor project and typed project edits rather than a sequence of flattened outputs.

Portable editable projects

A project directory contains project.fhproject and local assets. .fhpkg packages the project for transport. Read filehop://project-guide and the installed schema before creating content.

1. project_create starts a supported project kind; project_migrate imports existing .iep, .vep, .dep or .dwb projects without changing originals.
2. project_inspect returns stable IDs, manifest revision, dependency revision and resolved assets. Request an outline or pointer for large models, and journal: true to resume existing work.
3. Use typed project_image_edit or project_video_edit operations where available. Generic project_update supports atomic edits, dry_run and schema validation. Do not invent native editor JSON.
4. Render, inspect diagnostics and export with the inspected manifest and dependency revisions. An asset can change even when the manifest does not.

project_add_asset copies a local asset into the project and returns its ID. Refer to asset IDs in content. Assets must remain inside the project and permitted folders. Full editors can discard unreferenced assets on their next save, so complete the reference before handing the project back.

Basic image/PDF/video/data project kinds support headless export. Full imageEditor exports PNG/JPEG; full videoEditor exports MP4 with the editor’s supported model. dataEditor export requires its native editor. Creating, inspecting or migrating a project does not imply every kind supports headless export.

Image typed edits include text, shapes, images, grouping, geometry, styles, masks and retouching. Retouch coordinates refer to source photo pixels; warnings can identify 8-bit/sRGB/opaque behavior or missing red-eye. Locked objects refuse changes unless explicitly overridden through a supported option. Inspect the image view for target paths and the renderer’s feature diagnostics.

project_render provides a cached preview without changing the project; project_export creates a unique output. Unsupported export features are refused rather than silently omitted. A preview may report differences; read its diagnostics instead of assuming a preview proves export support.

For green/blue-screen overlays, project_video_edit can set an existing video overlay’s chromaKey using its track and id, with key: {color, similarity, smoothness, spill}. Use a #RRGGBB color, similarity 1–100 and smoothness/spill 0–100. key: null clears the effect. Locked items and non-video overlays are refused. Preview the affected range before export.

Use project_pack/project_unpack to move work and referenced assets together. History and checkpoints are excluded from packages unless include_history is requested. Use journal, history, diff and revert tools to record meaningful milestones and decisions.

Let a person review the working project live

Open the actual project.fhproject in a running FileHop window through desktop_tabs, or organize it in a desktop_sessions task with source/working/output roles. A clean open editor refreshes after saved external updates; unsaved human edits stay intact and produce a conflict. Keep working source editable and show coherent saved steps as the agent proceeds.

Session readiness can distinguish opening, loading and rendering, and record exactly which revision and surface were shown. Each tool operation has an activity record; projects also have a journal and revision history. See live review, sessions and audit trails for the full workflow and the distinction between render evidence and human approval.

Archives

archive_create writes ZIP (optional AES-256), 7z (optional encryption), tar.gz, tar.bz2 or tar.zst, leaving sources intact. Password protection and metadata hiding differ by archive format; consult its schema. Inspect creation warnings and skipped as well as the output path: a new archive can omit entries it cannot safely include. Archive creation and extraction need not handle links symmetrically; extraction skips links rather than following them.

archive_list inspects entries before extraction. archive_extract supports ZIP, 7z, RAR, tar variants, standalone compressed streams and supported disk images. Disk-image operations depend on platform/runtime availability; check the installed capabilities.

Extraction creates a new uniquely named directory and does not merge into an existing one. Paths escaping the destination, links, devices and pipes are skipped and reported. Inspect skipped before describing an extraction as complete. Current extraction bounds are 100,000 entries and a size allowance of 200× the archive size, bounded between 256 MB and 20 GB.

Listing a format does not guarantee every encrypted or damaged variant can be extracted. Treat passwords, unsupported codecs and corrupt input as specific constraints instead of repeatedly trying different filename extensions.