partforge 0.92.0 → 0.94.0

package/src/parts/emblem.js

@@ -0,0 +1,114 @@
+// The k.vector2d reference part — for BOTH paths the format supports: ingested
+// artwork (`emblem`, `units: "artwork"`, sized per call site) and an authored
+// millimetre drawing (`plate`, `units: "mm"`, placed exactly as drawn). The two
+// vectors share one build, composed together with an ordinary boolean.
+//
+// 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,
+  },
+  parameters: [
+    {
+      id: "plate",
+      title: "Plate",
+      description: "The backing plate the artwork is embossed on. Its outline — including the bolt "
+        + "holes and keyway — is drawn in plate.vector.json, not parameterized.",
+      advanced: [
+        { key: "plate_t", label: "Thickness", unit: "mm", min: 1, max: 10, step: 0.5, description: "Plate thickness." },
+      ],
+    },
+    {
+      id: "art",
+      title: "Artwork",
+      description: "The embossed vector art. `emblem.svg` carries a filled circle and a stroked bar, so both of ingest's geometry paths are exercised.",
+      advanced: [
+        { key: "emblem_w", label: "Emblem width", unit: "mm", min: 8, max: 70, step: 1,
+          description: "Width of the artwork's **tight bounding box** in mm — not its `viewBox`. Stroke thickness scales with it." },
+        { key: "emboss", label: "Emboss height", unit: "mm", min: 0.4, max: 4, step: 0.2,
+          description: "How far the artwork stands proud of the plate." },
+      ],
+    },
+  ],
+  defaults: { plate_t: 3, emblem_w: 30, emboss: 1 },
+  parts: {
+    plate: {
+      label: "Plate",
+      views: ["plate"],
+      export: { name: "emblem-plate" },
+      // No shape named and no size: the file's own roles compose it (body minus
+      // holes minus keyway), and units "mm" places it exactly as drawn. A size
+      // HERE would be safe — the composed call measures the whole document at
+      // once — but it would also be pointless. What is not safe is fetching
+      // body/holes/keyway separately and sizing each call: each would scale
+      // against ITS OWN bounds, and the drawing's shared frame would be gone
+      // (ERROR-PATTERNS.md#vector-mm-shapes-misscaled). Millimetres place as
+      // authored; that is the whole point of the units mode.
+      // The keyway sits clear of the artwork at the default `emblem_w` (30) —
+      // confirmed by measurement, not eyeballed: their 2-D footprints have zero
+      // intersection. That clearance is deliberate, not incidental: a much
+      // larger `emblem_w` would grow the emboss until it overlaps the keyway's
+      // footprint again, and the union below would then cap it from above —
+      // a through-slot the drawing marks `role: "subtract"` quietly becoming a
+      // blind pocket. This is exactly the failure mode the `holes` gate below
+      // exists to catch, which is why that gate is only asserted at defaults.
+      build: (k, p) => k
+        .vector2d("plate")
+        .extrude({ h: p.plate_t })
+        .union(k.vector2d("emblem", { width: p.emblem_w }).extrude({ h: p.emboss }).translate([0, 0, p.plate_t])),
+    },
+  },
+  views: { plate: { label: "Plate" } },
+  verify: {
+    expect: {
+      plate: {
+        // Tight in all three axes, by the same +1 mm convention as
+        // import-demo.js's gates: verify evaluates the `defaults` case only
+        // (this part declares no presets), so bbox is checked against one
+        // deterministic value (40 x 24 x 4) forever, not a swept range —
+        // z = plate_t + emboss = 3 + 1 = 4 at these defaults specifically,
+        // not the schema's wider plate_t/emboss envelope. Revisit this bound
+        // if a preset is ever added that sweeps plate_t or emboss.
+        bbox: "<=[41,25,5]",
+        // Measured at defaults: 3013 mm^3 (`npx partforge measure`). The bare
+        // plate (no emboss union) is 2748 mm^3 — comfortably under this bound —
+        // so a silently-vanished emboss union fails here. Complemented by the
+        // `holes` gate below for the opposite failure (a cut that stops working
+        // raises volume, not lowers it, so this bound alone can't catch that).
+        volume: ">=2900",
+        watertight: true,
+        // Three through-holes: the two bolt circles, plus the keyway triangle —
+        // all cut clean through the extruded plate and, at this part's default
+        // `emblem_w`, none of them sit under the artwork's emboss (see the
+        // build comment above for why that placement matters). Confirmed with
+        // `npx partforge measure`, and falsified by temporarily flipping
+        // "holes"/"keyway" to role "add" in plate.vector.json (which drops
+        // this to 0, proving the gate can fail).
+        holes: 3,
+      },
+      _view: { overlaps: 0 },
+    },
+  },
+};

package/src/testing/manifold.js

@@ -6,10 +6,11 @@ import { createManifoldKernel } from "../framework/geometry/manifold-backend.js"
 import { resolveFonts } from "../framework/fonts.js";
 import { normalizeOpentype, parseFont } from "../framework/geometry/opentype-interop.js";
 import { ensureImports } from "../framework/imports.js";
+import { ensureVectors } from "../framework/vectors.js";
 import { nodeAssetSources } from "./assets.js";
 import { tessellateStepAssets } from "./step-mesh.js";
 
-export async function bootManifoldKernel({ quality = "preview", fonts, imports, importMeshes } = {}) {
+export async function bootManifoldKernel({ quality = "preview", fonts, imports, importMeshes, vectors } = {}) {
   const wasm = await Module();
   wasm.setup();
   const kernel = createManifoldKernel(wasm, { quality });
@@ -24,5 +25,6 @@ export async function bootManifoldKernel({ quality = "preview", fonts, imports,
     const meshes = importMeshes ?? (stepEntries.length ? await tessellateStepAssets(stepEntries) : null);
     await ensureImports(kernel, decl, meshes);
   }
+  if (vectors) await ensureVectors(kernel, nodeAssetSources(vectors));
   return kernel;
 }

package/src/testing/occt.js

@@ -8,9 +8,10 @@ import { createOcctKernel } from "../framework/geometry/occt-backend.js";
 import { resolveFonts } from "../framework/fonts.js";
 import { normalizeOpentype, parseFont } from "../framework/geometry/opentype-interop.js";
 import { ensureImports } from "../framework/imports.js";
+import { ensureVectors } from "../framework/vectors.js";
 import { nodeAssetSources } from "./assets.js";
 
-export async function bootOcctKernel({ fonts, imports, importMeshes } = {}) {
+export async function bootOcctKernel({ fonts, imports, importMeshes, vectors } = {}) {
   const require = createRequire(import.meta.url);
   globalThis.require = globalThis.require ?? require;
   globalThis.__dirname = globalThis.__dirname ?? path.dirname(fileURLToPath(import.meta.url));
@@ -22,5 +23,6 @@ export async function bootOcctKernel({ fonts, imports, importMeshes } = {}) {
   if (fonts) { const opentype = normalizeOpentype(await import("opentype.js"));
     for (const [name, buf] of await resolveFonts(nodeAssetSources(fonts))) kernel._fonts.set(name, parseFont(opentype, buf, name)); }
   if (imports) await ensureImports(kernel, nodeAssetSources(imports), importMeshes ?? null);
+  if (vectors) await ensureVectors(kernel, nodeAssetSources(vectors));
   return kernel;
 }

package/types/ingest.d.ts

@@ -0,0 +1,118 @@
+// partforge/ingest — SVG -> the partforge-vector JSON format (docs/VECTOR-FORMAT.md).
+//
+// DOM-dependent and main-thread-only: this entry is deliberately NOT reachable
+// from the geometry worker, and is never re-exported from the main entry or
+// from `partforge/geometry`. A host runs it once per artwork, in a browser,
+// and stores the result — the same division of labour as `fontCatalog`.
+// partforge does not write files.
+//
+// These declarations describe the FORMAT, not just what `ingestSvg` happens to
+// emit — the same documents are hand-authored, so `bbox` and `source` are
+// optional here even though ingest always writes both.
+
+/** Coordinate meaning. `"mm"` places as authored; `"artwork"` requires a size at every call site. */
+export type VectorUnits = "mm" | "artwork";
+
+/** Whether a shape adds material to the composed result or is cut from it. `"add"` is the default. */
+export type VectorRole = "add" | "subtract";
+
+/** The document's tight bounding box. A cache, not an authority — placement recomputes it. */
+export interface VectorBbox {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+
+/** A parsed `partforge-vector` JSON document — see docs/VECTOR-FORMAT.md. */
+export interface VectorDocument {
+  format: "partforge-vector";
+  version: number;
+  units: VectorUnits;
+  /** Free text; ignored on load. Ingest writes the format's own one-paragraph summary. */
+  note?: string;
+  /** Provenance only — typically the original filename. Not validated or used at load/build time. */
+  source?: string | null;
+  /** Optional: an author need not compute analytic curve extrema, but a stale value is a named error. */
+  bbox?: VectorBbox;
+  /** Name -> shape. At least one shape, and at least one of them must have role `"add"`. */
+  shapes: Record<string, VectorShape>;
+}
+
+/**
+ * A named shape: either a bare region list (role `"add"`) or `{ role, regions }`.
+ * Both forms exist because `"add"` is an honest default — a painted region adds
+ * material, which is what every file written before roles existed already meant.
+ */
+export type VectorShape = VectorRegion[] | { role?: VectorRole; regions: VectorRegion[] };
+
+/** One filled region: an `outer` boundary with `holes` subtracted from it. */
+export interface VectorRegion {
+  outer: VectorContour;
+  holes?: VectorContour[];
+}
+
+/** One closed contour: the explicit `"path"` form, or one of the three primitives. */
+export type VectorContour = VectorPath | VectorCircle | VectorRect | VectorPolygon;
+
+/**
+ * Segments run head-to-tail from `start`, and the contour closes IMPLICITLY from
+ * the last segment's `to` back to `start`. At least one segment, and at least two
+ * if they are all `"line"` — a single straight edge and its closure are the same
+ * line, so they bound nothing, while a single `"arc"` or `"cubic"` bounds area
+ * against the closing chord.
+ */
+export interface VectorPath {
+  kind: "path";
+  start: [number, number];
+  segments: VectorSegment[];
+}
+
+/** Expands to two 180-degree arcs, counter-clockwise. */
+export interface VectorCircle {
+  kind: "circle";
+  center: [number, number];
+  r: number;
+}
+
+/** Axis-aligned, counter-clockwise. `radius` rounds all four corners; at most half the shorter side. */
+export interface VectorRect {
+  kind: "rect";
+  center: [number, number];
+  width: number;
+  height: number;
+  radius?: number;
+}
+
+/** At least 3 points, joined by straight edges in the author's own order. */
+export interface VectorPolygon {
+  kind: "polygon";
+  points: Array<[number, number]>;
+}
+
+export type VectorSegment =
+  | { kind: "line"; to: [number, number] }
+  | { kind: "arc"; to: [number, number]; through: [number, number] }
+  | { kind: "cubic"; to: [number, number]; c1: [number, number]; c2: [number, number] };
+
+export interface IngestSvgOptions {
+  /**
+   * `"outline"` (default) turns strokes into filled geometry; `"ignore"` drops
+   * stroke geometry entirely and keeps only fills. There is no equivalent
+   * option on `k.vector2d` — once ingested, there is no stroke left to ignore.
+   */
+  strokes?: "outline" | "ignore";
+  /** Provenance only — typically the original filename. Stored verbatim as `source`; not validated or used at load/build time. */
+  source?: string | null;
+}
+
+/**
+ * Convert an SVG document (as text) into the `partforge-vector` JSON format a
+ * part's `k.vector2d()` calls can place. DOM-required — call this in a browser,
+ * store the returned document (e.g. as `<name>.vector.json` beside the part),
+ * and reference it from the part's `vectors` field. The result is always one
+ * shape named `"artwork"` in `"artwork"` units, with `bbox` and `source` written.
+ * Throws if the SVG can't be parsed, or if it contains no painted geometry (every
+ * element is `fill="none"` with no stroke, hidden, or empty).
+ */
+export function ingestSvg(svgText: string, opts?: IngestSvgOptions): VectorDocument;

package/types/kernel.d.ts

@@ -455,6 +455,29 @@ export interface Text2dOptions {
   kerning?: boolean;
 }
 
+/** Horizontal alignment of a `vector2d` placement. */
+export type Vector2dAlign = "center" | "left" | "right";
+/** Vertical alignment of a `vector2d` placement. */
+export type Vector2dValign = "middle" | "top" | "bottom";
+
+export interface Vector2dOptions {
+  /**
+   * Name of one shape in the file, returned whatever its `role`. Omit for the
+   * composed result: every `"add"` shape unioned, minus every `"subtract"` one.
+   */
+  shape?: string;
+  /** Target width in mm. At most one of `width`/`height`/`fit`; required for `units: "artwork"`. */
+  width?: number;
+  /** Target height in mm. At most one of `width`/`height`/`fit`; required for `units: "artwork"`. */
+  height?: number;
+  /** Target size in mm for the larger extent. At most one of `width`/`height`/`fit`; required for `units: "artwork"`. */
+  fit?: number;
+  /** Defaults to `"center"` for `units: "artwork"`, and to no horizontal translate for `units: "mm"`. */
+  align?: Vector2dAlign;
+  /** Defaults to `"middle"` for `units: "artwork"`, and to no vertical translate for `units: "mm"`. */
+  valign?: Vector2dValign;
+}
+
 /** Anything `k.hull`/`k.hullChain` accepts as one input. */
 export type HullInput = Shape2D | Contour;
 
@@ -501,6 +524,11 @@ export interface GeometryKernel {
   shape2d(profile: ProfileInput): Shape2D;
   /** Render outline-font text as a `Shape2D`. */
   text2d(string: string, opts?: Text2dOptions): Shape2D;
+  /**
+   * Place a declared vector file as a `Shape2D`. `name` is a key in the part's
+   * `vectors` field (`partforge-vector` JSON, not raw `.svg`).
+   */
+  vector2d(name: string, opts?: Vector2dOptions): Shape2D;
   /** Convex hull of all inputs → a convex (faceted) `Shape2D`. */
   hull(inputs: HullInput[]): Shape2D;
   /** Swept hull over an ordered sequence (>= 2 inputs). */

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>;
 }