@appinternalleads/ui 0.4.1 → 0.4.2

package/dist/esm/motion/typesurface/construct.d.ts

@@ -0,0 +1,284 @@
+/**
+ * **The construction layer** — objects built from parts, not a catalogue of finished objects.
+ *
+ *   primitives     cylinder, sphere, ring, revolve (any profile), tube (along a path), box
+ *   manipulators   taper, flare, bulge, twist, bend, scale: applied to a part, in order
+ *   materials      plastic, matte, ceramic, glass, metal, chrome, in any colour
+ *   text           wraps one round part: printed straight onto it, or on a paper label
+ *   recipes        tumbler, mug, can, bottle: compositions of the above, nothing they alone can do
+ *
+ * An object is JSON (`TSObjectSpec`) and lives in the config as `object`, so what an agent builds
+ * is a preset it can save and edit later. `describeConstruction()` is the machine-readable
+ * manifest: every primitive, what can be done to it, and every parameter with its range, so an
+ * agent composes a tumbler (cylinder + taper + ring) without one having been written for it.
+ * `sanitizeObject` reads the same manifest: it never throws and always returns something drawable.
+ *
+ * Frame: y is up and is the object's axis; x is to the right of the camera, z toward it. Units are
+ * the lab's world units (the wine bottle's body is 0.36 in radius); the camera frames whatever is
+ * built. Pure; no DOM, no React.
+ */
+import { type Vec3 } from './ops';
+export type TSParam = {
+    type: 'number';
+    min: number;
+    max: number;
+    default: number;
+    unit?: string;
+    hint: string;
+} | {
+    type: 'boolean';
+    default: boolean;
+    hint: string;
+} | {
+    type: 'enum';
+    options: readonly string[];
+    default: string;
+    hint: string;
+}
+/** A list of points: `dims` numbers each, at least `min` of them. */
+ | {
+    type: 'points';
+    dims: 2 | 3;
+    min: number;
+    max: number;
+    hint: string;
+};
+export declare const TS_MANIPULATOR_IDS: readonly ["taper", "flare", "bulge", "twist", "bend", "scale"];
+export type TSManipulatorId = (typeof TS_MANIPULATOR_IDS)[number];
+/** What can be done to a part. Each acts in the part's own frame, before it is turned and placed. */
+export declare const TS_MANIPULATORS: Record<TSManipulatorId, {
+    summary: string;
+    keepsRound: boolean;
+    params: Record<string, TSParam>;
+}>;
+export declare const TS_PRIMITIVE_IDS: readonly ["cylinder", "sphere", "ring", "revolve", "tube", "box"];
+export type TSPrimitiveId = (typeof TS_PRIMITIVE_IDS)[number];
+/** A manipulator a primitive accepts, plus `material` (every part) and `text-wrap` (it can carry the text). */
+export type TSCapability = TSManipulatorId | 'material' | 'text-wrap';
+/** What an object is built from. `origin` says where `at` puts the part. */
+export declare const TS_PRIMITIVES: Record<TSPrimitiveId, {
+    summary: string;
+    origin: 'base' | 'centre' | 'path';
+    capabilities: readonly TSCapability[];
+    params: Record<string, TSParam>;
+}>;
+export declare const TS_OBJECT_MATERIAL_IDS: readonly ["plastic", "matte", "ceramic", "glass", "metal", "chrome"];
+export type TSObjectMaterialId = (typeof TS_OBJECT_MATERIAL_IDS)[number];
+/** How a part shades. `metalness` tints the reflection with the colour; `reflection` is how much of the studio it shows. */
+export declare const TS_OBJECT_MATERIALS: Record<TSObjectMaterialId, {
+    summary: string;
+    metalness: number;
+    roughness: number;
+    reflection: number;
+    gain: number;
+}>;
+export declare const TS_OBJECT_TABLES: readonly ["studio", "desk", "wood"];
+export type TSOp = {
+    op: TSManipulatorId;
+} & Record<string, number | string>;
+export type TSPartMaterial = {
+    type: TSObjectMaterialId;
+    color: string;
+    /** Override the material's own roughness / metalness, 0–1. */
+    roughness?: number;
+    metalness?: number;
+};
+export type TSPart = {
+    /** Unique within the object; `text.on` names one. */
+    id: string;
+    shape: TSPrimitiveId;
+    /** The primitive's parameters (`TS_PRIMITIVES[shape].params`); anything omitted takes its default. */
+    params: Record<string, unknown>;
+    /** Manipulators, applied in order. */
+    ops: TSOp[];
+    material: TSPartMaterial;
+    /** Where the part goes, in the object's frame. */
+    at: [number, number, number];
+    /** Degrees about x, then y, then z. */
+    rotate: [number, number, number];
+};
+export type TSObjectText = {
+    /** The part the text wraps. It must be round, on the axis and unturned. */
+    on: string;
+    /** Centre of the text area along the part's height, 0 bottom – 1 top. */
+    y: number;
+    /** Height of the text area, as a share of the part's height. */
+    height: number;
+    /** How far round the part the text area reaches, degrees (360 goes all the way). */
+    arc: number;
+    /** A paper label in this colour; null prints straight onto the part. */
+    label: string | null;
+};
+export type TSObjectSpec = {
+    name: string;
+    parts: TSPart[];
+    text: TSObjectText;
+    scene: {
+        table: (typeof TS_OBJECT_TABLES)[number];
+        backdrop: [string, string];
+    };
+};
+export declare const TS_OBJECT_TEXT_PARAMS: Record<'y' | 'height' | 'arc', TSParam>;
+export declare const MAX_OBJECT_PARTS = 24;
+/** How much of a round part's circumference reads from the front, degrees: text wider than this runs out of sight. */
+export declare const OBJECT_FRONT_ARC = 110;
+export type TSObjectError = {
+    path: string;
+    message: string;
+};
+/**
+ * A spec that always builds: every bad field is replaced (numbers are clamped, the rest take their
+ * default, parts and manipulators that make no sense are dropped) and named in `errors`. Returns
+ * `object: null` only when nothing in it can be drawn.
+ */
+export declare function sanitizeObject(input: unknown, base?: string): {
+    object: TSObjectSpec | null;
+    errors: TSObjectError[];
+};
+/** `[]` when the spec is drawable as written; otherwise every problem as `{ path, message }`. Never throws. */
+export declare function validateObject(spec: unknown, base?: string): TSObjectError[];
+export type ResolvedMaterial = {
+    color: string;
+    metalness: number;
+    roughness: number;
+    reflection: number;
+    gain: number;
+};
+/** One part's triangles in the object's index buffer, and how they shade. */
+export type PartRange = {
+    id: string;
+    start: number;
+    count: number;
+    material: ResolvedMaterial;
+};
+export type BuiltObject = {
+    positions: Float32Array;
+    normals: Float32Array;
+    indices: Uint32Array;
+    count: number;
+    ranges: PartRange[];
+    bounds: {
+        min: Vec3;
+        max: Vec3;
+    };
+    /** The part that carries the text: its extent along y and its outer radius at any height. */
+    host: {
+        id: string;
+        y0: number;
+        y1: number;
+        radiusAt: (y: number) => number;
+        color: string;
+    };
+};
+export declare function resolveMaterial(m: TSPartMaterial): ResolvedMaterial;
+/**
+ * Build a spec into one mesh in the object's frame: every part through its manipulators, turned and
+ * placed, with smooth normals and a triangle range per part. The spec is repaired first (omitted
+ * parameters take their defaults); it throws only when nothing in it can be drawn.
+ */
+export declare function buildObject(input: TSObjectSpec): BuiltObject;
+export type TSRecipeOptions = {
+    color?: string;
+    material?: TSObjectMaterialId;
+    accent?: string;
+    label?: string | null;
+};
+/**
+ * Semantic starting points. A recipe is only a composition of the primitives and manipulators above,
+ * returned as a plain spec to edit: nothing here is special-cased anywhere else, so an object with
+ * no recipe is built the same way, part by part.
+ */
+export declare const TS_RECIPES: Record<string, {
+    summary: string;
+    composition: string;
+    build: (o?: TSRecipeOptions) => TSObjectSpec;
+}>;
+/** A recipe's spec, ready to edit; unknown names fall back to a plain cylinder so something always draws. */
+export declare function createObject(recipe: string, options?: TSRecipeOptions): TSObjectSpec;
+/**
+ * Everything an agent needs to compose an object, as JSON: the primitives and what each can take,
+ * the manipulators, the materials, how text attaches, the recipes and what cannot be done.
+ */
+export declare function describeConstruction(): {
+    frame: string;
+    part: {
+        shape: string;
+        origin: {
+            base: string;
+            centre: string;
+            path: string;
+        };
+    };
+    primitives: Record<"box" | "ring" | "tube" | "cylinder" | "sphere" | "revolve", {
+        summary: string;
+        origin: "base" | "centre" | "path";
+        capabilities: readonly TSCapability[];
+        params: Record<string, TSParam>;
+    }>;
+    manipulators: Record<"scale" | "taper" | "flare" | "bulge" | "twist" | "bend", {
+        summary: string;
+        keepsRound: boolean;
+        params: Record<string, TSParam>;
+    }>;
+    materials: Record<"glass" | "plastic" | "matte" | "ceramic" | "metal" | "chrome", {
+        summary: string;
+        metalness: number;
+        roughness: number;
+        reflection: number;
+        gain: number;
+    }>;
+    text: {
+        summary: string;
+        params: Record<"y" | "height" | "arc", TSParam>;
+        label: string;
+        carriers: ("box" | "ring" | "tube" | "cylinder" | "sphere" | "revolve")[];
+        sizing: {
+            unit: string;
+            frontArc: number;
+            rule: string;
+            helper: string;
+        };
+        rules: string[];
+    };
+    scene: {
+        table: readonly ["studio", "desk", "wood"];
+        backdrop: string;
+    };
+    view: {
+        summary: string;
+        states: {
+            wrapped: string;
+            lying: string;
+            turned: string;
+            tipped: string;
+        };
+        apply: string;
+        controls: {
+            'deformation.tiltX': string;
+            'deformation.tiltY': string;
+            'view.roll': string;
+            'view.zoom': string;
+        };
+        avoid: string;
+    };
+    recipes: {
+        [k: string]: {
+            summary: string;
+            composition: string;
+            defaults: {
+                color: string;
+                material: "glass" | "plastic" | "matte" | "ceramic" | "metal" | "chrome";
+                label: null;
+            };
+            options: {
+                color: string;
+                material: string;
+                accent: string;
+                label: string;
+            };
+            use: string;
+        };
+    };
+    limits: string[];
+};
+//# sourceMappingURL=construct.d.ts.map

package/dist/esm/motion/typesurface/construct.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"construct.d.ts","sourceRoot":"","sources":["../../../../src/motion/typesurface/construct.ts"],"names":[],"mappings":"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"}