@felbrasil/dreamy 0.0.0-stage → 0.1.0

package/dist/types/viewport/src/decals/decal-limits.d.ts

@@ -0,0 +1,11 @@
+/** Decal budgets and atlas layout (the POC's decals.js). */
+export declare const MAX_DECALS = 64;
+export declare const MAX_INTERIORS = 8;
+/** Texels per decal: 3 matrix rows, atlas params, tint, extra (kind, room, depth, seed). */
+export declare const DECAL_TEX_W = 6;
+/** 1024 × 2048 atlas: the first cells hold the built-in art, the rest the creation's designs. */
+export declare const DECAL_COLS = 8;
+export declare const DECAL_ROWS = 16;
+export declare const DECAL_CELL = 128;
+/** Half-thickness of the projection box, in decal sizes. */
+export declare const DECAL_DEPTH = 0.35;

package/dist/types/viewport/src/decals/decal-uniforms.d.ts

@@ -0,0 +1,40 @@
+import type { Decal } from "../../../api/src/index.js";
+import { DataTexture, Vector3, type Texture } from "three";
+/** What the shader needs about a decal's art: its atlas cell (or an interior room) and whether it tints. */
+export type DecalArtInfo = {
+    readonly cell: number;
+    readonly tintable: boolean;
+    /** Interior room id (ray-traced, no atlas cell). */
+    readonly room?: number;
+    /** The art is gone (a deleted design): drawn fully transparent. */
+    readonly missing?: boolean;
+};
+export type DecalUniforms = {
+    readonly uDecalData: {
+        value: DataTexture;
+    };
+    readonly uDecalCount: {
+        value: number;
+    };
+    readonly uDecalAtlas: {
+        value: Texture | null;
+    };
+    readonly uDecalBounds: {
+        value: Float32Array;
+    };
+    /** Camera in the sculpt's bind space (interior rays). */
+    readonly uLocalCam: {
+        value: Vector3;
+    };
+    interiors: number;
+};
+export declare function createDecalUniforms(atlas: Texture | null): DecalUniforms;
+/**
+ * Packs decals into the shader's layout (rows 0–2: bind space → decal space, x / y in [−0.5, 0.5], z along the
+ * normal; then atlas cell + flip + tintable, tint rgb + opacity, interior kind / room / depth / seed) and a
+ * bounding sphere per decal. Returns the count drawn and how many are interiors.
+ */
+export declare function packDecals(decals: readonly Decal[], art: (d: Decal) => DecalArtInfo, tint: (d: Decal, info: DecalArtInfo) => readonly [number, number, number], data: Float32Array, bounds: Float32Array): {
+    count: number;
+    interiors: number;
+};

package/dist/types/viewport/src/decals/design-raster.d.ts

@@ -0,0 +1,8 @@
+import type { ColorRef, DesignPaint, DesignShape } from "../../../api/src/index.js";
+/** Art is clipped this far from the cell border: the atlas has no gutters and samples linearly. */
+export declare const DESIGN_INSET = 3;
+/** CSS for a design paint; palette refs it used go into `slots` (palette edits re-raster only those). */
+export declare function paintCss(p: DesignPaint, css: (ref: ColorRef) => string, slots: Set<ColorRef>): string | null;
+export declare function drawDesignShape(g: CanvasRenderingContext2D, sh: DesignShape, css: (ref: ColorRef) => string, slots: Set<ColorRef>, index: number): void;
+/** Paints a whole design (128 × 128 space) into a cell-sized context. */
+export declare function paintDesign(g: CanvasRenderingContext2D, shapes: readonly DesignShape[], css: (ref: ColorRef) => string, slots: Set<ColorRef>): void;

package/dist/types/viewport/src/decals/interior-thumbs.d.ts

@@ -0,0 +1,6 @@
+import type { BuiltinArt } from "./builtin-art.js";
+/**
+ * Renders each interior room once through the real shader code (a throwaway context) so the picker shows the
+ * real art; a plain swatch when WebGL is unavailable.
+ */
+export declare function renderInteriorThumbs(rooms: readonly BuiltinArt[]): Map<BuiltinArt, HTMLCanvasElement>;

package/dist/types/viewport/src/index.d.ts

@@ -0,0 +1 @@
+export { createViewport, type ViewportOptions } from "./create-viewport.js";

package/dist/types/viewport/src/interaction/bone-tool.d.ts

@@ -0,0 +1,13 @@
+import { RigView } from "../objects/rig-view.js";
+import { type InteractionContext } from "./interaction-context.js";
+/** Rig bones tool (the POC's rig.js): a click picks a bone of the selected rig, or adds one with the Add tool. */
+export declare class BoneTool {
+    private readonly ctx;
+    constructor(ctx: InteractionContext);
+    private selectedRig;
+    /** Screen positions of a rig's joints (as drawn). */
+    static jointsOnScreen(ctx: InteractionContext, view: RigView): (import("../math/screen.js").ScreenPoint | null)[];
+    click(): void;
+    private add;
+    private addBoneAt;
+}

package/dist/types/viewport/src/interaction/bones-visible.d.ts

@@ -0,0 +1,7 @@
+import type { RigObject } from "../../../api/src/index.js";
+import type { InteractionContext } from "./interaction-context.js";
+/**
+ * When a rig shows its bones (the POC's rigBonesVisible): always with the bone tool on the selected rig, and while
+ * one of its parts is sculpted; otherwise when bones are shown and the rig is selected or has no body to see.
+ */
+export declare function bonesVisible(ctx: InteractionContext, o: RigObject): boolean;

package/dist/types/viewport/src/interaction/cursor.d.ts

@@ -0,0 +1,3 @@
+import type { ViewSession } from "../../../api/src/index.js";
+/** The canvas cursor for the current tool (the POC's tools-ui.js updateCursor), as a CSS cursor value. */
+export declare function cursorFor(s: ViewSession, shift: boolean, ctrl: boolean): string;

package/dist/types/viewport/src/interaction/decal-tool.d.ts

@@ -0,0 +1,18 @@
+import type { DecalAtlas } from "../decals/decal-atlas.js";
+import { type InteractionContext } from "./interaction-context.js";
+/** Decal tool (the POC's decals.js placement): ghost on the surface, click places (or erases), Q places too. */
+export declare class DecalTool {
+    private readonly ctx;
+    private readonly atlas;
+    private readonly ghost;
+    private tex;
+    constructor(ctx: InteractionContext, atlas: () => DecalAtlas);
+    private hit;
+    /** Object-local pose: z = surface normal, y = world up (eyes stay upright), then the brush roll. */
+    private placement;
+    hover(): void;
+    hide(): void;
+    /** A click (or Q): place the brush's decal, or erase the nearest one. */
+    place(): void;
+    dispose(): void;
+}

package/dist/types/viewport/src/interaction/esc-hold.d.ts

@@ -0,0 +1,13 @@
+/** Holding Esc this long in sculpt mode leaves it (a tap is the module's: Select tool). */
+export declare const ESC_HOLD_MS = 1000;
+/** Esc tap / hold in sculpt mode, with a small progress bar over the view (the POC's #esc-hint). */
+export declare class EscHold {
+    private readonly exit;
+    private hold;
+    private readonly bar;
+    private readonly fill;
+    constructor(host: HTMLElement, exit: () => void);
+    start(): void;
+    end(): void;
+    dispose(): void;
+}

package/dist/types/viewport/src/interaction/ghost-geometry.d.ts

@@ -0,0 +1,6 @@
+import type { StampShape } from "../../../api/src/index.js";
+import { BufferGeometry } from "three";
+/** Ghost preview geometry per shape, modelled at 1.8 units (the POC's getGeometryForType); scale = size / 1.8. */
+export declare function ghostGeometry(shape: StampShape): BufferGeometry;
+/** Minimal line set per shape in the stamp's unit space (matches the SDF sizes): the selected shape's wireframe. */
+export declare function stampWireGeometry(shape: StampShape): BufferGeometry;

package/dist/types/viewport/src/interaction/gizmo.d.ts

@@ -0,0 +1,34 @@
+import { TransformControls } from "three/examples/jsm/controls/TransformControls.js";
+import { type InteractionContext } from "./interaction-context.js";
+/**
+ * Transform gizmo (three's TransformControls on a proxy): objects in assembly mode (one, or several about their
+ * center), the scoped sculpt's selected stamps, the kaleidoscope pivot, or the selected bone. A drag previews live
+ * and becomes one command on release.
+ */
+export declare class Gizmo {
+    private readonly ctx;
+    readonly controls: TransformControls;
+    private readonly proxy;
+    private target;
+    private drag;
+    private previewDirty;
+    /** Called when a drag starts / ends (orbit is off while dragging). */
+    onDragging: (on: boolean) => void;
+    constructor(ctx: InteractionContext);
+    get dragging(): boolean;
+    /** The pointer is over a handle (a press there must not pick or stamp). */
+    get hovering(): boolean;
+    private wanted;
+    /** Every frame: attach to what the session asks for and keep the proxy on it (not while dragging). */
+    sync(): void;
+    private setProxy;
+    private place;
+    private begin;
+    /** Delta of the proxy since the drag started, applied to every dragged thing (as a preview). */
+    private preview;
+    private stampPlacements;
+    private pivotOf;
+    private boneTransform;
+    private end;
+    dispose(): void;
+}

package/dist/types/viewport/src/interaction/interaction-context.d.ts

@@ -0,0 +1,41 @@
+import type { Command, Creation, DispatchResult, SceneObject, SculptTarget, Selection, ViewSession, ViewportCallbacks } from "../../../api/src/index.js";
+import { Raycaster, Vector2 } from "three";
+import type { SceneViews } from "../objects/scene-views.js";
+import type { Stage } from "../scene/stage.js";
+/** Pointer state in canvas pixels and normalized device coordinates. */
+export type PointerState = {
+    x: number;
+    y: number;
+    readonly ndc: Vector2;
+    down: boolean;
+    shift: boolean;
+    ctrl: boolean;
+};
+/** What every tool reads and how it reports back. Owned by one viewport instance. */
+export type InteractionContext = {
+    readonly stage: Stage;
+    readonly views: SceneViews;
+    readonly pointer: PointerState;
+    readonly raycaster: Raycaster;
+    readonly keys: Set<string>;
+    creation(): Creation;
+    session(): ViewSession;
+    callbacks(): ViewportCallbacks | null;
+    /** Sends a command; a rejection becomes a toast. */
+    dispatch(command: Command): DispatchResult;
+    select(selection: Selection): void;
+    toast(message: string): void;
+    /** True while play mode or the stress test owns the view. */
+    locked(): boolean;
+};
+export declare const objectById: (c: Creation, id: string) => SceneObject | undefined;
+/** The scoped sculpt in sculpt mode, if any. */
+export declare function scopeOf(ctx: InteractionContext): SculptTarget | undefined;
+export declare function createPointer(): PointerState;
+/** Updates the pointer from a DOM event relative to the canvas. */
+export declare function readPointer(p: PointerState, e: PointerEvent | MouseEvent, canvas: HTMLCanvasElement): void;
+export declare const viewSize: (ctx: InteractionContext) => {
+    w: number;
+    h: number;
+};
+export declare const emptySelection: Selection;

package/dist/types/viewport/src/interaction/marquee.d.ts

@@ -0,0 +1,8 @@
+/** The area-selection rectangle, a DOM overlay over the canvas (the POC's #marquee). */
+export declare class MarqueeOverlay {
+    private readonly el;
+    constructor(host: HTMLElement);
+    show(x1: number, y1: number, x2: number, y2: number): void;
+    hide(): void;
+    dispose(): void;
+}

package/dist/types/viewport/src/interaction/pivot-helper.d.ts

@@ -0,0 +1,13 @@
+import { type InteractionContext } from "./interaction-context.js";
+/**
+ * The kaleidoscope pivot marker (3 axis lines + a ball) of the scoped standalone sculpt, at a constant screen size;
+ * bright while the pivot tool is on or any shape uses symmetry, dim otherwise.
+ */
+export declare class PivotHelper {
+    private readonly ctx;
+    private readonly root;
+    private readonly mats;
+    constructor(ctx: InteractionContext);
+    update(): void;
+    dispose(): void;
+}

package/dist/types/viewport/src/interaction/select-tool.d.ts

@@ -0,0 +1,30 @@
+import type { Id, Sculpt } from "../../../api/src/index.js";
+import { Vector3 } from "three";
+import { type InteractionContext } from "./interaction-context.js";
+import type { MarqueeOverlay } from "./marquee.js";
+/** A stamp of a locked smear group stands for the whole group. */
+export declare function stampMembers(sculpt: Sculpt, stampId: Id): Id[];
+/**
+ * Selection gestures (the POC's selection.js / multi-select.js): a click picks one thing, Ctrl / Cmd toggles it,
+ * Shift + drag draws an area that selects everything it touches, a double-click frames an object. Assembly mode
+ * picks objects (bone dots first; a part picks its rig), sculpt mode the scoped sculpt's shapes.
+ */
+export declare class SelectTool {
+    private readonly ctx;
+    private readonly marquee;
+    private press;
+    constructor(ctx: InteractionContext, marquee: MarqueeOverlay);
+    get dragging(): boolean;
+    down(): void;
+    move(): void;
+    up(): void;
+    /** Esc while dragging an area cancels it. */
+    cancel(): boolean;
+    /** Picks what is under the cursor; a miss changes nothing (finishing an orbit never drops the selection). */
+    pick(additive: boolean): void;
+    /** The rig or sculpt object under the cursor (bone dots win: they are drawn on top). */
+    objectUnderCursor(): Id | undefined;
+    private finishArea;
+    /** Double-click in assembly mode: an object is framed and its Properties open; empty space deselects. */
+    doubleClick(focus: (center: Vector3) => void): void;
+}

package/dist/types/viewport/src/interaction/selection-boxes.d.ts

@@ -0,0 +1,11 @@
+import { type Group } from "three";
+import type { InteractionContext } from "./interaction-context.js";
+/** Assembly-mode outlines: the primary (last) selected object in sky blue, the others lighter. */
+export declare class SelectionBoxes {
+    private readonly ctx;
+    private readonly ui;
+    private readonly helpers;
+    constructor(ctx: InteractionContext, ui: Group);
+    update(): void;
+    dispose(): void;
+}

package/dist/types/viewport/src/interaction/stamp-tool.d.ts

@@ -0,0 +1,41 @@
+import type { Sculpt, SculptTarget } from "../../../api/src/index.js";
+import { type InteractionContext } from "./interaction-context.js";
+/**
+ * Stamp tool (the POC's stamping in input.js + ghost in scene.js + ghost copies in symmetry.js). Assembly mode: a
+ * click creates a sculpt. Sculpt mode: a click adds one stamp; with smear on, a drag lays dabs every 0.4 × size
+ * (≤ 24 per move), previewed live and committed as ONE AddStamps (a smear group) on release.
+ */
+export declare class StampTool {
+    private readonly ctx;
+    private readonly ghost;
+    private readonly ghostMat;
+    private readonly copyMat;
+    private readonly copies;
+    private shape;
+    private stroke;
+    constructor(ctx: InteractionContext);
+    private active;
+    /** Scope's sculpt space (sculpt mode), or undefined. */
+    private scopeSpace;
+    /** Follows the cursor: ghost at the surface / ground point, its symmetry copies about the pivot. */
+    hover(): void;
+    private updateCopies;
+    private ghostInstances;
+    hideGhost(): void;
+    /** One dab in the scope's local space: world-aligned like the ghost, at the ghost's world size. */
+    private spec;
+    /** Pointer down (or Q): stamp once, or start a smear stroke. */
+    press(fromKey?: boolean): void;
+    /** Pointer move while pressed: lay the dabs the cursor passed. */
+    drag(): void;
+    /** Pointer up: the whole stroke becomes one AddStamps (a single dab is a plain stamp). */
+    release(): void;
+    cancel(): void;
+    get stroking(): boolean;
+    private smearGroupFor;
+    private preview;
+    private commit;
+    private createSculpt;
+    dispose(): void;
+}
+export declare function sculptOf(c: import("../../../api/src/index.js").Creation, t: SculptTarget): Sculpt | undefined;

package/dist/types/viewport/src/interaction/stamp-wires.d.ts

@@ -0,0 +1,18 @@
+import { type InteractionContext } from "./interaction-context.js";
+/**
+ * Sculpt-mode selection overlays: the selected shape's wireframe (yellow) with dimmed copies of its kaleidoscope
+ * instances, or a box around a locked smear group (pink) / an area-selected set (blue).
+ */
+export declare class StampWires {
+    private readonly ctx;
+    private readonly space;
+    private readonly wire;
+    private readonly box;
+    private readonly instMat;
+    private readonly inst;
+    private readonly geos;
+    constructor(ctx: InteractionContext);
+    private geo;
+    update(): void;
+    dispose(): void;
+}

package/dist/types/viewport/src/interaction/surface-hit.d.ts

@@ -0,0 +1,14 @@
+import type { Id } from "../../../api/src/index.js";
+import { Vector3, type Intersection, type Object3D } from "three";
+import type { MeshOwner } from "../objects/scene-views.js";
+import type { InteractionContext } from "./interaction-context.js";
+export type SurfaceHit = {
+    readonly hit: Intersection<Object3D>;
+    readonly owner: MeshOwner;
+};
+/** The nearest sculpt / wing surface under the cursor (optionally only some objects' meshes). */
+export declare function surfaceHit(ctx: InteractionContext, only?: ReadonlySet<Id>): SurfaceHit | null;
+/** Where a stamp would land: a surface, else the ground, else the y = 1.5 plane. */
+export declare function stampPoint(ctx: InteractionContext): Vector3 | null;
+/** Average of the three vertex normals of the hit face (smoother than the face normal on a voxel mesh), in mesh space. */
+export declare function hitLocalNormal(hit: Intersection<Object3D>): Vector3;

package/dist/types/viewport/src/materials/fleck-material.d.ts

@@ -0,0 +1,69 @@
+import type { FleckShape, PatternKind } from "../../../api/src/index.js";
+import { Matrix3, MeshStandardMaterial, Vector3, type Texture } from "three";
+import type { DecalUniforms } from "../decals/decal-uniforms.js";
+import type { GlobalUniforms } from "./global-uniforms.js";
+import { type SkinUniforms } from "./skin.js";
+/** The POC's fleck shapes, in shader index order (the contract's FleckShape order). */
+export declare const FLECK_SHAPES: readonly FleckShape[];
+export declare const PATTERN_KINDS: readonly PatternKind[];
+/** Per-sculpt look uniforms; the sculpt view writes them, the shader reads them. */
+export type FleckUniforms = {
+    readonly uGrayscale: {
+        value: number;
+    };
+    readonly uFleckScale: {
+        value: number;
+    };
+    readonly uVariation: {
+        value: number;
+    };
+    readonly uCoverage: {
+        value: number;
+    };
+    readonly uFoundationDarkness: {
+        value: number;
+    };
+    readonly uRegularity: {
+        value: number;
+    };
+    readonly uBoil: {
+        value: number;
+    };
+    readonly uNormalStrength: {
+        value: number;
+    };
+    readonly uFleckShape: {
+        value: number;
+    };
+    readonly uOpacity: {
+        value: number;
+    };
+    readonly uPatternType: {
+        value: number;
+    };
+    readonly uPatternScale: {
+        value: number;
+    };
+    readonly uPatternStrength: {
+        value: number;
+    };
+    readonly uPatternRot: {
+        value: Matrix3;
+    };
+    readonly uPatternColor: {
+        value: Vector3;
+    };
+    readonly uPatternColor2: {
+        value: Vector3;
+    };
+    readonly uTeeth: {
+        value: Vector3;
+    };
+};
+export declare const createFleckUniforms: () => FleckUniforms;
+/**
+ * Sculpt surface (the POC's fleck-material.js): MeshStandardMaterial with vertex colors plus the foundation bed,
+ * flecks, 3D patterns, per-vertex material channels, decals, skinning, dithered opacity, grayscale isolation and
+ * the pixel-art offscreen output.
+ */
+export declare function createFleckMaterial(g: GlobalUniforms, f: FleckUniforms, skin: SkinUniforms, decal: DecalUniforms, env: Texture | null): MeshStandardMaterial;

package/dist/types/viewport/src/materials/global-uniforms.d.ts

@@ -0,0 +1,15 @@
+/** Uniforms every sculpt / wing material shares, owned by one viewport instance. */
+export type GlobalUniforms = {
+    readonly uTime: {
+        value: number;
+    };
+    /** 1 while the render pipeline draws the world offscreen: materials write gloss / kind into alpha. */
+    readonly uPixelOut: {
+        value: number;
+    };
+    /** Distance at which thin dark decal lines are boosted. */
+    readonly uDecalBoostDist: {
+        value: number;
+    };
+};
+export declare const createGlobalUniforms: () => GlobalUniforms;

package/dist/types/viewport/src/materials/skin.d.ts

@@ -0,0 +1,18 @@
+import { MeshDepthMaterial } from "three";
+/** Bone matrices a rig shares with its body and parts (the arrays are written in place every update). */
+export type SkinUniforms = {
+    readonly uBones: {
+        value: Float32Array;
+    };
+    readonly uSeg: {
+        value: Float32Array;
+    };
+    readonly uSkinned: {
+        value: number;
+    };
+};
+export declare const createSkinUniforms: () => SkinUniforms;
+/** boneWt.w < 0 marks a rigid body-part vertex: one segment matrix, no blending. */
+export declare const SKIN_GLSL = "\n  attribute vec4 boneIdx;\n  attribute vec4 boneWt;\n  uniform mat4 uBones[64];\n  uniform mat4 uSeg[64];\n  uniform float uSkinned;\n  mat4 getSkinMat() {\n    if (uSkinned < 0.5) return mat4(1.0);\n    if (boneWt.w < -0.5) return uSeg[int(boneIdx.x)];\n    return boneWt.x * uBones[int(boneIdx.x)] + boneWt.y * uBones[int(boneIdx.y)]\n         + boneWt.z * uBones[int(boneIdx.z)] + boneWt.w * uBones[int(boneIdx.w)];\n  }\n  // Inverse-transpose (up to scale) so normals stay correct under non-uniform stretch\n  mat3 skinNormalMat(mat4 m) {\n    vec3 a = m[0].xyz, b = m[1].xyz, c = m[2].xyz;\n    return mat3(cross(b, c), cross(c, a), cross(a, b));\n  }\n";
+/** Shadow pass must be skinned too, otherwise shadows stay in the bind pose. */
+export declare function createSkinDepthMaterial(skin: SkinUniforms): MeshDepthMaterial;

package/dist/types/viewport/src/materials/wing-material.d.ts

@@ -0,0 +1,21 @@
+import { MeshStandardMaterial, type Texture } from "three";
+import type { GlobalUniforms } from "./global-uniforms.js";
+import { type SkinUniforms } from "./skin.js";
+export type WingUniforms = {
+    readonly uGrayscale: {
+        value: number;
+    };
+    readonly uOpacity: {
+        value: number;
+    };
+    readonly uGlow: {
+        value: number;
+    };
+};
+export declare const createWingUniforms: () => WingUniforms;
+/**
+ * Flat wing membrane: standard material + the rig's skinning, dithered opacity (texture alpha × opacity),
+ * grayscale isolation and the pixel-art output the fleck material also writes. `edge` makes the material for the
+ * wing's contour line, drawn only in pixel art.
+ */
+export declare function createWingMaterial(g: GlobalUniforms, w: WingUniforms, skin: SkinUniforms, tex: Texture, env: Texture | null, edge?: boolean): MeshStandardMaterial;

package/dist/types/viewport/src/math/colors.d.ts

@@ -0,0 +1,29 @@
+import type { ColorRef, Palette, Rgb } from "../../../api/src/index.js";
+import { Color, Vector3 } from "three";
+/** Fixed colors: always available, never edited (the POC's FIXED_COLORS). */
+export declare const FIXED_COLORS: {
+    readonly tongue: 16021135;
+    readonly teeth: 16514042;
+    readonly black: 1118481;
+};
+/** The POC's palette order (slot index → the shader's palette list for pixel art). */
+export declare const PALETTE_ORDER: readonly ["primary", "secondary", "detail", "highlight", "eye", "pupil", "custom"];
+export declare function hexOf(ref: ColorRef, palette: Palette): Rgb;
+export declare function cssOf(ref: ColorRef, palette: Palette): string;
+export declare const cssHex: (hex: Rgb) => string;
+/**
+ * The POC (three r128, no color management) fed hex / 255 to its shaders as-is. Every palette color the
+ * viewport hands a shader goes through here so the look matches (no sRGB → linear conversion).
+ */
+export declare function rawColor(hex: Rgb, out?: Color): Color;
+/** sRGB transfer → linear, per channel. */
+export declare const srgbToLinear: (c: number) => number;
+/**
+ * Palette colors on materials: the swatch hex is sRGB, so shading works on its linear value and the
+ * screen shows the swatch's color (as the wing and decal textures, which three linearizes, already do).
+ */
+export declare function linearVec(hex: Rgb, out?: Vector3): Vector3;
+export declare function linearColor(hex: Rgb, out?: Color): Color;
+export declare function rawVec(hex: Rgb, out?: Vector3): Vector3;
+/** A stable key of the palette (re-raster / re-paint triggers). */
+export declare const paletteKey: (p: Palette) => string;

package/dist/types/viewport/src/math/convert.d.ts

@@ -0,0 +1,15 @@
+import type { Quaternion as ApiQuat, Transform, Vec3 } from "../../../api/src/index.js";
+import { Matrix4, Object3D, Quaternion, Vector3 } from "three";
+/** Contract values ↔ three.js objects. The contract is plain readonly data; three is mutable. */
+export declare const v3: (v: Vec3, out?: Vector3) => Vector3;
+export declare const quat: (q: ApiQuat, out?: Quaternion) => Quaternion;
+export declare const vec3Of: (v: Vector3) => Vec3;
+export declare const quatOf: (q: Quaternion) => ApiQuat;
+export declare const IDENTITY_QUAT: ApiQuat;
+export declare const ZERO: Vec3;
+export declare const ONE: Vec3;
+export declare function matrixOf(t: Transform, out?: Matrix4): Matrix4;
+export declare function applyTransform(obj: Object3D, t: Transform): void;
+export declare function transformOf(obj: Object3D): Transform;
+export declare function transformOfMatrix(m: Matrix4): Transform;
+export declare function sameTransform(a: Transform, b: Transform): boolean;

package/dist/types/viewport/src/math/decal-pose.d.ts

@@ -0,0 +1,7 @@
+import { Quaternion, Vector3 } from "three";
+/**
+ * Decal orientation from a surface normal (the POC's decalPoseFromHit): z = normal, y = the world up seen in
+ * the object's space (eyes stay upright), falling back to world −z when the surface faces straight up / down;
+ * then `rollDeg` about the normal.
+ */
+export declare function decalBasis(normal: Vector3, up: Vector3, fallbackUp: Vector3, rollDeg: number): Quaternion;

package/dist/types/viewport/src/math/lod.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Per-object distance LOD (the POC's lod.js): the voxel grid of each sculpt gets coarser the smaller it is on
+ * screen. Runtime only, never saved. The target is 4 px per voxel (the POC used 8, which melted small details
+ * such as spikes and claws off rig parts at an ordinary zoom).
+ */
+export declare const LOD_TARGET_PX = 4;
+export declare const LOD_HYST = 0.25;
+/** Grid resolutions, finest first, from the base resolution (16–64, default 36 → 36 / 24 / 16). */
+export declare function lodLevels(base: number): readonly number[];
+/** On-screen size in pixels of an object of world size `size` at distance `dist` (perspective camera). */
+export declare function projectedPx(size: number, dist: number, fovDeg: number, viewHeightPx: number): number;
+/**
+ * Resolution the object should have: the coarsest level that still gives ≤ LOD_TARGET_PX px per voxel, finer at once,
+ * coarser only with 25 % slack (so orbiting doesn't flicker). Pinned objects (being edited) stay finest.
+ */
+export declare function lodWanted(levels: readonly number[], px: number | null, current: number | undefined, pinned: boolean): number;

package/dist/types/viewport/src/math/picking.d.ts

@@ -0,0 +1,32 @@
+import type { Ray } from "three";
+import type { ScreenPoint } from "./screen.js";
+/** A shape candidate for sculpt-mode picking: world center and its pick radius (0.6 × size × object scale). */
+export type StampPickCandidate = {
+    readonly center: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    readonly radius: number;
+};
+/** Index of the shape whose center passes closest to the ray, within its radius, or -1. */
+export declare function pickStampOnRay(ray: Ray, candidates: readonly StampPickCandidate[]): number;
+/** Index of the screen point nearest to (x, y) within maxPx (bone dots: 16 px), or -1. Null points are skipped. */
+export declare function nearestScreenPoint(points: readonly (ScreenPoint | null)[], x: number, y: number, maxPx?: number): number;
+/** Index of the decal nearest to a local point, within 0.6 × its size (eraser), or -1. */
+export declare function nearestDecal(decals: readonly {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    size: number;
+}[], p: {
+    x: number;
+    y: number;
+    z: number;
+}): number;
+/** Ctrl+click: toggles one id in a list (order kept, the toggled one last when added). */
+export declare function toggleId<T>(list: readonly T[], id: T): T[];
+/** Ctrl+click on a stamp of a set: toggles every member (a locked group toggles as one). */
+export declare function toggleMembers<T>(current: readonly T[], members: readonly T[]): T[];

package/dist/types/viewport/src/math/pixel-palette.d.ts

@@ -0,0 +1,15 @@
+import { Color } from "three";
+/**
+ * Pixel art: one light and one shadow variation per palette color (the POC's rendering.js), in the raw
+ * (hex / 255) convention the shaders use.
+ */
+export declare function paletteVariants(hex: number, black: number): {
+    base: Color;
+    light: Color;
+    shade: Color;
+};
+export declare function rgbToHsl(r: number, g: number, b: number, out: {
+    h: number;
+    s: number;
+    l: number;
+}): void;

package/dist/types/viewport/src/math/screen.d.ts

@@ -0,0 +1,26 @@
+import type { Box3, Camera } from "three";
+import { Vector3 } from "three";
+export type ScreenPoint = {
+    x: number;
+    y: number;
+};
+export type ScreenRect = {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+};
+/** Pixel position of a world point in a w × h view, or null when it is behind the camera (near plane). */
+export declare function worldToScreen(v: Vector3, camera: Camera & {
+    near: number;
+}, w: number, h: number): ScreenPoint | null;
+/** Screen bounds of a world box, or null when it is entirely behind the camera. */
+export declare function screenRectOfBox(box: Box3, camera: Camera & {
+    near: number;
+}, w: number, h: number): ScreenRect | null;
+export declare const rectFromDrag: (sx: number, sy: number, ex: number, ey: number) => ScreenRect;
+export declare const rectsOverlap: (a: ScreenRect, b: ScreenRect) => boolean;
+export declare const rectContains: (r: ScreenRect, p: ScreenPoint) => boolean;
+/** A press that moved at most this many pixels is a click (orbiting never places or picks). */
+export declare const CLICK_SLOP_PX = 4;
+export declare const isClick: (sx: number, sy: number, ex: number, ey: number) => boolean;