From eef67d9fb780a55d0d83bab377c0490eba6f3b21 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Mon, 16 Nov 2026 11:07:15 +0100 Subject: [PATCH] Document file and clipboard feature support matrices --- docs/canvas-pilot/changelog.md | 4 + docs/canvas-pilot/guide/files.md | 3 + docs/canvas-pilot/guide/format-matrix.md | 134 ++++++++++++++++++++ docs/canvas-pilot/guide/formats-and-crop.md | 3 + docs/canvas-pilot/guide/overview.md | 1 + docs/manuals/canvas-pilot/SUMMARY.md | 1 + 6 files changed, 146 insertions(+) create mode 100644 docs/canvas-pilot/guide/format-matrix.md diff --git a/docs/canvas-pilot/changelog.md b/docs/canvas-pilot/changelog.md index 944309b..97c940e 100644 --- a/docs/canvas-pilot/changelog.md +++ b/docs/canvas-pilot/changelog.md @@ -4,6 +4,10 @@ ## Unreleased +- Added user-guide feature matrices for all eleven exchange formats, project saves + and separate clipboard workflows. Distinguished geometry, names, visual crop/mask + pictures and editable snapshot restoration, checked against the codec behavior. + - Simplified READMEs to navigation and kept user instructions in the book's source chapters. Moved task-list discovery behind Development and indexed contracts, research and handoffs in `AGENT_DOCUMENTATION.md`; removed internal records from diff --git a/docs/canvas-pilot/guide/files.md b/docs/canvas-pilot/guide/files.md index 05b1286..d562b95 100644 --- a/docs/canvas-pilot/guide/files.md +++ b/docs/canvas-pilot/guide/files.md @@ -2,6 +2,9 @@ [Canvas Pilot](../introduction.md) · [Guide contents](overview.md) · [Starter files](../../templates/canvas-pilot/catalog.md) +Choosing an exchange format? See the [file and clipboard feature matrix](format-matrix.md) +for naming, crop, pictures and editable-settings support. + ## Paste layer values and import geometry Drop SVG, draw.io/XML, geometry JSON/CSV, DXF/DWG, HTML, PPTX, FIG, FIGCRAFT or AI files into diff --git a/docs/canvas-pilot/guide/format-matrix.md b/docs/canvas-pilot/guide/format-matrix.md new file mode 100644 index 0000000..47aaa04 --- /dev/null +++ b/docs/canvas-pilot/guide/format-matrix.md @@ -0,0 +1,134 @@ +# Choosing a file or clipboard format + +[Guide contents](overview.md) · [Import and export instructions](files.md) · [Starter files](../../templates/canvas-pilot/catalog.md) + +Use **Save project** to continue editing later. Use **SVG** for straightforward +vector-editor exchange, **draw.io** for diagrams.net, **PPTX** for slides, and +**FIG / FIGCRAFT** for Figma / FigCraft files. Prefer **SVG over AI** for Illustrator +unless you specifically need a native AI file. **DXF / DWG** suit CAD geometry; +**JSON / CSV** suit scripts and tables. HTML provides a browser-viewable layout. + +These tables describe what **Canvas Pilot implements**, not everything each file +format can theoretically contain. ☑ means supported; ☐ means unavailable in this +workflow. Features marked * have conditions explained below. Checkboxes are a +reference, not controls. + +## File exchange matrix + +All eleven exchange formats import and export layer positions and sizes. Geometry +import maps boxes to **existing destination layers**: it keeps their names, source +settings and device links, and does not change the output resolution. File names +and layer labels can help identify the boxes; they do not rename destinations. + +| File | Import | Export | Layer names in export | Background picture | Crop/mask preview pictures | Extra settings snapshot | +| --- | :---: | :---: | :---: | :---: | :---: | :---: | +| Canvas Pilot project (`.midra.json`) | ☑* | ☑* | ☑ | ☑* | ☑* | ☑* | +| SVG (`.svg`) | ☑ | ☑ | ☑ | ☑ | ☑ | ☑ | +| draw.io (`.drawio`, XML) | ☑ | ☑ | ☑ | ☑ | ☑ | ☑ | +| Geometry JSON (`.json`) | ☑ | ☑ | ☑ | ☑ | ☑ | ☑ | +| Geometry CSV (`.csv`) | ☑ | ☑ | ☑ | ☐ | ☐ | ☑ | +| DXF (`.dxf`) | ☑ | ☑ | ☑* | ☐ | ☐ | ☑ | +| DWG (`.dwg`) | ☑* | ☑* | ☑* | ☐ | ☐ | ☐ | +| HTML / CSS (`.html`) | ☑ | ☑ | ☑ | ☑ | ☑ | ☑ | +| PowerPoint (`.pptx`) | ☑* | ☑* | ☑ | ☑ | ☑ | ☑ | +| Figma file (`.fig`) | ☑* | ☑* | ☑ | ☑ | ☑ | ☐ | +| FigCraft file (`.figcraft`) | ☑* | ☑* | ☑ | ☑ | ☑ | ☐ | +| Illustrator file (`.ai`) | ☑* | ☑* | ☑* | ☑ | ☑ | ☐ | + +- **Projects:** use Open/Save project, not geometry import/export. Pictures and + editable settings are saved directly; no optional snapshot is needed. +- **Pictures:** enable **Include background layer** and/or **Include placeholder + pictures** when exporting. Background pictures flatten visible references. + Placeholder pictures show source-grid patterns with crop, fit and masking; + they are not live input images. Reimport reads their boxes, not their pixels + or editable crop. CSV, DXF and DWG can include a background **rectangle** only. +- **Names:** exported as format-specific labels/metadata. CAD uses stable layer + IDs with human names in descriptions; AI goes through an SVG conversion. + Another application's layer panel may display these differently. +- **Native codecs:** DWG, PPTX, FIG, FIGCRAFT and AI require a build with vendor + formats enabled (the default). AI additionally requires the separately installed + [VectorCraft converter](files.md#illustrator-ai-optional-converter-required). +- **Extra settings:** experimental and opt-in. Restore the original snapshot with + **Project → Restore parameters from export…**; ordinary geometry import never + applies it. External applications may strip it or leave it stale after edits. + +Exports use one screen-sized canvas, slide, frame or artboard. PPTX import offers +a slide picker; FIG / FIGCRAFT offer page/frame choices; AI offers artboards. +Draw.io supports single-page files, including compressed files. These are supported +layout profiles, not general-purpose artwork importers: arbitrary HTML, SVG effects, +CAD entities or complex native document features may be rejected or omitted. +See [file import limits](files.md) before choosing a workflow for complex artwork. + +## Clipboard matrix + +Figma file import and Figma copy/paste are different paths. The same distinction +applies to Illustrator and draw.io. “Paste” below means **into Canvas Pilot**; +“Copy out” means a clipboard format Canvas Pilot itself generates. + +| Clipboard path | Paste positions and sizes | Copy out in this format | Rename destination layers | Crop zoom | Crop edges / offsets, fit and masks | +| --- | :---: | :---: | :---: | :---: | :---: | +| Canvas Pilot **Copy layer values**, normal crop | ☑ | ☑ | ☐ | ☑ | ☐ | +| Figma **SVG text** copy/paste | ☑ | ☐ | ☐ | ☐ | ☐ | +| Illustrator **SVG text** copy/paste | ☑ | ☐ | ☐ | ☐ | ☐ | +| draw.io diagram XML copy/paste | ☑ | ☐ | ☐ | ☐ | ☐ | +| SVG file contents pasted as text | ☑ | ☐ | ☐ | ☐ | ☐ | +| Geometry JSON / CSV file contents pasted as text | ☑ | ☐ | ☐ | ☐ | ☐ | +| Canvas Pilot HTML / ASCII DXF file contents pasted as text | ☑ | ☐ | ☐ | ☐ | ☐ | +| PowerPoint native clipboard | ☐ | ☐ | ☐ | ☐ | ☐ | +| QCAD native clipboard | ☐ | ☐ | ☐ | ☐ | ☐ | + +Figma SVG, Illustrator SVG and draw.io XML clipboard paths have been confirmed in +user testing. This does not imply support for every application's native binary +or HTML clipboard payload. Use the corresponding file path if no supported text +is available. PowerPoint and QCAD use file exchange in this workflow. + +Paste opens a mapping review with separate **Position**, **Format** (width/height) +and, when present, **Crop zoom** choices. Names in copied values identify rows; +they do not rename destination layers. Zoom alone does not reproduce the original +crop offsets or source settings. Older Canvas Pilot values may omit zoom. +**Advanced-fit container values are not the normal-crop paste format**; use a +project or supported snapshot to retain those modes. + +SVG and draw.io imports can optionally include supported outline widths in the +bounds. Colors, text styling and artwork are not applied to the destination. +Pasting exported text with extra parameters still imports geometry; use the +separate restore action to recover the embedded settings. + +## Which editing features survive? + +This table separates editable state from a picture of its appearance. “Snapshot” +means one of the seven checked exchange formats above, exported with extra +parameters and reopened through **Restore parameters from export**. + +| Feature | Project Open/Save | Plain geometry file import | Snapshot restore | +| --- | :---: | :---: | :---: | +| Layer position and size | ☑ | ☑ | ☑ | +| Full-precision saved coordinates | ☑ | ☐* | ☑ | +| Output screen resolution | ☑ | ☐ | ☑ | +| Layer names and stacking order | ☑ | ☐ | ☑ | +| Folders, collapsed folders, visibility and locks | ☑ | ☐ | ☑* | +| Source formats, assignments and shared input relationships | ☑ | ☐ | ☑* | +| Input crop edges | ☑ | ☐ | ☑ | +| Normal layer crop zoom and offsets | ☑ | ☐ | ☑ | +| Advanced fit modes and their crop edges | ☑ | ☐ | ☑ | +| Editable blanking masks | ☑ | ☐ | ☑ | +| Resize pivots and group resize settings | ☑ | ☐ | ☑ | +| Saved device screen/layer links | ☑ | ☐ | ☑ | +| Reference images and their individual settings | ☑ | ☐ | ☐ | +| Capture assignments and saved preview stills | ☑ | ☐ | ☐ | +| Selection, camera, guides, snapping and workspace settings | ☑ | ☐ | ☑* | +| Undo history, pending edits and active device operations | ☐ | ☐ | ☐ | +| Application theme, connection history and Program permission | ☐* | ☐ | ☐ | + +- Geometry **exports round boxes to whole pixels**; import can retain fractional + coordinates where the reader supports them. Use a project or snapshot for + full-precision recovery. Geometry import never reorders destination layers. +- Snapshot restoration includes only exported layers and their referenced inputs; + selection and folders are filtered accordingly. It replaces the document with + the saved snapshot, not a merge of the external artwork's latest edits. +- Application preferences are saved separately from projects. Opening a project + or restoring a snapshot does not connect or send to a switcher. +- PNG, JPEG and BMP are **reference-image imports**, not layer-geometry formats. + PDF, PSD, VSDX and ODG are not supported geometry-exchange choices. + +For a complete editable backup, **Save project** remains the recommended choice. diff --git a/docs/canvas-pilot/guide/formats-and-crop.md b/docs/canvas-pilot/guide/formats-and-crop.md index 672a1c6..5201cec 100644 --- a/docs/canvas-pilot/guide/formats-and-crop.md +++ b/docs/canvas-pilot/guide/formats-and-crop.md @@ -2,6 +2,9 @@ [Canvas Pilot](../introduction.md) · [Guide contents](overview.md) · [Starter files](../../templates/canvas-pilot/catalog.md) +Choosing an exchange format? See the [file and clipboard feature matrix](format-matrix.md) +for naming, crop, pictures and editable-settings support. + ## Formats and content framing Open the **Output format** icon (screen with sliders), first in the toolbar, for HD (1280 × 720), Full HD (1920 × 1080), UHD 4K diff --git a/docs/canvas-pilot/guide/overview.md b/docs/canvas-pilot/guide/overview.md index ffb7b16..90d4608 100644 --- a/docs/canvas-pilot/guide/overview.md +++ b/docs/canvas-pilot/guide/overview.md @@ -10,6 +10,7 @@ directly to the detailed controls, workflows and limitations you need. | [Installation and updates](install.md) | Prebuilt downloads, cargo-binstall, source installation and troubleshooting | | [Layers and editing](editing.md) | Select, move, resize, align, name, order and group layers | | [Canvas and reference images](canvas.md) | Workspace defaults, view tools, guides, grid, reference pictures and positioning points | +| [File and clipboard feature matrix](format-matrix.md) | Choose a format by geometry, naming, pictures, crop and saved settings support | | [Formats, crop and precision](formats-and-crop.md) | Input/output sizes, content framing, visual crop controls and numeric precision | | [Import, export and project files](files.md) | Clipboard mapping, geometry files, export scopes, saving and recovery | | [Menus and preferences](preferences.md) | Application menus, themes, saved settings and snapping | diff --git a/docs/manuals/canvas-pilot/SUMMARY.md b/docs/manuals/canvas-pilot/SUMMARY.md index c7c9b57..063aec1 100644 --- a/docs/manuals/canvas-pilot/SUMMARY.md +++ b/docs/manuals/canvas-pilot/SUMMARY.md @@ -13,6 +13,7 @@ - [Guide overview](../../canvas-pilot/guide/overview.md) - [Layers and editing](../../canvas-pilot/guide/editing.md) - [Canvas and reference images](../../canvas-pilot/guide/canvas.md) + - [File and clipboard feature matrix](../../canvas-pilot/guide/format-matrix.md) - [Formats, crop and precision](../../canvas-pilot/guide/formats-and-crop.md) - [Import, export and project files](../../canvas-pilot/guide/files.md) - [Menus and preferences](../../canvas-pilot/guide/preferences.md)