partforge 0.92.0 → 0.93.0

package/src/parts/emblem.js

@@ -0,0 +1,102 @@
+// 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.
+//
+// `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 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.
+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),
+  },
+  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). */