@almadar/ui 5.142.0 → 5.144.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-rwc3svaX.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-BdGFhYe3.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-BQn5Lyx1.cjs';
+import '../paintDispatch-Cb_hQj4Y.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-BDwC4QpH.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-DNkqAWZK.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-BQn5Lyx1.js';
+import '../paintDispatch-Cb_hQj4Y.js';
 import 'clsx';
 
 /**

package/dist/marketing/index.cjs

@@ -3343,6 +3343,10 @@ var atlasCache = /* @__PURE__ */ new Map();
 function isTilesheet(a) {
   return typeof a.tileWidth === "number";
 }
+function isSpriteSheetAtlas(a) {
+  const s = a;
+  return typeof s.frameWidth === "number" && typeof s.frameHeight === "number" && typeof s.animations === "object";
+}
 function getAtlas(url, onReady) {
   if (atlasCache.has(url)) return atlasCache.get(url) ?? void 0;
   atlasCache.set(url, void 0);
@@ -3379,6 +3383,7 @@ function subRectFor(atlas, sprite) {
       sh: atlas.tileHeight
     };
   }
+  if (isSpriteSheetAtlas(atlas)) return null;
   const st = atlas.subTextures[sprite];
   if (!st) return null;
   return { sx: st.x, sy: st.y, sw: st.width, sh: st.height };
@@ -3612,7 +3617,7 @@ var Button = React12__namespace.default.forwardRef(
         "data-testid": dataTestId ?? (action ? `action-${action}` : void 0),
         children: [
           isLoading ? /* @__PURE__ */ jsxRuntime.jsx(LucideIcons2.Loader2, { className: "h-icon-default w-icon-default animate-spin" }) : resolvedLeftIcon && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "flex-shrink-0", children: resolvedLeftIcon }),
-          children || label,
+          (Array.isArray(children) ? children.length > 0 : Boolean(children)) ? children : label,
           resolvedRightIcon && !isLoading && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "flex-shrink-0", children: resolvedRightIcon })
         ]
       }

package/dist/marketing/index.js

@@ -3322,6 +3322,10 @@ var atlasCache = /* @__PURE__ */ new Map();
 function isTilesheet(a) {
   return typeof a.tileWidth === "number";
 }
+function isSpriteSheetAtlas(a) {
+  const s = a;
+  return typeof s.frameWidth === "number" && typeof s.frameHeight === "number" && typeof s.animations === "object";
+}
 function getAtlas(url, onReady) {
   if (atlasCache.has(url)) return atlasCache.get(url) ?? void 0;
   atlasCache.set(url, void 0);
@@ -3358,6 +3362,7 @@ function subRectFor(atlas, sprite) {
       sh: atlas.tileHeight
     };
   }
+  if (isSpriteSheetAtlas(atlas)) return null;
   const st = atlas.subTextures[sprite];
   if (!st) return null;
   return { sx: st.x, sy: st.y, sw: st.width, sh: st.height };
@@ -3591,7 +3596,7 @@ var Button = React12__default.forwardRef(
         "data-testid": dataTestId ?? (action ? `action-${action}` : void 0),
         children: [
           isLoading ? /* @__PURE__ */ jsx(Loader2, { className: "h-icon-default w-icon-default animate-spin" }) : resolvedLeftIcon && /* @__PURE__ */ jsx("span", { className: "flex-shrink-0", children: resolvedLeftIcon }),
-          children || label,
+          (Array.isArray(children) ? children.length > 0 : Boolean(children)) ? children : label,
           resolvedRightIcon && !isLoading && /* @__PURE__ */ jsx("span", { className: "flex-shrink-0", children: resolvedRightIcon })
         ]
       }

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

@@ -87,8 +87,10 @@ interface DrawSpriteProps extends DrawableBase {
     height?: number;
     /** Explicit atlas sub-rect override (px); omitted → resolved from `asset.atlas`/`asset.sprite`. */
     frame?: BlitSrc;
-    /** Named GLB animation clip to play (3D backend only; the 2D painter animates via `frame`). Matched case-insensitively against the model's clips. */
+    /** 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;
     /** Mirror horizontally (facing). */
     flipX?: boolean;
     /** Rotation in radians about the sprite's center. */
@@ -271,42 +273,15 @@ interface DrawTextProps extends DrawableBase {
     opacity?: number;
 }
 
-/**
- * `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. 2D-canvas only — the 3D backend skips it with a warn.
- */
-
-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;
-    /** 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
+ * 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:
@@ -316,7 +291,7 @@ interface DrawGroupProps extends DrawableBase {
  * pattern and standalone pages stay inspectable.
  */
 
-type MeshShapeKind = 'box' | 'sphere' | 'capsule' | 'cylinder' | 'cone' | 'torus' | 'plane' | 'circle';
+type MeshShapeKind = 'box' | 'sphere' | 'capsule' | 'cylinder' | 'cone' | 'torus' | 'plane' | 'circle' | 'polyhedron';
 type MeshMaterialKind = 'standard' | 'physical' | 'toon' | 'basic';
 type MeshMaterialSide = 'front' | 'back' | 'double';
 /**
@@ -346,6 +321,8 @@ interface MeshMaterial {
     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 {
@@ -386,6 +363,22 @@ interface DrawMeshAnimation {
     /** 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;
@@ -407,9 +400,17 @@ interface DrawMeshProps extends DrawableBase {
     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. */
+    /** `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;
@@ -421,6 +422,51 @@ interface DrawMeshProps extends DrawableBase {
     opacity?: number;
 }
 
+/**
+ * `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[];
+}
+
 /**
  * `draw-sprite-layer` — batch multiple sprites in one descriptor for O(layers) rendering.
  *

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

@@ -87,8 +87,10 @@ interface DrawSpriteProps extends DrawableBase {
     height?: number;
     /** Explicit atlas sub-rect override (px); omitted → resolved from `asset.atlas`/`asset.sprite`. */
     frame?: BlitSrc;
-    /** Named GLB animation clip to play (3D backend only; the 2D painter animates via `frame`). Matched case-insensitively against the model's clips. */
+    /** 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;
     /** Mirror horizontally (facing). */
     flipX?: boolean;
     /** Rotation in radians about the sprite's center. */
@@ -271,42 +273,15 @@ interface DrawTextProps extends DrawableBase {
     opacity?: number;
 }
 
-/**
- * `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. 2D-canvas only — the 3D backend skips it with a warn.
- */
-
-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;
-    /** 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
+ * 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:
@@ -316,7 +291,7 @@ interface DrawGroupProps extends DrawableBase {
  * pattern and standalone pages stay inspectable.
  */
 
-type MeshShapeKind = 'box' | 'sphere' | 'capsule' | 'cylinder' | 'cone' | 'torus' | 'plane' | 'circle';
+type MeshShapeKind = 'box' | 'sphere' | 'capsule' | 'cylinder' | 'cone' | 'torus' | 'plane' | 'circle' | 'polyhedron';
 type MeshMaterialKind = 'standard' | 'physical' | 'toon' | 'basic';
 type MeshMaterialSide = 'front' | 'back' | 'double';
 /**
@@ -346,6 +321,8 @@ interface MeshMaterial {
     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 {
@@ -386,6 +363,22 @@ interface DrawMeshAnimation {
     /** 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;
@@ -407,9 +400,17 @@ interface DrawMeshProps extends DrawableBase {
     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. */
+    /** `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;
@@ -421,6 +422,51 @@ interface DrawMeshProps extends DrawableBase {
     opacity?: number;
 }
 
+/**
+ * `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[];
+}
+
 /**
  * `draw-sprite-layer` — batch multiple sprites in one descriptor for O(layers) rendering.
  *