@almadar/ui 5.134.0 → 5.135.0

package/dist/lib/index.cjs

@@ -840,6 +840,32 @@ function formatValue(value, format) {
       return String(value);
   }
 }
+function compareCellValues(a, b) {
+  const aEmpty = a === null || a === void 0 || a === "";
+  const bEmpty = b === null || b === void 0 || b === "";
+  if (aEmpty || bEmpty) return aEmpty && bEmpty ? 0 : aEmpty ? 1 : -1;
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "boolean" && typeof b === "boolean") return Number(a) - Number(b);
+  const aNum = Number(a);
+  const bNum = Number(b);
+  if (Number.isFinite(aNum) && Number.isFinite(bNum)) return aNum - bNum;
+  const aTime = dateLikeTime(a);
+  const bTime = dateLikeTime(b);
+  if (aTime !== null && bTime !== null) return aTime - bTime;
+  return String(a).localeCompare(String(b));
+}
+function dateLikeTime(value) {
+  if (value instanceof Date) return value.getTime();
+  const text = String(value);
+  if (!/\d/.test(text) || !/[-/:T]/.test(text)) return null;
+  const time = Date.parse(text);
+  return Number.isNaN(time) ? null : time;
+}
+function sortRows(rows, field, direction = "asc") {
+  if (!field) return rows;
+  const dir = direction === "desc" ? -1 : 1;
+  return [...rows].sort((a, b) => dir * compareCellValues(a?.[field], b?.[field]));
+}
 
 // lib/getNestedValue.ts
 function getNestedValue(obj, path) {
@@ -1914,6 +1940,7 @@ exports.clearTicks = clearTicks;
 exports.clearTraits = clearTraits;
 exports.clearVerification = clearVerification;
 exports.cn = cn;
+exports.compareCellValues = compareCellValues;
 exports.computeJazariLayout = computeJazariLayout;
 exports.debug = debug;
 exports.debugCollision = debugCollision;
@@ -1988,6 +2015,7 @@ exports.renderStateMachineToSvg = renderStateMachineToSvg;
 exports.setDebugEnabled = setDebugEnabled;
 exports.setEntityProvider = setEntityProvider;
 exports.setTickActive = setTickActive;
+exports.sortRows = sortRows;
 exports.subscribeToDebugEvents = subscribeToDebugEvents;
 exports.subscribeToGuardChanges = subscribeToGuardChanges;
 exports.subscribeToTickChanges = subscribeToTickChanges;

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-D3H9UzCW.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-B8GXqrtp.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-BXJgISot.cjs';
+import '../paintDispatch-Bl2sfRFb.cjs';
 import 'clsx';
 
 /**
@@ -311,6 +311,24 @@ declare function formatDateTime(value: FieldValue | undefined): string;
  * of the declared format (a raw `true`/`false` cell is never intended output).
  */
 declare function formatValue(value: FieldValue | undefined, format?: string): string;
+/** Sort direction for {@link sortRows}. */
+type SortDirection = 'asc' | 'desc';
+/**
+ * Order two cell values by their own type, never by what the field is called.
+ *
+ * Numbers compare numerically, date-like strings chronologically, everything
+ * else by locale string order. `null`/`undefined` sort last in both directions
+ * so empty cells never displace real data at the top of a list.
+ */
+declare function compareCellValues(a: FieldValue | undefined, b: FieldValue | undefined): number;
+/**
+ * Return a new array ordered by `field`. Non-mutating, and a no-op without a
+ * field so callers can pass the prop through unconditionally.
+ *
+ * NOTE: this orders only the rows already fetched. A collection larger than its
+ * `limit` still needs ordering at the data layer — see `L-NO-COLLECTION-ORDERING`.
+ */
+declare function sortRows<T extends Record<string, FieldValue | undefined>>(rows: readonly T[], field?: string, direction?: SortDirection): readonly T[];
 
 /**
  * Get Nested Value Utility
@@ -531,4 +549,4 @@ declare function eightPointedStarPath(cx: number, cy: number, outerR: number, in
  */
 declare function arrowheadPath(size: number): string;
 
-export { ApiError, type DebugEvent, type DebugEventType, type EntitySnapshot, type EntityState, type GuardContext, type GuardEvaluation, JAZARI_COLORS, type JazariArmLayout, type JazariEffectInfo, type JazariGearLayout, type JazariGuardInfo, type JazariLayout, type LayoutInput, type LayoutState, type LayoutTransition, type PersistentEntityInfo, type RuntimeEntity, type TickExecution, type TraitDebugInfo, type TraitGuard, type TraitTransition, type ValueFormat, apiClient, arrowheadPath, brainIconPath, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, computeJazariLayout, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, eightPointedStarPath, formatDate, formatDateTime, formatNestedFieldLabel, formatTime, formatValue, gearTeethPath, getAllTicks, getAllTraits, getDebugEvents, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getTick, getTrait, humanizeEnumValue, humanizeFieldName, initDebugShortcut, isDebugEnabled, lockIconPath, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, pipeIconPath, recordGuardEvaluation, registerTick, registerTrait, setDebugEnabled, setEntityProvider, setTickActive, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, toggleDebug, unregisterTick, unregisterTrait, updateGuardResult, updateTickExecution, updateTraitState };
+export { ApiError, type DebugEvent, type DebugEventType, type EntitySnapshot, type EntityState, type GuardContext, type GuardEvaluation, JAZARI_COLORS, type JazariArmLayout, type JazariEffectInfo, type JazariGearLayout, type JazariGuardInfo, type JazariLayout, type LayoutInput, type LayoutState, type LayoutTransition, type PersistentEntityInfo, type RuntimeEntity, type SortDirection, type TickExecution, type TraitDebugInfo, type TraitGuard, type TraitTransition, type ValueFormat, apiClient, arrowheadPath, brainIconPath, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, compareCellValues, computeJazariLayout, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, eightPointedStarPath, formatDate, formatDateTime, formatNestedFieldLabel, formatTime, formatValue, gearTeethPath, getAllTicks, getAllTraits, getDebugEvents, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getTick, getTrait, humanizeEnumValue, humanizeFieldName, initDebugShortcut, isDebugEnabled, lockIconPath, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, pipeIconPath, recordGuardEvaluation, registerTick, registerTrait, setDebugEnabled, setEntityProvider, setTickActive, sortRows, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, toggleDebug, unregisterTick, unregisterTrait, updateGuardResult, updateTickExecution, updateTraitState };

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-Dm0VrLRG.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-CZq0uJLA.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-BXJgISot.js';
+import '../paintDispatch-Bl2sfRFb.js';
 import 'clsx';
 
 /**
@@ -311,6 +311,24 @@ declare function formatDateTime(value: FieldValue | undefined): string;
  * of the declared format (a raw `true`/`false` cell is never intended output).
  */
 declare function formatValue(value: FieldValue | undefined, format?: string): string;
+/** Sort direction for {@link sortRows}. */
+type SortDirection = 'asc' | 'desc';
+/**
+ * Order two cell values by their own type, never by what the field is called.
+ *
+ * Numbers compare numerically, date-like strings chronologically, everything
+ * else by locale string order. `null`/`undefined` sort last in both directions
+ * so empty cells never displace real data at the top of a list.
+ */
+declare function compareCellValues(a: FieldValue | undefined, b: FieldValue | undefined): number;
+/**
+ * Return a new array ordered by `field`. Non-mutating, and a no-op without a
+ * field so callers can pass the prop through unconditionally.
+ *
+ * NOTE: this orders only the rows already fetched. A collection larger than its
+ * `limit` still needs ordering at the data layer — see `L-NO-COLLECTION-ORDERING`.
+ */
+declare function sortRows<T extends Record<string, FieldValue | undefined>>(rows: readonly T[], field?: string, direction?: SortDirection): readonly T[];
 
 /**
  * Get Nested Value Utility
@@ -531,4 +549,4 @@ declare function eightPointedStarPath(cx: number, cy: number, outerR: number, in
  */
 declare function arrowheadPath(size: number): string;
 
-export { ApiError, type DebugEvent, type DebugEventType, type EntitySnapshot, type EntityState, type GuardContext, type GuardEvaluation, JAZARI_COLORS, type JazariArmLayout, type JazariEffectInfo, type JazariGearLayout, type JazariGuardInfo, type JazariLayout, type LayoutInput, type LayoutState, type LayoutTransition, type PersistentEntityInfo, type RuntimeEntity, type TickExecution, type TraitDebugInfo, type TraitGuard, type TraitTransition, type ValueFormat, apiClient, arrowheadPath, brainIconPath, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, computeJazariLayout, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, eightPointedStarPath, formatDate, formatDateTime, formatNestedFieldLabel, formatTime, formatValue, gearTeethPath, getAllTicks, getAllTraits, getDebugEvents, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getTick, getTrait, humanizeEnumValue, humanizeFieldName, initDebugShortcut, isDebugEnabled, lockIconPath, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, pipeIconPath, recordGuardEvaluation, registerTick, registerTrait, setDebugEnabled, setEntityProvider, setTickActive, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, toggleDebug, unregisterTick, unregisterTrait, updateGuardResult, updateTickExecution, updateTraitState };
+export { ApiError, type DebugEvent, type DebugEventType, type EntitySnapshot, type EntityState, type GuardContext, type GuardEvaluation, JAZARI_COLORS, type JazariArmLayout, type JazariEffectInfo, type JazariGearLayout, type JazariGuardInfo, type JazariLayout, type LayoutInput, type LayoutState, type LayoutTransition, type PersistentEntityInfo, type RuntimeEntity, type SortDirection, type TickExecution, type TraitDebugInfo, type TraitGuard, type TraitTransition, type ValueFormat, apiClient, arrowheadPath, brainIconPath, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, compareCellValues, computeJazariLayout, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, eightPointedStarPath, formatDate, formatDateTime, formatNestedFieldLabel, formatTime, formatValue, gearTeethPath, getAllTicks, getAllTraits, getDebugEvents, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getTick, getTrait, humanizeEnumValue, humanizeFieldName, initDebugShortcut, isDebugEnabled, lockIconPath, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, pipeIconPath, recordGuardEvaluation, registerTick, registerTrait, setDebugEnabled, setEntityProvider, setTickActive, sortRows, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, toggleDebug, unregisterTick, unregisterTrait, updateGuardResult, updateTickExecution, updateTraitState };

package/dist/lib/index.js

@@ -838,6 +838,32 @@ function formatValue(value, format) {
       return String(value);
   }
 }
+function compareCellValues(a, b) {
+  const aEmpty = a === null || a === void 0 || a === "";
+  const bEmpty = b === null || b === void 0 || b === "";
+  if (aEmpty || bEmpty) return aEmpty && bEmpty ? 0 : aEmpty ? 1 : -1;
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "boolean" && typeof b === "boolean") return Number(a) - Number(b);
+  const aNum = Number(a);
+  const bNum = Number(b);
+  if (Number.isFinite(aNum) && Number.isFinite(bNum)) return aNum - bNum;
+  const aTime = dateLikeTime(a);
+  const bTime = dateLikeTime(b);
+  if (aTime !== null && bTime !== null) return aTime - bTime;
+  return String(a).localeCompare(String(b));
+}
+function dateLikeTime(value) {
+  if (value instanceof Date) return value.getTime();
+  const text = String(value);
+  if (!/\d/.test(text) || !/[-/:T]/.test(text)) return null;
+  const time = Date.parse(text);
+  return Number.isNaN(time) ? null : time;
+}
+function sortRows(rows, field, direction = "asc") {
+  if (!field) return rows;
+  const dir = direction === "desc" ? -1 : 1;
+  return [...rows].sort((a, b) => dir * compareCellValues(a?.[field], b?.[field]));
+}
 
 // lib/getNestedValue.ts
 function getNestedValue(obj, path) {
@@ -1895,4 +1921,4 @@ var JAZARI_COLORS = {
   darkBg: "#1a1a2e"
 };
 
-export { ApiError, DEFAULT_CONFIG, JAZARI_COLORS, apiClient, arrowheadPath, bindCanvasCapture, bindEventBus, bindLastDrawables, bindTraitStateGetter, brainIconPath, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, clearVerification, cn, computeJazariLayout, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, eightPointedStarPath, extractOutputsFromTransitions, extractStateMachine, formatDate, formatDateTime, formatGuard, formatNestedFieldLabel, formatTime, formatValue, gearTeethPath, getAllChecks, getAllTicks, getAllTraits, getBridgeHealth, getDebugEvents, getEffectSummary, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getSnapshot, getSummary, getTick, getTrait, getTraitSnapshots, getTransitions, getTransitionsForTrait, humanizeEnumValue, humanizeFieldName, initDebugShortcut, isDebugEnabled, lockIconPath, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, parseContentSegments, parseMarkdownWithCodeBlocks, pipeIconPath, recordGuardEvaluation, recordServerResponse, recordTransition, registerCheck, registerTick, registerTrait, registerTraitSnapshot, renderStateMachineToDomData, renderStateMachineToSvg, setDebugEnabled, setEntityProvider, setTickActive, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, subscribeToVerification, toggleDebug, unregisterTick, unregisterTrait, updateAssetStatus, updateBridgeHealth, updateCheck, updateGuardResult, updateTickExecution, updateTraitState, waitForTransition };
+export { ApiError, DEFAULT_CONFIG, JAZARI_COLORS, apiClient, arrowheadPath, bindCanvasCapture, bindEventBus, bindLastDrawables, bindTraitStateGetter, brainIconPath, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, clearVerification, cn, compareCellValues, computeJazariLayout, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, eightPointedStarPath, extractOutputsFromTransitions, extractStateMachine, formatDate, formatDateTime, formatGuard, formatNestedFieldLabel, formatTime, formatValue, gearTeethPath, getAllChecks, getAllTicks, getAllTraits, getBridgeHealth, getDebugEvents, getEffectSummary, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getSnapshot, getSummary, getTick, getTrait, getTraitSnapshots, getTransitions, getTransitionsForTrait, humanizeEnumValue, humanizeFieldName, initDebugShortcut, isDebugEnabled, lockIconPath, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, parseContentSegments, parseMarkdownWithCodeBlocks, pipeIconPath, recordGuardEvaluation, recordServerResponse, recordTransition, registerCheck, registerTick, registerTrait, registerTraitSnapshot, renderStateMachineToDomData, renderStateMachineToSvg, setDebugEnabled, setEntityProvider, setTickActive, sortRows, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, subscribeToVerification, toggleDebug, unregisterTick, unregisterTrait, updateAssetStatus, updateBridgeHealth, updateCheck, updateGuardResult, updateTickExecution, updateTraitState, waitForTransition };

package/dist/{paintDispatch-BXJgISot.d.cts → paintDispatch-Bl2sfRFb.d.cts}

@@ -100,16 +100,16 @@ interface DrawSpriteProps extends DrawableBase {
  * 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, or a poly 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) 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
+ * 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';
+type ShapeKind = 'cell' | 'rect' | 'ellipse' | 'poly' | 'path';
 interface DrawShapeProps extends DrawableBase {
     type: 'draw-shape';
     shape: ShapeKind;
@@ -130,6 +130,8 @@ interface DrawShapeProps extends DrawableBase {
     offsetY?: number;
     /** Poly vertices as world-unit offsets relative to the cell's projected top-left. */
     points?: PainterPoint[];
+    /** SVG path data in world units relative to the cell's projected top-left — same coordinate convention as `points`. */
+    d?: string;
     fill?: string;
     stroke?: string;
     strokeWidth?: number;
@@ -162,6 +164,33 @@ 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;
+    /** The grouped drawables, painted through the normal dispatch. */
+    items: DrawableNode[];
+}
+
 /**
  * `draw-sprite-layer` — batch multiple sprites in one descriptor for O(layers) rendering.
  *
@@ -218,6 +247,6 @@ interface DrawTextLayerProps extends DrawableBase {
  */
 
 /** Every drawable descriptor. The host's `children` are a `DrawableNode[]`. */
-type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps;
+type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawGroupProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps;
 
 export type { DrawableNode as D };

package/dist/{paintDispatch-BXJgISot.d.ts → paintDispatch-Bl2sfRFb.d.ts}

@@ -100,16 +100,16 @@ interface DrawSpriteProps extends DrawableBase {
  * 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, or a poly 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) 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
+ * 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';
+type ShapeKind = 'cell' | 'rect' | 'ellipse' | 'poly' | 'path';
 interface DrawShapeProps extends DrawableBase {
     type: 'draw-shape';
     shape: ShapeKind;
@@ -130,6 +130,8 @@ interface DrawShapeProps extends DrawableBase {
     offsetY?: number;
     /** Poly vertices as world-unit offsets relative to the cell's projected top-left. */
     points?: PainterPoint[];
+    /** SVG path data in world units relative to the cell's projected top-left — same coordinate convention as `points`. */
+    d?: string;
     fill?: string;
     stroke?: string;
     strokeWidth?: number;
@@ -162,6 +164,33 @@ 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;
+    /** The grouped drawables, painted through the normal dispatch. */
+    items: DrawableNode[];
+}
+
 /**
  * `draw-sprite-layer` — batch multiple sprites in one descriptor for O(layers) rendering.
  *
@@ -218,6 +247,6 @@ interface DrawTextLayerProps extends DrawableBase {
  */
 
 /** Every drawable descriptor. The host's `children` are a `DrawableNode[]`. */
-type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps;
+type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawGroupProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps;
 
 export type { DrawableNode as D };