partforge 0.93.0 → 0.94.0

package/docs/AUTHORING-PARTS.md

@@ -139,6 +139,9 @@ export default {
   grammar and preload timing as `fonts` above — but the source resolves to **JSON** in the
   `partforge-vector` format, never to raw `.svg`. That JSON is either **authored** by hand
   (millimetre coordinates, placed as drawn) or the **ingested** output of `partforge/ingest`.
+  A vector source may additionally be that JSON **already parsed** — the object itself,
+  rather than bytes or a URL pointing at it — which is the form to use when the artwork
+  lives beside the part and is meant to stay hand-editable.
   See "Vector geometry" below for the full contract.
 
 ---
@@ -1553,6 +1556,28 @@ import outside a Vite build, so `partforge lint`/`measure`/`render` can't resolv
 source must resolve to the `.vector.json`, never to a raw `.svg` — `k.vector2d` does no
 SVG parsing at all.
 
+**A source may also be the parsed file itself.** Alongside bytes, a URL and a thunk, a
+`vectors` entry accepts the **contents** of a `.vector.json` — the object a JSON import
+yields, or anything else that already holds it:
+
+```js
+import plate from "./assets/plate.vector.json" with { type: "json" };
+export default { vectors: { plate }, /* … */ };
+```
+
+The `with { type: "json" }` attribute is required — Node refuses a JSON import without it.
+Reach for this form when the artwork is **hand-authored and meant to stay editable**: the
+numbers sit in a file a reader can open and change, next to the part that uses them, with
+nothing to fetch in order to see them. Reach for `new URL(…)` instead when the file is
+**ingested output** — generated, large, and not read by hand. `src/parts/emblem.js`
+declares one of each, side by side, for exactly this contrast.
+
+Two consequences worth knowing. `partforge/lint`'s document-aware rules can read a parsed
+source on the very first lint, before any build has run, because there is nothing to
+resolve — with a URL they stay silent until the bytes arrive. And the object is validated
+on every resolve, so a malformed one fails with the same message its fetched twin would;
+it is read and never written, so `build` stays pure.
+
 **Sizing is against the tight geometric bounding box, not a `viewBox`.** Icon sets pad
 their `viewBox` inconsistently, so sizing relative to `viewBox` makes two icons declared at
 the same nominal size look different on the plate. `width`/`height`/`fit` instead measure
@@ -1583,7 +1608,9 @@ a `"role": "subtract"` shape in the JSON, or `.cut()` it in `build`), and
 
 **What this is not.** `k.shape2d` does **not** accept the JSON dialect — it takes the
 internal contour form the polygon helpers and `pathProfile` produce — and there is no
-inline document form in `build`. The two vocabularies stay separated by the file boundary,
+inline document form in `build`. A parsed source (above) does not change that: it is a
+`vectors` **declaration**, resolved and validated before `build` runs, not a document
+`build` may assemble or hand to the kernel. The two vocabularies stay separated by the file boundary,
 which is what lets `docs/VECTOR-FORMAT.md` be the only place they meet. Inline authoring
 stays `pathProfile` (see § "Geometry: the kernel / `Solid` API" above, where `pathProfile` is
 introduced, for which to reach for).

package/docs/VECTOR-FORMAT.md

@@ -567,9 +567,18 @@ one:
 - **Existing artwork** — an `.svg` someone else made — goes through
   `partforge/ingest` once and is then referenced like any other document.
 
+Wherever it comes from, the file reaches a part through its `vectors` map — as a
+URL, as bytes, or as the parsed contents themselves (`import doc from
+"./x.vector.json" with { type: "json" }`). The last form is the one to prefer for
+authored artwork, because it keeps the numbers in a file a reader can open and
+edit rather than behind a fetch. See "Vector geometry" in
+`docs/AUTHORING-PARTS.md` for the declaration rules.
+
 `k.shape2d` does **not** accept this JSON dialect, and there is no inline
-document form in `build`. The two vocabularies stay separated by the file
-boundary; that separation is what lets this document be the only place they meet.
+document form in `build` — a parsed source is a declaration resolved before the
+build, not something `build` assembles. The two vocabularies stay separated by
+the file boundary; that separation is what lets this document be the only place
+they meet.
 
 ## 6. Converting an SVG to this format by hand
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.93.0",
+  "version": "0.94.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/asset-resolve.js

@@ -11,6 +11,15 @@
 // thunk, is content-stable for a session — resolve it once). DOM-free and
 // node:-free so it stays safe in the geometry worker's import closure.
 
+// The `{ default: … }` module namespace a dynamic `import()` yields, unwrapped to
+// the value itself; every other value passes through untouched. Exported because
+// vectors.js applies the same rule OUTSIDE this resolver — its synchronous lint
+// path reads a declared source directly, without resolving it — and the rule for
+// what a module wrapper looks like must have exactly one definition.
+export function unwrapModule(v) {
+  return v && typeof v === "object" && "default" in v && !toBuffer(v) && !(v instanceof URL) ? v.default : v;
+}
+
 export function toBuffer(v) {
   if (v instanceof ArrayBuffer) return v;
   // A view may not span its whole backing buffer — slice to its exact range (Node
@@ -33,13 +42,21 @@ function describeSource(v) {
 // async); `errorMessage` is thrown when `source` doesn't match the grammar.
 // Results are cached on the caller-supplied `cache` Map, keyed by source
 // identity, so a repeated declaration resolves (and fetches) only once.
-export function makeAssetResolver(cache, finish, errorMessage) {
+//
+// `adopt(value, source)` is an optional last chance to claim a source that is
+// neither bytes nor fetchable. vectors.js uses it for a source that is ALREADY
+// the parsed contents of its file, where the source IS the asset rather than a
+// way to reach its bytes. It is consulted only for values the grammar is about
+// to refuse, so it can never shadow the bytes/URL/thunk forms; returning
+// `undefined` declines and restores the refusal. Whatever it returns becomes
+// resolveOne's result directly — `finish` takes bytes, and is not called.
+export function makeAssetResolver(cache, finish, errorMessage, adopt = null) {
   return function resolveOne(source) {
     if (cache.has(source)) return cache.get(source);
     const p = (async () => {
       let v = source;
       if (typeof v === "function") v = await v();
-      if (v && typeof v === "object" && "default" in v && !toBuffer(v) && !(v instanceof URL)) v = v.default; // dynamic-import module
+      v = unwrapModule(v);                                          // dynamic-import module
       let bytes = toBuffer(v);
       if (!bytes) {
         if (v instanceof URL || typeof v === "string") {
@@ -53,7 +70,11 @@ export function makeAssetResolver(cache, finish, errorMessage) {
           }
           bytes = await res.arrayBuffer();
         }
-        else throw new Error(errorMessage);
+        else {
+          const claimed = adopt ? adopt(v, source) : undefined;
+          if (claimed !== undefined) return claimed;
+          throw new Error(errorMessage);
+        }
       }
       return finish(bytes, v, source);
     })();

package/src/framework/vectors.js

@@ -12,7 +12,7 @@
 // argument kernel-front.js:117-121 records for text2d.
 //
 // DOM-free and node:-free.
-import { makeAssetResolver, resolveDecl } from "./asset-resolve.js";
+import { makeAssetResolver, resolveDecl, unwrapModule } from "./asset-resolve.js";
 import { toInternalDocument } from "./geometry/vector-format.js";
 
 const cache = new Map();   // source → Promise<Uint8Array> (raw bytes)
@@ -26,9 +26,32 @@ const cache = new Map();   // source → Promise<Uint8Array> (raw bytes)
 // under the next name that declares it, with that name in the message.
 const parsed = new Map();
 
-function parseDocument(bytes, label) {
+// 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(bytes); }
+  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); }
@@ -55,7 +78,9 @@ const rawBySource = new Map();
 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",
+  "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) {
@@ -73,9 +98,9 @@ export async function resolveVectors(vectorsDecl) {
   }
   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); }
+  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;
@@ -99,8 +124,13 @@ export async function resolveVectorDocs(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));
+      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);
@@ -139,6 +169,11 @@ export function cachedVectorDocs(vectorsDecl) {
   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;

package/src/parts/emblem.js

@@ -3,20 +3,32 @@
 // millimetre drawing (`plate`, `units: "mm"`, placed exactly as drawn). The two
 // vectors share one build, composed together with an ordinary boolean.
 //
-// `vectors` is declared with `new URL(..., import.meta.url)`, the same form
-// import-demo.js uses for its STL: Vite turns it into a bundled asset URL, and
-// in Node it is a file: URL that src/testing/assets.js reads off disk. A bare
-// `() => import("./assets/emblem.vector.json")` would work in Vite and fail in the CLI.
+// The two entries also demonstrate the two SOURCE forms, deliberately:
+//
+//   `emblem` is `new URL(..., import.meta.url)` — the form import-demo.js uses
+//   for its STL. Vite turns it into a bundled asset URL; in Node it is a file:
+//   URL src/testing/assets.js reads off disk. Right for ingested output, which is
+//   generated, large, and not meant to be read by hand.
+//
+//   `plate` is the file's parsed CONTENTS, imported directly. Right for artwork
+//   that is hand-authored and meant to STAY hand-editable: the numbers live in a
+//   .json a reader can open, and nothing has to fetch anything to see them —
+//   which is also what lets lint read the file before the first build has run.
+//   The `with { type: "json" }` attribute is required: Node refuses a JSON import
+//   without it, and a bare `() => import("./assets/plate.vector.json")` would
+//   work under Vite and fail in the CLI.
 //
 // The source artwork lives beside it as emblem.svg, and the .json is regenerated
 // with `node scripts/ingest-svg.mjs src/parts/assets/emblem.svg`. plate.vector.json
 // is hand-authored — no ingest step, no source SVG — and is kept legible enough
 // to serve as documentation's worked example of a multi-shape, role-composed file.
+import plate from "./assets/plate.vector.json" with { type: "json" };
+
 export default {
   meta: { title: "Emblem", units: "mm", background: 0x15181d },
   vectors: {
     emblem: new URL("./assets/emblem.vector.json", import.meta.url),
-    plate: new URL("./assets/plate.vector.json", import.meta.url),
+    plate,
   },
   parameters: [
     {

package/types/part.d.ts

@@ -257,6 +257,57 @@ export type FontSource =
 
 type FontSourceValue = string | ArrayBuffer | ArrayBufferView | { default: string };
 
+// --- imports and vectors ------------------------------------------------------
+
+/**
+ * One entry of a part's `imports` map: the STEP/STL/3MF file a `k.import()` call
+ * names. Same source grammar and preload timing as {@link FontSource}.
+ */
+export type ImportSource = FontSource;
+
+/**
+ * One entry of a part's `vectors` map: a `partforge-vector` file for `k.vector2d()`
+ * to place — never a raw `.svg`, which nothing in the geometry worker can read.
+ *
+ * Beyond the bytes/URL/thunk forms every asset source accepts, a vector source may
+ * be the file's ALREADY-PARSED contents: the object a `.vector.json` yields when
+ * something has imported or fetched it. That is the form to reach for when the
+ * artwork lives in the part's own tree and is meant to stay readable and editable,
+ * rather than sitting behind an opaque asset token.
+ *
+ * The object is read, never written, and is validated on every resolve — so a
+ * malformed one fails with the same message its on-disk twin would produce.
+ */
+export type VectorSource =
+  | string
+  | ArrayBuffer
+  | ArrayBufferView
+  | VectorDocument
+  | (() => VectorSourceValue | Promise<VectorSourceValue>);
+
+type VectorSourceValue =
+  | string
+  | ArrayBuffer
+  | ArrayBufferView
+  | VectorDocument
+  | { default: string | VectorDocument };
+
+/**
+ * The parsed contents of a `partforge-vector` file. `docs/VECTOR-FORMAT.md` is the
+ * normative spec; this type is deliberately shallow — it pins the envelope every
+ * reader depends on and leaves contour shapes to the runtime validator, which
+ * reports far better errors than a structural type mismatch can.
+ */
+export interface VectorDocument {
+  format: "partforge-vector";
+  version: number;
+  units: "mm" | "artwork";
+  shapes: Record<string, unknown>;
+  source?: unknown;
+  bbox?: unknown;
+  note?: string;
+}
+
 // --- derive -----------------------------------------------------------------
 
 /**
@@ -316,6 +367,11 @@ export interface SubPartDefinition<P = ResolvedParams, D = Derived> {
 
 export interface ViewDefinition {
   label: string;
+  /**
+   * Open this view first. With none flagged, the first key wins — see
+   * `default-view.js`, which also falls back when the flagged view is empty.
+   */
+  default?: boolean;
   /**
    * Named animations belonging to this view — keyframe data driving this view's
    * params and sub-part opacity over time. See `AnimationSpec` below; the
@@ -548,6 +604,10 @@ export interface PartDefinition<P = ResolvedParams, D = Derived> {
   defaults: Defaults;
   /** Outline fonts a part's `k.text2d()` calls need, as `{ name: source }`. */
   fonts?: Record<string, FontSource>;
+  /** STEP/STL/3MF files a part's `k.import()` calls need, as `{ name: source }`. */
+  imports?: Record<string, ImportSource>;
+  /** Vector artwork a part's `k.vector2d()` calls place, as `{ name: source }`. */
+  vectors?: Record<string, VectorSource>;
   /** Dependent values computed once per build. */
   derive?: DeriveSpec<P, D>;
   /** Named sub-parts; each builds exactly one solid. */
@@ -556,4 +616,9 @@ export interface PartDefinition<P = ResolvedParams, D = Derived> {
   views: Record<string, ViewDefinition>;
   /** Self-verification, co-located with the schema. */
   verify?: VerifyBlock<P, D>;
+  /**
+   * Named measurements reported by `measure`/`inspect` — never rendered, never
+   * exported. Each entry returns either a solid to measure or plain JSON.
+   */
+  probes?: Record<string, (k: GeometryKernel, p: P, d: D) => unknown>;
 }