@almadar/ui 5.105.0 → 5.107.0

package/dist/lib/drawable/Drawable3D.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Drawable3D — the R3F dispatcher for neutral drawable descriptors.
+ *
+ * The 3D twin of `paintDrawable`: given ONE descriptor, it renders the matching
+ * R3F element (mesh/billboard). ⚠ R3F throws if a plain descriptor object reaches
+ * `<group>{children}` — the host must ALWAYS map descriptors through THIS
+ * component first, never pass raw `DrawableNode`s as children. Consumes the same
+ * `DrawSpriteProps`/`DrawShapeProps`/`DrawTextProps` descriptors as the 2D paint
+ * dispatch — that is what makes canvas-2d and canvas-3d the same `children`
+ * interface.
+ */
+import React from 'react';
+import type { Projector3D } from './projector3d';
+import type { DrawableNode } from './paintDispatch';
+export interface Drawable3DProps {
+    node: DrawableNode;
+    projector: Projector3D;
+}
+export declare function Drawable3D({ node, projector }: Drawable3DProps): React.JSX.Element | null;
+export default Drawable3D;

package/dist/lib/drawable/contract.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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`.
+ */
+import type { ScenePos } from '@almadar/core';
+import type { Painter2D, PainterPoint } from '../painter2d';
+/**
+ * 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).
+ */
+export 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).
+ */
+export 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[];
+    /** Scaled cell width in px (`TILE_WIDTH * scale`). */
+    readonly tileWidth: number;
+    /** Scaled floor/diamond height in px (`FLOOR_HEIGHT * scale`). */
+    readonly floorHeight: number;
+    /** Scaled diamond-top offset in px (`DIAMOND_TOP_Y * scale`). */
+    readonly diamondTopY: number;
+    /** Render scale factor. */
+    readonly scale: number;
+    /** True for square-pitch grids (`flat`/`free`); false for diamond (iso/hex). */
+    readonly squareGrid: boolean;
+}
+/** Per-frame context handed to every paint fn. */
+export interface DrawContext {
+    projector: Projector;
+    /** Animation clock in ms (0 when static). Reserved for a LOLO-driven pulse/breathe input. */
+    time: number;
+    /** Force a host re-draw once an async resource (image / atlas JSON) has loaded. */
+    invalidate: () => void;
+}
+/** Common shape of every drawable descriptor. `type` keys the host's paint dispatch. */
+export 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;
+}
+/** A paint function: draws one descriptor of type `T` to the painter. */
+export type PaintFn<T extends DrawableBase> = (painter: Painter2D, node: T, dctx: DrawContext) => void;

package/dist/lib/drawable/hitTest.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Drawable click hit-test — the shared walk both canvas hosts (2D + 3D) use to
+ * resolve a pointer/raycast at a scene cell to a per-entity id.
+ *
+ * A drawable descriptor carries an optional source-tagged `id` (see
+ * {@link DrawableBase.id}); a board tags its unit sprites (`id: (@u id)`). The
+ * host collects every drawn descriptor's `ScenePos` + `id`, builds a
+ * `"x,y" → id` index (later descriptors win, so a unit drawn over its tile takes
+ * the cell), and a click that lands on a tagged cell becomes `unitClick {unitId}`.
+ * No id → the host emits only the coordinate (tile click). One owner, both hosts —
+ * no per-host duplicate walker.
+ */
+import type { ScenePos } from '@almadar/core';
+import type { DrawableNode } from './paintDispatch';
+/** One drawn descriptor's scene position + optional hit-test id. */
+export interface DrawnItem {
+    pos: ScenePos;
+    id?: string;
+}
+/** Collect every drawable's scene position + hit id (atoms directly; layers via `items`). */
+export declare function collectDrawnItems(nodes: DrawableNode[]): DrawnItem[];
+/** Build the `"x,y" → id` cell index from the tagged descriptors (later wins). */
+export declare function buildHitIndex(items: DrawnItem[]): Map<string, string>;

package/dist/lib/drawable/mesh3d.d.ts

@@ -0,0 +1,28 @@
+/**
+ * R3F mesh backends for the neutral drawable atoms — the 3D twin of the atoms'
+ * 2D `paint*` fns. Kept HERE (not in the atom files) so the `three`/`drei`/`fiber`
+ * dependency stays out of the 2D paint path; only the 3D dispatcher `Drawable3D`
+ * (→ used by `GameCanvas3D`, itself in the code-split 3D surface) imports this.
+ * Each mesh consumes the SAME descriptor as its 2D painter, so canvas-2d and
+ * canvas-3d render the same `children`.
+ */
+import React from 'react';
+import type { DrawSpriteProps } from '../../components/game/atoms/DrawSprite';
+import type { DrawShapeProps } from '../../components/game/atoms/DrawShape';
+import type { DrawTextProps } from '../../components/game/atoms/DrawText';
+import type { Projector3D } from './projector3d';
+/** R3F mesh backend for `draw-sprite`: a GLB via `ModelLoader` when `asset.dimension === '3d'`; else a billboard. */
+export declare function Sprite3D({ node, projector }: {
+    node: DrawSpriteProps;
+    projector: Projector3D;
+}): React.JSX.Element | null;
+/** R3F mesh backend for `draw-shape`: a flat mesh on the ground plane. */
+export declare function Shape3D({ node, projector }: {
+    node: DrawShapeProps;
+    projector: Projector3D;
+}): React.JSX.Element | null;
+/** R3F mesh backend for `draw-text`: a billboarded drei `<Text>` above the scene position. */
+export declare function Text3D({ node, projector }: {
+    node: DrawTextProps;
+    projector: Projector3D;
+}): React.JSX.Element | null;

package/dist/lib/drawable/paintDispatch.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+import type { Painter2D } from '../painter2d';
+import type { DrawContext } from './contract';
+import { type DrawSpriteProps } from '../../components/game/atoms/DrawSprite';
+import { type DrawShapeProps } from '../../components/game/atoms/DrawShape';
+import { type DrawTextProps } from '../../components/game/atoms/DrawText';
+import { type DrawSpriteLayerProps } from '../../components/game/molecules/DrawSpriteLayer';
+import { type DrawShapeLayerProps } from '../../components/game/molecules/DrawShapeLayer';
+import { type DrawTextLayerProps } from '../../components/game/molecules/DrawTextLayer';
+/** Every drawable descriptor. The host's `children` are a `DrawableNode[]`. */
+export type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps;
+/** Dispatch a drawable descriptor to its 2D painter. Unknown types are skipped — never throws. */
+export declare function paintDrawable(painter: Painter2D, node: DrawableNode, dctx: DrawContext): void;

package/dist/lib/drawable/projector.d.ts

@@ -0,0 +1,14 @@
+import type { Projector } from './contract';
+import { type TileLayout } from '../../components/game/lib/isometric';
+/** Projection modes the 2D host supports. `side` is handled by the side host, not here. */
+export type Projection2D = TileLayout | 'free';
+export interface Projector2DOptions {
+    scale: number;
+    /** Horizontal offset that centers the grid (0 for `flat`/`free`). */
+    baseOffsetX: number;
+    layout: Projection2D;
+    /** Override the measured diamond-top offset (default `DIAMOND_TOP_Y`). */
+    diamondTopY?: number;
+}
+/** Build a {@link Projector} for a 2D projection. */
+export declare function create2DProjector(opts: Projector2DOptions): Projector;

package/dist/lib/drawable/projector3d.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 3D projector — maps a core `ScenePos` to an R3F world position, mirroring the
+ * `gridToWorld` convention in `grid3D.ts` (grid X → world X, grid Y → world Z on
+ * the ground plane, scene Z → world Y as height). The 3D twin of `create2DProjector`;
+ * the SAME drawable descriptors flow to both, only the renderer differs (mesh vs paint).
+ */
+import type { ScenePos } from '@almadar/core';
+export interface Projector3D {
+    /** Scene position → `[x, y, z]` world position (y is up). */
+    toWorld(pos: ScenePos): [number, number, number];
+    /** World units per grid cell. */
+    readonly cellSize: number;
+}
+export interface Projector3DOptions {
+    cellSize?: number;
+    offsetX?: number;
+    offsetZ?: number;
+}
+/** Build a {@link Projector3D}. */
+export declare function create3DProjector(opts?: Projector3DOptions): Projector3D;

package/dist/lib/imageCache.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Return the decoded image for `url`, or `null` if it is not ready yet (a load
+ * is kicked off on the first miss). Safe to call every frame — cached after the
+ * first request. SSR-safe: returns `null` without a DOM. `onReady` (optional)
+ * fires once when a pending load resolves so a caller can trigger a re-draw.
+ */
+export declare function getOrLoadImage(url: string, onReady?: () => void): HTMLImageElement | null;
+/** Test/reset hook — clears the module cache. */
+export declare function clearImageCache(): void;

package/dist/lib/painter2d.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Painter2D — the portable 2D draw seam.
+ *
+ * A small verb set that every drawable atom paints through, so a scene stays a
+ * pure descriptor tree with no `CanvasRenderingContext2D` reference of its own.
+ * The web implementation (`createWebPainter`) wraps a `ctx`; a native platform
+ * ships its own implementation of the SAME interface — that is the cross-platform
+ * driver (draw-list over DOM overlays). This file is DOM-free: it is the shared
+ * contract, importable by any target.
+ *
+ * Coordinates are PIXELS in the painter's current transform. Scene→pixel mapping
+ * is the host projector's job (it maps a core `ScenePos` before calling here), so
+ * the painter carries no scene/projection semantics.
+ */
+/** An opaque, painter-owned handle to a resolved texture (web: a decoded image). */
+export interface TextureHandle {
+    readonly width: number;
+    readonly height: number;
+}
+/** Destination rectangle for a blit; `w`/`h` omitted → the source's natural size. */
+export interface BlitDest {
+    x: number;
+    y: number;
+    w?: number;
+    h?: number;
+}
+/** Source sub-rectangle within a texture (an atlas frame). Omitted → whole texture. */
+export interface BlitSrc {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** A polyline/polygon vertex in pixel space. */
+export interface PainterPoint {
+    x: number;
+    y: number;
+}
+export interface TextStyle {
+    color: string;
+    /** CSS font shorthand (e.g. `"12px sans-serif"`). */
+    font?: string;
+    align?: CanvasTextAlign;
+    baseline?: CanvasTextBaseline;
+}
+/** A drop shadow applied to subsequent draws until cleared. */
+export interface PainterShadow {
+    color: string;
+    blur: number;
+}
+/**
+ * The verb set. Roughly the union of what `Canvas2D`'s draw passes call on a 2D
+ * context, reframed as painter-neutral operations so the same drawable atoms
+ * paint identically on web `ctx` and on a native surface.
+ */
+export interface Painter2D {
+    /** Reset the surface to `width`×`height` logical px at device-pixel-ratio `dpr`. */
+    setViewport(width: number, height: number, dpr: number): void;
+    /** Clear the whole surface. */
+    clear(): void;
+    save(): void;
+    restore(): void;
+    translate(x: number, y: number): void;
+    scale(sx: number, sy: number): void;
+    rotate(radians: number): void;
+    /** Global alpha (0..1) for subsequent draws. */
+    setAlpha(alpha: number): void;
+    /** Drop shadow for subsequent draws; `null` clears it. */
+    setShadow(shadow: PainterShadow | null): void;
+    /** Resolve a texture URL to a handle, or `null` if not loaded yet (load is kicked off). */
+    resolveTexture(url: string): TextureHandle | null;
+    /** Blit a (sub-rect of a) texture to a destination rectangle. */
+    blit(tex: TextureHandle, dest: BlitDest, src?: BlitSrc): void;
+    fillRect(x: number, y: number, w: number, h: number, color: string): void;
+    strokeRect(x: number, y: number, w: number, h: number, color: string, lineWidth?: number): void;
+    fillPoly(points: readonly PainterPoint[], color: string): void;
+    strokePoly(points: readonly PainterPoint[], color: string, lineWidth?: number, closed?: boolean): void;
+    fillEllipse(cx: number, cy: number, rx: number, ry: number, color: string): void;
+    strokeEllipse(cx: number, cy: number, rx: number, ry: number, color: string, lineWidth?: number): void;
+    text(str: string, x: number, y: number, style: TextStyle): void;
+}

package/dist/lib/webPainter2d.d.ts

@@ -0,0 +1,7 @@
+import type { Painter2D } from './painter2d';
+/**
+ * Create a {@link Painter2D} backed by a web 2D context. `onAssetLoad` (optional)
+ * fires when a texture requested via `resolveTexture` finishes loading, so a
+ * draw-host can schedule a re-draw.
+ */
+export declare function createWebPainter(ctx: CanvasRenderingContext2D, onAssetLoad?: () => void): Painter2D;

package/dist/marketing/index.cjs

@@ -4633,6 +4633,15 @@ var tagVariantMap = {
   secondary: "secondary",
   accent: "info"
 };
+var backgroundStyles = {
+  dark: "bg-foreground text-background",
+  gradient: [
+    "bg-[radial-gradient(ellipse_at_top,var(--color-primary)/0.08,transparent_60%),",
+    "radial-gradient(ellipse_at_bottom_right,var(--color-accent)/0.06,transparent_50%)]",
+    "bg-background"
+  ].join(" "),
+  subtle: "bg-muted/30"
+};
 var MarketingImage = ({ src, alt, className }) => /* @__PURE__ */ jsxRuntime.jsx(
   Box,
   {
@@ -4774,6 +4783,7 @@ var HeroSection = ({
         "w-full min-h-[60vh] flex items-center justify-center",
         "py-20",
         "relative overflow-hidden",
+        backgroundStyles[background],
         className
       ),
       children: [

package/dist/marketing/index.js

@@ -4612,6 +4612,15 @@ var tagVariantMap = {
   secondary: "secondary",
   accent: "info"
 };
+var backgroundStyles = {
+  dark: "bg-foreground text-background",
+  gradient: [
+    "bg-[radial-gradient(ellipse_at_top,var(--color-primary)/0.08,transparent_60%),",
+    "radial-gradient(ellipse_at_bottom_right,var(--color-accent)/0.06,transparent_50%)]",
+    "bg-background"
+  ].join(" "),
+  subtle: "bg-muted/30"
+};
 var MarketingImage = ({ src, alt, className }) => /* @__PURE__ */ jsx(
   Box,
   {
@@ -4753,6 +4762,7 @@ var HeroSection = ({
         "w-full min-h-[60vh] flex items-center justify-center",
         "py-20",
         "relative overflow-hidden",
+        backgroundStyles[background],
         className
       ),
       children: [