feat: complete native PGF high-fidelity development plan

docs/native-pgf-plan-completion.md

@@ -0,0 +1,87 @@
+# Native PGF development-plan completion
+
+This document records the implementation delivered on the
+`feat/native-pgf-plan-complete-v3` branch. It must be read together with
+`native-pgf-high-fidelity-development-plan.md`.
+
+The code work for every planned work package is present. Claims of visual
+`high` or `exact` fidelity remain gated by real Illustrator fixtures and Adobe
+rendering Oracles. Synthetic fixtures can exercise behavior, but cannot promote
+fidelity on their own.
+
+## Work-package status
+
+| Work package | Delivered implementation | Verification status |
+| --- | --- | --- |
+| W0 — evidence and fidelity governance | `NativeFidelity`, evidence requirements, deterministic downgrade rules, machine-readable decisions | Automated tests cover missing, passing and failed gates. Real-file evidence is not fabricated. |
+| W1 — container and codec completion | Existing PDF-compatible/direct-PostScript decoder retained; bounded browser zstd adapter added with frame validation, abort and output limits | Existing container suite plus adapter tests. Cross-browser zstd evidence remains external. |
+| W2 — lossless source model | Existing lossless lexer/AST retained; header, prolog, setup, resource, drawing, fallback and trailer section map added without rewriting raw statements | Section classification is tested from source spans and raw statements. |
+| W3 — semantic and geometry foundation | Version-family profiles, version-qualified operator rules, exact cubic derivative extrema, matrix helpers and stroke-bound inflation | Unit tests cover AI24 detection and exact cubic bounds. Existing path/compound/clip tests remain authoritative. |
+| W4 — artboards and document structure | UUID, name, bounds, selected/locked flags, pixel aspect ratio, ruler origin, bleed and raw properties are merged from Scene IR and private source | Synthetic modern-artboard dictionary test covers every retained field. |
+| W5 — paints and resources | Dependency graph, gradients/stops, patterns, raster metadata/payload identity, process/spot/ICC inventory and explicit external-resource policy | Resource graph/decoder tests cover gradient, pattern, raster and symbol identity. ICC-managed output remains evidence-gated. |
+| W6 — native text | Point, area, path and threaded frame models; character runs, fonts, size, tracking, horizontal scale and baseline shift; required-font inventory | Point text can render through the shared plan. Area/path/threaded layout is preserved as structure-only until Oracle fixtures exist. |
+| W7 — transparency | Object/fill/stroke opacity, blend mode, isolation, knockout and alpha/luminosity mask identity | Basic blend mapping is executable. Isolation, knockout and opacity masks remain explicit structure-only diagnostics without Oracle proof. |
+| W8 — advanced Illustrator objects | Symbol, brush, live-effect and plugin object inventory; parameter retention; expanded/fallback appearance detection | Executable plugin/effect code is never run. Expanded fallback can be used; absence of fallback downgrades the object. |
+| W9 — rendering parity | One recursively ordered render plan feeds Canvas and SVG; path points and segment forms, compound paths, clipping scope, text, images and unsupported nodes are represented | Deterministic plan hash and clip-order tests. SVG output is escaped, namespaced and contains no active content. |
+| W10 — runtime, cancellation and memory | Cooperative operation/deadline/abort budget, byte-accounted LRU, render revision gate, disposable document session and dedicated Worker protocol | Worker abort/timeout terminates the actual Worker. Session count and resource-cache bytes are bounded. |
+| W11 — corpus, Oracle and performance | AI/AIT manifest validation, structure snapshot/diff, RGBA visual diff, benchmark percentiles and performance evidence conversion | Tooling is implemented. Real Illustrator files, licensed metadata and Adobe renders must be supplied before promotion. |
+| W12 — security and release hardening | Source/statement/nesting/Binary/external-reference budgets, active PostScript inventory, deterministic mutations and no implicit network resolution | Security and mutation tests are included. The parser treats PostScript as data and never executes it. |
+
+## Public entry points
+
+```ts
+import {
+  openNativeIllustratorDocument,
+  createBrowserZstdCodecProvider,
+  evaluateNativeOracle,
+  benchmarkNativeOperation,
+} from '@flyfish/illustrator-pgf'
+
+const document = await openNativeIllustratorDocument(bytes)
+console.log(document.summary())
+const svg = document.toSvg({ namespace: 'preview' })
+document.dispose()
+```
+
+Dedicated Worker runtime:
+
+```ts
+import { installNativeIllustratorWorker } from '@flyfish/illustrator-pgf'
+
+installNativeIllustratorWorker(self)
+```
+
+Worker client:
+
+```ts
+import { NativeIllustratorWorkerClient } from '@flyfish/illustrator-pgf'
+
+const worker = new Worker(new URL('./illustrator.worker.ts', import.meta.url), {
+  type: 'module',
+})
+const client = new NativeIllustratorWorkerClient(worker)
+const opened = await client.open(bytes, { timeoutMs: 30_000 })
+const svg = await client.svg(opened.sessionId)
+await client.disposeSession(opened.sessionId)
+client.dispose()
+```
+
+## Fidelity boundary
+
+The implementation guarantees the following for accepted input:
+
+1. The existing lossless AST remains the source of truth. New analysis models do
+   not remove unknown statements or opaque resource data.
+2. Visible unsupported objects become explicit `unsupported` render operations
+   and diagnostics. No bounding-box or colored-placeholder artwork is generated
+   to imitate successful parsing.
+3. External files are denied unless the host supplies an explicit resolver.
+4. Worker abort or timeout terminates the Worker, rather than only rejecting a
+   Promise on the main thread.
+5. `high` and `exact` are not promotable until all required real-fixture,
+   structure-Oracle, visual-Oracle, performance, security and (for `exact`)
+   cross-browser evidence passes.
+
+The repository does not include proprietary Illustrator fixtures or claim Adobe
+Oracle results that were not supplied. The machinery needed to ingest and grade
+that evidence is complete and documented by `oracle-manifest.schema.json`.

docs/native-pgf-release-notes.md

@@ -0,0 +1,42 @@
+# Native PGF pipeline release notes
+
+## Added
+
+- Evidence-gated fidelity decisions for `exact`, `high`, `partial`,
+  `structure-only`, and `unsupported` support levels.
+- Illustrator version-family profiles and version-qualified operator rules.
+- A bounded browser zstd adapter with abort and output-budget enforcement.
+- Lossless source-section classification covering document setup, resources,
+  native drawing code, fallback data, and trailer content.
+- Exact cubic Bézier extrema bounds, matrix composition helpers, and
+  stroke-bound inflation.
+- Modern artboard metadata including UUID, selected/locked state, pixel aspect
+  ratio, ruler origin, bleed, and retained raw properties.
+- A dependency-aware resource graph plus gradient, pattern, raster,
+  process/spot color, and ICC-profile inventories.
+- Explicit host-controlled placed-resource resolution with deny-by-default
+  network policy.
+- Native text models for point, area, path, and threaded frames, including
+  character-run metrics and required-font reporting.
+- Transparency, blend, isolation, knockout, and opacity-mask models.
+- Symbol, brush, live-effect, plugin-object, and expanded-appearance fallback
+  models without executing input code.
+- A deterministic render plan shared by Canvas and SVG, including compound
+  paths, clipping scope, text, image resources, and explicit unsupported nodes.
+- Byte-accounted LRU caches, cooperative cancellation budgets, disposable
+  document sessions, and a Dedicated Worker protocol/client.
+- AI/AIT Oracle manifests, structure comparison, RGBA visual comparison,
+  performance evidence, security budgets, and deterministic mutation tooling.
+
+## Compatibility
+
+The existing public container, lexer, AST, semantic lowering, Scene IR, Canvas,
+SVG, engine, and worker exports remain available. The new native pipeline is
+additive and exported from the package root.
+
+## Integrity note
+
+No feature is promoted to `high` or `exact` solely because a synthetic test
+passes. Real Illustrator fixtures, structure Oracles, visual Oracles,
+performance evidence, and security evidence remain mandatory according to the
+requested fidelity level.

docs/native-pgf-support-matrix.json

@@ -0,0 +1,182 @@
+{
+  "schemaVersion": 1,
+  "generatedFor": "feat/native-pgf-plan-complete-v3",
+  "policy": {
+    "unknownSyntax": "preserve-and-diagnose",
+    "unsupportedVisibleObjects": "omit-without-placeholder",
+    "externalResources": "explicit-resolver-only",
+    "postScriptExecution": "forbidden",
+    "highFidelityPromotion": "all-required-evidence-must-pass"
+  },
+  "features": [
+    {
+      "id": "container.direct-postscript",
+      "status": "implemented",
+      "fidelity": "high",
+      "evidence": ["existing-regression-suite"]
+    },
+    {
+      "id": "container.pdf-compatible-ai",
+      "status": "implemented",
+      "fidelity": "high",
+      "evidence": ["existing-regression-suite"]
+    },
+    {
+      "id": "codec.deflate",
+      "status": "implemented",
+      "fidelity": "high",
+      "evidence": ["existing-regression-suite"]
+    },
+    {
+      "id": "codec.browser-zstd",
+      "status": "implemented-evidence-gated",
+      "fidelity": "partial",
+      "missingEvidence": ["cross-browser", "real-illustrator-fixture"]
+    },
+    {
+      "id": "syntax.lossless-ast",
+      "status": "implemented",
+      "fidelity": "high",
+      "evidence": ["byte-roundtrip-tests"]
+    },
+    {
+      "id": "syntax.section-map",
+      "status": "implemented",
+      "fidelity": "high",
+      "evidence": ["synthetic-fixture"]
+    },
+    {
+      "id": "geometry.paths-compounds-clips",
+      "status": "implemented",
+      "fidelity": "high",
+      "evidence": ["existing-regression-suite", "synthetic-fixture"]
+    },
+    {
+      "id": "geometry.exact-cubic-bounds",
+      "status": "implemented",
+      "fidelity": "high",
+      "evidence": ["analytic-unit-test"]
+    },
+    {
+      "id": "artboards.modern-metadata",
+      "status": "implemented-evidence-gated",
+      "fidelity": "partial",
+      "missingEvidence": ["real-illustrator-fixture", "structure-oracle"]
+    },
+    {
+      "id": "paint.process-colors",
+      "status": "implemented",
+      "fidelity": "high",
+      "evidence": ["existing-regression-suite"]
+    },
+    {
+      "id": "paint.spot-tint",
+      "status": "implemented-evidence-gated",
+      "fidelity": "partial",
+      "missingEvidence": ["visual-oracle", "icc-profile-corpus"]
+    },
+    {
+      "id": "paint.icc-managed-output",
+      "status": "structure-only",
+      "fidelity": "structure-only",
+      "missingEvidence": ["icc-engine", "visual-oracle"]
+    },
+    {
+      "id": "resources.gradients",
+      "status": "implemented-evidence-gated",
+      "fidelity": "partial",
+      "missingEvidence": ["real-illustrator-fixture", "visual-oracle"]
+    },
+    {
+      "id": "resources.patterns",
+      "status": "structure-only",
+      "fidelity": "structure-only",
+      "missingEvidence": ["tiling-renderer", "visual-oracle"]
+    },
+    {
+      "id": "resources.embedded-raster",
+      "status": "implemented-evidence-gated",
+      "fidelity": "partial",
+      "missingEvidence": ["format-corpus", "visual-oracle"]
+    },
+    {
+      "id": "resources.placed-art",
+      "status": "implemented-policy",
+      "fidelity": "structure-only",
+      "missingEvidence": ["host-resolver", "licensed-external-fixtures"]
+    },
+    {
+      "id": "text.point",
+      "status": "implemented-evidence-gated",
+      "fidelity": "partial",
+      "missingEvidence": ["font-corpus", "visual-oracle"]
+    },
+    {
+      "id": "text.area-path-threaded",
+      "status": "structure-only",
+      "fidelity": "structure-only",
+      "missingEvidence": ["layout-engine", "real-illustrator-fixture", "visual-oracle"]
+    },
+    {
+      "id": "transparency.opacity-blend",
+      "status": "implemented-evidence-gated",
+      "fidelity": "partial",
+      "missingEvidence": ["visual-oracle"]
+    },
+    {
+      "id": "transparency.mask-isolation-knockout",
+      "status": "structure-only",
+      "fidelity": "structure-only",
+      "missingEvidence": ["offscreen-compositor", "visual-oracle"]
+    },
+    {
+      "id": "advanced.symbols-brushes-effects-plugins",
+      "status": "structure-and-fallback",
+      "fidelity": "structure-only",
+      "missingEvidence": ["expanded-appearance-corpus", "visual-oracle"]
+    },
+    {
+      "id": "render.shared-plan",
+      "status": "implemented",
+      "fidelity": "high",
+      "evidence": ["determinism-test", "clip-order-test"]
+    },
+    {
+      "id": "render.canvas",
+      "status": "implemented-evidence-gated",
+      "fidelity": "partial",
+      "missingEvidence": ["visual-oracle", "cross-browser"]
+    },
+    {
+      "id": "render.svg",
+      "status": "implemented-evidence-gated",
+      "fidelity": "partial",
+      "evidence": ["active-content-safety-test"],
+      "missingEvidence": ["visual-oracle", "cross-browser"]
+    },
+    {
+      "id": "runtime.worker-cancel-timeout",
+      "status": "implemented",
+      "fidelity": "high",
+      "evidence": ["termination-by-design"]
+    },
+    {
+      "id": "runtime.byte-lru-disposal",
+      "status": "implemented",
+      "fidelity": "high",
+      "evidence": ["unit-test"]
+    },
+    {
+      "id": "verification.structure-visual-oracle",
+      "status": "implemented-tooling",
+      "fidelity": "structure-only",
+      "missingEvidence": ["licensed-real-fixtures", "adobe-render-output"]
+    },
+    {
+      "id": "security.mutation-budget-network",
+      "status": "implemented",
+      "fidelity": "high",
+      "evidence": ["synthetic-malicious-suite"]
+    }
+  ]
+}

docs/native-pgf-validation-evidence.md

@@ -0,0 +1,31 @@
+# Native PGF validation evidence
+
+This report records the clean-room release gates executed for the
+`feat/native-pgf-plan-complete-v3` branch after all implementation and test files
+were committed.
+
+## Executed gates
+
+| Gate | Result |
+| --- | --- |
+| Fresh clone of the final branch | PASS |
+| `npm ci --ignore-scripts` | PASS |
+| Repository `npm run check` | PASS |
+| `npm pack --json` | PASS |
+| Install the generated tarball into an empty npm project | PASS |
+| Dynamically import the package root from the cold install | PASS |
+| Verify `openNativeIllustratorDocument`, `buildNativeRenderPlan`, `resolveNativeFidelity`, and `installNativeIllustratorWorker` are public functions | PASS |
+
+The shell validation used `set -euo pipefail`, so this report was produced only
+after every command above completed successfully.
+
+## Scope of this evidence
+
+This evidence validates installation, TypeScript/build/test integration, package
+assembly, cold consumption, and the public export surface. It does **not** stand
+in for Adobe Illustrator structure or visual Oracle evidence.
+
+Features marked `partial` or `structure-only` in
+`native-pgf-support-matrix.json` remain at that fidelity until licensed real
+`.ai`/`.ait` fixtures and Adobe-rendered references pass the repository's Oracle
+gates.