@almadar/ui 6.0.0 → 6.1.0

package/dist/lib/drawable/three/index.cjs

@@ -727,6 +727,7 @@ function resolveFxView(item, presets) {
     vy: item.vy ?? row.vy,
     vz: item.vz ?? row.vz,
     particleCount: item.particleCount ?? row.particleCount,
+    animation: item.animation ?? row.animation,
     shape: row.shape,
     count: row.count,
     glow: row.glow,
@@ -880,7 +881,10 @@ function expandFxItem(view, node, epochNowMs, dim) {
       anchor: "center",
       width: spriteSize,
       height: spriteSize,
-      opacity: fade
+      opacity: fade,
+      animation: view.animation ?? sprite.animations?.[0],
+      // One-shot fx rows (burst) play from the item's birth, not wall-time.
+      clockMs: ageMs
     });
   } else {
     out.push(...proceduralShapes(view, pos, fade, progress));

package/dist/lib/drawable/three/index.d.cts

@@ -1,12 +1,12 @@
-import { C as CanvasPointLightConfig, I as IsometricTile, a as IsometricUnit, b as IsometricFeature, A as ApplicationLevelData, O as OrbitalLevelData, T as TraitLevelData, c as TransitionLevelData } from '../../../avl-schema-parser-Do_LPV1o.cjs';
-export { d as Canvas3DHost, e as Canvas3DHostHandle, f as Canvas3DHostProps, d as GameCanvas3D, U as UnitAnimationState } from '../../../avl-schema-parser-Do_LPV1o.cjs';
+import { C as CanvasPointLightConfig, I as IsometricTile, a as IsometricUnit, b as IsometricFeature, A as ApplicationLevelData, O as OrbitalLevelData, T as TraitLevelData, c as TransitionLevelData } from '../../../avl-schema-parser-C6Yz2MuW.cjs';
+export { d as Canvas3DHost, e as Canvas3DHostHandle, f as Canvas3DHostProps, d as GameCanvas3D, U as UnitAnimationState } from '../../../avl-schema-parser-C6Yz2MuW.cjs';
 import * as React$1 from 'react';
 import React__default, { Component, ReactNode, ErrorInfo } from 'react';
 import * as THREE from 'three';
 import { QuadraticBezierCurve3 } from 'three';
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
 import { JsonObject, EventEmit, OrbitalSchema } from '@almadar/core';
-import '../../../paintDispatch-DgBctxIq.cjs';
+import '../../../paintDispatch-D3R8NNmV.cjs';
 import '../../../types-B3nHgnMG.cjs';
 
 /**

package/dist/lib/drawable/three/index.d.ts

@@ -1,12 +1,12 @@
-import { C as CanvasPointLightConfig, I as IsometricTile, a as IsometricUnit, b as IsometricFeature, A as ApplicationLevelData, O as OrbitalLevelData, T as TraitLevelData, c as TransitionLevelData } from '../../../avl-schema-parser-CLIm28Wa.js';
-export { d as Canvas3DHost, e as Canvas3DHostHandle, f as Canvas3DHostProps, d as GameCanvas3D, U as UnitAnimationState } from '../../../avl-schema-parser-CLIm28Wa.js';
+import { C as CanvasPointLightConfig, I as IsometricTile, a as IsometricUnit, b as IsometricFeature, A as ApplicationLevelData, O as OrbitalLevelData, T as TraitLevelData, c as TransitionLevelData } from '../../../avl-schema-parser-BKbH_SFt.js';
+export { d as Canvas3DHost, e as Canvas3DHostHandle, f as Canvas3DHostProps, d as GameCanvas3D, U as UnitAnimationState } from '../../../avl-schema-parser-BKbH_SFt.js';
 import * as React$1 from 'react';
 import React__default, { Component, ReactNode, ErrorInfo } from 'react';
 import * as THREE from 'three';
 import { QuadraticBezierCurve3 } from 'three';
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
 import { JsonObject, EventEmit, OrbitalSchema } from '@almadar/core';
-import '../../../paintDispatch-B5n2DTB-.js';
+import '../../../paintDispatch-B5ObLnUv.js';
 import '../../../types-B3nHgnMG.js';
 
 /**

package/dist/lib/drawable/three/index.js

@@ -703,6 +703,7 @@ function resolveFxView(item, presets) {
     vy: item.vy ?? row.vy,
     vz: item.vz ?? row.vz,
     particleCount: item.particleCount ?? row.particleCount,
+    animation: item.animation ?? row.animation,
     shape: row.shape,
     count: row.count,
     glow: row.glow,
@@ -856,7 +857,10 @@ function expandFxItem(view, node, epochNowMs, dim) {
       anchor: "center",
       width: spriteSize,
       height: spriteSize,
-      opacity: fade
+      opacity: fade,
+      animation: view.animation ?? sprite.animations?.[0],
+      // One-shot fx rows (burst) play from the item's birth, not wall-time.
+      clockMs: ageMs
     });
   } else {
     out.push(...proceduralShapes(view, pos, fade, progress));

package/dist/lib/index.d.cts

@@ -1,10 +1,10 @@
-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, L as LessonSegment, 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 parseLessonSegments, B as parseMarkdownWithCodeBlocks, F as recordServerResponse, G as recordTransition, H as registerCheck, I as registerTraitSnapshot, J as renderStateMachineToDomData, K as renderStateMachineToSvg, M as subscribeToVerification, N as updateAssetStatus, O as updateBridgeHealth, P as updateCheck, Q as waitForTransition } from '../cn-TH-RHihd.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, L as LessonSegment, 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 parseLessonSegments, B as parseMarkdownWithCodeBlocks, F as recordServerResponse, G as recordTransition, H as registerCheck, I as registerTraitSnapshot, J as renderStateMachineToDomData, K as renderStateMachineToSvg, M as subscribeToVerification, N as updateAssetStatus, O as updateBridgeHealth, P as updateCheck, Q as waitForTransition } from '../cn-DJSBBm5W.cjs';
 import { FieldValue, EntityRow, EventPayload } from '@almadar/core';
 export { AssetLoadStatus, BridgeHealth, CheckStatus, EffectTrace, EventLogEntry, OrbitalVerificationAPI, ServerResponseTrace, TraitStateSnapshot, TransitionTrace, VerificationCheck, VerificationSnapshot, VerificationSummary } from '@almadar/core';
 export { p as profilerOnRender, u as usePerfBuffer } from '../perf-DaVdsbU0.cjs';
 export { PERF_NAMESPACE, PerfEntry, clearPerf, perfEnd, perfGauge, perfStart, perfTime, perfTimeAsync } from '@almadar/runtime/ui';
 import 'react';
-import '../paintDispatch-DgBctxIq.cjs';
+import '../paintDispatch-D3R8NNmV.cjs';
 import '../types-B3nHgnMG.cjs';
 import 'clsx';
 

package/dist/lib/index.d.ts

@@ -1,10 +1,10 @@
-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, L as LessonSegment, 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 parseLessonSegments, B as parseMarkdownWithCodeBlocks, F as recordServerResponse, G as recordTransition, H as registerCheck, I as registerTraitSnapshot, J as renderStateMachineToDomData, K as renderStateMachineToSvg, M as subscribeToVerification, N as updateAssetStatus, O as updateBridgeHealth, P as updateCheck, Q as waitForTransition } from '../cn-CFurBb2q.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, L as LessonSegment, 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 parseLessonSegments, B as parseMarkdownWithCodeBlocks, F as recordServerResponse, G as recordTransition, H as registerCheck, I as registerTraitSnapshot, J as renderStateMachineToDomData, K as renderStateMachineToSvg, M as subscribeToVerification, N as updateAssetStatus, O as updateBridgeHealth, P as updateCheck, Q as waitForTransition } from '../cn-BbhJq_nr.js';
 import { FieldValue, EntityRow, EventPayload } from '@almadar/core';
 export { AssetLoadStatus, BridgeHealth, CheckStatus, EffectTrace, EventLogEntry, OrbitalVerificationAPI, ServerResponseTrace, TraitStateSnapshot, TransitionTrace, VerificationCheck, VerificationSnapshot, VerificationSummary } from '@almadar/core';
 export { p as profilerOnRender, u as usePerfBuffer } from '../perf-DaVdsbU0.js';
 export { PERF_NAMESPACE, PerfEntry, clearPerf, perfEnd, perfGauge, perfStart, perfTime, perfTimeAsync } from '@almadar/runtime/ui';
 import 'react';
-import '../paintDispatch-B5n2DTB-.js';
+import '../paintDispatch-B5ObLnUv.js';
 import '../types-B3nHgnMG.js';
 import 'clsx';
 

package/dist/marketing/index.d.cts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { EventKey, EventPayload, AssetUrl, Asset } from '@almadar/core';
+import { EventKey, EventPayload, EventEmit, AssetUrl, Asset } from '@almadar/core';
 import { LucideIcon } from 'lucide-react';
 
 /**
@@ -53,10 +53,14 @@ interface BoxProps extends React.HTMLAttributes<HTMLDivElement> {
     as?: React.ElementType;
     /** Declarative event name — emits UI:{action} via eventBus on click */
     action?: EventKey;
-    /** Payload to include with the action event */
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
     actionPayload?: EventPayload;
     /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave */
-    hoverEvent?: EventKey;
+    hoverEvent?: EventEmit<{
+        hovered: boolean;
+    }>;
     /** When true (default), a touch/pen tap also fires `hoverEvent` (toggling hovered) so hover-only reveals work on touch. */
     tapReveal?: boolean;
     /** Maximum width (CSS value, e.g., "550px", "80rem") */
@@ -113,7 +117,9 @@ interface StackProps {
     tabIndex?: number;
     /** Declarative event name — emits UI:{action} via eventBus on click */
     action?: EventKey;
-    /** Payload to include with the action event */
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
     actionPayload?: EventPayload;
     /** When true, horizontal stacks flip to vertical below the md breakpoint (768px) */
     responsive?: boolean;
@@ -272,7 +278,9 @@ interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
     iconAsset?: Asset;
     /** Declarative event name — emits UI:{action} via eventBus on click */
     action?: EventKey;
-    /** Payload to include with the action event */
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
     actionPayload?: EventPayload;
     /** Button label text (alternative to children for schema-driven rendering) */
     label?: string;

package/dist/marketing/index.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { EventKey, EventPayload, AssetUrl, Asset } from '@almadar/core';
+import { EventKey, EventPayload, EventEmit, AssetUrl, Asset } from '@almadar/core';
 import { LucideIcon } from 'lucide-react';
 
 /**
@@ -53,10 +53,14 @@ interface BoxProps extends React.HTMLAttributes<HTMLDivElement> {
     as?: React.ElementType;
     /** Declarative event name — emits UI:{action} via eventBus on click */
     action?: EventKey;
-    /** Payload to include with the action event */
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
     actionPayload?: EventPayload;
     /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave */
-    hoverEvent?: EventKey;
+    hoverEvent?: EventEmit<{
+        hovered: boolean;
+    }>;
     /** When true (default), a touch/pen tap also fires `hoverEvent` (toggling hovered) so hover-only reveals work on touch. */
     tapReveal?: boolean;
     /** Maximum width (CSS value, e.g., "550px", "80rem") */
@@ -113,7 +117,9 @@ interface StackProps {
     tabIndex?: number;
     /** Declarative event name — emits UI:{action} via eventBus on click */
     action?: EventKey;
-    /** Payload to include with the action event */
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
     actionPayload?: EventPayload;
     /** When true, horizontal stacks flip to vertical below the md breakpoint (768px) */
     responsive?: boolean;
@@ -272,7 +278,9 @@ interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
     iconAsset?: Asset;
     /** Declarative event name — emits UI:{action} via eventBus on click */
     action?: EventKey;
-    /** Payload to include with the action event */
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
     actionPayload?: EventPayload;
     /** Button label text (alternative to children for schema-driven rendering) */
     label?: string;

package/dist/{paintDispatch-B5n2DTB-.d.ts → paintDispatch-B5ObLnUv.d.ts}

@@ -1,6 +1,11 @@
 import { ScenePos, Asset } from '@almadar/core';
 import { P as Point, R as Rect } from './types-B3nHgnMG.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;
@@ -28,6 +33,31 @@ interface PainterGradientStop {
  * - `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;
@@ -222,6 +252,8 @@ interface DrawSpriteProps extends DrawableBase {
     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. */
@@ -573,6 +605,8 @@ interface FxItem {
     vz?: number;
     /** Sub-particle count override (procedural burst / confetti). */
     particleCount?: number;
+    /** Sprite-sheet animation name (e.g. "burst") — used when the resolved look is a sprite atlas. */
+    animation?: string;
 }
 /**
  * One row of a consumer-declared effect vocabulary: the look + recipe for one
@@ -605,6 +639,8 @@ interface FxPreset {
     effect?: FxOverlayKind;
     /** Sub-particle count for screen-space kinds (confetti/sparkle). */
     particleCount?: number;
+    /** Sprite-sheet animation name to play when this preset resolves to a sprite atlas. */
+    animation?: string;
 }
 /**
  * A screen-space fx entry as `fx-overlay` consumes it — the same mechanic rows,
@@ -695,4 +731,4 @@ interface DrawFxLayerProps extends DrawableBase {
 /** Every drawable descriptor. The host's `children` are a `DrawableNode[]`. */
 type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawGroupProps | DrawMeshProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps | DrawFxLayerProps;
 
-export type { DrawableNode as D, FxOverlayItem as F, MeshShapeKind as M, MeshMaterial as a, DrawGroupProps as b, DrawTextProps as c, DrawMeshProps as d, FxOverlayKind as e };
+export type { DrawableNode as D, FxOverlayItem as F, MeshShapeKind as M, Projector as P, MeshMaterial as a, DrawGroupProps as b, DrawTextProps as c, DrawMeshProps as d, FxOverlayKind as e };

package/dist/{paintDispatch-DgBctxIq.d.cts → paintDispatch-D3R8NNmV.d.cts}

@@ -1,6 +1,11 @@
 import { ScenePos, Asset } from '@almadar/core';
 import { P as Point, R as Rect } from './types-B3nHgnMG.cjs';
 
+/** 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;
@@ -28,6 +33,31 @@ interface PainterGradientStop {
  * - `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;
@@ -222,6 +252,8 @@ interface DrawSpriteProps extends DrawableBase {
     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. */
@@ -573,6 +605,8 @@ interface FxItem {
     vz?: number;
     /** Sub-particle count override (procedural burst / confetti). */
     particleCount?: number;
+    /** Sprite-sheet animation name (e.g. "burst") — used when the resolved look is a sprite atlas. */
+    animation?: string;
 }
 /**
  * One row of a consumer-declared effect vocabulary: the look + recipe for one
@@ -605,6 +639,8 @@ interface FxPreset {
     effect?: FxOverlayKind;
     /** Sub-particle count for screen-space kinds (confetti/sparkle). */
     particleCount?: number;
+    /** Sprite-sheet animation name to play when this preset resolves to a sprite atlas. */
+    animation?: string;
 }
 /**
  * A screen-space fx entry as `fx-overlay` consumes it — the same mechanic rows,
@@ -695,4 +731,4 @@ interface DrawFxLayerProps extends DrawableBase {
 /** Every drawable descriptor. The host's `children` are a `DrawableNode[]`. */
 type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawGroupProps | DrawMeshProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps | DrawFxLayerProps;
 
-export type { DrawableNode as D, FxOverlayItem as F, MeshShapeKind as M, MeshMaterial as a, DrawGroupProps as b, DrawTextProps as c, DrawMeshProps as d, FxOverlayKind as e };
+export type { DrawableNode as D, FxOverlayItem as F, MeshShapeKind as M, Projector as P, MeshMaterial as a, DrawGroupProps as b, DrawTextProps as c, DrawMeshProps as d, FxOverlayKind as e };

package/dist/providers/index.cjs

@@ -5874,6 +5874,7 @@ function resolveFxView(item, presets) {
     vy: item.vy ?? row.vy,
     vz: item.vz ?? row.vz,
     particleCount: item.particleCount ?? row.particleCount,
+    animation: item.animation ?? row.animation,
     shape: row.shape,
     count: row.count,
     glow: row.glow,
@@ -7406,9 +7407,6 @@ var init_isometric = __esm({
     };
   }
 });
-function isAnimationName(name) {
-  return core.ANIMATION_NAMES.includes(name);
-}
 function frameRect(frame, row, columns, frameWidth, frameHeight) {
   return {
     sx: frame % columns * frameWidth,
@@ -9342,13 +9340,17 @@ var init_DrawSprite = __esm({
           return;
         }
         if (isSpriteSheetAtlas(atlas)) {
-          const def = isAnimationName(node.animation) ? atlas.animations[node.animation] : void 0;
+          const def = atlas.animations[node.animation];
           if (!def) {
             paintFallbackSquare(painter, node, dctx, "sprite-missing");
             return;
           }
-          const { frame } = getCurrentFrameFromDef(node.loop === void 0 ? def : { ...def, loop: node.loop }, dctx.time);
+          const { frame } = getCurrentFrameFromDef(node.loop === void 0 ? def : { ...def, loop: node.loop }, node.clockMs ?? dctx.time);
           const r = frameRect(frame, def.row, atlas.columns, atlas.frameWidth, atlas.frameHeight);
+          if (![r.sx, r.sy, r.sw, r.sh].every(Number.isFinite)) {
+            paintFallbackSquare(painter, node, dctx, "sprite-missing");
+            return;
+          }
           src = { x: r.sx, y: r.sy, w: r.sw, h: r.sh };
         }
       }
@@ -9896,7 +9898,10 @@ function expandFxItem(view, node, epochNowMs, dim) {
       anchor: "center",
       width: spriteSize,
       height: spriteSize,
-      opacity: fade
+      opacity: fade,
+      animation: view.animation ?? sprite.animations?.[0],
+      // One-shot fx rows (burst) play from the item's birth, not wall-time.
+      clockMs: ageMs
     });
   } else {
     out.push(...proceduralShapes(view, pos, fade, progress));
@@ -11743,6 +11748,7 @@ var init_GameShell = __esm({
     init_Typography();
     init_AtlasImage();
     GAME_FONTS = {
+      fredoka: "Fredoka",
       future: "Kenney Future",
       "future-narrow": "Kenney Future Narrow",
       pixel: "Kenney Pixel",
@@ -11759,10 +11765,10 @@ var init_GameShell = __esm({
       showTopBar = true,
       children,
       backgroundAsset,
-      fontFamily = "future",
+      fontFamily,
       "data-theme": dataTheme
     }) => {
-      const font = GAME_FONTS[fontFamily] ?? fontFamily;
+      const font = fontFamily ? GAME_FONTS[fontFamily] ?? fontFamily : void 0;
       return /* @__PURE__ */ jsxRuntime.jsxs(
         Box,
         {
@@ -11777,8 +11783,11 @@ var init_GameShell = __esm({
             color: "var(--color-foreground, #e0e0e0)",
             // The fontFamily knob is a scoped override of the theme contract's
             // display slot: titles/numerics take the game face, body text keeps
-            // the active theme's --font-family-body.
-            "--font-family-display": `'${font}', ui-sans-serif, system-ui, sans-serif`
+            // the active theme's --font-family-body. Set ONLY when explicitly
+            // passed — an always-on inline stamp would shadow the orbital's
+            // inline-theme font-family-display token (inline style beats the
+            // theme provider's vars for the whole shell subtree).
+            ...font ? { "--font-family-display": `'${font}', ui-sans-serif, system-ui, sans-serif` } : {}
           },
           children: [
             backgroundAsset && /* @__PURE__ */ jsxRuntime.jsx(
@@ -12246,6 +12255,16 @@ function traceShapes(panel, k, width, height) {
   }
   return out;
 }
+function drawableNeedsAnimation(nodes) {
+  if (!nodes) return false;
+  return nodes.some((node) => {
+    if (node.type === "draw-sprite") return node.animation !== void 0;
+    if (node.type === "draw-fx-layer") return Array.isArray(node.items) && node.items.length > 0;
+    if (node.type === "draw-sprite-layer") return Array.isArray(node.items) && node.items.some((it) => it.animation !== void 0);
+    if (node.type === "draw-group") return Array.isArray(node.items) && drawableNeedsAnimation(node.items);
+    return false;
+  });
+}
 var DASH_PATTERNS, TRACE_SERIES_COLORS, LearningCanvas;
 var init_LearningCanvas = __esm({
   "components/learning/atoms/LearningCanvas.tsx"() {
@@ -12253,6 +12272,8 @@ var init_LearningCanvas = __esm({
     init_cn();
     init_perf();
     init_useEventBus();
+    init_webPainter2d();
+    init_paintDispatch();
     DASH_PATTERNS = { dashed: [6, 4], dotted: [2, 3] };
     TRACE_SERIES_COLORS = ["#2563eb", "#dc2626", "#16a34a", "#f59e0b"];
     LearningCanvas = ({
@@ -12261,6 +12282,8 @@ var init_LearningCanvas = __esm({
       height = 400,
       backgroundColor,
       shapes = [],
+      drawables,
+      projector,
       readouts,
       traces,
       interactive = false,
@@ -12274,6 +12297,9 @@ var init_LearningCanvas = __esm({
       const eventBus = useEventBus();
       const animRef = React87.useRef(0);
       const hoverIndexRef = React87.useRef(-1);
+      const [drawVersion, setDrawVersion] = React87.useState(0);
+      const invalidateRef = React87.useRef(() => setDrawVersion((v) => v + 1));
+      const needsAnim = React87.useMemo(() => drawableNeedsAnimation(drawables), [drawables]);
       const findShapeAt = React87.useCallback((clientX, clientY) => {
         const canvas = canvasRef.current;
         if (!canvas) return -1;
@@ -12317,20 +12343,29 @@ var init_LearningCanvas = __esm({
         for (const shape of derivedShapes) {
           if (shape.type === "text") drawShape(ctx, shape, width, height, derivedShapes);
         }
+        if (drawables?.length && projector) {
+          const painter = createWebPainter(ctx, invalidateRef.current);
+          const timeMs = needsAnim && typeof performance !== "undefined" ? performance.now() : 0;
+          const dctx = { projector, time: timeMs, invalidate: invalidateRef.current };
+          for (const node of drawables) {
+            paintDrawable(painter, node, dctx);
+          }
+        }
         ui.perfEnd("learningcanvas:paint", _perfT);
-      }, [width, height, backgroundColor, derivedShapes]);
+      }, [width, height, backgroundColor, derivedShapes, drawables, projector, needsAnim]);
       React87.useEffect(() => {
         draw();
-      }, [draw]);
+      }, [draw, drawVersion]);
       React87.useEffect(() => {
-        if (!animate) return;
+        const shouldAnimate = animate || needsAnim;
+        if (!shouldAnimate) return;
         const loop = () => {
           draw();
           animRef.current = requestAnimationFrame(loop);
         };
         animRef.current = requestAnimationFrame(loop);
         return () => cancelAnimationFrame(animRef.current);
-      }, [animate, draw]);
+      }, [animate, needsAnim, draw]);
       const handlePointerMove = React87.useCallback(
         (e) => {
           if (!interactive) return;
@@ -24972,8 +25007,9 @@ var init_DashboardLayout = __esm({
         if (notificationClickEvent) eventBus.emit(`UI:${notificationClickEvent}`, {});
         if (onNotificationClick) onNotificationClick();
       };
-      const handleTopBarActionClick = (event) => {
-        eventBus.emit(`UI:${event}`, {});
+      const handleTopBarActionClick = (action) => {
+        if (action.event) eventBus.emit(`UI:${action.event}`, {});
+        if (action.navigatesTo) eventBus.emit("UI:NAVIGATE", { url: action.navigatesTo });
       };
       const [sidebarOpen, setSidebarOpen] = React87.useState(false);
       const [userMenuOpen, setUserMenuOpen] = React87.useState(false);
@@ -25188,7 +25224,7 @@ var init_DashboardLayout = __esm({
                             {
                               variant: "ghost",
                               className: "relative p-2 rounded-full hover:bg-muted dark:hover:bg-muted",
-                              onClick: () => handleTopBarActionClick(action.event),
+                              onClick: () => handleTopBarActionClick(action),
                               "aria-label": action.label ?? (typeof action.icon === "string" ? action.icon : void 0),
                               children: [
                                 /* @__PURE__ */ jsxRuntime.jsx(Icon, { icon: action.icon, className: "h-5 w-5 text-muted-foreground dark:text-muted-foreground" }),
@@ -25205,7 +25241,7 @@ var init_DashboardLayout = __esm({
                                 )
                               ]
                             },
-                            `${action.event}-${idx}`
+                            `${action.event ?? action.navigatesTo ?? "action"}-${idx}`
                           )),
                           notificationsEnabled && /* @__PURE__ */ jsxRuntime.jsxs(
                             Button,
@@ -30867,6 +30903,7 @@ var init_MathCanvas = __esm({
       angles = [],
       hops = [],
       shapes = [],
+      drawables,
       readouts,
       traces,
       interactive = false,
@@ -31173,6 +31210,42 @@ var init_MathCanvas = __esm({
         hops,
         shapes
       ]);
+      const projector = React87.useMemo(() => {
+        if (!drawables?.length) return void 0;
+        const margin = 24;
+        const plotW = width - margin * 2;
+        const plotH = height - margin * 2;
+        const xScale = plotW / (xMax - xMin);
+        const mapX = (x) => margin + (x - xMin) / (xMax - xMin) * plotW;
+        const mapY = (y) => height - (margin + (y - yMin) / (yMax - yMin) * plotH);
+        const project = (pos) => ({ x: mapX(pos.x), y: mapY(pos.y) });
+        const anchorPoint = (pos, anchor) => {
+          const base = project(pos);
+          if (anchor === "top-left") return base;
+          const cx = base.x + xScale / 2;
+          if (anchor === "ground") return { x: cx, y: base.y + xScale * 0.92 };
+          return { x: cx, y: base.y + xScale / 2 };
+        };
+        const cellPath = (pos) => {
+          const base = project(pos);
+          return [
+            { x: base.x, y: base.y },
+            { x: base.x + xScale, y: base.y },
+            { x: base.x + xScale, y: base.y + xScale },
+            { x: base.x, y: base.y + xScale }
+          ];
+        };
+        return {
+          project,
+          anchorPoint,
+          cellPath,
+          tileWidth: xScale,
+          floorHeight: xScale / 2,
+          diamondTopY: 0,
+          squareGrid: true,
+          worldPixelDirect: false
+        };
+      }, [drawables?.length, width, height, xMin, xMax, yMin, yMax]);
       return /* @__PURE__ */ jsxRuntime.jsx(Card, { className, children: /* @__PURE__ */ jsxRuntime.jsxs(VStack, { gap: "sm", children: [
         title ? /* @__PURE__ */ jsxRuntime.jsx(Typography, { variant: "h4", children: title }) : null,
         /* @__PURE__ */ jsxRuntime.jsx(
@@ -31182,6 +31255,8 @@ var init_MathCanvas = __esm({
             height,
             backgroundColor,
             shapes: derivedShapes,
+            drawables,
+            projector,
             readouts,
             traces,
             interactive,
@@ -32411,7 +32486,7 @@ var init_MapView = __esm({
         shadowSize: [41, 41]
       });
       L.Marker.prototype.options.icon = defaultIcon;
-      const { useEffect: useEffect67, useRef: useRef65, useCallback: useCallback97, useState: useState97 } = React87__namespace.default;
+      const { useEffect: useEffect67, useRef: useRef65, useCallback: useCallback97, useState: useState98 } = React87__namespace.default;
       const { Typography: Typography2 } = await Promise.resolve().then(() => (init_Typography(), Typography_exports));
       const { useEventBus: useEventBus2 } = await Promise.resolve().then(() => (init_useEventBus(), useEventBus_exports));
       function MapUpdater({ centerLat, centerLng, zoom }) {
@@ -32456,7 +32531,7 @@ var init_MapView = __esm({
         showAttribution = true
       }) {
         const eventBus = useEventBus2();
-        const [clickedPosition, setClickedPosition] = useState97(null);
+        const [clickedPosition, setClickedPosition] = useState98(null);
         const handleMapClick = useCallback97((lat, lng) => {
           if (showClickedPin) {
             setClickedPosition({ lat, lng });