partforge 0.92.0 → 0.94.0

package/src/framework/jobs.js

@@ -9,6 +9,7 @@ import { fontsFor, resolveFonts } from "./fonts.js";
 import { normalizeOpentype, parseFont } from "./geometry/opentype-interop.js";
 import { ensureImports, resolveImports } from "./imports.js";
 import { safeName } from "./safe-name.js";
+import { ensureVectors } from "./vectors.js";
 import { exportSubParts, resolveParams, buildPosed } from "./part-model.js";
 
 // The oracle loads LAZILY, per job family, never at worker boot. It is the largest
@@ -226,6 +227,16 @@ export async function handle(kernel, part, msg, post, opts = {}) {
     // lazy-error policy that keeps a STEP import inert until a build actually
     // calls k.import on it.
     if (part.imports) await ensureImports(kernel, part.imports, opts.importMeshes ?? null);
+    // Vector art, the third asset family after fonts and imports. Same pre-build
+    // timing; ensureVectors owns the prune, so this stays one line. Call it
+    // unconditionally, even when this part has no `vectors` at all: ensureVectors
+    // treats a nullish declaration as `{}` and its prune loop is what drops
+    // names a *previous* part (on a rebound worker) registered — the same
+    // stale-registration bug the unconditional fonts prune above exists to
+    // prevent. Guarding this on `part.vectors` would skip exactly the case where
+    // pruning matters most: a worker rebound from a part WITH artwork to one
+    // WITHOUT would leave the old names resolvable forever.
+    await ensureVectors(kernel, part.vectors);
     // Local shorthand over the shared helper: kernel/part/view/p/d are fixed per job.
     const posed = (name, purpose, prog) => buildPosed(kernel, part, name, { purpose, view: msg.view, p, d, onProgress: prog });
     // Explicit selection (headless exportParts) overrides view-derived selection.

package/src/framework/lint/index.js

@@ -18,8 +18,9 @@ import { PLACE_RULES } from "./rules-place.js";
 import { IMPORT_RULES } from "./rules-imports.js";
 import { FONT_RULES } from "./rules-fonts.js";
 import { SOURCE_RULES } from "./rules-source.js";
+import { VECTOR_RULES } from "./rules-vector.js";
 
-export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES, ...ANIMATION_RULES, ...PLACE_RULES, ...IMPORT_RULES, ...FONT_RULES, ...SOURCE_RULES];
+export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES, ...ANIMATION_RULES, ...PLACE_RULES, ...IMPORT_RULES, ...FONT_RULES, ...SOURCE_RULES, ...VECTOR_RULES];
 
 // A usable sources input, or null. Deliberately forgiving: lintPart's callers
 // include hosted paths handing over user/LLM-authored trees, so a malformed
@@ -44,6 +45,24 @@ function normalizeSources(sources) {
   return { files, entrypoint };
 }
 
+// The caller's parsed vector files, or null. Deliberately forgiving for the same
+// reason normalizeSources is: hosted callers hand over user- and agent-authored
+// trees, and a malformed input must mean "no document-dependent findings",
+// never a throw. Lint itself never reads a file — it is pure and synchronous by
+// contract (see this file's header); the caller does the I/O and passes the
+// result in.
+function normalizeVectorDocs(docs) {
+  if (!docs || typeof docs !== "object") return null;
+  const out = Object.create(null);
+  let any = false;
+  for (const [name, doc] of Object.entries(docs)) {
+    if (!doc || typeof doc !== "object") continue;
+    out[name] = doc;
+    any = true;
+  }
+  return any ? out : null;
+}
+
 // Every rule runs inside a guard. lintPart is called on a user-facing hosted path
 // (partforge-cloud's sandbox), and a linter that takes down the preview it exists to
 // protect is worse than no linter — so a throwing rule becomes a WARNING, never an
@@ -98,9 +117,12 @@ export function lintContext(part, params) {
 /**
  * Lint a PartDefinition. Never throws.
  * @param {object} part   the default-exported PartDefinition
- * @param {{params?: object, sources?: {files?: Record<string, string>, entrypoint?: string}}} [opts]
+ * @param {{params?: object, sources?: {files?: Record<string, string>, entrypoint?: string}, vectorDocs?: Record<string, object>}} [opts]
  *   `params` are layered over part.defaults for the probe pass; `sources` is the part's own
  *   source text, which unlocks the source rules (Group 9) — omit it and lint behaves as before.
+ *   `vectorDocs` is `{ name: parsedDocument }`, the raw parsed JSON of the part's declared
+ *   vector files (see vectors.js's resolveVectorDocs) — omit it and the document-dependent
+ *   vector rules (vector-size-missing, vector-unknown-shape) stay silent rather than guess.
  * @returns {{ok: boolean, errors: object[], warnings: object[], notes: object[]}}
  */
 export function lintPart(part, opts) {
@@ -108,7 +130,7 @@ export function lintPart(part, opts) {
   // parameter only fires on `undefined` — a caller passing `lintPart(part, null)`
   // (a plausible downstream-harness call) would otherwise throw destructuring
   // `{ params }` out of `null` before this function's body ever runs.
-  const { params, sources } = opts ?? {};
+  const { params, sources, vectorDocs } = opts ?? {};
   // lintContext already guards its own internals (see its comment above), but it
   // is user-authored data all the way down — wrap the call itself too, so a
   // failure mode neither of us has thought of still degrades to a report instead
@@ -136,6 +158,9 @@ export function lintPart(part, opts) {
   // host filtering source findings out to keep them non-blocking would instead
   // refuse to render a part that builds fine.
   try { ctx.sources = normalizeSources(sources); } catch { ctx.sources = null; }
+  // Same deliberate own-guard as sources above: a malformed vectorDocs input
+  // means "the document-dependent vector rules stay quiet", never a broken part.
+  try { ctx.vectorDocs = normalizeVectorDocs(vectorDocs); } catch { ctx.vectorDocs = null; }
   const findings = runRules(RULES, ctx);
   // `p` (params merged from `defaults`) failed to build — every rule still ran
   // against the `{}` fallback (each guarded individually by runRules), but the

package/src/framework/lint/rules-vector.js

@@ -0,0 +1,112 @@
+// Group 10 — vector-art call well-formedness. All three conditions throw at
+// build time anyway; these rules move them ahead of the kernel boot, which is
+// where an authoring agent wants them.
+//
+// All read `probe().calls`, whose `args` are JSON.stringify of the RESOLVED
+// argument values under the part's default params (probe.js's `describe`), not
+// source text. So these judge what the part actually builds by default — the
+// same basis rules-imports.js's import-unknown-name already uses. A call that
+// only goes wrong for non-default params is not caught here and still fails
+// correctly at build time; this catches the common case early, it does not
+// replace that authority.
+//
+// vector-size-missing and vector-unknown-shape additionally need `ctx.vectorDocs`
+// — the caller's parsed vector files (see lint/index.js's normalizeVectorDocs,
+// vectors.js's resolveVectorDocs). Lint itself never reads a file (this
+// package's header), so without a supplied document neither rule can tell
+// units from shapes and both stay silent rather than guess.
+import { err } from "./finding.js";
+
+const declaredVectors = (part) => Object.keys(part?.vectors ?? {});
+
+// The name arrives JSON-serialized, so JSON.parse recovers it — and yields null
+// for anything that is not a string (import-unknown-name reads its name the same way).
+const literalName = (src) => {
+  try { const v = JSON.parse(src); return typeof v === "string" ? v : null; } catch { return null; }
+};
+
+// Probe args are JSON-serialized resolved VALUES (probe.js's `describe`), not
+// source text — so an options object arrives as `{"width":10,"shape":"body"}`.
+// Parsing it back is exact for the literal cases these rules judge; anything
+// that does not parse to a plain object means "cannot tell", and the rule stays
+// quiet rather than guessing. A missing argument (`src == null`) is not
+// malformed — it means "no options object" — so it reads as `{}`, not "unknown".
+const optsOf = (src) => {
+  if (src == null) return {};
+  try { const v = JSON.parse(src); return v && typeof v === "object" && !Array.isArray(v) ? v : null; } catch { return null; }
+};
+
+const vectorCalls = (probe) => probe().calls.filter((c) => c.scope === "kernel" && c.op === "vector2d");
+
+export const VECTOR_RULES = [
+  {
+    id: "vector-unknown-name",
+    run: ({ part, probe }) => {
+      const known = new Set(declaredVectors(part));
+      const seen = new Set();
+      const out = [];
+      for (const call of vectorCalls(probe)) {
+        const name = literalName(call.args[0]);
+        if (name == null || known.has(name) || seen.has(name)) continue;
+        seen.add(name);
+        out.push(err("vector-unknown-name",
+          `build calls k.vector2d with name "${name}", which the part's vectors field does not declare: ${[...known].join(", ") || "(nothing)"}`,
+          "Declare the ingested artwork under vectors: { name: source }, or fix the name to match an existing entry.",
+          "vectors"));
+      }
+      return out;
+    },
+  },
+  {
+    id: "vector-size-missing",
+    run: ({ probe, vectorDocs }) => {
+      if (!vectorDocs) return [];                       // caller supplied nothing — cannot judge units
+      const out = [];
+      for (const call of vectorCalls(probe)) {
+        const name = literalName(call.args[0]);
+        if (name == null) continue;
+        const doc = Object.hasOwn(vectorDocs, name) ? vectorDocs[name] : null;
+        if (doc?.units !== "artwork") continue;         // mm files place as authored; a size is optional
+        const opts = optsOf(call.args[1]);
+        if (opts == null) continue;
+        if (opts.width != null || opts.height != null || opts.fit != null) continue;
+        out.push(err("vector-size-missing",
+          `k.vector2d("${name}", …) declares no size, and "${name}" has units "artwork" — one of { width }, { height }, or { fit } is required, in millimetres`,
+          "Artwork units have no physical meaning, so there is no safe default to fall back on (unlike k.text2d's cap-height `size`). "
+          + `Add one, e.g. k.vector2d("${name}", { width: 20 }) — or re-author the file with "units": "mm" if its coordinates really are millimetres.`,
+          "build"));
+      }
+      return out;
+    },
+  },
+  {
+    id: "vector-unknown-shape",
+    run: ({ probe, vectorDocs }) => {
+      if (!vectorDocs) return [];
+      // Keyed by JSON.stringify([name, shape]) — a JSON array literal cannot be
+      // produced by any other (name, shape) pairing, so two distinct pairings can
+      // never collide even though both halves are arbitrary author-chosen strings.
+      // Same pairing repeated across calls reports once; a DIFFERENT bad shape
+      // name on the same vector still reports separately.
+      const seen = new Set();
+      const out = [];
+      for (const call of vectorCalls(probe)) {
+        const name = literalName(call.args[0]);
+        const opts = optsOf(call.args[1]);
+        if (name == null || opts == null || typeof opts.shape !== "string") continue;
+        const key = JSON.stringify([name, opts.shape]);
+        if (seen.has(key)) continue;
+        const doc = Object.hasOwn(vectorDocs, name) ? vectorDocs[name] : null;
+        const shapes = doc?.shapes;
+        if (!shapes || typeof shapes !== "object" || Array.isArray(shapes)) continue;
+        if (Object.hasOwn(shapes, opts.shape)) continue;
+        seen.add(key);
+        out.push(err("vector-unknown-shape",
+          `k.vector2d("${name}", { shape: "${opts.shape}" }) names a shape "${opts.shape}" that "${name}" does not contain: ${Object.keys(shapes).join(", ") || "(none)"}`,
+          "Fix the shape name to match one the file declares, or omit `shape` to use the role-composed result — every \"add\" shape unioned, minus every \"subtract\" shape.",
+          "build"));
+      }
+      return out;
+    },
+  },
+];

package/src/framework/vectors.js

@@ -0,0 +1,205 @@
+// Resolve a part's declared `vectors` ({ name: source }) to internal regions before
+// the synchronous build — the vector-art sibling of fonts.js and imports.js:
+// same source grammar and identity-memoization rule, built on the shared core in
+// asset-resolve.js. The source resolves to JSON in the partforge-vector format,
+// not to SVG; conversion happened once, in a browser, at ingest.
+//
+// No content digest, deliberately. It looks like a missing piece next to
+// imports.js and is not: k.vector2d lowers to k.shape2d(regions) and the Shape2D
+// hash keys on the actual coordinates, so different artwork gives a different
+// cache entry automatically. Imports need a digest because a Solid master is
+// registered by NAME and is opaque to that hash; parsed regions are not. Same
+// argument kernel-front.js:117-121 records for text2d.
+//
+// DOM-free and node:-free.
+import { makeAssetResolver, resolveDecl, unwrapModule } from "./asset-resolve.js";
+import { toInternalDocument } from "./geometry/vector-format.js";
+
+const cache = new Map();   // source → Promise<Uint8Array> (raw bytes)
+// source → { units, shapes }. The bytes memo above stops a refetch; this stops a re-PARSE
+// (UTF-8 decode + JSON.parse + validation + a bbox recomputation that tessellates
+// every contour). Without it every regen of a part with artwork redoes all of that.
+// Fonts solve the same problem with kernel._fontsBySource (jobs.js:206-212) and
+// imports with a digest comparison; this is the third pipeline's version of it.
+// Keyed on the SOURCE, not the name: one worker outlives many parts, and a name is
+// not an identity. Only successes are cached — a parse failure must throw again
+// under the next name that declares it, with that name in the message.
+const parsed = new Map();
+
+// A source that IS the parsed contents of a partforge-vector file, rather than a
+// way to reach its bytes — the in-tree form, `import doc from "./x.vector.json"`.
+// Returns that object, or null for every other source form.
+//
+// `unwrapModule` first, so a dynamic `import("./x.vector.json")` namespace reads
+// the same as the static default import, matching the rule the resolver applies
+// to bytes and URLs.
+//
+// Deliberately STRUCTURAL, not a format check: anything object-shaped is claimed
+// here and judged afterwards by toInternalDocument, so an object that is not
+// artwork draws the validator's specific complaint (`has format "svg"`) rather
+// than the source grammar's generic one. Arrays are not claimed — an array is
+// never a file, and for it the grammar error names the real mistake.
+function asParsedFile(source) {
+  const v = unwrapModule(source);
+  if (!v || typeof v !== "object" || Array.isArray(v)) return null;
+  if (v instanceof ArrayBuffer || ArrayBuffer.isView(v) || v instanceof URL) return null;
+  return v;
+}
+
+// `payload` is what resolveOne produced: the resolved bytes, or — for a source
+// `asParsedFile` claimed — the file's contents themselves, already parsed.
+function parseDocument(payload, label) {
+  if (!(payload instanceof ArrayBuffer)) return toInternalDocument(payload, label);
+  let text;
+  try { text = new TextDecoder().decode(payload); }
+  catch { throw new Error(`vector2d: "${label}" could not be decoded as UTF-8 text`); }
+  let doc;
+  try { doc = JSON.parse(text); }
+  catch (e) {
+    throw new Error(`vector2d: "${label}" is not valid JSON — ${e.message}. `
+      + "A vectors source is an ingested partforge-vector file, not an .svg file; see docs/VECTOR-FORMAT.md");
+  }
+  return toInternalDocument(doc, label);
+}
+
+// source -> resolved bytes, recorded only once a source has SUCCESSFULLY resolved.
+// `cache` above cannot answer that question: makeAssetResolver stores the promise
+// synchronously, so `cache.has(source)` is true the instant a fetch starts and
+// stays true if it never finishes. This map is what `cachedVectorDocs` reads, and
+// its whole point is that membership means "the bytes are here, now".
+const bytesBySource = new Map();
+// source -> raw parsed JSON, or null if it is not a JSON object. Filled LAZILY by
+// cachedVectorDocs rather than at resolve time, so the build path never pays a
+// JSON.parse for lint's benefit, and lint never re-parses the same file twice.
+const rawBySource = new Map();
+
+// The resolver memoizes by source identity and cannot see the declared name, so
+// the name is bound per declaration below rather than baked into the resolver.
+const resolveOne = makeAssetResolver(
+  cache,
+  (bytes, _value, source) => { bytesBySource.set(source, bytes); return bytes; },
+  "resolveVectors: a vector source must be bytes, a URL, a thunk returning one, "
+    + "or the already-parsed contents of a partforge-vector file",
+  (value) => asParsedFile(value) ?? undefined,
+);
+
+export async function resolveVectors(vectorsDecl) {
+  // A function reaching here means a caller passed `part.vectors` raw, the way
+  // fonts.js's resolveFonts guards against the same mistake for `part.fonts`.
+  // `Object.entries` on a function is `[]`, not a thrown error, so without
+  // this check a function-valued `vectors` would silently resolve to an empty
+  // map and only surface much later as `vector2d: unknown vector "…"` — a name a
+  // part author declared correctly, that k.vector2d insists doesn't exist. No
+  // part currently declares `vectors` as a function (unlike fonts, which a
+  // `type: "font"` control already drives this way) — this exists so the
+  // day that form is added, it fails loudly instead of silently.
+  if (typeof vectorsDecl === "function") {
+    throw new Error("resolveVectors: `vectors` is a function — it is not resolved against params yet; pass the plain object form");
+  }
+  const raw = await resolveDecl(vectorsDecl, resolveOne);
+  const out = new Map();
+  for (const [name, payload] of raw) {
+    let doc = parsed.get(payload);
+    if (!doc) { doc = parseDocument(payload, name); parsed.set(payload, doc); }
+    out.set(name, doc);
+  }
+  return out;
+}
+
+// The RAW parsed JSON, before validation or conversion — what lint's
+// document-dependent rules need to read `units` and `shapes`. Never throws: a
+// source that will not fetch, decode, or parse (to a JSON object) maps to
+// null, and the rules that depend on it stay quiet for that name only —
+// resolution is PER-SOURCE, not all-or-nothing, so one broken vector among
+// several does not silence document-aware lint for its siblings. Deliberately
+// calls `resolveOne` itself rather than going through `resolveDecl` (whose
+// `Promise.all` rejects the whole batch on a single failure) — this still
+// shares `resolveOne`'s bytes memo with resolveVectors, so running `lint`
+// ahead of `measure` (the CLI does both) costs no extra fetch. It does its own
+// decode/parse rather than reusing the `parsed` memo, which holds the
+// VALIDATED/converted document, not the raw JSON this needs.
+export async function resolveVectorDocs(vectorsDecl) {
+  if (typeof vectorsDecl === "function") return new Map();
+  const decl = vectorsDecl ?? {};
+  const out = new Map();
+  await Promise.all(Object.entries(decl).map(async ([name, source]) => {
+    try {
+      const payload = await resolveOne(source);
+      // An adopted source resolves to the raw JSON itself — there is nothing to
+      // decode, and running it through TextDecoder would map a perfectly good
+      // file to null.
+      const doc = payload instanceof ArrayBuffer
+        ? JSON.parse(new TextDecoder().decode(payload))
+        : payload;
+      out.set(name, doc && typeof doc === "object" ? doc : null);
+    } catch {
+      out.set(name, null);
+    }
+  }));
+  return out;
+}
+
+// The SYNCHRONOUS, FETCH-FREE sibling of resolveVectorDocs: the raw parsed JSON
+// for every declared vector whose bytes are ALREADY resolved, and nothing for the
+// rest. Never fetches, never awaits, never throws.
+//
+// This exists because lint is instant and offline BY CONSTRUCTION — that is the
+// property that lets a browser sandbox run it on every keystroke — and calling
+// the async resolver from the lint path quietly gave that away: a slow or hanging
+// vector URL (asset-resolve.js's fetch has no timeout) would stall the lint reply
+// forever, and a throwing `vectors` getter would reject in a floating promise,
+// which surfaces as `unhandledrejection` rather than an `error` event, so a host
+// waiting on a lint-report simply waits.
+//
+// The degradation is the one the two document-dependent rules are designed for:
+// no document, no finding. In a hosted sandbox a build has almost always run
+// first, so the bytes are already in the memo and both rules light up; before the
+// first build they stay silent, exactly as they do today for a caller that passes
+// no vectorDocs at all. Nothing regresses, and lint cannot become slower or
+// hangable than it was before vectors existed.
+//
+// `decl` is caller data all the way down (a throwing getter, a Proxy whose
+// ownKeys trap throws), so every step that touches it is guarded per-name and the
+// whole walk is guarded once.
+export function cachedVectorDocs(vectorsDecl) {
+  const out = new Map();
+  if (!vectorsDecl || typeof vectorsDecl !== "object") return out;
+  let entries;
+  try { entries = Object.entries(vectorsDecl); } catch { return out; }
+  for (const entry of entries) {
+    try {
+      const [name, source] = entry;
+      // An already-parsed source has nothing to resolve, so unlike bytes and URLs
+      // it is readable on the very first lint — before any build has run. That is
+      // the state a hosted editor spends most of its time in.
+      const inline = asParsedFile(source);
+      if (inline) { out.set(name, inline); continue; }
+      if (!bytesBySource.has(source)) continue;        // not resolved yet — stay silent
+      if (!rawBySource.has(source)) {
+        let doc = null;
+        try {
+          const parsedJson = JSON.parse(new TextDecoder().decode(bytesBySource.get(source)));
+          doc = parsedJson && typeof parsedJson === "object" ? parsedJson : null;
+        } catch { doc = null; }                        // not JSON, or not decodable
+        rawBySource.set(source, doc);
+      }
+      out.set(name, rawBySource.get(source));
+    } catch { /* one hostile entry silences itself, not its siblings */ }
+  }
+  return out;
+}
+
+// Register a part's vectors on a booted kernel. Called in the async phase before
+// every job's synchronous build — worker (jobs.js) and Node boots alike.
+export async function ensureVectors(kernel, vectorsDecl) {
+  if (!kernel?._vectors) return;
+  const declared = vectorsDecl ?? {};
+  for (const [name, doc] of await resolveVectors(declared)) kernel._vectors.set(name, doc);
+  // Drop names this declaration does not supply. `_vectors` is the kernel's and the
+  // kernel outlives the job (worker-rebind, many parts), so without this a name
+  // from a previous part stays resolvable — the stale-registration bug jobs.js's
+  // font prune exists to prevent.
+  for (const name of [...kernel._vectors.keys()]) {
+    if (!Object.hasOwn(declared, name)) kernel._vectors.delete(name);
+  }
+}

package/src/framework/worker.js

@@ -10,6 +10,7 @@
 // in docs/KERNEL-CONTRACT.md.
 import { handle } from "./jobs.js";
 import { lintPart } from "../lint.js";
+import { cachedVectorDocs } from "./vectors.js";
 
 async function manifoldKernels() {
   const [{ default: Module }, { createManifoldKernel }] = await Promise.all([
@@ -140,7 +141,51 @@ export function runWorker(part, opts = {}) {
     // the pump awaits that boot, so routing lint through the queue would drag in
     // OCCT's ~11 MB WASM to run a check that never calls the kernel at all.
     if (e.data?.type === "lint") {
-      postMessage({ type: "lint-report", report: lintPart(current, { params: e.data.params }) });
+      // `vectorDocs` is what the two document-dependent vector rules need —
+      // vector-size-missing (does this file's `units` require a size?) and
+      // vector-unknown-shape (does it declare that shape name?). Without it both
+      // stay silent, which is how they are designed to degrade.
+      //
+      // CACHED ONLY, and deliberately so. This handler must stay synchronous:
+      // lint is instant and offline by construction, which is the property that
+      // lets a sandbox run it on every keystroke. Awaiting the async resolver
+      // here made lint hangable (asset-resolve.js's fetch has no timeout) and
+      // made the reply order depend on how fast each part's vectors fetched.
+      // cachedVectorDocs reads only bytes that are already resolved and never
+      // initiates a fetch, so a hosted sandbox gets both rules as soon as one
+      // build has run — the common case — and never waits for them.
+      //
+      // Guarded even so: lintPart's never-throws contract is worth nothing to a
+      // host if the handler around it can throw first and post NOTHING at all —
+      // in a real worker that surfaces as `unhandledrejection`, not an `error`
+      // event, so a host waiting on a lint-report just waits.
+      //
+      // Two levels, because they mean different things. The inner one covers a
+      // hostile `vectors` (a throwing getter, a Proxy whose ownKeys trap throws):
+      // that means "no documents", exactly as if the caller passed none, so the
+      // report is the same one lintPart alone would produce. The outer one is the
+      // last resort for anything neither of us has thought of.
+      let report;
+      try {
+        let vectorDocs;
+        try { vectorDocs = Object.fromEntries(cachedVectorDocs(current?.vectors)); }
+        catch { vectorDocs = undefined; }
+        report = lintPart(current, { params: e.data.params, vectorDocs });
+      } catch (cause) {
+        report = {
+          ok: false,
+          errors: [{
+            rule: "lint-context-error",
+            severity: "error",
+            message: `partforge/lint could not run: ${cause?.message || String(cause)}`,
+            hint: "The part or the lint request is too malformed to analyze — make sure `vectors`, `defaults` and `params` are plain, side-effect-free data rather than throwing getters or hostile Proxies.",
+            path: "",
+          }],
+          warnings: [],
+          notes: [],
+        };
+      }
+      postMessage({ type: "lint-report", report });
       return;
     }
     // Only generates supersede each other; exports/inspect always run (cancelling

package/src/ingest.js

@@ -0,0 +1,8 @@
+// The published `partforge/ingest` entry: SVG -> the partforge-vector JSON
+// format. DOM-required and main-thread only — a host runs it once per artwork
+// and stores the result, the same division of labour as `fontCatalog`.
+// partforge does not write files.
+//
+// Deliberately NOT re-exported from `partforge` (the main entry) or from
+// `partforge/geometry`: this must stay unreachable from the geometry worker.
+export { ingestSvg } from "./framework/ingest/svg-ingest.js";

package/src/parts/assets/emblem.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48">
+  <!-- A filled shape and a stroked OPEN shape, so this one file exercises both
+       of ingest's geometry paths. The union's tight bbox is 40 x 30 artwork
+       units: the circle spans 14..34 in both axes, and the stroked bar spans
+       4..44 in x (round caps add half the 4-unit width at each end) and 40..44
+       in y. Deliberately NOT centred in the viewBox, so anything that sizes from
+       the viewBox instead of the geometry gets a visibly wrong answer. -->
+  <circle cx="24" cy="24" r="10" fill="#111"/>
+  <polyline points="6 42 42 42" fill="none" stroke="#111" stroke-width="4" stroke-linecap="round"/>
+</svg>

package/src/parts/assets/emblem.vector.json

@@ -0,0 +1,110 @@
+{
+  "format": "partforge-vector",
+  "version": 1,
+  "units": "artwork",
+  "note": "Filled 2-D outlines for k.vector2d. `units` is \"mm\" (coordinates are millimetres, placed as authored) or \"artwork\" (no physical meaning; a size is required at every call site). `shapes` maps a name to a list of filled regions; each region's `outer` is its boundary and `holes` are subtracted from it. A contour is a `kind`: \"path\", \"circle\", \"rect\", or \"polygon\". Path segments run head-to-tail from `start`, and the contour closes implicitly from the last `to` back to `start`. y points UP. See docs/VECTOR-FORMAT.md.",
+  "source": "emblem.svg",
+  "bbox": {
+    "minX": 4,
+    "minY": -44,
+    "maxX": 44,
+    "maxY": -14
+  },
+  "shapes": {
+    "artwork": [
+      {
+        "outer": {
+          "kind": "path",
+          "start": [
+            14,
+            -24
+          ],
+          "segments": [
+            {
+              "kind": "arc",
+              "to": [
+                31.071068,
+                -31.071068
+              ],
+              "through": [
+                20.173166,
+                -33.238795
+              ]
+            },
+            {
+              "kind": "arc",
+              "to": [
+                24,
+                -14
+              ],
+              "through": [
+                33.238795,
+                -20.173166
+              ]
+            },
+            {
+              "kind": "arc",
+              "to": [
+                14,
+                -24
+              ],
+              "through": [
+                16.928932,
+                -16.928932
+              ]
+            }
+          ]
+        },
+        "holes": []
+      },
+      {
+        "outer": {
+          "kind": "path",
+          "start": [
+            6,
+            -40
+          ],
+          "segments": [
+            {
+              "kind": "arc",
+              "to": [
+                6,
+                -44
+              ],
+              "through": [
+                4,
+                -42
+              ]
+            },
+            {
+              "kind": "line",
+              "to": [
+                42,
+                -44
+              ]
+            },
+            {
+              "kind": "arc",
+              "to": [
+                42,
+                -40
+              ],
+              "through": [
+                44,
+                -42
+              ]
+            },
+            {
+              "kind": "line",
+              "to": [
+                6,
+                -40
+              ]
+            }
+          ]
+        },
+        "holes": []
+      }
+    ]
+  }
+}

package/src/parts/assets/plate.vector.json

@@ -0,0 +1,27 @@
+{
+  "format": "partforge-vector",
+  "version": 1,
+  "units": "mm",
+  "note": "Emblem backing plate. Drawn at 40 x 24 mm with M3 clearance holes on 28 mm centres and a keyway placed low, in the gap between the emblem artwork's disc and its bar, so it stays a real through-slot rather than getting capped by the emboss at the default emblem_w. Coordinates are millimetres and place as authored, so `body`, `holes`, and `keyway` share one frame — the cut in build lands where it is drawn.",
+  "shapes": {
+    "body": {
+      "role": "add",
+      "regions": [
+        { "outer": { "kind": "rect", "center": [0, 0], "width": 40, "height": 24, "radius": 4 } }
+      ]
+    },
+    "holes": {
+      "role": "subtract",
+      "regions": [
+        { "outer": { "kind": "circle", "center": [-14, 0], "r": 1.7 } },
+        { "outer": { "kind": "circle", "center": [14, 0], "r": 1.7 } }
+      ]
+    },
+    "keyway": {
+      "role": "subtract",
+      "regions": [
+        { "outer": { "kind": "polygon", "points": [[-3, -8], [3, -8], [0, -4]] } }
+      ]
+    }
+  }
+}