partforge 0.91.0 → 0.93.0

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). */