partforge 0.96.0 → 0.98.0

package/types/index.d.ts

@@ -101,6 +101,50 @@ export interface MountElements {
   };
 }
 
+/** Which control family a dropped file belongs to. */
+export type AssetKind = "image" | "vector" | "font";
+
+/** One selectable face in a `FontCatalog` family. */
+export interface FontVariant {
+  variant: string;
+  label: string;
+  /** What the picker writes into `params`. */
+  url: string;
+  bytes?: number;
+}
+
+export interface FontFamily {
+  id: string;
+  family: string;
+  category?: string;
+  variants: FontVariant[];
+  /** A name-only subset used to draw the list row. */
+  menuUrl?: string;
+}
+
+/** Backs `type: "font"` controls. Supplied by the host; partforge ships none. */
+export interface FontCatalog {
+  search: (query: string, opts: { limit?: number }) => Promise<FontFamily[]>;
+  /** Reverse lookup, so a hashed-filename URL can still be named in the UI. */
+  describe?: (source: string) => { family: string; variant: string } | null;
+}
+
+export interface ImageAsset {
+  id: string;
+  label: string;
+  /** What the picker writes into `params`. */
+  url: string;
+  width?: number;
+  height?: number;
+  thumbUrl?: string;
+}
+
+/** Backs `type: "image"` controls. Supplied by the host; partforge ships none. */
+export interface ImageCatalog {
+  search: (query: string, opts: { limit?: number }) => Promise<ImageAsset[]>;
+  describe?: (source: string) => { label: string; width: number; height: number } | null;
+}
+
 export interface MountOptions {
   /**
    * Spawns a geometry worker. Called once per backend with `name` as the
@@ -143,6 +187,28 @@ export interface MountOptions {
    * part cannot support is dropped, never fatal.
    */
   viewerState?: ViewerState | null;
+  /**
+   * A provider backing every `type: "font"` control in the part. partforge
+   * ships none — without one, a font control renders as a plain URL field.
+   */
+  fontCatalog?: FontCatalog;
+  /**
+   * A provider backing every `type: "image"` control in the part. Without one,
+   * an image control degrades to a plain URL field.
+   */
+  imageCatalog?: ImageCatalog;
+  /**
+   * The upload hook for the drop target shared by the `"image"`, `"vector"`
+   * and `"font"` controls. Called with the CONVERTED artifact — a PNG, a
+   * partforge-vector document serialized as JSON, or the original file for a
+   * font — never the user's raw drop, and must resolve to a non-empty source
+   * string (an `https:` URL, or a host-defined `pfc-asset:` token) which is
+   * written into the param. Anything else, or a rejection, is reported through
+   * the control's own error line and never written. Omit it and the converted
+   * artifact lands in the param directly — the path a host that cannot fetch
+   * URLs needs, not a degraded fallback.
+   */
+  onAssetUpload?: (blob: Blob, info: { kind: AssetKind; filename: string }) => Promise<string>;
   /** @deprecated alias for `elements.viewer`. */
   container?: HTMLElement | null;
   /** @deprecated alias for `elements.controls`. */
@@ -454,3 +520,4 @@ export function viewSubParts(
   view: string,
   params: Record<string, ParamValue>,
 ): string[];
+

package/types/ingest.d.ts

@@ -116,3 +116,16 @@ export interface IngestSvgOptions {
  * element is `fill="none"` with no stroke, hidden, or empty).
  */
 export function ingestSvg(svgText: string, opts?: IngestSvgOptions): VectorDocument;
+
+export interface ImageToPngOptions {
+  /** Long-edge cap in px; an image already under this is not upscaled. Default 1024. */
+  maxSize?: number;
+}
+
+/**
+ * Convert any image the browser can decode into a PNG `Blob`, downsampling the
+ * long edge to `maxSize` on the way. Main-thread only (uses `createImageBitmap`
+ * and a canvas) — for a host normalising uploads before storing them, since a
+ * part's `images` field decodes PNG only. Never call from a part's `build`.
+ */
+export function imageToPng(fileOrBlob: Blob | File, options?: ImageToPngOptions): Promise<Blob>;

package/types/kernel.d.ts

@@ -481,6 +481,31 @@ export interface Vector2dOptions {
 /** Anything `k.hull`/`k.hullChain` accepts as one input. */
 export type HullInput = Shape2D | Contour;
 
+/** An inline depth-map grid, row-major, 0..65535 per sample. */
+export interface HeightfieldGrid {
+  width: number;
+  height: number;
+  data: Uint16Array;
+}
+
+/** k.heightfield — a depth map as a relief solid. */
+export interface HeightfieldOptions {
+  w: number;
+  d: number;
+  /** Slab thickness under the relief (mm, > 0). Default 1. */
+  base?: number;
+  /** Relief height above `base` at a full-scale (1.0) sample. Default 1. */
+  maxZ?: number;
+  /** Sample spacing (mm, > 0); clamped to a vertex budget with a build warning. Default 0.5. */
+  pitch?: number;
+  /** Flip sampled value as `1 - v`, applied after `range`. */
+  invert?: boolean;
+  /** Remap with clamped ends: `range[0]` -> 0, `range[1]` -> 1. Default [0, 1]. */
+  range?: [number, number];
+  /** Footprint placement in XY only — the base always sits at z = 0. Default "center". */
+  origin?: "center" | "corner";
+}
+
 // --- the kernel -------------------------------------------------------------
 
 /**
@@ -541,6 +566,13 @@ export interface GeometryKernel {
    * side-channel (not a part author's calling surface).
    */
   import(name: string): Solid;
+  /**
+   * A depth map as a relief solid. `nameOrGrid` is a name declared in the part's
+   * `images` field, or an inline grid — the name path is registered pre-build by
+   * the framework via the underscore-prefixed `_registerImage` side-channel (not
+   * a part author's calling surface).
+   */
+  heightfield(nameOrGrid: string | HeightfieldGrid, opts: HeightfieldOptions): Solid;
 
   // Backend-optional: the sub-part cache brackets and WASM lifetime hooks. Every
   // framework caller reaches these through `?.`, so a third-party backend may

package/types/part.d.ts

@@ -257,6 +257,21 @@ export type FontSource =
 
 type FontSourceValue = string | ArrayBuffer | ArrayBufferView | { default: string };
 
+// --- images -----------------------------------------------------------------
+
+/**
+ * One entry of a part's `images` map: raw bytes, a URL string, or a thunk
+ * returning either (a Vite `() => import("./x.png")` resolves to
+ * `{ default: url }`). Resolved to a decoded luminance grid before the
+ * synchronous `build` runs — the source `k.heightfield()` samples.
+ */
+export type ImageSource =
+  | string
+  | ArrayBuffer
+  | ArrayBufferView
+  | (() => ImageSourceValue | Promise<ImageSourceValue>);
+
+type ImageSourceValue = string | ArrayBuffer | ArrayBufferView | { default: string };
 // --- imports and vectors ------------------------------------------------------
 
 /**
@@ -604,6 +619,12 @@ 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>;
+  /**
+   * Depth-map images a part's `k.heightfield()` calls need, as
+   * `{ name: source }` — or a function of the resolved params returning that
+   * map, which is what lets a `type: "image"` control drive the source.
+   */
+  images?: Record<string, ImageSource> | ((p: P) => Record<string, ImageSource>);
   /** 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 }`. */