Part of #868: docs for Save As .ai legacy version 7 (artboard picker, Transparent Images)

2026-10-24 09:46:59 -06:00 · 2026-10-16 01:36:24 +07:00
parent 91ed4853a8
commit 32df15a554
6 changed files with 34 additions and 11 deletions
@@ -211,7 +211,7 @@ and what's next; [`docs/target-app-parity.md`](docs/target-app-parity.md) the fu
 all of Illustrator): everyday
 vector illustration is close to usable: drawing and path tools,
 Pathfinder and Shape Builder, paint, gradients, appearance and transparency, type with styles, threading and Hebrew/Arabic bidirectional layout, and
-files (SVG, PDF and PDF-compatible `.ai` with PDF/X, EPS, DXF, EMF/WMF, raster formats, PSD out and PSD/PSB in as their merged image, Print, Package).
+files (SVG, PDF and PDF-compatible `.ai` with PDF/X, legacy version 7 `.ai` keeping layers and groups, EPS, DXF, EMF/WMF, raster formats, PSD out and PSD/PSB in as their merged image, Print, Package).
 Affinity documents (`.af` from Affinity 3, `.afdesign`, `.afpub` and, by their content, `.afphoto` from Affinity 1 and 2) open
 and place natively: layers, groups, artboards and pages, curves and shapes, fills, gradients and strokes, clipping
 and masks, text and images, with what didn't come in (effects, adjustments, brushes, master pages…) listed in the
@@ -621,7 +621,10 @@ Native save options: File → Save As to a native or `.ai` file opens the `saveO
 (heading "VectorCraft Options" or "PDF-compatible .ai Options"). Fields: `separateArtboards`, `all` (true: every
 artboard; false: `range`, such as "1-3, 5"), `includeLinked`, `embedProfiles`, `pdfCompatible`, `compress`, and for
 native files `version` and `preview`. A bad range keeps the dialog open; `ui.dialog.confirm` writes the file and the
-artboards' files.
+artboards' files. A `.ai` file's `aiVersion` comes first: `"pdf"` (the default) or `"7"` (legacy, heading "Legacy .ai
+Options"), which takes only `transparentImages` (`"flatten"` or `"omit"`) and, with several artboards, the artboard
+picker: `boards`, one bool per artboard (default: those last saved, else all), saved as `range`, one file per checked
+artboard. OK is disabled with none checked.

 EMF and WMF: Export As… lists both formats (`file.exportAs {format: "emf"}` or `"wmf"`); they have no options
 dialog, so `ui.dialog.confirm` asks for the path and writes the file (one per artboard with Use Artboards). Open and
@@ -18,7 +18,7 @@ from the public specifications, and users' own `.ai` files are used locally only
 | | Illustrator | VectorCraft | Notes |
 |---|---:|---:|---|
 | Formats opened or placed | ~30 | 22 | missing: FreeHand, CorelDRAW, DWG, HEIC/HEIF, JPEG 2000, PICT, PCX, Pixar, RTF/Word, PS |
-| Formats saved (Save As) | 6 (AI, AIT, PDF, EPS, SVG, SVGZ) | 6 + native | `.ai` written as PDF-compatible only (no Illustrator editing data) |
+| Formats saved (Save As) | 6 (AI, AIT, PDF, EPS, SVG, SVGZ) | 6 + native | `.ai` written PDF-compatible (no Illustrator editing data) or as legacy version 7 (layers and groups, one artboard per file) |
 | Formats exported | ~16 | 17 | missing: DWG, 3D (OBJ/USDA/glTF); extra: GIF/PNG-8 palette export, DXF up to 2018, layered PSD |
 | **Overall (weighted by use)** | | **~75%** | `.ai` and PDF dominate the weighting |

@@ -40,12 +40,24 @@ private editing data. VectorCraft:
  A PDF saved with its editing data (`AIPDFPrivateData`) opens the same way.
 - **Writes** a PDF-compatible `.ai` (Save As › `ai`): Illustrator opens it as plain art. It never writes
  Illustrator's private editing data, which is undocumented.
+- **Writes** a legacy `.ai` of version 7 (Save As › `ai` › Version: Legacy (version 7), `aiVersion: "7"`): the
+  PostScript form, from the published *Adobe Illustrator File Format Specification* version 7.0
+  ([PRONOM fmt/423](https://www.nationalarchives.gov.uk/PRONOM/fmt/423)), which apps reading `.ai` open with its
+  structure (#868). It keeps layers (names, order, visibility, lock), groups, compound paths, clipping groups,
+  solid colours, linear and radial gradients and RGB images. The format has one artboard: each artboard chosen in
+  the options dialog's artboard picker (thumbnails to check, default all) is a file of its own,
+  `{name}-{artboard}.ai` when there are several. It has no transparency: objects are written opaque, and images
+  with see-through pixels, opacity or a blending mode are flattened (an opaque image of themselves and the art
+  under them, clipped to where they show; that art stays) or omitted (Transparent Images,
+  `transparentImages: "flatten"|"omit"`). Type is written as outlines, sublayers as groups; appearances, effects
+  and brushes are expanded; object names are left out.
 - **Known failures in users' files:** layer structure flattened or multiplied (#951: 109 layers instead of
  14; #868: round trip with Illustrator 2018 loses layers and groups), guides and non-printing construction
  lines lost (#779), some files 4× slower to open since the editing data is read whole (#758), live effects,
  brushes and symbols come in as their drawn look (#637; pattern fills are read since #1025); legacy `.ai`
  without the prolog opens since #1027, its legacy type (`To` … `TO`) not read yet.
- Estimate: **~65%** for real exchange with Illustrator users (open: ~75%; save: PDF-compatible only).
+- Estimate: **~65%** for real exchange with Illustrator users (open: ~75%; save: PDF-compatible, or legacy
+  version 7 with layers and groups; not yet tested by users who hand files back).
  Closing the open-side issues: 10–20 h with users' files.

 ### Illustrator's private editing data
@@ -57,7 +69,7 @@ the app's own editing copy of a file (an EPS after its `%%EOF`, a `.ai`'s `AIPri
 | Format | Illustrator | Ours: open/place | Ours: save/export | Fidelity and tests |
 |---|---|---|---|---|
 | VectorCraft `.vectorcraft` / `.vctemplate` | — | yes | yes | lossless JSON, versioned, save down to v1; property-tested round trips (`format/tests/prop_format.rs`); documents with a lot of path data are written as compact JSON, about a fifth of the size (#1492); a save falls back to a plain fsync and to writing elsewhere and copying in when the folder refuses the usual steps (#1625, #1649, part of #1620; not confirmed on a real network share); the size limits on embedded data also apply to files read from memory (#1783), and saving over a private file on Unix leaves no readable temporary copy beside it (#1778) |
-| Illustrator `.ai` | open, save | yes (PDF-compatible + editing-data structure) | PDF-compatible only | see above; no real-file corpus |
+| Illustrator `.ai` | open, save | yes (PDF-compatible + editing-data structure) | PDF-compatible, or legacy version 7 (layers and groups) | see above; no real-file corpus |
 | Illustrator template `.ait` | open, save | yes | no (save as `.vctemplate`) | |
 | PDF | open, place, save | yes (layers, masks, editable text, security, overprint; Crop To › Trim takes the bleed box as the document's bleed) | yes (presets, PDF/X-1a/3/4, layers, marks and bleed, ICC, fast web view, 1.3+) | fuzzed import; shared guarded writer and windowed reader ([pdf-backend.md](pdf-backend.md)), metadata, incomplete-content and dependency-source regressions; PDF text placement issues in some files (#722); alpha soft masks drawn as images import with the mask (#1551); a clip only counts as covering the page when its shape does (#1542); a PDF another app copied pastes as editable vector art (#1499); letter-spaced type on a path keeps its length and its glyph-by-glyph stroke comes in as one text object (#1586, #1585); a crafted name tree with shared nodes no longer takes exponential time on open (#1781) |
 | EPS | open, place, save | yes (own PostScript L3 interpreter, Illustrator EPS editing data structure) | yes (L2/L3, TIFF previews) | CID-keyed CJK type and CCITTFax images not read; #505; Type 42 (TrueType) fonts set type at its size (#1553); a clip only counts as covering the page when its shape does (#1542); an EPS another app copied pastes as editable vector art (`clipboard.importEps`, #1499); a stitched shading keeps its hard colour changes on import (#1654); ruzstd 0.9.1 for compressed editing data (#1807, RUSTSEC-2026-0344) |
@@ -81,8 +81,12 @@ from G14 and the budget run of G15: **~170–270 h** one agent, ~50–80 h wall
  of 14), guides and non-printing construction
  lines (#779), open speed on large files (#758), legacy type in `.ai` files in PostScript form (those without
  their prolog open since #1027), live effects, brushes and symbols as live objects (#637; pattern fills and global colours are read since #1025, placed (linked) files since #1264). Writing Illustrator's own editing data is out of scope
-  (undocumented); Save As `.ai` stays PDF-compatible, and Illustrator 2018 opens such a file without its layers and
-  groups (#868).
+  (undocumented): a PDF-compatible `.ai` opens in Illustrator 2018 without its layers and groups (#868). Save As
+  `.ai` › Version: Legacy (version 7) writes the PostScript form from the published version 7 specification
+  instead, keeping layers (names, order, visibility, lock), groups, compound paths, clipping groups, gradients and
+  images, one artboard per file (an artboard picker chooses which); transparency, type, live effects and object
+  names don't survive it (transparent images are flattened or omitted). It waits for testing by users who hand
+  files back.
 - **Evidence:** the issues above; 28 of the 350 issues are about `.ai`/EPS (about 22 people, the most common single
  format theme), 20 fixed, and the 8 open ones are about structure (layers, guides, speed, live objects), not missing
  art. No real-file `.ai` corpus (users' files may be used locally, never committed).
@@ -594,7 +594,10 @@ imported instead and the first warning says why. Choosing a standard turns it of
 path (`document.save {path: "art.ai"}` or `{format: "ai"}`) writes a PDF-compatible file that always carries the
 document, takes the PDF options and keeps its path when reopened, so Save writes `.ai` again; a `.ait` opens untitled.
 `document.export` / `serialize` to `.ai` (and the CLI's `run --export x.ai` and `convert in.svg out.ai`) write the same file
-without giving the document a path.
+without giving the document a path. `options: {aiVersion: "7"}` writes legacy `.ai` files of version 7 instead (the
+PostScript form, which keeps layers, groups, compound paths and clipping groups in apps that read it), one per artboard
+of `range` (default all; `{name}-{artboard}.ai` when several, listed in the result's `files`), with
+`transparentImages: "flatten"` (default) or `"omit"` for images with see-through pixels, opacity or a blending mode.

 Drive a tool like a mouse:

@@ -157,8 +157,9 @@ The discounts, with the evidence:
  about `.ai`/EPS, the most common single format theme. 20 of the 28 are fixed (often the same day). The 8 open
  ones are about structure, not missing art: layers flattened or multiplied (#951: 109 layers instead of 14;
  #868), guides lost (#779), slower opening (#758), live effects, brushes and symbols as their drawn look
-  (#637). VectorCraft can't write Illustrator's editing data (undocumented), so its `.ai` opens in Illustrator
-  as plain art. That blocks beta (the main-format rule) for people who hand files back to Illustrator users,
+  (#637). VectorCraft can't write Illustrator's editing data (undocumented), so its PDF-compatible `.ai` opens
+  in Illustrator as plain art; the legacy `.ai` of version 7 it also writes keeps layers and groups (one artboard
+  per file, no transparency or live type) but hasn't been tested by users yet (#868). That blocks beta (the main-format rule) for people who hand files back to Illustrator users,
  but it doesn't stop someone opening and reworking their own archive.
 - **Interaction fidelity (×0.9).** Pen, Direct Selection, smart guides and snapping are deep
  ([ui-parity.md](ui-parity.md)), and there has never been a side-by-side session. The issue tracker says the
@@ -365,7 +366,7 @@ since 2026-10-01.
 | **Large missing subsystems** | 0–20% | 3D & Materials (~25%, initial 3D types without materials), Photoshop-style raster effects and the Effect Gallery (~19 of ~56 filters), SVG Filters, CJK composition (vertical type with kinsoku, tate-chu-yoko and the font's vertical metrics; ruby, mojikumi and proportional vertical metrics open), scripting |
 | **Interaction fidelity:** modifiers, cursors, small behaviours | ~30–40% | The dedicated pass hasn't started, and there has been no side-by-side session with Illustrator yet. A power user notices this first |
 | **Look & feel** | ~75–80% | Measured against Illustrator 2026 screenshots (2026-10-02); the panels added since haven't been re-measured |
-| **File interop** | ~85% | SVG/SVGZ, PDF and PDF-compatible `.ai`, EPS, DXF, EMF/WMF, raster formats, PSD export and PSD/PSB placement (merged image), Place and Links, Package, Print, clipboard flavours. Affinity documents (Affinity 1–3) open natively as editable art, checked against 51 pinned public files (33 current `.af`), with selected saved-thumbnail comparisons and every-board native/SVG/PDF/PSD checks for current files; Affinity export is missing and effects, adjustments and brushes don't import. Affinity isn't an Illustrator feature, so this doesn't raise the parity score. The editing copy inside an Illustrator EPS or `.ai` is read for its structure: layers, groups, names, hidden objects and type, colours, gradients, transparency, images and every artboard (see Out of scope for what it doesn't read yet); DWG has no open spec |
+| **File interop** | ~85% | SVG/SVGZ, PDF and PDF-compatible `.ai` (and legacy version 7 `.ai` out, keeping layers and groups), EPS, DXF, EMF/WMF, raster formats, PSD export and PSD/PSB placement (merged image), Place and Links, Package, Print, clipboard flavours. Affinity documents (Affinity 1–3) open natively as editable art, checked against 51 pinned public files (33 current `.af`), with selected saved-thumbnail comparisons and every-board native/SVG/PDF/PSD checks for current files; Affinity export is missing and effects, adjustments and brushes don't import. Affinity isn't an Illustrator feature, so this doesn't raise the parity score. The editing copy inside an Illustrator EPS or `.ai` is read for its structure: layers, groups, names, hidden objects and type, colours, gradients, transparency, images and every artboard (see Out of scope for what it doesn't read yet); DWG has no open spec |
 | **Bundled content:** brush, symbol, style and swatch libraries | ~30% | Ours are original and generated in code, and far fewer than Illustrator ships; brush and symbol libraries are still missing |
 | **Performance** | unverified | Multithreaded, off-thread rendering and caches are in place. The last budget run (2026-10-01, loaded machine) measured 290 ms for a 50k-path fit against a 16 ms budget. Re-run `vectorcraft-cli perf` on an idle machine |
 | **Robustness** | good, new | ~2,840 tests, property tests, no panics in shipped code (lints, the `guard` safety net, import fuzzing), Data Recovery. Missing: a corpus of real-world files, Windows/Linux/browser QA |