partforge 0.91.0 → 0.93.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/mount.js

@@ -61,7 +61,7 @@ const IMPORT_MESH_BROKEN_MESSAGE = "STEP import tessellation failed to satisfy t
 // carries the worker's own error text. See the correlated "error" case below.
 const importTessellateFailedMessage = (workerMessage) => `STEP import tessellation failed — ${workerMessage}`;
 
-export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection }) {
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker }) {
   return {
     ready, dispose, setParams,
     // Part-declared animation playback (spec 2026-08-02): animations are
@@ -123,6 +123,16 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
       set: () => {},
       onChange: () => () => {},
     },
+    // The pick marker as a thing with a lifetime, for a host that hangs its own
+    // UI off it: hold() keeps the newest marker on screen (earlier held ones
+    // stay held), release() clears them all, and onAnchorChange reports where
+    // the newest one is on the canvas as the camera moves. Same shape
+    // convention as `measure`, `annotate` and `projection`.
+    pickMarker: pickMarker ?? {
+      hold: () => false,
+      release: () => {},
+      onAnchorChange: () => () => {},
+    },
   };
 }
 
@@ -188,6 +198,15 @@ function createCleanupStack() {
 //                                 // { sync, hide, detach } — call sync() after you
 //                                 // toggle a button's disabled state. Detached
 //                                 // automatically on dispose().
+//   runtime.pickMarker.hold();    // keep the marker from the last pick on screen
+//                                 // (earlier held markers stay held), and start
+//                                 // reporting where it is. False when there is
+//                                 // nothing to hold — a marker's flash has a
+//                                 // lifetime, so hold promptly after a pick.
+//   runtime.pickMarker.onAnchorChange((a) => …);  // {x, y, visible} in CSS px from the
+//                                 // canvas's top-left, as the camera moves; null when
+//                                 // nothing is held. Returns an unsubscribe.
+//   runtime.pickMarker.release(); // clear every held marker
 //   runtime.setActive(false);     // park the viewer: stop the render loop and release
 //                                 // both large GPU allocations (the drawing buffer and
 //                                 // the cached capture target). For a host that hides the
@@ -580,11 +599,15 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
         // deliberately not guarded — one is armed by an explicit dev toggle,
         // the other per agent request.
         suppressed: () => measureMode.isEnabled() || (annotateMode?.isEnabled() ?? false),
-        onPick: (selection) => onPick({
+        onPick: (selection, anchor) => onPick({
           selection,
           label: selection.feature?.label ?? part.parts[selection.subPart]?.label ?? selection.subPart,
           prompt: formatSelection(selection, { style: "prompt" }),
           token: formatSelection(selection, { style: "token" }),
+          // Where the marker is on the canvas, in CSS px from its top-left, so
+          // a host can put its own UI beside the dot on the first frame rather
+          // than a round trip later.
+          anchor,
         }),
       });
       cleanup.defer(() => picker.detach());
@@ -1098,6 +1121,11 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
         set: (mode) => viewer.setProjection(mode),
         onChange: (cb) => viewer.onProjectionChange(cb),
       },
+      pickMarker: {
+        hold: () => viewer.holdFlashPoint(),
+        release: () => viewer.releaseFlashPoints(),
+        onAnchorChange: (cb) => viewer.onFlashAnchorChange(cb),
+      },
     });
   } catch (error) {
     try {

package/src/framework/pick-flash.js

@@ -42,3 +42,34 @@ export function flashWorldRadius(
   const radius = worldPerPixel(camera, worldPoint, viewportHeightPx) * pixelRadius;
   return Number.isFinite(radius) && radius > MIN_RADIUS ? radius : MIN_RADIUS;
 }
+
+const _projected = new THREE.Vector3();
+
+// Where a world point lands on the canvas, in CSS px from its top-left.
+//
+// `visible` is the answer to "is the marker actually on screen", which is two
+// questions: is it in FRONT of the camera (a point behind a perspective eye
+// projects to a mirrored position with no warning — `ndc.z > 1` is what
+// catches it), and is it inside the canvas. The position is reported either
+// way: an off-screen anchor is information, and the caller decides what to do
+// with it.
+export function projectToScreen(camera, worldPoint, width, height) {
+  _projected.copy(worldPoint).project(camera);
+  const x = (_projected.x * 0.5 + 0.5) * width;
+  // NDC y grows upward, screen y downward — the flip is the whole reason this
+  // is a named function rather than two lines at each call site.
+  const y = (0.5 - _projected.y * 0.5) * height;
+  const inFront = _projected.z >= -1 && _projected.z <= 1;
+  const onCanvas = x >= 0 && x <= width && y >= 0 && y <= height;
+  return { x, y, visible: inFront && onCanvas };
+}
+
+// Is `next` different enough from `previous` to be worth telling anyone about?
+// A still camera re-projects to the same pixel every frame, and publishing that
+// 60 times a second across a postMessage boundary is pure noise.
+export function anchorMoved(previous, next, epsilon = 0.5) {
+  if (!previous || !next) return previous !== next;
+  return previous.visible !== next.visible
+    || Math.abs(previous.x - next.x) >= epsilon
+    || Math.abs(previous.y - next.y) >= epsilon;
+}

package/src/framework/selection/pick.js

@@ -3,6 +3,7 @@
 import { raycastViewer, worldToSubPartLocal } from "./raycast.js";
 import { resolveSelection } from "./resolve.js";
 import { createDragTracker } from "./drag-tracker.js";
+import { projectToScreen } from "../pick-flash.js";
 
 export { worldToSubPartLocal };
 
@@ -10,6 +11,8 @@ export { worldToSubPartLocal };
 // whose suppression condition lives elsewhere (mount passes measure mode's
 // isEnabled): while it returns true a click neither raycasts, flashes, nor
 // picks — no resync bookkeeping the way an event-driven setActive would need.
+// onPick receives (selection, anchor): where the marker this click flashed
+// landed on the canvas, in CSS px from its top-left.
 export function attachPicker(viewer, { part, getContext, onPick, suppressed }) {
   let active = false;
   const drag = createDragTracker();
@@ -25,7 +28,19 @@ export function attachPicker(viewer, { part, getContext, onPick, suppressed }) {
     if (!hit) return;
     const selection = resolveSelection(part, getContext(), hit);
     viewer.flashPoint([hit.pointWorld.x, hit.pointWorld.y, hit.pointWorld.z]);
-    onPick(selection);
+    // The anchor is the MARKER's projection, not the pointer's position, even
+    // though the two coincide at this instant: the host's follow-the-camera
+    // stream projects the same world point through the same function every
+    // frame after, so the first answer is of a piece with the rest.
+    // Sized from the rect the raycast just used, which is what makes this
+    // anchor land back on the pixel the user clicked. The stream sizes from the
+    // renderer's last setSize instead — also CSS px, but the CONTAINER's
+    // integer clientWidth/Height as of the last ResizeObserver call, and 1x1
+    // while the viewer is parked. They agree in steady state; the divergence is
+    // staleness, never units.
+    const rect = viewer.domElement.getBoundingClientRect();
+    const anchor = projectToScreen(viewer.camera, hit.pointWorld, rect.width, rect.height);
+    onPick(selection, { x: anchor.x, y: anchor.y });
   }
 
   viewer.domElement.addEventListener("pointerdown", drag.onDown);

package/src/framework/vectors.js

@@ -0,0 +1,170 @@
+// 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 } 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();
+
+function parseDocument(bytes, label) {
+  let text;
+  try { text = new TextDecoder().decode(bytes); }
+  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, or a thunk returning one",
+);
+
+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, bytes] of raw) {
+    let doc = parsed.get(bytes);
+    if (!doc) { doc = parseDocument(bytes, name); parsed.set(bytes, 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 bytes = await resolveOne(source);
+      const doc = JSON.parse(new TextDecoder().decode(bytes));
+      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;
+      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);
+  }
+}