@compilr-dev/sdk 0.29.7 → 0.30.0

package/dist/canvas/scene.d.ts

@@ -0,0 +1,207 @@
+/**
+ * 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';
+export declare const SCENE_OBJECT_TYPES: readonly SceneObjectType[];
+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. */
+    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;
+}
+export interface CylinderObject extends SceneObjectBase {
+    type: 'cylinder';
+    radius: number;
+    height: number;
+}
+export interface ConeObject extends SceneObjectBase {
+    type: 'cone';
+    radius: number;
+    height: 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 in plan (x, z), local to position, extruded upward by `height`. Walls and floors. */
+export interface ExtrudeObject extends SceneObjectBase {
+    type: 'extrude';
+    points: Vec2[];
+    height: number;
+}
+export type SceneObject = BoxObject | SphereObject | CylinderObject | ConeObject | TorusObject | ExtrudeObject;
+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;
+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 is 0: its geometry already starts at the floor. 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. 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 empty. */
+export declare function sceneBounds(scene: SceneFile): 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, 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;