@almadar/ui 5.112.0 → 5.113.0

package/dist/components/index.js

@@ -16072,14 +16072,16 @@ function Canvas2D({
   cameraPos,
   bgColor
 }) {
+  const instanceId = useMemo(() => Math.random().toString(36).slice(2, 8), []);
+  function isDrawableLayer(node) {
+    return node.type === "draw-sprite-layer" || node.type === "draw-shape-layer" || node.type === "draw-text-layer";
+  }
   const layerSummaries = drawables?.map((d) => {
-    if (!d || typeof d !== "object") return d;
-    const rec = d;
-    return { type: rec.type, itemsLen: Array.isArray(rec.items) ? rec.items.length : void 0, firstItem: Array.isArray(rec.items) ? rec.items[0] : void 0 };
+    if (!isDrawableLayer(d)) return { type: d.type };
+    return { type: d.type, itemsLen: d.items.length, firstItem: d.items[0] };
   });
-  console.error("[debug:Canvas2D] " + JSON.stringify({ projection, scale, cameraMode: camera, cameraPos, drawablesCount: drawables?.length, layerSummaries }));
+  canvas2DLog.debug("Canvas2D render", { instanceId, projection, scale, cameraMode: camera, cameraPos: cameraPos ? JSON.stringify(cameraPos) : void 0, drawablesCount: drawables?.length, layerSummaries: layerSummaries ? JSON.stringify(layerSummaries) : void 0 });
   const backgroundImage = normalizeBackdrop(backgroundImageRaw);
-  const instanceId = useMemo(() => Math.random().toString(36).slice(2, 8), []);
   const isFree = projection === "free";
   const squareGrid = projection === "flat" || isFree || projection === "side";
   const layout = projection === "side" ? "free" : projection;
@@ -16214,7 +16216,7 @@ function Canvas2D({
     }
     const containerRect = containerRef.current?.getBoundingClientRect();
     const canvasRect = canvas.getBoundingClientRect();
-    console.error("[debug:Canvas2D:draw:" + instanceId + "] " + JSON.stringify({ viewportSize, baseOffsetX, cam: { x: cam.x, y: cam.y, zoom: cam.zoom }, cameraPos, containerRect: containerRect ? { width: containerRect.width, height: containerRect.height } : null, canvasRect: canvasRect ? { width: canvasRect.width, height: canvasRect.height } : null }));
+    canvas2DLog.debug("Canvas2D draw", { instanceId, viewportSize, baseOffsetX, cam: { x: cam.x, y: cam.y, zoom: cam.zoom }, cameraPos: cameraPos ? JSON.stringify(cameraPos) : void 0, containerRect: containerRect ? { width: containerRect.width, height: containerRect.height } : null, canvasRect: canvasRect ? { width: canvasRect.width, height: canvasRect.height } : null });
     const painter = createWebPainter(ctx, bumpAtlas);
     painter.save();
     painter.translate(viewportSize.width / 2, viewportSize.height / 2);
@@ -16426,6 +16428,7 @@ function Canvas2D({
     }
   );
 }
+var canvas2DLog;
 var init_Canvas2D = __esm({
   "components/game/molecules/Canvas2D.tsx"() {
     "use client";
@@ -16447,6 +16450,7 @@ var init_Canvas2D = __esm({
     init_paintDispatch();
     init_hitTest();
     init_isometric();
+    canvas2DLog = createLogger("almadar:ui:game-canvas");
     Canvas2D.displayName = "Canvas2D";
   }
 });
@@ -16485,7 +16489,7 @@ function Canvas({
   keyMap,
   keyUpMap
 }) {
-  console.error("[debug:Canvas] " + JSON.stringify({ mode, drawablesCount: drawables?.length, projection, camera }));
+  canvasLog.debug("Canvas render", { mode, drawablesCount: drawables?.length, projection, camera: camera ? JSON.stringify(camera) : void 0 });
   const zoom = camera?.zoom;
   if (mode === "3d") {
     const props3d = {
@@ -16538,7 +16542,7 @@ function Canvas({
     }
   );
 }
-var Canvas3DHost;
+var Canvas3DHost, canvasLog;
 var init_Canvas = __esm({
   "components/game/molecules/Canvas.tsx"() {
     "use client";
@@ -16546,6 +16550,7 @@ var init_Canvas = __esm({
     Canvas3DHost = lazy(
       () => import('@almadar/ui/components/molecules/game/three').then((m) => ({ default: m.Canvas3DHost }))
     );
+    canvasLog = createLogger("almadar:ui:game-canvas");
     Canvas.displayName = "Canvas";
   }
 });

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

@@ -3,9 +3,10 @@ import React__default, { Component, ReactNode, ErrorInfo } from 'react';
 import { ScenePos, EventEmit, JsonObject, OrbitalSchema } from '@almadar/core';
 import * as THREE from 'three';
 import { QuadraticBezierCurve3 } from 'three';
-import { D as DrawableNode, 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-DKRm-nyh.cjs';
-export { U as UnitAnimationState } from '../../../avl-schema-parser-DKRm-nyh.cjs';
+import { D as DrawableNode } from '../../../paintDispatch-DR942knx.cjs';
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+import { 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-B8Onmfsu.cjs';
+export { U as UnitAnimationState } from '../../../avl-schema-parser-B8Onmfsu.cjs';
 
 /**
  * Canvas3DHost — the thin 3D draw-host: the `canvas` host's 3D painter backend

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

@@ -3,9 +3,10 @@ import React__default, { Component, ReactNode, ErrorInfo } from 'react';
 import { ScenePos, EventEmit, JsonObject, OrbitalSchema } from '@almadar/core';
 import * as THREE from 'three';
 import { QuadraticBezierCurve3 } from 'three';
-import { D as DrawableNode, 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-DKRm-nyh.js';
-export { U as UnitAnimationState } from '../../../avl-schema-parser-DKRm-nyh.js';
+import { D as DrawableNode } from '../../../paintDispatch-DR942knx.js';
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+import { 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-B8Onmfsu.js';
+export { U as UnitAnimationState } from '../../../avl-schema-parser-B8Onmfsu.js';
 
 /**
  * Canvas3DHost — the thin 3D draw-host: the `canvas` host's 3D painter backend

package/dist/lib/index.d.cts

@@ -1,6 +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-BbPvQLHt.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-BkQrMR01.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-DR942knx.cjs';
 import 'clsx';
 
 /**

package/dist/lib/index.d.ts

@@ -1,6 +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-BbPvQLHt.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-CTEFm9PC.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-DR942knx.js';
 import 'clsx';
 
 /**

package/dist/paintDispatch-DR942knx.d.cts

@@ -0,0 +1,221 @@
+import { ScenePos, Asset } from '@almadar/core';
+
+/** Source sub-rectangle within a texture (an atlas frame). Omitted → whole texture. */
+interface BlitSrc {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** A polyline/polygon vertex in pixel space. */
+interface PainterPoint {
+    x: number;
+    y: number;
+}
+/** A drop shadow applied to subsequent draws until cleared. */
+interface PainterShadow {
+    color: string;
+    blur: number;
+}
+
+/**
+ * Drawable contract — the shared vocabulary every neutral drawable primitive
+ * (the `draw-sprite`/`draw-shape`/`draw-text` atoms, `draw-sprite-layer`/
+ * `draw-shape-layer` molecules) is authored against. A drawable is a pure
+ * descriptor the canvas HOST walks and paints via the portable {@link Painter2D}
+ * seam — no `CanvasRenderingContext2D`, no DOM. Genre (a "unit"/"tile"/
+ * "highlight") is a `.lolo` COMPOSITION of these, never its own primitive.
+ *
+ * A position is a core `ScenePos` (logical scene space). The host's {@link Projector}
+ * maps it to pixels; primitives never do projection math themselves. Because the
+ * `ScenePos` type identity is what pattern-sync stamps as the `drawable`
+ * capability, every drawable descriptor's `position` MUST be a core `ScenePos`.
+ */
+
+/**
+ * How a drawable aligns to its projected position.
+ * - `top-left` — the cell's top-left corner (tiles).
+ * - `ground`   — the cell's ground point, bottom-center of the drawable (units/features).
+ * - `center`   — the cell's visual center (effects).
+ */
+type DrawableAnchor = 'top-left' | 'ground' | 'center';
+/** Common shape of every drawable descriptor. `type` keys the host's paint dispatch. */
+interface DrawableBase {
+    type: string;
+    /**
+     * Optional hit-test handle. When a board authors a per-entity id here (e.g.
+     * `id: (object/get @u id)` on a unit sprite), the canvas host indexes the
+     * descriptor's `ScenePos → id` and resolves a pointer/raycast at that cell to
+     * this id — the source of `unitClickEvent {unitId}`. A source-tagged handle,
+     * NOT a heuristic: no id → the host emits only the coordinate (tile click).
+     */
+    id?: string;
+}
+
+/**
+ * `draw-sprite` — the neutral image/atlas-frame drawable atom (dimension-agnostic).
+ *
+ * ONE descriptor (`DrawSpriteProps`, grounded in core `ScenePos` + `Asset`) with
+ * TWO backends: `paintSprite` (2D, here — via the portable `Painter2D` seam) and
+ * an R3F mesh (`Sprite3D` in `lib/drawable/mesh3d`, kept OUT of this file so the
+ * 2D paint path never pulls `three`/`drei` into an app bundle — the codebase
+ * code-splits R3F). The canvas host picks the backend by `mode`; that is what
+ * makes canvas-2d and canvas-3d the same `children` interface. Genre uses (tile,
+ * unit body, feature, effect, movement ghost, background cover) are all this atom
+ * with different `anchor`/`size`/`frame`/`flip`/`shadow` — composed in `.lolo`,
+ * not here. The React component renders `null` (a drawable is painted by the host,
+ * not the DOM); it exists so the pattern pipeline registers a `draw-sprite`
+ * pattern and standalone pages stay inspectable.
+ */
+
+interface DrawSpriteProps extends DrawableBase {
+    type: 'draw-sprite';
+    /** Logical scene position; the projector maps it to pixels / world. */
+    position: ScenePos;
+    /** The image / atlas reference to blit. */
+    asset: Asset;
+    /** How the sprite aligns to its projected position. Default `'top-left'`. */
+    anchor?: DrawableAnchor;
+    /** Draw width in world units (fractions of `projector.tileWidth`); omitted → resolved source width in px. */
+    width?: number;
+    /** Draw height in world units (fractions of `projector.tileWidth`); omitted → resolved source height in px. */
+    height?: number;
+    /** Explicit atlas sub-rect override (px); omitted → resolved from `asset.atlas`/`asset.sprite`. */
+    frame?: BlitSrc;
+    /** Mirror horizontally (facing). */
+    flipX?: boolean;
+    /** Rotation in radians about the sprite's center. */
+    rotation?: number;
+    /** 0..1 opacity. */
+    opacity?: number;
+    /** Drop shadow (e.g. a team-colored glow). */
+    shadow?: PainterShadow;
+}
+
+/**
+ * `draw-shape` — the neutral vector-fill/stroke drawable atom (dimension-agnostic).
+ *
+ * ONE descriptor (`DrawShapeProps`, grounded in core `ScenePos`) with TWO
+ * backends: `paintShape` (2D, here) and an R3F ground-plane mesh (`Shape3D` in
+ * `lib/drawable/mesh3d`, kept OUT of this file so the 2D path never pulls R3F).
+ * Paints a cell footprint, an axis-aligned rect, an ellipse, 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
+ * registers a `draw-shape` pattern and standalone pages stay inspectable.
+ */
+
+type ShapeKind = 'cell' | 'rect' | 'ellipse' | 'poly';
+interface DrawShapeProps extends DrawableBase {
+    type: 'draw-shape';
+    shape: ShapeKind;
+    /** Logical scene position; the projector maps it to pixels / world. */
+    position: ScenePos;
+    /** How the shape aligns to its projected position. Default varies by `shape`. */
+    anchor?: DrawableAnchor;
+    /** Rect width in world units (fractions of `projector.tileWidth`). */
+    width?: number;
+    /** Rect height in world units (fractions of `projector.tileWidth`). */
+    height?: number;
+    /** Ellipse horizontal radius in world units (fractions of `projector.tileWidth`). */
+    radiusX?: number;
+    /** Ellipse vertical radius in world units; omitted → `radiusX` (a circle). */
+    radiusY?: number;
+    /** Fine nudge from the anchor point in world units. */
+    offsetX?: number;
+    offsetY?: number;
+    /** Poly vertices as world-unit offsets relative to the cell's projected top-left. */
+    points?: PainterPoint[];
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    /** 0..1 opacity. */
+    opacity?: number;
+}
+
+/**
+ * `draw-text` — the neutral text drawable atom (dimension-agnostic).
+ *
+ * ONE descriptor (`DrawTextProps`, grounded in core `ScenePos`) with TWO backends:
+ * `paintText` (2D, here) and an R3F billboarded `<Text>` (`Text3D` in
+ * `lib/drawable/mesh3d`, kept OUT of this file so the 2D path never pulls R3F).
+ * Paints a string at a scene position with font/color/alignment. The React
+ * component renders `null` (a drawable is painted by the host, not the DOM).
+ */
+
+interface DrawTextProps extends DrawableBase {
+    type: 'draw-text';
+    text: string;
+    /** Logical scene position; the projector maps it to pixels / world. */
+    position: ScenePos;
+    anchor?: DrawableAnchor;
+    offsetX?: number;
+    offsetY?: number;
+    color: string;
+    font?: string;
+    align?: CanvasTextAlign;
+    baseline?: CanvasTextBaseline;
+    opacity?: number;
+}
+
+/**
+ * `draw-sprite-layer` — batch multiple sprites in one descriptor for O(layers) rendering.
+ *
+ * Composes the `draw-sprite` atom; the layer itself carries no `position` — each
+ * item does. It is drawable-by-composition: its `items` are `draw-sprite`
+ * descriptors (each grounded in core `ScenePos`), which is what stamps the layer
+ * `drawable` at pattern-sync time.
+ */
+
+interface DrawSpriteLayerProps extends DrawableBase {
+    type: 'draw-sprite-layer';
+    /** Sprites painted in array order; z-ordering is the caller's responsibility. */
+    items: DrawSpriteProps[];
+}
+
+/**
+ * `draw-shape-layer` — batch of shapes in one descriptor for O(layers) perf.
+ *
+ * Composes the `draw-shape` atom; drawable-by-composition (its `items` are
+ * `draw-shape` descriptors, each grounded in core `ScenePos`). The React
+ * component renders `null` (a drawable is painted by the host, not the DOM).
+ */
+
+interface DrawShapeLayerProps extends DrawableBase {
+    type: 'draw-shape-layer';
+    items: DrawShapeProps[];
+}
+
+/**
+ * `draw-text-layer` — batch of text labels in one descriptor for O(layers) perf.
+ *
+ * Composes the `draw-text` atom; drawable-by-composition (its `items` are
+ * `draw-text` descriptors, each grounded in core `ScenePos`). Covers the batched
+ * world-space text pass — fx messages, damage numbers, unit labels — that a
+ * board maps from an entity array (`items: (array/map @entity.fx (fn ...))`),
+ * which a literal `children` array can't express. The React component renders
+ * `null` (a drawable is painted by the host, not the DOM).
+ */
+
+interface DrawTextLayerProps extends DrawableBase {
+    type: 'draw-text-layer';
+    items: DrawTextProps[];
+}
+
+/**
+ * Drawable paint dispatch (2D) + the `DrawableNode` union.
+ *
+ * `paintDrawable` routes ONE descriptor to its 2D painter; the host walks its
+ * `children` through it. The "drawable" designation itself is NOT recorded here —
+ * it is DERIVED from the core `ScenePos` type each descriptor's `position` uses
+ * and stamped into `patterns-registry.json` by pattern-sync (mirroring how `Asset`
+ * is tagged), then read by the orbital-rust validator. So this module is pure
+ * paint routing; the capability is the registry's, not a hand-list.
+ */
+
+/** Every drawable descriptor. The host's `children` are a `DrawableNode[]`. */
+type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps;
+
+export type { DrawableNode as D };

package/dist/paintDispatch-DR942knx.d.ts

@@ -0,0 +1,221 @@
+import { ScenePos, Asset } from '@almadar/core';
+
+/** Source sub-rectangle within a texture (an atlas frame). Omitted → whole texture. */
+interface BlitSrc {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** A polyline/polygon vertex in pixel space. */
+interface PainterPoint {
+    x: number;
+    y: number;
+}
+/** A drop shadow applied to subsequent draws until cleared. */
+interface PainterShadow {
+    color: string;
+    blur: number;
+}
+
+/**
+ * Drawable contract — the shared vocabulary every neutral drawable primitive
+ * (the `draw-sprite`/`draw-shape`/`draw-text` atoms, `draw-sprite-layer`/
+ * `draw-shape-layer` molecules) is authored against. A drawable is a pure
+ * descriptor the canvas HOST walks and paints via the portable {@link Painter2D}
+ * seam — no `CanvasRenderingContext2D`, no DOM. Genre (a "unit"/"tile"/
+ * "highlight") is a `.lolo` COMPOSITION of these, never its own primitive.
+ *
+ * A position is a core `ScenePos` (logical scene space). The host's {@link Projector}
+ * maps it to pixels; primitives never do projection math themselves. Because the
+ * `ScenePos` type identity is what pattern-sync stamps as the `drawable`
+ * capability, every drawable descriptor's `position` MUST be a core `ScenePos`.
+ */
+
+/**
+ * How a drawable aligns to its projected position.
+ * - `top-left` — the cell's top-left corner (tiles).
+ * - `ground`   — the cell's ground point, bottom-center of the drawable (units/features).
+ * - `center`   — the cell's visual center (effects).
+ */
+type DrawableAnchor = 'top-left' | 'ground' | 'center';
+/** Common shape of every drawable descriptor. `type` keys the host's paint dispatch. */
+interface DrawableBase {
+    type: string;
+    /**
+     * Optional hit-test handle. When a board authors a per-entity id here (e.g.
+     * `id: (object/get @u id)` on a unit sprite), the canvas host indexes the
+     * descriptor's `ScenePos → id` and resolves a pointer/raycast at that cell to
+     * this id — the source of `unitClickEvent {unitId}`. A source-tagged handle,
+     * NOT a heuristic: no id → the host emits only the coordinate (tile click).
+     */
+    id?: string;
+}
+
+/**
+ * `draw-sprite` — the neutral image/atlas-frame drawable atom (dimension-agnostic).
+ *
+ * ONE descriptor (`DrawSpriteProps`, grounded in core `ScenePos` + `Asset`) with
+ * TWO backends: `paintSprite` (2D, here — via the portable `Painter2D` seam) and
+ * an R3F mesh (`Sprite3D` in `lib/drawable/mesh3d`, kept OUT of this file so the
+ * 2D paint path never pulls `three`/`drei` into an app bundle — the codebase
+ * code-splits R3F). The canvas host picks the backend by `mode`; that is what
+ * makes canvas-2d and canvas-3d the same `children` interface. Genre uses (tile,
+ * unit body, feature, effect, movement ghost, background cover) are all this atom
+ * with different `anchor`/`size`/`frame`/`flip`/`shadow` — composed in `.lolo`,
+ * not here. The React component renders `null` (a drawable is painted by the host,
+ * not the DOM); it exists so the pattern pipeline registers a `draw-sprite`
+ * pattern and standalone pages stay inspectable.
+ */
+
+interface DrawSpriteProps extends DrawableBase {
+    type: 'draw-sprite';
+    /** Logical scene position; the projector maps it to pixels / world. */
+    position: ScenePos;
+    /** The image / atlas reference to blit. */
+    asset: Asset;
+    /** How the sprite aligns to its projected position. Default `'top-left'`. */
+    anchor?: DrawableAnchor;
+    /** Draw width in world units (fractions of `projector.tileWidth`); omitted → resolved source width in px. */
+    width?: number;
+    /** Draw height in world units (fractions of `projector.tileWidth`); omitted → resolved source height in px. */
+    height?: number;
+    /** Explicit atlas sub-rect override (px); omitted → resolved from `asset.atlas`/`asset.sprite`. */
+    frame?: BlitSrc;
+    /** Mirror horizontally (facing). */
+    flipX?: boolean;
+    /** Rotation in radians about the sprite's center. */
+    rotation?: number;
+    /** 0..1 opacity. */
+    opacity?: number;
+    /** Drop shadow (e.g. a team-colored glow). */
+    shadow?: PainterShadow;
+}
+
+/**
+ * `draw-shape` — the neutral vector-fill/stroke drawable atom (dimension-agnostic).
+ *
+ * ONE descriptor (`DrawShapeProps`, grounded in core `ScenePos`) with TWO
+ * backends: `paintShape` (2D, here) and an R3F ground-plane mesh (`Shape3D` in
+ * `lib/drawable/mesh3d`, kept OUT of this file so the 2D path never pulls R3F).
+ * Paints a cell footprint, an axis-aligned rect, an ellipse, 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
+ * registers a `draw-shape` pattern and standalone pages stay inspectable.
+ */
+
+type ShapeKind = 'cell' | 'rect' | 'ellipse' | 'poly';
+interface DrawShapeProps extends DrawableBase {
+    type: 'draw-shape';
+    shape: ShapeKind;
+    /** Logical scene position; the projector maps it to pixels / world. */
+    position: ScenePos;
+    /** How the shape aligns to its projected position. Default varies by `shape`. */
+    anchor?: DrawableAnchor;
+    /** Rect width in world units (fractions of `projector.tileWidth`). */
+    width?: number;
+    /** Rect height in world units (fractions of `projector.tileWidth`). */
+    height?: number;
+    /** Ellipse horizontal radius in world units (fractions of `projector.tileWidth`). */
+    radiusX?: number;
+    /** Ellipse vertical radius in world units; omitted → `radiusX` (a circle). */
+    radiusY?: number;
+    /** Fine nudge from the anchor point in world units. */
+    offsetX?: number;
+    offsetY?: number;
+    /** Poly vertices as world-unit offsets relative to the cell's projected top-left. */
+    points?: PainterPoint[];
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    /** 0..1 opacity. */
+    opacity?: number;
+}
+
+/**
+ * `draw-text` — the neutral text drawable atom (dimension-agnostic).
+ *
+ * ONE descriptor (`DrawTextProps`, grounded in core `ScenePos`) with TWO backends:
+ * `paintText` (2D, here) and an R3F billboarded `<Text>` (`Text3D` in
+ * `lib/drawable/mesh3d`, kept OUT of this file so the 2D path never pulls R3F).
+ * Paints a string at a scene position with font/color/alignment. The React
+ * component renders `null` (a drawable is painted by the host, not the DOM).
+ */
+
+interface DrawTextProps extends DrawableBase {
+    type: 'draw-text';
+    text: string;
+    /** Logical scene position; the projector maps it to pixels / world. */
+    position: ScenePos;
+    anchor?: DrawableAnchor;
+    offsetX?: number;
+    offsetY?: number;
+    color: string;
+    font?: string;
+    align?: CanvasTextAlign;
+    baseline?: CanvasTextBaseline;
+    opacity?: number;
+}
+
+/**
+ * `draw-sprite-layer` — batch multiple sprites in one descriptor for O(layers) rendering.
+ *
+ * Composes the `draw-sprite` atom; the layer itself carries no `position` — each
+ * item does. It is drawable-by-composition: its `items` are `draw-sprite`
+ * descriptors (each grounded in core `ScenePos`), which is what stamps the layer
+ * `drawable` at pattern-sync time.
+ */
+
+interface DrawSpriteLayerProps extends DrawableBase {
+    type: 'draw-sprite-layer';
+    /** Sprites painted in array order; z-ordering is the caller's responsibility. */
+    items: DrawSpriteProps[];
+}
+
+/**
+ * `draw-shape-layer` — batch of shapes in one descriptor for O(layers) perf.
+ *
+ * Composes the `draw-shape` atom; drawable-by-composition (its `items` are
+ * `draw-shape` descriptors, each grounded in core `ScenePos`). The React
+ * component renders `null` (a drawable is painted by the host, not the DOM).
+ */
+
+interface DrawShapeLayerProps extends DrawableBase {
+    type: 'draw-shape-layer';
+    items: DrawShapeProps[];
+}
+
+/**
+ * `draw-text-layer` — batch of text labels in one descriptor for O(layers) perf.
+ *
+ * Composes the `draw-text` atom; drawable-by-composition (its `items` are
+ * `draw-text` descriptors, each grounded in core `ScenePos`). Covers the batched
+ * world-space text pass — fx messages, damage numbers, unit labels — that a
+ * board maps from an entity array (`items: (array/map @entity.fx (fn ...))`),
+ * which a literal `children` array can't express. The React component renders
+ * `null` (a drawable is painted by the host, not the DOM).
+ */
+
+interface DrawTextLayerProps extends DrawableBase {
+    type: 'draw-text-layer';
+    items: DrawTextProps[];
+}
+
+/**
+ * Drawable paint dispatch (2D) + the `DrawableNode` union.
+ *
+ * `paintDrawable` routes ONE descriptor to its 2D painter; the host walks its
+ * `children` through it. The "drawable" designation itself is NOT recorded here —
+ * it is DERIVED from the core `ScenePos` type each descriptor's `position` uses
+ * and stamped into `patterns-registry.json` by pattern-sync (mirroring how `Asset`
+ * is tagged), then read by the orbital-rust validator. So this module is pure
+ * paint routing; the capability is the registry's, not a hand-list.
+ */
+
+/** Every drawable descriptor. The host's `children` are a `DrawableNode[]`. */
+type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps;
+
+export type { DrawableNode as D };

package/dist/providers/index.cjs

@@ -9503,14 +9503,16 @@ function Canvas2D({
   cameraPos,
   bgColor
 }) {
+  const instanceId = React83.useMemo(() => Math.random().toString(36).slice(2, 8), []);
+  function isDrawableLayer(node) {
+    return node.type === "draw-sprite-layer" || node.type === "draw-shape-layer" || node.type === "draw-text-layer";
+  }
   const layerSummaries = drawables?.map((d) => {
-    if (!d || typeof d !== "object") return d;
-    const rec = d;
-    return { type: rec.type, itemsLen: Array.isArray(rec.items) ? rec.items.length : void 0, firstItem: Array.isArray(rec.items) ? rec.items[0] : void 0 };
+    if (!isDrawableLayer(d)) return { type: d.type };
+    return { type: d.type, itemsLen: d.items.length, firstItem: d.items[0] };
   });
-  console.error("[debug:Canvas2D] " + JSON.stringify({ projection, scale, cameraMode: camera, cameraPos, drawablesCount: drawables?.length, layerSummaries }));
+  canvas2DLog.debug("Canvas2D render", { instanceId, projection, scale, cameraMode: camera, cameraPos: cameraPos ? JSON.stringify(cameraPos) : void 0, drawablesCount: drawables?.length, layerSummaries: layerSummaries ? JSON.stringify(layerSummaries) : void 0 });
   const backgroundImage = normalizeBackdrop(backgroundImageRaw);
-  const instanceId = React83.useMemo(() => Math.random().toString(36).slice(2, 8), []);
   const isFree = projection === "free";
   const squareGrid = projection === "flat" || isFree || projection === "side";
   const layout = projection === "side" ? "free" : projection;
@@ -9645,7 +9647,7 @@ function Canvas2D({
     }
     const containerRect = containerRef.current?.getBoundingClientRect();
     const canvasRect = canvas.getBoundingClientRect();
-    console.error("[debug:Canvas2D:draw:" + instanceId + "] " + JSON.stringify({ viewportSize, baseOffsetX, cam: { x: cam.x, y: cam.y, zoom: cam.zoom }, cameraPos, containerRect: containerRect ? { width: containerRect.width, height: containerRect.height } : null, canvasRect: canvasRect ? { width: canvasRect.width, height: canvasRect.height } : null }));
+    canvas2DLog.debug("Canvas2D draw", { instanceId, viewportSize, baseOffsetX, cam: { x: cam.x, y: cam.y, zoom: cam.zoom }, cameraPos: cameraPos ? JSON.stringify(cameraPos) : void 0, containerRect: containerRect ? { width: containerRect.width, height: containerRect.height } : null, canvasRect: canvasRect ? { width: canvasRect.width, height: canvasRect.height } : null });
     const painter = createWebPainter(ctx, bumpAtlas);
     painter.save();
     painter.translate(viewportSize.width / 2, viewportSize.height / 2);
@@ -9857,6 +9859,7 @@ function Canvas2D({
     }
   );
 }
+var canvas2DLog;
 var init_Canvas2D = __esm({
   "components/game/molecules/Canvas2D.tsx"() {
     "use client";
@@ -9878,6 +9881,7 @@ var init_Canvas2D = __esm({
     init_paintDispatch();
     init_hitTest();
     init_isometric();
+    canvas2DLog = logger.createLogger("almadar:ui:game-canvas");
     Canvas2D.displayName = "Canvas2D";
   }
 });
@@ -9916,7 +9920,7 @@ function Canvas({
   keyMap,
   keyUpMap
 }) {
-  console.error("[debug:Canvas] " + JSON.stringify({ mode, drawablesCount: drawables?.length, projection, camera }));
+  canvasLog.debug("Canvas render", { mode, drawablesCount: drawables?.length, projection, camera: camera ? JSON.stringify(camera) : void 0 });
   const zoom = camera?.zoom;
   if (mode === "3d") {
     const props3d = {
@@ -9969,7 +9973,7 @@ function Canvas({
     }
   );
 }
-var Canvas3DHost;
+var Canvas3DHost, canvasLog;
 var init_Canvas = __esm({
   "components/game/molecules/Canvas.tsx"() {
     "use client";
@@ -9977,6 +9981,7 @@ var init_Canvas = __esm({
     Canvas3DHost = React83.lazy(
       () => import('@almadar/ui/components/molecules/game/three').then((m) => ({ default: m.Canvas3DHost }))
     );
+    canvasLog = logger.createLogger("almadar:ui:game-canvas");
     Canvas.displayName = "Canvas";
   }
 });