@almadar/shell-web 0.0.0-stage → 0.1.0

package/dist/paintDispatch-ChW5mVuK.d.ts

@@ -0,0 +1,698 @@
+import React__default from 'react';
+import { ScenePos, Asset } from '@almadar/core';
+import { P as Point, R as Rect, F as FxItem, a as FxPreset } from './fx-CmQjnHmT.js';
+import './EventBusProvider-CVwjkV_2.js';
+
+/** A polyline/polygon vertex in pixel space. */
+interface PainterPoint {
+    x: number;
+    y: number;
+}
+/** One color stop of a {@link PainterGradient}; `offset` is 0..1 along the gradient. */
+interface PainterGradientStop {
+    offset: number;
+    color: string;
+}
+
+/**
+ * Drawable contract — the shared vocabulary every neutral drawable primitive
+ * (the `draw-sprite`/`draw-shape`/`draw-text` atoms, `draw-sprite-layer`/
+ * `draw-shape-layer` molecules) is authored against. A drawable is a pure
+ * descriptor the canvas HOST walks and paints via the portable {@link Painter2D}
+ * seam — no `CanvasRenderingContext2D`, no DOM. Genre (a "unit"/"tile"/
+ * "highlight") is a `.lolo` COMPOSITION of these, never its own primitive.
+ *
+ * A position is a core `ScenePos` (logical scene space). The host's {@link Projector}
+ * maps it to pixels; primitives never do projection math themselves. Because the
+ * `ScenePos` type identity is what pattern-sync stamps as the `drawable`
+ * capability, every drawable descriptor's `position` MUST be a core `ScenePos`.
+ */
+
+/**
+ * How a drawable aligns to its projected position.
+ * - `top-left` — the cell's top-left corner (tiles).
+ * - `ground`   — the cell's ground point, bottom-center of the drawable (units/features).
+ * - `center`   — the cell's visual center (effects).
+ */
+type DrawableAnchor = 'top-left' | 'ground' | 'center';
+/**
+ * Maps logical scene coordinates to pixel space for one projection (iso/hex/flat/free).
+ * Owns ALL projection geometry so the primitives stay projection-agnostic. The host
+ * applies the camera transform on the painter around the walk; the projector is
+ * pre-camera (logical→cell-pixel).
+ */
+interface Projector {
+    /** Cell top-left in pixels. */
+    project(pos: ScenePos): PainterPoint;
+    /** The pixel reference point for an anchor (see {@link DrawableAnchor}). */
+    anchorPoint(pos: ScenePos, anchor: DrawableAnchor): PainterPoint;
+    /** The cell footprint polygon — a rect (square grids) or a diamond (iso/hex). */
+    cellPath(pos: ScenePos): PainterPoint[];
+    /** Cell width in source-px tile-space — the board's native tile width for grid layouts (`flat`/`iso`/`hex`), 1 for `free`/`side` (world-pixel-direct). The host camera applies the on-screen zoom once. */
+    readonly tileWidth: number;
+    /** Cell floor height in source-px tile-space (`tileWidth / 2` for grid layouts, 1 for `free`/`side`). */
+    readonly floorHeight: number;
+    /** Diamond-top offset in source-px tile-space (where the iso diamond starts in the sprite). */
+    readonly diamondTopY: number;
+    /** Render scale factor. */
+    /** True for square-pitch grids (`flat`/`free`); false for diamond (iso/hex). */
+    readonly squareGrid: boolean;
+    /** True for world-pixel-direct layouts (`free`/`side`); false for tile grids (`flat`/`iso`/`hex`). */
+    readonly worldPixelDirect: boolean;
+}
+/** Common shape of every drawable descriptor. `type` keys the host's paint dispatch. */
+interface DrawableBase {
+    type: string;
+    /**
+     * Optional hit-test handle. When a board authors a per-entity id here (e.g.
+     * `id: (object/get @u id)` on a unit sprite), the canvas host indexes the
+     * descriptor's `ScenePos → id` and resolves a pointer/raycast at that cell to
+     * this id — the source of `unitClickEvent {unitId}`. A source-tagged handle,
+     * NOT a heuristic: no id → the host emits only the coordinate (tile click).
+     */
+    id?: string;
+}
+
+/**
+ * `draw-shape` — the neutral vector-fill/stroke drawable atom (dimension-agnostic).
+ *
+ * ONE descriptor (`DrawShapeProps`, grounded in core `ScenePos`) with TWO
+ * backends: `paintShape` (2D, here) and an R3F ground-plane mesh (`Shape3D` in
+ * `lib/drawable/mesh3d`, kept OUT of this file so the 2D path never pulls R3F).
+ * Paints a cell footprint, an axis-aligned rect, an ellipse, a poly, or an SVG
+ * path at a scene position, fill and/or stroke. Genre uses (tile fallback, iso/hex
+ * diamond fallback, cell highlight, feature disc, unit selection ring, unit
+ * fallback circle, ground/ghost discs, solid backgrounds, side-view platform
+ * rects, hand-authored vector art) are all this atom with different
+ * `shape`/`anchor`/geometry — composed in `.lolo`, not here. The React component renders `null`; it exists so the pattern pipeline
+ * registers a `draw-shape` pattern and standalone pages stay inspectable.
+ */
+
+type ShapeKind = 'cell' | 'rect' | 'ellipse' | 'poly' | 'path';
+/** Composite modes a shape may blend with — the canvas `globalCompositeOperation` set, spelled out so the pattern schema carries a real enum. */
+type DrawShapeBlendMode = 'source-over' | 'lighter' | 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten' | 'color-dodge' | 'color-burn' | 'hard-light' | 'soft-light' | 'difference' | 'exclusion' | 'hue' | 'saturation' | 'color' | 'luminosity' | 'source-atop' | 'destination-over' | 'destination-out' | 'xor';
+/** One gradient color stop; `offset` is 0..1 along the gradient axis. */
+type DrawShapeGradientStop = PainterGradientStop;
+/**
+ * A gradient fill in world units relative to the cell's projected top-left —
+ * same coordinate convention as `points` and `d`. Overrides `fill` when present.
+ */
+interface DrawShapeGradient {
+    kind: 'linear' | 'radial' | 'conic';
+    /** Linear start point in world units. */
+    from?: Point;
+    /** Linear end point in world units. */
+    to?: Point;
+    /** Radial/conic center in world units. */
+    center?: Point;
+    /** Radial radius in world units. */
+    radius?: number;
+    /** Conic start angle in radians. */
+    angle?: number;
+    /** Ordered color stops. */
+    stops: DrawShapeGradientStop[];
+}
+/**
+ * A repeating texture painted OVER the fill, clipped to the same geometry —
+ * procedural grain (`noise`) or a tiling image. `scale` is painter-px per noise
+ * cell (default 2) / an image scale multiplier; grain stays constant-px under
+ * group scale, like strokes.
+ */
+interface DrawShapeFillPattern {
+    kind: 'noise' | 'image';
+    /** Image pattern URL (`kind: 'image'`). */
+    url?: string;
+    scale?: number;
+    /** Noise speckle max alpha (default 0.12). */
+    alpha?: number;
+    /** Noise speckle color (default black). */
+    color?: string;
+}
+/** A soft glow / drop-shadow behind the shape; `blur` is in world units. */
+interface DrawShapeShadow {
+    color: string;
+    blur: number;
+}
+/**
+ * One keyframe of a {@link DrawShapeAnimation}: `at` is the 0..1 position in
+ * the cycle; every other field overrides the shape's base prop at that moment.
+ */
+interface DrawShapeKeyframe {
+    at: number;
+    offsetX?: number;
+    offsetY?: number;
+    rotate?: number;
+    opacity?: number;
+    radiusX?: number;
+    radiusY?: number;
+    width?: number;
+    height?: number;
+    strokeWidth?: number;
+    strokeDashOffset?: number;
+    blur?: number;
+    fill?: string;
+    stroke?: string;
+    shadow?: DrawShapeShadow;
+}
+/**
+ * Declarative keyframe animation for a drawable. The host runs a paint clock
+ * while any drawable declares one; numeric tracks lerp between keyframes,
+ * string tracks hold the previous keyframe's value, `shadow` lerps `blur` and
+ * holds `color`. A track starts from the shape's base prop until its first
+ * keyframe defines it.
+ */
+interface DrawShapeAnimation {
+    /** One cycle length in ms. */
+    durationMs: number;
+    /** Loop the cycle (default true); false plays once and holds the final keyframes. */
+    loop?: boolean;
+    /** Keyframes ordered by `at` (0..1). */
+    keyframes: DrawShapeKeyframe[];
+}
+interface DrawShapeProps extends DrawableBase {
+    type: 'draw-shape';
+    shape: ShapeKind;
+    /** Logical scene position; the projector maps it to pixels / world. */
+    position: ScenePos;
+    /** How the shape aligns to its projected position. Default varies by `shape`. */
+    anchor?: DrawableAnchor;
+    /** Rect width in world units (fractions of `projector.tileWidth`). */
+    width?: number;
+    /** Rect height in world units (fractions of `projector.tileWidth`). */
+    height?: number;
+    /** Ellipse horizontal radius in world units (fractions of `projector.tileWidth`). */
+    radiusX?: number;
+    /** Ellipse vertical radius in world units; omitted → `radiusX` (a circle). */
+    radiusY?: number;
+    /** Fine nudge in world units — applies to every shape kind except `cell` (rect/ellipse from their anchor point; poly/path from the projected top-left). */
+    offsetX?: number;
+    offsetY?: number;
+    /** Poly vertices as world-unit offsets relative to the cell's projected top-left. */
+    points?: Point[];
+    /** SVG path data in world units relative to the cell's projected top-left — same coordinate convention as `points`. */
+    d?: string;
+    fill?: string;
+    /** Gradient fill in world units; overrides `fill` when present. */
+    gradient?: DrawShapeGradient;
+    /** Repeating texture painted over the fill (grain / tiling image). */
+    fillPattern?: DrawShapeFillPattern;
+    stroke?: string;
+    strokeWidth?: number;
+    /** Gradient stroke in world units; overrides `stroke` when present. */
+    strokeGradient?: DrawShapeGradient;
+    /** Dash pattern in painter-px (constant under group scale, like `strokeWidth`). */
+    strokeDash?: number[];
+    /** Dash phase offset in painter-px; animatable (marching ants). */
+    strokeDashOffset?: number;
+    /** Composite/blend mode for this shape's draws (`lighter`, `multiply`, `screen`, …). */
+    blendMode?: DrawShapeBlendMode;
+    /** Gaussian blur in painter-px. Expensive — forces an intermediate raster; use sparingly. */
+    blur?: number;
+    /** Rotation in radians (painter units, same as `draw-group`), about `pivot`. */
+    rotate?: number;
+    /** Rotation pivot in world units relative to the cell's projected top-left; default `{x:0.5, y:0.5}` (cell center). */
+    pivot?: Point;
+    /** Soft glow / drop-shadow behind the shape; `blur` in world units. */
+    shadow?: DrawShapeShadow;
+    /** Keyframe animation over this shape's props; the host runs a paint clock while present. */
+    animation?: DrawShapeAnimation;
+    /** 0..1 opacity. */
+    opacity?: number;
+}
+/** Registry/standalone stub — the host paints this atom; the DOM renders nothing.
+ *  When composed as a React child of a draw-host (Canvas2D), registers its
+ *  descriptor via context so the host paints it. */
+declare function DrawShape(props: DrawShapeProps): React__default.JSX.Element | null;
+
+/**
+ * `draw-sprite` — the neutral image/atlas-frame drawable atom (dimension-agnostic).
+ *
+ * ONE descriptor (`DrawSpriteProps`, grounded in core `ScenePos` + `Asset`) with
+ * TWO backends: `paintSprite` (2D, here — via the portable `Painter2D` seam) and
+ * an R3F mesh (`Sprite3D` in `lib/drawable/mesh3d`, kept OUT of this file so the
+ * 2D paint path never pulls `three`/`drei` into an app bundle — the codebase
+ * code-splits R3F). The canvas host picks the backend by `mode`; that is what
+ * makes canvas-2d and canvas-3d the same `children` interface. Genre uses (tile,
+ * unit body, feature, effect, movement ghost, background cover) are all this atom
+ * with different `anchor`/`size`/`frame`/`flip`/`shadow` — composed in `.lolo`,
+ * not here. The React component renders `null` (a drawable is painted by the host,
+ * not the DOM); it exists so the pattern pipeline registers a `draw-sprite`
+ * pattern and standalone pages stay inspectable.
+ */
+
+interface DrawSpriteProps extends DrawableBase {
+    type: 'draw-sprite';
+    /** Logical scene position; the projector maps it to pixels / world. */
+    position: ScenePos;
+    /** The image / atlas reference to blit. */
+    asset: Asset;
+    /** How the sprite aligns to its projected position. Default `'top-left'`. */
+    anchor?: DrawableAnchor;
+    /** Draw width in world units (fractions of `projector.tileWidth`). Omitted → one cell on tile grids (`flat`/`iso`/`hex`); native source px on `free`/`side`. */
+    width?: number;
+    /** Draw height in world units (fractions of `projector.tileWidth`). Omitted → one cell on tile grids (`flat`/`iso`/`hex`); native source px on `free`/`side`. */
+    height?: number;
+    /** Explicit atlas sub-rect override (px); omitted → resolved from `asset.atlas`/`asset.sprite`. */
+    frame?: Rect;
+    /** Animation to play. 3D backend: a named GLB clip (matched case-insensitively). 2D painter: when `asset.atlas` resolves to a `SpriteSheetAtlas` manifest, the canonical row of that name (idle/walk/attack/hit/death) plays off the host paint clock; an explicit `frame` rect overrides. */
+    animation?: string;
+    /** Override the sheet row's loop flag. The paint clock is wall-time, so one-shot rows hold their final frame — preview pages set `true` to cycle attack/hit/death continuously. */
+    loop?: boolean;
+    /** Animation clock override in ms (e.g. an fx entry's age since spawn). Omitted → the host paint clock; one-shot rows anchored to wall-time would otherwise sit on their final frame. */
+    clockMs?: number;
+    /** Mirror horizontally (facing). */
+    flipX?: boolean;
+    /** Rotation in radians about the sprite's center. */
+    rotation?: number;
+    /** 0..1 opacity. */
+    opacity?: number;
+    /** Drop shadow (e.g. a team-colored glow). */
+    shadow?: DrawShapeShadow;
+}
+/** Registry/standalone stub — the host paints this atom; the DOM renders nothing. */
+declare function DrawSprite(_props: DrawSpriteProps): React__default.JSX.Element | null;
+
+/**
+ * `draw-text` — the neutral text drawable atom (dimension-agnostic).
+ *
+ * ONE descriptor (`DrawTextProps`, grounded in core `ScenePos`) with TWO backends:
+ * `paintText` (2D, here) and an R3F billboarded `<Text>` (`Text3D` in
+ * `lib/drawable/mesh3d`, kept OUT of this file so the 2D path never pulls R3F).
+ * Paints a string at a scene position with font/color/alignment. The React
+ * component renders `null` (a drawable is painted by the host, not the DOM).
+ */
+
+/**
+ * Mirrors DOM lib.dom.d.ts `CanvasTextAlign` by value (used directly instead
+ * of the ambient global so the pattern-sync scanner — which only indexes
+ * `components/**` and can't see ambient TS-lib types — resolves this to a
+ * concrete enum instead of `json`). Structurally identical; `node.align`
+ * still flows straight into `Painter2D.text`'s `TextStyle.align`.
+ */
+type DrawTextAlign = 'center' | 'end' | 'left' | 'right' | 'start';
+/** Mirrors DOM `CanvasTextBaseline` by value — see {@link DrawTextAlign}. */
+type DrawTextBaseline = 'alphabetic' | 'bottom' | 'hanging' | 'ideographic' | 'middle' | 'top';
+interface DrawTextProps extends DrawableBase {
+    type: 'draw-text';
+    text: string;
+    /** Logical scene position; the projector maps it to pixels / world. */
+    position: ScenePos;
+    anchor?: DrawableAnchor;
+    offsetX?: number;
+    offsetY?: number;
+    color: string;
+    font?: string;
+    align?: DrawTextAlign;
+    baseline?: DrawTextBaseline;
+    opacity?: number;
+}
+/** Registry/standalone stub — the host paints this atom; the DOM renders nothing. */
+declare function DrawText(_props: DrawTextProps): React__default.JSX.Element | null;
+
+/**
+ * `draw-mesh` — the volumetric 3D drawable atom (3D-canvas backend).
+ *
+ * ONE descriptor (`DrawMeshProps`, grounded in core `ScenePos`) with the R3F
+ * backend `Mesh3D` in `lib/drawable/three/DrawMesh3D` (kept OUT of this file so
+ * the 2D path never pulls three). A parametric primitive (box, sphere, capsule,
+ * cylinder, cone, torus, plane, circle — `plane`/`circle` lie flat in the
+ * scene ground plane facing up, matching the 2D painter) or a raw-geometry `polyhedron`
+ * (`vertices` + `faces` as plain data) at a scene position — `position.z` is
+ * height in cells — with a data-driven material (`standard`/`physical`/`toon`/
+ * `basic`), an optional inverted-hull outline, and keyframe animation over
+ * transform/material tracks. Low-poly is a knob, not a geometry rewrite:
+ * `segments` 4–8 + `material.flatShading`. Composed in `.lolo` like every
+ * drawable; the 2D painter skips it with a one-time warn. The React component
+ * renders `null`; it exists so the pattern pipeline registers a `draw-mesh`
+ * pattern and standalone pages stay inspectable.
+ */
+
+type MeshShapeKind = 'box' | 'sphere' | 'capsule' | 'cylinder' | 'cone' | 'torus' | 'plane' | 'circle' | 'polyhedron';
+type MeshMaterialKind = 'standard' | 'physical' | 'toon' | 'basic';
+type MeshMaterialSide = 'front' | 'back' | 'double';
+/**
+ * Data-driven surface description — the 3D analog of the 2D fill/gradient knobs.
+ * `standard`/`physical` are lit PBR (physical adds `transmission`/`ior` for glass
+ * and crystal), `toon` is cel-banded, `basic` is unlit flat color.
+ */
+interface MeshMaterial {
+    kind?: MeshMaterialKind;
+    /** Albedo color (CSS color string). */
+    color?: string;
+    /** 0..1 — how metallic the surface reads (PBR kinds). */
+    metalness?: number;
+    /** 0..1 — microfacet roughness; low = glossy (PBR kinds). */
+    roughness?: number;
+    /** Emissive color; pairs with the canvas `post.bloom` for neon/glow. */
+    emissive?: string;
+    /** Emissive strength multiplier (default 1 when `emissive` is set). */
+    emissiveIntensity?: number;
+    /** 0..1 material opacity; multiplies the node/group opacity. */
+    opacity?: number;
+    /** 0..1 light transmission — glass/crystal (`physical` only). */
+    transmission?: number;
+    /** Index of refraction (`physical` only, default 1.5). */
+    ior?: number;
+    /** Faceted shading — the low-poly look (pairs with low `segments`). */
+    flatShading?: boolean;
+    /** Which faces render (default `front`). */
+    side?: MeshMaterialSide;
+    /** Albedo texture: an image URL or `data:` URI, sampled through the polyhedron's `uvs`. Multiplied by `color` — keep `color` white (or unset) to show the texture unmodified. */
+    map?: string;
+}
+/** Inverted-hull toon outline: a back-face shell of the same geometry, scaled out by `width`. */
+interface MeshOutline {
+    /** Outline color (default near-black). */
+    color?: string;
+    /** Shell expansion as a fraction of the mesh size (default 0.05). */
+    width?: number;
+}
+/**
+ * One keyframe of a {@link DrawMeshAnimation}: `at` is the 0..1 position in the
+ * cycle. Transform tracks are DELTAS from the base props (offsets in cells,
+ * rotations in radians, `scale` a multiplier); material tracks override.
+ */
+interface DrawMeshKeyframe {
+    at: number;
+    offsetX?: number;
+    offsetY?: number;
+    offsetZ?: number;
+    rotateX?: number;
+    rotateY?: number;
+    rotateZ?: number;
+    scale?: number;
+    opacity?: number;
+    emissiveIntensity?: number;
+    color?: string;
+    emissive?: string;
+}
+/**
+ * Declarative keyframe animation for a mesh; the 3D host advances it per frame.
+ * Numeric tracks lerp between keyframes, color tracks hold the previous
+ * keyframe's value. A track rests at its identity until its first keyframe.
+ */
+interface DrawMeshAnimation {
+    /** One cycle length in ms. */
+    durationMs: number;
+    /** Loop the cycle (default true); false plays once and holds the final keyframes. */
+    loop?: boolean;
+    /** Keyframes ordered by `at` (0..1). */
+    keyframes: DrawMeshKeyframe[];
+}
+/**
+ * Smooth-skinning data for a `polyhedron` — plain declarative data, no runtime
+ * objects. Vertices carry blended bone weights (a neck-base vertex can be 60%
+ * neck / 40% spine), so the surface stretches continuously across joints
+ * instead of cracking at rigid chunk boundaries.
+ */
+interface DrawMeshSkin {
+    /** Bone names, resolved against sibling `draw-group` `bone:` names in the same canvas. */
+    bones: string[];
+    /** One 16-float column-major inverse bind matrix per bone (model space → bone bind-local; translations in cells). */
+    inverseBindMatrices: number[][];
+    /** Per-vertex bone indices into `bones`, up to 4 each (pad with 0). */
+    indices: number[][];
+    /** Per-vertex blend weights matching `indices`, normalized to sum 1 (pad with 0). */
+    weights: number[][];
+}
+interface DrawMeshProps extends DrawableBase {
+    type: 'draw-mesh';
+    shape: MeshShapeKind;
+    /** Logical scene position; `z` is height in cells (projected to world Y). */
+    position: ScenePos;
+    /** Box/plane X extent in cells (default 1). */
+    width?: number;
+    /** Box Y (height) extent / capsule-cylinder-cone length in cells (default 1). */
+    height?: number;
+    /** Box/plane Z extent in cells (default `width`). */
+    depth?: number;
+    /** Sphere/capsule/cone/torus/circle radius in cells (default 0.4). */
+    radius?: number;
+    /** Cylinder top radius (default `radius`). */
+    radiusTop?: number;
+    /** Cylinder bottom radius (default `radius`). */
+    radiusBottom?: number;
+    /** Torus tube radius in cells (default `radius` / 3). */
+    tube?: number;
+    /** Curved-surface tessellation, clamped 3..64 (default 24). 4–8 + `flatShading` = low-poly. */
+    segments?: number;
+    /** `polyhedron` only: raw vertices as scene-frame `[x, y, z]` triples in cells, `z` = up. */
+    vertices?: number[][];
+    /** `polyhedron` only: triangle index triples into `vertices`, wound counter-clockwise seen from OUTSIDE in the scene frame. */
+    faces?: number[][];
+    /** `polyhedron` only: per-vertex `[u, v]` texture coordinates parallel to `vertices`, glTF convention (`v` grows DOWN from the image's top-left). Pairs with `material.map`. */
+    uvs?: number[][];
+    /** `polyhedron` only: smooth-skinning weights binding the vertices to named bone groups. Vertices must then be authored in BIND POSE model space; the bones' animated transforms deform them. */
+    skin?: DrawMeshSkin;
+    /** Euler rotation `[x, y, z]` in radians. */
+    rotation?: [number, number, number];
+    /** `bottom` (default) rests the mesh on its position's ground plane; `center` centers it there. For `polyhedron`, `bottom` lifts by −min(z) and `center` applies no offset — the vertices are authoritative. */
+    pivot?: 'bottom' | 'center';
+    material?: MeshMaterial;
+    outline?: MeshOutline;
+    castShadow?: boolean;
+    receiveShadow?: boolean;
+    /** Keyframe animation over transform/material tracks; the 3D host runs it per frame. */
+    animation?: DrawMeshAnimation;
+    /** 0..1 opacity; multiplies the material and enclosing group opacity. */
+    opacity?: number;
+}
+/** Registry/standalone stub — the 3D host renders this atom; the DOM renders nothing.
+ *  When composed as a React child of a draw-host, registers its descriptor via
+ *  context so the host paints it — same path as DrawShape. */
+declare function DrawMesh(props: DrawMeshProps): React__default.JSX.Element | null;
+
+/**
+ * `draw-group` — the drawable CONTAINER atom (dimension-agnostic).
+ *
+ * Multi-shape art (a hero token = cloak + head + sword shapes) travels as ONE
+ * node: the host paints the group by translating to its projected position,
+ * applying `scale`/`rotate`/`opacity`, then painting each `items` descriptor
+ * through the normal dispatch. `items` is a plain data prop (NOT `children`,
+ * which UISlotRenderer special-cases) — same convention as the `draw-*-layer`
+ * molecules. The React component renders `null`; it exists so the pattern
+ * pipeline registers a `draw-group` pattern and standalone pages stay
+ * inspectable. Both backends paint it: 2D as a canvas transform, 3D as a three
+ * `<group>` — with `rotation` + `animation` a nested group chain is a skeleton
+ * bone chain (rotate the shoulder group and the forearm group follows).
+ */
+
+interface DrawGroupProps extends DrawableBase {
+    type: 'draw-group';
+    /** Logical scene position; the projector maps it to pixels / world. */
+    position: ScenePos;
+    /** Uniform scale applied to the whole group. */
+    scale?: number;
+    /** Rotation in radians (painter units). */
+    rotate?: number;
+    /** Euler rotation `[x, y, z]` in radians (world axes) — per-axis joint rotation for the 3D backend; a group placed at a joint with children authored joint-local IS a bone. The 2D painter applies only the in-plane `z` component, after `rotate`. */
+    rotation?: [number, number, number];
+    /** Skeleton bone name. A named group is addressable by a `draw-mesh` `skin`
+     *  block (smooth skinning): the skinned mesh deforms with this group's
+     *  animated transform. Names resolve within the nearest enclosing
+     *  `skeleton: true` group (falling back to the canvas), so multiple
+     *  instances of one rig never collide. Distinct from `id` (the hit-test
+     *  handle). */
+    bone?: string;
+    /** Marks this group as a skeleton SCOPE: `bone` names and `skin` bindings in
+     *  its subtree resolve against each other only — one scope per rig instance. */
+    skeleton?: boolean;
+    /** Keyframe animation over the group TRANSFORM tracks (`offsetX/Y/Z` in cells, `rotateX/Y/Z` in radians, `scale`; the 2D painter also honors `opacity`) — children inherit it, so nested animated groups form a joint chain. Material tracks belong on leaf meshes. */
+    animation?: DrawMeshAnimation;
+    /** 0..1 opacity. */
+    opacity?: number;
+    /** Clip the group's items to an SVG path (`d` syntax) in world units relative to the group origin — masked reveals, meters, portraits. */
+    clip?: string;
+    /** The grouped drawables, painted through the normal dispatch. */
+    items: DrawableNode[];
+}
+/** Registry/standalone stub — the host paints this atom; the DOM renders nothing.
+ *  When composed as a React child of a draw-host (Canvas2D), registers its
+ *  descriptor via context so the host paints it — same path as DrawShape. */
+declare function DrawGroup(props: DrawGroupProps): React__default.JSX.Element | null;
+
+interface SkinWeight {
+    /** Index into the drawable's `bones` array. */
+    bone: number;
+    w: number;
+}
+interface SkinVertex {
+    x: number;
+    y: number;
+    /** Normalized 0..1 texture coordinates. */
+    u: number;
+    v: number;
+    weights: SkinWeight[];
+}
+interface SkinMesh {
+    vertices: SkinVertex[];
+    triangles: [number, number, number][];
+}
+interface BoneDef {
+    name: string;
+    parent: string | null;
+    /** Rotation pivot in local space (the joint the bone turns about). */
+    pivot: [number, number];
+    /** Bone end point in local space (render/inspect hint; no skinning role). */
+    tip: [number, number];
+}
+/** Bone name → rotation in degrees relative to the bind pose. */
+type Pose = Record<string, number>;
+
+/**
+ * `draw-skinned-mesh` — the skeletal-mesh drawable atom: a bind-pose triangle
+ * mesh deformed by linear blend skinning and painted per-triangle from a texture.
+ *
+ * The general-purpose primitive for animated 2D characters (puppet rigs): a pose
+ * rotates each bone about its pivot (degrees, relative to bind), `lib/skinning`
+ * computes the deformed vertices, and each triangle is blit through the affine
+ * mapping its UV tri → its painted tri (clipped to the tri, so seams don't bleed).
+ * Mesh + bones + UVs come from the bundle exporter (inline `mesh` or a fetched
+ * `meshUrl`); animation is `clip.frames[frame % len]`, driven by the host like
+ * any other drawable frame counter. `weightsOverlay` swaps the texture for a
+ * per-bone categorical fill (rig inspection); `ghost` paints an onion-skin pass
+ * of another clip frame underneath. The React component renders `null` (the host
+ * paints it); it exists so the pattern pipeline registers a `draw-skinned-mesh`
+ * pattern and JSX children register through the drawable registry.
+ */
+
+interface DrawSkinnedMeshProps extends DrawableBase {
+    type: 'draw-skinned-mesh';
+    /** Logical scene position; mesh local coords are world units relative to its projected top-left. */
+    position: ScenePos;
+    /** The texture the mesh UVs cut into. */
+    asset: Asset;
+    /** Inline bind mesh; wins over `meshUrl`. */
+    mesh?: SkinMesh;
+    /** URL of a JSON `SkinMesh` (fetched + cached); used when `mesh` is absent. */
+    meshUrl?: string;
+    /** The skeleton (bind pose; FK chain via `parent` names). Falls back to the rigbundle's `bones` when empty. */
+    bones: BoneDef[];
+    /** Static pose (bone name → degrees relative to bind). Overridden by `clip` + `frame`. */
+    pose?: Pose;
+    /** Pose animation clip; with `frame`, pose = `frames[frame % frames.length]`. */
+    clip?: {
+        frames: Pose[];
+    };
+    /** Named clip inside the rigbundle at `meshUrl` (`clips[clipName].frames`); used when `clip` is absent. Empty/unknown = no clip. */
+    clipName?: string;
+    /** Clip frame counter (host-driven paint clock frame). */
+    frame?: number;
+    /** 0..1 opacity. */
+    opacity?: number;
+    /** Paint per-triangle dominant-bone colors instead of the texture (rig inspection). */
+    weightsOverlay?: boolean;
+    /** Onion skin: render the mesh at this clip frame underneath, at this opacity. */
+    ghost?: {
+        frame: number;
+        opacity: number;
+    };
+}
+/** Registry/standalone stub — the host paints this atom; the DOM renders nothing.
+ *  When composed as a React child of a draw-host (Canvas2D), registers its
+ *  descriptor via context so the host paints it. */
+declare function DrawSkinnedMesh(props: DrawSkinnedMeshProps): React__default.JSX.Element | null;
+
+/**
+ * `draw-sprite-layer` — batch multiple sprites in one descriptor for O(layers) rendering.
+ *
+ * Composes the `draw-sprite` atom; the layer itself carries no `position` — each
+ * item does. It is drawable-by-composition: its `items` are `draw-sprite`
+ * descriptors (each grounded in core `ScenePos`), which is what stamps the layer
+ * `drawable` at pattern-sync time.
+ */
+
+interface DrawSpriteLayerProps extends DrawableBase {
+    type: 'draw-sprite-layer';
+    /** Sprites painted in array order; z-ordering is the caller's responsibility. */
+    items: DrawSpriteProps[];
+}
+/** Registry/standalone stub — the host paints this molecule; the DOM renders nothing. */
+declare function DrawSpriteLayer(_props: DrawSpriteLayerProps): React__default.JSX.Element | null;
+
+/**
+ * `draw-shape-layer` — batch of shapes in one descriptor for O(layers) perf.
+ *
+ * Composes the `draw-shape` atom; drawable-by-composition (its `items` are
+ * `draw-shape` descriptors, each grounded in core `ScenePos`). The React
+ * component renders `null` (a drawable is painted by the host, not the DOM).
+ */
+
+interface DrawShapeLayerProps extends DrawableBase {
+    type: 'draw-shape-layer';
+    items: DrawShapeProps[];
+}
+/** Registry/standalone stub — the host paints this molecule; the DOM renders nothing. */
+declare function DrawShapeLayer(_props: DrawShapeLayerProps): React__default.JSX.Element | null;
+
+/**
+ * `draw-text-layer` — batch of text labels in one descriptor for O(layers) perf.
+ *
+ * Composes the `draw-text` atom; drawable-by-composition (its `items` are
+ * `draw-text` descriptors, each grounded in core `ScenePos`). Covers the batched
+ * world-space text pass — fx messages, damage numbers, unit labels — that a
+ * board maps from an entity array (`items: (array/map @entity.fx (fn ...))`),
+ * which a literal `children` array can't express. The React component renders
+ * `null` (a drawable is painted by the host, not the DOM).
+ */
+
+interface DrawTextLayerProps extends DrawableBase {
+    type: 'draw-text-layer';
+    items: DrawTextProps[];
+}
+/** Registry/standalone stub — the host paints this molecule; the DOM renders nothing. */
+declare function DrawTextLayer(_props: DrawTextLayerProps): React__default.JSX.Element | null;
+
+/**
+ * `draw-fx-layer` — the batched transient-effects pass in one descriptor.
+ *
+ * Collapses the fx triple every board used to hand-roll (message text layer +
+ * sprite fallback layer + vector-art group per fx entry) into ONE node:
+ * `{ type: draw-fx-layer, items: @entity.fx, presets: @config.fxPresets, … }`.
+ * NAME-BLIND: each item's look comes from its resolved typed fields via the
+ * consumer-declared `FxPreset[]` table — never a kind→look table in here.
+ * Render priority per item: vector `art[type].idle` (draw-group) → sprite
+ * `sprites[type]` (draw-sprite) → a procedural seeded recipe
+ * (spark/ring/puff/streak draw-shapes); a `message` always adds a rising,
+ * fading draw-text. Expansion is PURE (descriptors → descriptors, routed
+ * through the normal paint dispatch); per-frame smoothness comes from the host
+ * paint clock against each item's `bornAt`, while the fx mechanic's ttl decay
+ * stays the authoritative removal clock. `space: "screen"` entries are skipped
+ * — the `fx-overlay` core molecule owns those. The React component renders
+ * `null` (a drawable is painted by the host, not the DOM).
+ */
+
+interface DrawFxLayerProps extends DrawableBase {
+    type: 'draw-fx-layer';
+    /** The live fx entries — the mechanic's `@entity.fx` list passed whole; `space: "screen"` entries are skipped (the overlay owns those). */
+    items: FxItem[];
+    /** Consumer-declared effect vocabulary — one row per fx `type` (look + recipe). Unknown types fall back to a neutral spark burst. */
+    presets?: FxPreset[];
+    /** Vector art per fx type (an asset-art map: type → anim-state → drawables); a type's `idle` state wins over sprites/procedural. */
+    art?: Record<string, Record<string, DrawableNode[]>>;
+    /** Sprite asset per fx type (an asset-manifest effects map) — used when no vector art matches. */
+    sprites?: Record<string, Asset>;
+    /** The fx mechanic's decay tick period in ms; lifetime = maxTtl × tickMs. Default 500. */
+    tickMs?: number;
+    /** Floating-message text color when an item declares none. Default `#ffe066`. */
+    textColor?: string;
+}
+/** Registry/standalone stub — the host paints this molecule; the DOM renders nothing. */
+declare function DrawFxLayer(_props: DrawFxLayerProps): React__default.JSX.Element | null;
+
+/**
+ * Drawable paint dispatch (2D) + the `DrawableNode` union.
+ *
+ * `paintDrawable` routes ONE descriptor to its 2D painter; the host walks its
+ * `children` through it. The "drawable" designation itself is NOT recorded here —
+ * it is DERIVED from the core `ScenePos` type each descriptor's `position` uses
+ * and stamped into `patterns-registry.json` by pattern-sync (mirroring how `Asset`
+ * is tagged), then read by the orbital-rust validator. So this module is pure
+ * paint routing; the capability is the registry's, not a hand-list.
+ */
+
+/** Every drawable descriptor. The host's `children` are a `DrawableNode[]`. */
+type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawGroupProps | DrawMeshProps | DrawSkinnedMeshProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps | DrawFxLayerProps;
+
+export { DrawFxLayer as e, DrawGroup as f, DrawMesh as g, DrawShape as h, DrawShapeLayer as i, DrawSkinnedMesh as j, DrawSprite as k, DrawSpriteLayer as l, DrawText as m, DrawTextLayer as n };
+export type { DrawableNode as D, MeshShapeKind as M, Projector as P, MeshMaterial as a, DrawGroupProps as b, DrawTextProps as c, DrawMeshProps as d };