@almadar/ui 5.139.0 → 5.141.0

package/dist/lib/index.d.cts

@@ -1,7 +1,7 @@
-export { C as ContentSegment, D as DEFAULT_CONFIG, a as DomEntityBox, b as DomLayoutData, c as DomOutputsBox, d as DomStateNode, e as DomTransitionLabel, f as DomTransitionPath, E as EntityDefinition, R as RenderOptions, S as StateDefinition, g as StateMachineDefinition, T as TraitSnapshotGetter, h as TransitionDefinition, V as VisualizerConfig, i as bindCanvasCapture, j as bindEventBus, k as bindLastDrawables, l as bindTraitStateGetter, m as clearVerification, n as cn, o as extractOutputsFromTransitions, p as extractStateMachine, q as formatGuard, r as getAllChecks, s as getBridgeHealth, t as getEffectSummary, u as getSnapshot, v as getSummary, w as getTraitSnapshots, x as getTransitions, y as getTransitionsForTrait, z as parseContentSegments, A as parseMarkdownWithCodeBlocks, B as recordServerResponse, F as recordTransition, G as registerCheck, H as registerTraitSnapshot, I as renderStateMachineToDomData, J as renderStateMachineToSvg, K as subscribeToVerification, L as updateAssetStatus, M as updateBridgeHealth, N as updateCheck, O as waitForTransition } from '../cn-CL0kdshO.cjs';
+export { C as ContentSegment, D as DEFAULT_CONFIG, a as DomEntityBox, b as DomLayoutData, c as DomOutputsBox, d as DomStateNode, e as DomTransitionLabel, f as DomTransitionPath, E as EntityDefinition, R as RenderOptions, S as StateDefinition, g as StateMachineDefinition, T as TraitSnapshotGetter, h as TransitionDefinition, V as VisualizerConfig, i as bindCanvasCapture, j as bindEventBus, k as bindLastDrawables, l as bindTraitStateGetter, m as clearVerification, n as cn, o as extractOutputsFromTransitions, p as extractStateMachine, q as formatGuard, r as getAllChecks, s as getBridgeHealth, t as getEffectSummary, u as getSnapshot, v as getSummary, w as getTraitSnapshots, x as getTransitions, y as getTransitionsForTrait, z as parseContentSegments, A as parseMarkdownWithCodeBlocks, B as recordServerResponse, F as recordTransition, G as registerCheck, H as registerTraitSnapshot, I as renderStateMachineToDomData, J as renderStateMachineToSvg, K as subscribeToVerification, L as updateAssetStatus, M as updateBridgeHealth, N as updateCheck, O as waitForTransition } from '../cn-rwc3svaX.cjs';
 import { FieldValue, EntityRow, EventPayload } from '@almadar/core';
 export { AssetLoadStatus, BridgeHealth, CheckStatus, EffectTrace, EventLogEntry, OrbitalVerificationAPI, ServerResponseTrace, TraitStateSnapshot, TransitionTrace, VerificationCheck, VerificationSnapshot, VerificationSummary } from '@almadar/core';
-import '../paintDispatch-DXygiK7M.cjs';
+import '../paintDispatch-BQn5Lyx1.cjs';
 import 'clsx';
 
 /**

package/dist/lib/index.d.ts

@@ -1,7 +1,7 @@
-export { C as ContentSegment, D as DEFAULT_CONFIG, a as DomEntityBox, b as DomLayoutData, c as DomOutputsBox, d as DomStateNode, e as DomTransitionLabel, f as DomTransitionPath, E as EntityDefinition, R as RenderOptions, S as StateDefinition, g as StateMachineDefinition, T as TraitSnapshotGetter, h as TransitionDefinition, V as VisualizerConfig, i as bindCanvasCapture, j as bindEventBus, k as bindLastDrawables, l as bindTraitStateGetter, m as clearVerification, n as cn, o as extractOutputsFromTransitions, p as extractStateMachine, q as formatGuard, r as getAllChecks, s as getBridgeHealth, t as getEffectSummary, u as getSnapshot, v as getSummary, w as getTraitSnapshots, x as getTransitions, y as getTransitionsForTrait, z as parseContentSegments, A as parseMarkdownWithCodeBlocks, B as recordServerResponse, F as recordTransition, G as registerCheck, H as registerTraitSnapshot, I as renderStateMachineToDomData, J as renderStateMachineToSvg, K as subscribeToVerification, L as updateAssetStatus, M as updateBridgeHealth, N as updateCheck, O as waitForTransition } from '../cn-CCaph5o9.js';
+export { C as ContentSegment, D as DEFAULT_CONFIG, a as DomEntityBox, b as DomLayoutData, c as DomOutputsBox, d as DomStateNode, e as DomTransitionLabel, f as DomTransitionPath, E as EntityDefinition, R as RenderOptions, S as StateDefinition, g as StateMachineDefinition, T as TraitSnapshotGetter, h as TransitionDefinition, V as VisualizerConfig, i as bindCanvasCapture, j as bindEventBus, k as bindLastDrawables, l as bindTraitStateGetter, m as clearVerification, n as cn, o as extractOutputsFromTransitions, p as extractStateMachine, q as formatGuard, r as getAllChecks, s as getBridgeHealth, t as getEffectSummary, u as getSnapshot, v as getSummary, w as getTraitSnapshots, x as getTransitions, y as getTransitionsForTrait, z as parseContentSegments, A as parseMarkdownWithCodeBlocks, B as recordServerResponse, F as recordTransition, G as registerCheck, H as registerTraitSnapshot, I as renderStateMachineToDomData, J as renderStateMachineToSvg, K as subscribeToVerification, L as updateAssetStatus, M as updateBridgeHealth, N as updateCheck, O as waitForTransition } from '../cn-BDwC4QpH.js';
 import { FieldValue, EntityRow, EventPayload } from '@almadar/core';
 export { AssetLoadStatus, BridgeHealth, CheckStatus, EffectTrace, EventLogEntry, OrbitalVerificationAPI, ServerResponseTrace, TraitStateSnapshot, TransitionTrace, VerificationCheck, VerificationSnapshot, VerificationSummary } from '@almadar/core';
-import '../paintDispatch-DXygiK7M.js';
+import '../paintDispatch-BQn5Lyx1.js';
 import 'clsx';
 
 /**

package/dist/{paintDispatch-DXygiK7M.d.cts → paintDispatch-BQn5Lyx1.d.cts}

@@ -17,6 +17,11 @@ interface PainterShadow {
     color: string;
     blur: 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
@@ -110,6 +115,86 @@ interface DrawSpriteProps extends DrawableBase {
  */
 
 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?: PainterPoint;
+    /** Linear end point in world units. */
+    to?: PainterPoint;
+    /** Radial/conic center in world units. */
+    center?: PainterPoint;
+    /** 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;
@@ -125,7 +210,7 @@ interface DrawShapeProps extends DrawableBase {
     radiusX?: number;
     /** Ellipse vertical radius in world units; omitted → `radiusX` (a circle). */
     radiusY?: number;
-    /** Fine nudge from the anchor point in world units. */
+    /** 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. */
@@ -133,8 +218,30 @@ interface DrawShapeProps extends DrawableBase {
     /** 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?: PainterPoint;
+    /** 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;
 }
@@ -187,10 +294,133 @@ interface DrawGroupProps extends DrawableBase {
     rotate?: number;
     /** 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[];
 }
 
+/**
+ * `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) 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';
+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;
+}
+/** 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[];
+}
+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;
+    /** 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. */
+    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;
+}
+
 /**
  * `draw-sprite-layer` — batch multiple sprites in one descriptor for O(layers) rendering.
  *
@@ -247,6 +477,6 @@ interface DrawTextLayerProps extends DrawableBase {
  */
 
 /** Every drawable descriptor. The host's `children` are a `DrawableNode[]`. */
-type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawGroupProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps;
+type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawGroupProps | DrawMeshProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps;
 
 export type { DrawableNode as D };

package/dist/{paintDispatch-DXygiK7M.d.ts → paintDispatch-BQn5Lyx1.d.ts}

@@ -17,6 +17,11 @@ interface PainterShadow {
     color: string;
     blur: 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
@@ -110,6 +115,86 @@ interface DrawSpriteProps extends DrawableBase {
  */
 
 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?: PainterPoint;
+    /** Linear end point in world units. */
+    to?: PainterPoint;
+    /** Radial/conic center in world units. */
+    center?: PainterPoint;
+    /** 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;
@@ -125,7 +210,7 @@ interface DrawShapeProps extends DrawableBase {
     radiusX?: number;
     /** Ellipse vertical radius in world units; omitted → `radiusX` (a circle). */
     radiusY?: number;
-    /** Fine nudge from the anchor point in world units. */
+    /** 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. */
@@ -133,8 +218,30 @@ interface DrawShapeProps extends DrawableBase {
     /** 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?: PainterPoint;
+    /** 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;
 }
@@ -187,10 +294,133 @@ interface DrawGroupProps extends DrawableBase {
     rotate?: number;
     /** 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[];
 }
 
+/**
+ * `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) 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';
+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;
+}
+/** 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[];
+}
+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;
+    /** 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. */
+    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;
+}
+
 /**
  * `draw-sprite-layer` — batch multiple sprites in one descriptor for O(layers) rendering.
  *
@@ -247,6 +477,6 @@ interface DrawTextLayerProps extends DrawableBase {
  */
 
 /** Every drawable descriptor. The host's `children` are a `DrawableNode[]`. */
-type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawGroupProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps;
+type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawGroupProps | DrawMeshProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps;
 
 export type { DrawableNode as D };