@compilr-dev/sdk 0.29.8 → 0.31.0

package/dist/canvas/scene.d.ts

@@ -0,0 +1,277 @@
+/**
+ * 3D scene contract — the `scene` canvas type (3d-canvas-spec §2).
+ *
+ * A scene is VALIDATED JSON DATA, never code: a list of primitives in metres. Agents write
+ * it through the scene tools; the host draws it (three.js in Desktop's renderer). This module
+ * is the contract both sides bind to — types, limits, validation, normalisation and the few
+ * pieces of geometry (lift, bounds, fit) that must be ONE function everywhere.
+ *
+ * ⚠️ Renderer-safe on purpose: no imports at all. Desktop's renderer imports this through
+ * `@compilr-dev/sdk/canvas`; one node import here breaks its bundle (see
+ * `tests/canvas-subpath.test.ts`).
+ */
+export declare const SCENE_VERSION = 1;
+export type Vec3 = [number, number, number];
+export type Vec2 = [number, number];
+export type SceneObjectType = 'box' | 'sphere' | 'cylinder' | 'cone' | 'torus' | 'extrude' | 'wedge' | 'group';
+export declare const SCENE_OBJECT_TYPES: readonly SceneObjectType[];
+/** The direction an extrude extends along (§17). */
+export type ExtrudeAxis = 'x' | 'y' | 'z';
+export declare const SCENE_EXTRUDE_AXES: readonly ExtrudeAxis[];
+export interface SceneMaterial {
+    /** 0..1, default 0.78 */
+    roughness?: number;
+    /** 0..1, default 0.02 */
+    metalness?: number;
+    /** 0.05..1, default 1 (transparent when < 1) */
+    opacity?: number;
+}
+export interface SceneObjectBase {
+    /** Unique in the scene; /^[a-z0-9][a-z0-9_-]{0,47}$/ */
+    id: string;
+    /** Display name, ≤ 80 chars; the UI title-cases the id when absent. */
+    name?: string;
+    type: SceneObjectType;
+    /** Metres. y is the BOTTOM of the object: y = 0 sits on the floor (in the parent's frame). */
+    position: Vec3;
+    /** Degrees, Euler XYZ (three.js default order). Default [0, 0, 0]. */
+    rotation?: Vec3;
+    /** '#RRGGBB'. Filled by the writer from the neutral palette when absent. */
+    color?: string;
+    /**
+     * Parent object id — position/rotation are relative to the parent's frame. A `group` is the
+     * intended container, but ANY object may be a parent (P1 scenes parent to shapes; kept for
+     * backward compatibility). No cycles, depth ≤ SCENE_MAX_GROUP_DEPTH.
+     */
+    group?: string;
+    material?: SceneMaterial;
+    /** User-only lock: the inspector cannot move/remove it; agents still can (and are warned). */
+    locked?: boolean;
+}
+export interface BoxObject extends SceneObjectBase {
+    type: 'box';
+    /** w, h, d */
+    size: Vec3;
+}
+export interface SphereObject extends SceneObjectBase {
+    type: 'sphere';
+    radius: number;
+}
+/**
+ * `segments` (integer 3–64, optional): a faceted prism instead of a smooth round one. Omitted =
+ * smooth. Vertex k sits at angle θ = 2πk/segments with x = radius·sin θ, z = radius·cos θ
+ * (three.js CylinderGeometry/ConeGeometry, thetaStart 0) — so vertex 0 is on +z, and `radius`
+ * is the CIRCUMradius. A 4-segment cone is a pyramid with corners on the ±x/±z axes (rotate 45°
+ * about Y for sides parallel to the axes; its base side is radius·√2).
+ */
+export interface CylinderObject extends SceneObjectBase {
+    type: 'cylinder';
+    radius: number;
+    height: number;
+    segments?: number;
+}
+export interface ConeObject extends SceneObjectBase {
+    type: 'cone';
+    radius: number;
+    height: number;
+    segments?: number;
+}
+/** Lies flat (ring in the x–z plane). radius = ring radius, tube = tube radius. */
+export interface TorusObject extends SceneObjectBase {
+    type: 'torus';
+    radius: number;
+    tube: number;
+}
+/**
+ * An outline extruded by `height` along `axis` (default 'y'). Points are local to `position`;
+ * which world axes a point [a, b] maps to depends on the axis:
+ *
+ * | axis | point [a, b] is | the outline lies in | extends along  |
+ * |------|-----------------|---------------------|----------------|
+ * | 'y'  | [x, z] (plan)   | the floor (x–z)     | +y, 0 → height |
+ * | 'z'  | [x, y] (side)   | the x–y plane       | +z, 0 → height |
+ * | 'x'  | [z, y] (side)   | the z–y plane       | +x, 0 → height |
+ *
+ * For 'x'/'z' the SECOND coordinate is up (y) and the first is the horizontal one — a side
+ * profile (a gable, a roof section) pushed sideways. y-bottom rule: the mesh is lifted by
+ * −min(b) for 'x'/'z' (0 for 'y'), so the lowest point of the outline sits at `position.y`.
+ * The rotation pivot is the outline's [0, 0] at the start of the extrusion (lifted likewise).
+ */
+export interface ExtrudeObject extends SceneObjectBase {
+    type: 'extrude';
+    points: Vec2[];
+    height: number;
+    axis?: ExtrudeAxis;
+}
+/**
+ * A triangular prism (roofs): `size` [w, h, d]. The triangle is in the x–y plane and the ridge
+ * runs along z. Mesh-local (centred like a box, lift h/2): base corners (−w/2, −h/2) and
+ * (w/2, −h/2), apex (−w/2 + ridge·w, h/2); the prism spans z ∈ [−d/2, d/2]. `ridge` 0–1,
+ * default 0.5 (centred apex; 0 or 1 = a lean-to with a vertical side).
+ */
+export interface WedgeObject extends SceneObjectBase {
+    type: 'wedge';
+    size: Vec3;
+    ridge?: number;
+}
+/**
+ * A transform node — no geometry, no size, no colour/material (rejected: colour its children).
+ * Children (`group: "<this id>"`) are positioned in its frame: its `position` is their origin
+ * (a group has no height, so its lift is 0 and child y = 0 is the group's y) and its rotation
+ * pivots there. Its bounds are the union of its descendants' (none while it is empty).
+ */
+export interface GroupObject extends SceneObjectBase {
+    type: 'group';
+    color?: never;
+    material?: never;
+}
+export type SceneObject = BoxObject | SphereObject | CylinderObject | ConeObject | TorusObject | ExtrudeObject | WedgeObject | GroupObject;
+export interface SceneCamera {
+    position: Vec3;
+    target: Vec3;
+}
+export type SceneLight = {
+    type: 'sun';
+    position: Vec3;
+    intensity?: number;
+    castShadow?: boolean;
+} | {
+    type: 'ambient';
+    intensity?: number;
+};
+export interface SceneFile {
+    version: 1;
+    name: string;
+    /** Only metres in v1. */
+    units: 'm';
+    /** Missing → the viewer fits the camera to the objects. */
+    camera?: SceneCamera;
+    /** Missing → the default studio light. */
+    lights?: SceneLight[];
+    objects: SceneObject[];
+}
+export interface SceneBounds {
+    min: Vec3;
+    max: Vec3;
+}
+export declare const SCENE_MAX_OBJECTS = 500;
+export declare const SCENE_MAX_BYTES: number;
+/** Max objects in one scene_add_object batch (Q-1). */
+export declare const SCENE_MAX_BATCH = 50;
+export declare const SCENE_MAX_COORD = 1000;
+export declare const SCENE_SIZE_MIN = 0.01;
+export declare const SCENE_SIZE_MAX = 500;
+export declare const SCENE_RADIUS_MIN = 0.01;
+export declare const SCENE_RADIUS_MAX = 250;
+export declare const SCENE_TUBE_MIN = 0.005;
+/** `segments` on cone/cylinder: integer range (§17). */
+export declare const SCENE_SEGMENTS_MIN = 3;
+export declare const SCENE_SEGMENTS_MAX = 64;
+/** wedge `ridge` default: apex centred across the width. */
+export declare const SCENE_WEDGE_RIDGE_DEFAULT = 0.5;
+export declare const SCENE_POINTS_MIN = 3;
+export declare const SCENE_POINTS_MAX = 256;
+export declare const SCENE_MAX_LIGHTS = 4;
+export declare const SCENE_MAX_SHADOW_LIGHTS = 2;
+export declare const SCENE_LIGHT_INTENSITY_MAX = 10;
+export declare const SCENE_MAX_GROUP_DEPTH = 8;
+export declare const SCENE_NAME_MAX = 80;
+export declare const SCENE_OPACITY_MIN = 0.05;
+export declare const SCENE_ID_PATTERN: RegExp;
+/** Object colours never read as state (README) — a neutral palette, filled by insertion index. */
+export declare const SCENE_NEUTRAL_PALETTE: readonly string[];
+/** Accessible names for the palette swatches, same order (Q-10). */
+export declare const SCENE_PALETTE_NAMES: readonly string[];
+export declare const SCENE_DEFAULT_MATERIAL: Readonly<Required<SceneMaterial>>;
+/** The reference camera, used for an empty scene. */
+export declare const SCENE_DEFAULT_CAMERA: Readonly<SceneCamera>;
+/** Vertical field of view of the viewer camera, degrees. */
+export declare const SCENE_CAMERA_FOV = 38;
+/** A new, empty scene. */
+export declare function emptyScene(name: string): SceneFile;
+/**
+ * Defaults for a freshly added shape of each type (the reference's fallbacks), for the
+ * inspector's "Add a shape" menu. Position is the origin.
+ */
+export declare function defaultObjectFor(type: SceneObjectType, id: string): SceneObject;
+/** The stored form: pretty-printed, because agents read and cite it (§4.1). */
+export declare function serializeScene(scene: SceneFile): string;
+/** `slug(title).scene.json` — the display file name and the JSON export's default name. */
+export declare function sceneFileName(title: string): string;
+/** UTF-8 byte length without TextEncoder (keeps this module free of DOM/node typings). */
+export declare function utf8Bytes(s: string): number;
+export type SceneValidationResult = {
+    ok: true;
+    scene: SceneFile;
+} | {
+    ok: false;
+    errors: string[];
+};
+/** Short, stable number rendering for messages and summaries. */
+export declare function fmtNum(n: number): string;
+export declare function fmtVec(v: readonly number[]): string;
+/** Drop a closing duplicate of the first point (§2.3: dropped, not rejected). */
+export declare function openOutline(points: Vec2[]): Vec2[];
+/**
+ * Is the (open) outline a simple polygon? O(n²) segment test — ExtrudeGeometry's
+ * triangulation silently breaks on self-intersection. Returns the first offending edge pair.
+ */
+export declare function findSelfIntersection(points: Vec2[]): [number, number] | null;
+/**
+ * Validate an untrusted scene (agent JSON, a stored row, an import). Every error names the
+ * field path and what is allowed. On success the returned scene is a deep copy of the input
+ * (not yet normalised — see `normalizeScene`).
+ */
+export declare function validateScene(input: unknown): SceneValidationResult;
+/** '#abc' / '#aabbcc' → '#AABBCC'. Assumes a valid hex (validated first). */
+export declare function normalizeColor(hex: string): string;
+/** Degrees → (−180, 180]. */
+export declare function normalizeAngle(deg: number): number;
+/**
+ * Fill what the writer owns: upper-case #RRGGBB colours, the neutral default colour by
+ * insertion index (so the stored file is explicit and agent-readable), rotations wrapped to
+ * (−180, 180], closing duplicate points dropped. Never fills camera/lights — their absence
+ * means "fit" / "studio light". Pure; returns a new scene.
+ */
+export declare function normalizeScene(scene: SceneFile): SceneFile;
+/**
+ * Half-height from the object's BOTTOM (its `position.y`) to its geometric centre, where the
+ * mesh sits. extrude along y is 0: its geometry already starts at the floor; along x/z it is
+ * −min(profile y), so the profile's lowest point sits at position.y. A group has no height: 0.
+ * ONE function — the viewer, the fit and the GLB export must agree.
+ */
+export declare function liftFor(obj: SceneObject): number;
+/**
+ * World matrix of each object's mesh (row-major 4×4), keyed by id, with group parenting
+ * applied. A `group` has no mesh and lift 0, so its entry is its frame: T(position) · R,
+ * rotating about its position. Assumes a validated scene (no cycles).
+ */
+export declare function sceneWorldMatrices(scene: SceneFile): Map<string, number[]>;
+/**
+ * World-space AABB of all objects (conservative for rotated shapes). null when nothing has
+ * geometry — an empty scene, or one holding only empty groups (the camera then uses the
+ * reference default, as for an empty scene).
+ */
+export declare function sceneBounds(scene: SceneFile): SceneBounds | null;
+/**
+ * World AABB of one object and everything grouped under it — for a `group`, the union of its
+ * descendants (null while it holds no geometry); for a shape, its own mesh plus any children.
+ * null for an unknown id. (The viewer outlines a selected group's whole subtree with this.)
+ */
+export declare function sceneObjectBounds(scene: SceneFile, id: string): SceneBounds | null;
+/** The reference view direction ([7, 5.5, 8], normalised). */
+export declare const SCENE_CAMERA_DIRECTION: Readonly<Vec3>;
+/**
+ * The camera used when a scene has none: look at the bounds' centre from the reference
+ * direction, at the distance that fits the bounding sphere in the vertical FOV, × 1.2.
+ * null bounds (empty scene) → the reference default.
+ */
+export declare function fitCamera(bounds: SceneBounds | null, fovDeg?: number): SceneCamera;
+/** The camera to view a scene with: its own, or the fit. */
+export declare function sceneCamera(scene: SceneFile): SceneCamera;
+/** One line: "12 objects (2 groups), bounds 6.2 × 4 × 2.7 m" (W × D × H). */
+export declare function describeScene(scene: SceneFile): string;
+/** The ids of an object's descendants (children, grandchildren, …), in scene order. */
+export declare function descendantsOf(scene: SceneFile, id: string): string[];
+/** Turn a display name (or type) into an id candidate: lowercase slug, ≤ 48 chars. */
+export declare function slugifySceneId(text: string): string;