@almadar/ui 5.32.1 → 5.32.3

package/dist/avl/index.cjs

@@ -7253,6 +7253,13 @@ var init_Textarea = __esm({
     Textarea.displayName = "Textarea";
   }
 });
+function dispatchValueChange(onValueChange, eventBus, value) {
+  if (typeof onValueChange === "string") {
+    eventBus.emit(`UI:${onValueChange}`, { value });
+  } else {
+    onValueChange?.(value);
+  }
+}
 function flatOptions(opts, groups) {
   const flat = opts ?? [];
   const grp = (groups ?? []).flatMap((g) => g.options);
@@ -7276,7 +7283,7 @@ function NativeSelect({
     } else {
       onChange?.(e);
     }
-    onValueChange?.(e.target.value);
+    dispatchValueChange(onValueChange, eventBus, e.target.value);
   };
   return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "relative", children: [
     /* @__PURE__ */ jsxRuntime.jsxs(
@@ -7336,7 +7343,7 @@ function RichSelect({
     if (typeof onChange === "string") {
       eventBus.emit(`UI:${onChange}`, { value: next });
     }
-    onValueChange?.(next);
+    dispatchValueChange(onValueChange, eventBus, next);
   };
   const clear = (e) => {
     e.stopPropagation();
@@ -7344,7 +7351,7 @@ function RichSelect({
     if (typeof onChange === "string") {
       eventBus.emit(`UI:${onChange}`, { value: next });
     }
-    onValueChange?.(next);
+    dispatchValueChange(onValueChange, eventBus, next);
   };
   React88.useEffect(() => {
     const handler = (e) => {

package/dist/avl/index.js

@@ -7204,6 +7204,13 @@ var init_Textarea = __esm({
     Textarea.displayName = "Textarea";
   }
 });
+function dispatchValueChange(onValueChange, eventBus, value) {
+  if (typeof onValueChange === "string") {
+    eventBus.emit(`UI:${onValueChange}`, { value });
+  } else {
+    onValueChange?.(value);
+  }
+}
 function flatOptions(opts, groups) {
   const flat = opts ?? [];
   const grp = (groups ?? []).flatMap((g) => g.options);
@@ -7227,7 +7234,7 @@ function NativeSelect({
     } else {
       onChange?.(e);
     }
-    onValueChange?.(e.target.value);
+    dispatchValueChange(onValueChange, eventBus, e.target.value);
   };
   return /* @__PURE__ */ jsxs("div", { className: "relative", children: [
     /* @__PURE__ */ jsxs(
@@ -7287,7 +7294,7 @@ function RichSelect({
     if (typeof onChange === "string") {
       eventBus.emit(`UI:${onChange}`, { value: next });
     }
-    onValueChange?.(next);
+    dispatchValueChange(onValueChange, eventBus, next);
   };
   const clear = (e) => {
     e.stopPropagation();
@@ -7295,7 +7302,7 @@ function RichSelect({
     if (typeof onChange === "string") {
       eventBus.emit(`UI:${onChange}`, { value: next });
     }
-    onValueChange?.(next);
+    dispatchValueChange(onValueChange, eventBus, next);
   };
   useEffect(() => {
     const handler = (e) => {

package/dist/components/core/atoms/Select.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
-import type { EventKey } from "@almadar/core";
+import type { EventKey, EventEmit } from "@almadar/core";
 export interface SelectOption {
     value: string;
     label: string;
@@ -38,7 +38,12 @@ export interface SelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectE
     clearable?: boolean;
     /** onChange handler (native ChangeEvent) or declarative event key for trait dispatch */
     onChange?: React.ChangeEventHandler<HTMLSelectElement> | EventKey;
-    /** Value-based callback — receives the selected string (or string[] for multiple). */
-    onValueChange?: (value: string | string[]) => void;
+    /** Value-based change: a React callback (internal use) OR a declarative event
+     *  key that emits `{ value }` on the bus (render-ui / lolo authoring). Mirrors
+     *  the `onChange` handler|event convention so it's an event-emitting prop, not a
+     *  bare callback. */
+    onValueChange?: ((value: string | string[]) => void) | EventEmit<{
+        value: string | string[];
+    }>;
 }
 export declare const Select: React.ForwardRefExoticComponent<SelectProps & React.RefAttributes<HTMLSelectElement>>;

package/dist/components/core/molecules/ActivationBlock.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ActivationBlock Molecule Component
+ *
+ * Pre-lesson activation prompt. Invites learners to surface prior knowledge
+ * before content begins. Emits `UI:SAVE_ACTIVATION { response }`.
+ *
+ * Event Contract:
+ * - Emits: UI:SAVE_ACTIVATION { response }
+ * - entityAware: false
+ */
+import React from 'react';
+export interface ActivationBlockProps {
+    /** The prior-knowledge question */
+    question: string;
+    /** Pre-filled response from saved state */
+    savedResponse?: string;
+    /** Event name emitted on save/skip (as `UI:<saveEvent>`). Defaults to 'SAVE_ACTIVATION'. */
+    saveEvent?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const ActivationBlock: React.FC<ActivationBlockProps>;

package/dist/components/core/molecules/BloomQuizBlock.d.ts

@@ -0,0 +1,25 @@
+/**
+ * BloomQuizBlock Molecule Component
+ *
+ * Practice Q&A with Bloom's Taxonomy level badge. Emits `UI:ANSWER_BLOOM { index, level }`.
+ *
+ * Event Contract:
+ * - Emits: UI:ANSWER_BLOOM { index, level }
+ * - entityAware: false
+ */
+import React from 'react';
+export type BloomLevel = 'remember' | 'understand' | 'apply' | 'analyze' | 'evaluate' | 'create';
+export interface BloomQuizBlockProps {
+    level: BloomLevel;
+    question: string;
+    answer: string;
+    /** Zero-based index (used in the emitted event payload) */
+    index?: number;
+    /** Whether the learner has already answered */
+    isAnswered?: boolean;
+    /** Event name emitted on first reveal (as `UI:<answerEvent>`). Defaults to 'ANSWER_BLOOM'. */
+    answerEvent?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const BloomQuizBlock: React.FC<BloomQuizBlockProps>;

package/dist/components/core/molecules/ConnectionBlock.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ConnectionBlock Molecule Component
+ *
+ * Surfaces prior-knowledge connections before new content.
+ * Renders arbitrary markdown via MarkdownContent.
+ *
+ * Event Contract:
+ * - No events emitted (display-only)
+ * - entityAware: false
+ */
+import React from 'react';
+export interface ConnectionBlockProps {
+    /** Markdown content summarising what the learner already knows */
+    content: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const ConnectionBlock: React.FC<ConnectionBlockProps>;

package/dist/components/core/molecules/ReflectionBlock.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ReflectionBlock Molecule Component
+ *
+ * Inline reflection prompt for deep processing. Emits `UI:SAVE_REFLECTION { index, note }`.
+ *
+ * Event Contract:
+ * - Emits: UI:SAVE_REFLECTION { index, note }
+ * - entityAware: false
+ */
+import React from 'react';
+export interface ReflectionBlockProps {
+    /** The reflection prompt */
+    prompt: string;
+    /** Zero-based index of this block (used in the emitted event payload) */
+    index: number;
+    /** Pre-filled note from saved state */
+    savedNote?: string;
+    /** Event name emitted on save (as `UI:<saveEvent>`). Defaults to 'SAVE_REFLECTION'. */
+    saveEvent?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const ReflectionBlock: React.FC<ReflectionBlockProps>;

package/dist/components/core/molecules/index.d.ts

@@ -125,3 +125,9 @@ export { Chart, type ChartProps, type ChartType, type ChartSeries, } from "./Cha
 export { SignaturePad, type SignaturePadProps, } from "./SignaturePad";
 export { DocumentViewer, type DocumentViewerProps, type DocumentType, } from "./DocumentViewer";
 export { GraphCanvas, type GraphCanvasProps, type GraphNode, type GraphEdge, } from "./GraphCanvas";
+export { ActivationBlock, type ActivationBlockProps } from './ActivationBlock';
+export { ReflectionBlock, type ReflectionBlockProps } from './ReflectionBlock';
+export { ConnectionBlock, type ConnectionBlockProps } from './ConnectionBlock';
+export { BloomQuizBlock, type BloomQuizBlockProps, type BloomLevel } from './BloomQuizBlock';
+export { parseLessonSegments, type LessonSegment, type LessonUserProgress } from './parseLessonSegments';
+export { parseMarkdownWithCodeBlocks, type MixedSegment } from './lessonSegmentUtils';

package/dist/components/core/molecules/lessonSegmentUtils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Utility for lesson-segment parsing: splits a markdown string into alternating
+ * markdown and fenced-code-block segments. Exported so SegmentRenderer and
+ * BloomQuizBlock can reuse without circular imports.
+ */
+export type MarkdownSegment = {
+    type: 'markdown';
+    content: string;
+};
+export type CodeSegment = {
+    type: 'code';
+    language: string;
+    content: string;
+    runnable?: boolean;
+};
+export type MixedSegment = MarkdownSegment | CodeSegment;
+/** Splits markdown content into markdown and fenced-code-block segments. */
+export declare function parseMarkdownWithCodeBlocks(content: string): MixedSegment[];

package/dist/components/core/molecules/parseLessonSegments.d.ts

@@ -0,0 +1,43 @@
+/**
+ * parseLessonSegments — parses lesson markdown with embedded learning-science
+ * XML-style tags into a typed Segment array.
+ *
+ * Supported tags: <activate>, <connect>, <reflect>, <bloom level="...">,
+ * <question>/<answer>, <visualize type="..." description="..." />.
+ *
+ * Tags may be open (unclosed) — the parser falls back to consuming content
+ * until the next recognised tag, a section heading (`\n\n#`), or end-of-input.
+ */
+import type { BloomLevel } from './BloomQuizBlock';
+import { type MixedSegment } from './lessonSegmentUtils';
+export type LessonSegment = MixedSegment | {
+    type: 'quiz';
+    question: string;
+    answer: string;
+} | {
+    type: 'activate';
+    question: string;
+} | {
+    type: 'connect';
+    content: string;
+} | {
+    type: 'reflect';
+    prompt: string;
+} | {
+    type: 'bloom';
+    level: BloomLevel;
+    question: string;
+    answer: string;
+} | {
+    type: 'visualization';
+    visualizationType: 'chart' | 'simulation';
+    description: string;
+};
+/** User progress state passed into SegmentRenderer. */
+export interface LessonUserProgress {
+    activationResponse?: string;
+    reflectionNotes?: string[];
+    bloomAnswered?: Record<number, boolean>;
+}
+/** Parse a lesson string into typed segments. Returns `[]` when input is empty. */
+export declare function parseLessonSegments(lesson: string | undefined): LessonSegment[];

package/dist/components/core/organisms/CodeRunnerPanel.d.ts

@@ -0,0 +1,42 @@
+/**
+ * CodeRunnerPanel Organism Component
+ *
+ * Editable code block with Run/Reset buttons and simulated terminal output.
+ * Real execution is a future concern; callers supply a simulation function via
+ * `onRun`. Emits `UI:RUN_CODE { language, exitCode }` on every run attempt.
+ *
+ * Event Contract:
+ * - Emits: UI:RUN_CODE { language, exitCode, error? }
+ * - entityAware: false
+ */
+import React from 'react';
+export interface CodeSimulationOutput {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    testResults: Array<{
+        input: string;
+        expectedOutput: string;
+        actualOutput: string;
+        passed: boolean;
+    }>;
+}
+export interface CodeRunnerPanelProps {
+    /** Initial code content */
+    code: string;
+    /** Programming language for syntax highlighting */
+    language: string;
+    /** Whether the panel allows running (false = read-only code block) */
+    runnable?: boolean;
+    /**
+     * Simulate executing the code. Omit to render a read-only block.
+     * Real execution is a separate future track — this callback supplies
+     * deterministic simulated output for UI feedback.
+     */
+    onRun?: (code: string) => Promise<CodeSimulationOutput>;
+    /** Event name to emit on run (emitted as `UI:<runEvent>`). Defaults to 'RUN_CODE'. */
+    runEvent?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const CodeRunnerPanel: React.FC<CodeRunnerPanelProps>;

package/dist/components/core/organisms/SegmentRenderer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * SegmentRenderer Organism Component
+ *
+ * Renders a parsed array of LessonSegments — markdown, code, quizzes,
+ * activation prompts, connections, reflections, Bloom questions.
+ * The `visualization` segment type is passed through as a no-op unless the
+ * caller provides `onRenderVisualization` (future extensibility hook).
+ *
+ * Event Contract:
+ * - Delegates to child molecules: UI:SAVE_ACTIVATION, UI:SAVE_REFLECTION, UI:ANSWER_BLOOM
+ * - entityAware: false
+ */
+import React from 'react';
+import { type CodeSimulationOutput } from './CodeRunnerPanel';
+import type { LessonSegment, LessonUserProgress } from '../molecules/parseLessonSegments';
+export type { LessonSegment, LessonUserProgress, CodeSimulationOutput };
+export interface SegmentRendererProps {
+    /** Parsed lesson segments (see `parseLessonSegments`) */
+    segments: LessonSegment[];
+    /** Additional CSS classes for the root container */
+    className?: string;
+    /** CSS classes for the outer wrapping div */
+    containerClassName?: string;
+    /** User progress for restoring activation/reflection state */
+    userProgress?: LessonUserProgress;
+    /**
+     * Simulate executing runnable code blocks. Omit to render runnable blocks
+     * as read-only. Real execution is a future track.
+     */
+    onRunCodeSimulation?: (code: string, language: string) => Promise<CodeSimulationOutput>;
+    /**
+     * Optional render slot for `visualization` segment types. When not provided,
+     * visualization segments are silently skipped. Callers can wire this to any
+     * custom component or orbital generator.
+     */
+    onRenderVisualization?: (type: 'chart' | 'simulation', description: string, index: number) => React.ReactNode;
+}
+export declare const SegmentRenderer: React.FC<SegmentRendererProps>;

package/dist/components/core/organisms/index.d.ts

@@ -26,3 +26,5 @@ export { StepFlowOrganism, type StepFlowOrganismProps, } from "../../marketing/o
 export { ShowcaseOrganism, type ShowcaseOrganismProps, } from "../../marketing/organisms/ShowcaseOrganism";
 export { TeamOrganism, type TeamOrganismProps, } from "../../marketing/organisms/TeamOrganism";
 export { CaseStudyOrganism, type CaseStudyOrganismProps, } from "../../marketing/organisms/CaseStudyOrganism";
+export { CodeRunnerPanel, type CodeRunnerPanelProps, type CodeSimulationOutput, } from './CodeRunnerPanel';
+export { SegmentRenderer, type SegmentRendererProps, } from './SegmentRenderer';

package/dist/components/game/molecules/GameCanvas3D.d.ts

@@ -17,6 +17,7 @@ import React from 'react';
 import type { EventEmit } from '@almadar/core';
 import * as THREE from 'three';
 import { AssetLoader } from './three/loaders/AssetLoader';
+import { type MinimalMouseEvent } from './three/hooks/useGameCanvas3DEvents';
 import type { IsometricTile, IsometricUnit, IsometricFeature } from '../organisms/types/isometric';
 import './GameCanvas3D.css';
 export type { IsometricTile, IsometricUnit, IsometricFeature };
@@ -74,15 +75,15 @@ export interface GameCanvas3DProps {
     /** Background color */
     backgroundColor?: string;
     /** Callback when a tile is clicked */
-    onTileClick?: (tile: IsometricTile, event: React.MouseEvent) => void;
+    onTileClick?: (tile: IsometricTile, event: MinimalMouseEvent) => void;
     /** Callback when a unit is clicked */
-    onUnitClick?: (unit: IsometricUnit, event: React.MouseEvent) => void;
+    onUnitClick?: (unit: IsometricUnit, event: MinimalMouseEvent) => void;
     /** Callback when a feature is clicked */
-    onFeatureClick?: (feature: IsometricFeature, event: React.MouseEvent) => void;
+    onFeatureClick?: (feature: IsometricFeature, event: MinimalMouseEvent) => void;
     /** Callback when canvas is clicked (background) */
-    onCanvasClick?: (event: React.MouseEvent) => void;
+    onCanvasClick?: (event: MinimalMouseEvent) => void;
     /** Callback when mouse moves over a tile */
-    onTileHover?: (tile: IsometricTile | null, event: React.MouseEvent) => void;
+    onTileHover?: (tile: IsometricTile | null, event: MinimalMouseEvent) => void;
     /** Callback for unit animation state change */
     onUnitAnimation?: (unitId: string, state: string) => void;
     /** Asset loader instance (uses global singleton if not provided) */

package/dist/components/game/molecules/three/hooks/useGameCanvas3DEvents.d.ts

@@ -69,29 +69,29 @@ export interface MinimalMouseEvent {
 }
 export interface UseGameCanvas3DEventsOptions extends GameCanvas3DEventConfig {
     /** Callback for tile clicks (direct) */
-    onTileClick?: (tile: IsometricTile, event: React.MouseEvent) => void;
+    onTileClick?: (tile: IsometricTile, event: MinimalMouseEvent) => void;
     /** Callback for unit clicks (direct) */
-    onUnitClick?: (unit: IsometricUnit, event: React.MouseEvent) => void;
+    onUnitClick?: (unit: IsometricUnit, event: MinimalMouseEvent) => void;
     /** Callback for feature clicks (direct) */
-    onFeatureClick?: (feature: IsometricFeature, event: React.MouseEvent) => void;
+    onFeatureClick?: (feature: IsometricFeature, event: MinimalMouseEvent) => void;
     /** Callback for canvas clicks (direct) */
-    onCanvasClick?: (event: React.MouseEvent) => void;
+    onCanvasClick?: (event: MinimalMouseEvent) => void;
     /** Callback for tile hover (direct) */
-    onTileHover?: (tile: IsometricTile | null, event: React.MouseEvent) => void;
+    onTileHover?: (tile: IsometricTile | null, event: MinimalMouseEvent) => void;
     /** Callback for unit animation changes (direct) */
     onUnitAnimation?: (unitId: string, state: string) => void;
 }
 export interface UseGameCanvas3DEventsReturn {
     /** Handle tile click - emits event and calls callback */
-    handleTileClick: (tile: IsometricTile, event: React.MouseEvent) => void;
+    handleTileClick: (tile: IsometricTile, event: MinimalMouseEvent) => void;
     /** Handle unit click - emits event and calls callback */
-    handleUnitClick: (unit: IsometricUnit, event: React.MouseEvent) => void;
+    handleUnitClick: (unit: IsometricUnit, event: MinimalMouseEvent) => void;
     /** Handle feature click - emits event and calls callback */
-    handleFeatureClick: (feature: IsometricFeature, event: React.MouseEvent) => void;
+    handleFeatureClick: (feature: IsometricFeature, event: MinimalMouseEvent) => void;
     /** Handle canvas click - emits event and calls callback */
     handleCanvasClick: (event: MinimalMouseEvent) => void;
     /** Handle tile hover - emits event and calls callback */
-    handleTileHover: (tile: IsometricTile | null, event: React.MouseEvent) => void;
+    handleTileHover: (tile: IsometricTile | null, event: MinimalMouseEvent) => void;
     /** Handle unit animation - emits event and calls callback */
     handleUnitAnimation: (unitId: string, state: string) => void;
     /** Handle camera change - emits event */

package/dist/components/game/molecules/three/index.cjs

@@ -2518,6 +2518,28 @@ var GameCanvas3D = React11.forwardRef(
         else if (isAttackTarget) emissive = 4456448;
         else if (isValidMove) emissive = 17408;
         else if (isHovered) emissive = 2236962;
+        if (tile.modelUrl) {
+          return /* @__PURE__ */ jsxRuntime.jsx(
+            "group",
+            {
+              position,
+              onClick: (e) => handleTileClick(tile, e),
+              onPointerEnter: (e) => handleTileHover(tile, e),
+              onPointerLeave: (e) => handleTileHover(null, e),
+              userData: { type: "tile", tileId: tile.id, gridX: tile.x, gridZ: tile.z ?? tile.y },
+              children: /* @__PURE__ */ jsxRuntime.jsx(
+                ModelLoader,
+                {
+                  url: tile.modelUrl,
+                  scale: 0.95,
+                  fallbackGeometry: "box",
+                  castShadow: true,
+                  receiveShadow: true
+                }
+              )
+            }
+          );
+        }
         return /* @__PURE__ */ jsxRuntime.jsxs(
           "mesh",
           {
@@ -2550,17 +2572,30 @@ var GameCanvas3D = React11.forwardRef(
                 /* @__PURE__ */ jsxRuntime.jsx("ringGeometry", { args: [0.4, 0.5, 32] }),
                 /* @__PURE__ */ jsxRuntime.jsx("meshBasicMaterial", { color: "#ffff00", transparent: true, opacity: 0.8 })
               ] }),
-              /* @__PURE__ */ jsxRuntime.jsxs("mesh", { position: [0, 0.3, 0], children: [
-                /* @__PURE__ */ jsxRuntime.jsx("cylinderGeometry", { args: [0.3, 0.3, 0.1, 8] }),
-                /* @__PURE__ */ jsxRuntime.jsx("meshStandardMaterial", { color })
-              ] }),
-              /* @__PURE__ */ jsxRuntime.jsxs("mesh", { position: [0, 0.6, 0], children: [
-                /* @__PURE__ */ jsxRuntime.jsx("capsuleGeometry", { args: [0.2, 0.4, 4, 8] }),
-                /* @__PURE__ */ jsxRuntime.jsx("meshStandardMaterial", { color })
-              ] }),
-              /* @__PURE__ */ jsxRuntime.jsxs("mesh", { position: [0, 0.9, 0], children: [
-                /* @__PURE__ */ jsxRuntime.jsx("sphereGeometry", { args: [0.12, 8, 8] }),
-                /* @__PURE__ */ jsxRuntime.jsx("meshStandardMaterial", { color })
+              unit.modelUrl ? (
+                /* GLB unit model (box fallback while loading / on error) */
+                /* @__PURE__ */ jsxRuntime.jsx(
+                  ModelLoader,
+                  {
+                    url: unit.modelUrl,
+                    scale: 0.5,
+                    fallbackGeometry: "box",
+                    castShadow: true
+                  }
+                )
+              ) : /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+                /* @__PURE__ */ jsxRuntime.jsxs("mesh", { position: [0, 0.3, 0], children: [
+                  /* @__PURE__ */ jsxRuntime.jsx("cylinderGeometry", { args: [0.3, 0.3, 0.1, 8] }),
+                  /* @__PURE__ */ jsxRuntime.jsx("meshStandardMaterial", { color })
+                ] }),
+                /* @__PURE__ */ jsxRuntime.jsxs("mesh", { position: [0, 0.6, 0], children: [
+                  /* @__PURE__ */ jsxRuntime.jsx("capsuleGeometry", { args: [0.2, 0.4, 4, 8] }),
+                  /* @__PURE__ */ jsxRuntime.jsx("meshStandardMaterial", { color })
+                ] }),
+                /* @__PURE__ */ jsxRuntime.jsxs("mesh", { position: [0, 0.9, 0], children: [
+                  /* @__PURE__ */ jsxRuntime.jsx("sphereGeometry", { args: [0.12, 8, 8] }),
+                  /* @__PURE__ */ jsxRuntime.jsx("meshStandardMaterial", { color })
+                ] })
               ] }),
               unit.health !== void 0 && unit.maxHealth !== void 0 && /* @__PURE__ */ jsxRuntime.jsxs("group", { position: [0, 1.2, 0], children: [
                 /* @__PURE__ */ jsxRuntime.jsxs("mesh", { position: [-0.25, 0, 0], children: [

package/dist/components/game/molecules/three/index.js

@@ -2494,6 +2494,28 @@ var GameCanvas3D = forwardRef(
         else if (isAttackTarget) emissive = 4456448;
         else if (isValidMove) emissive = 17408;
         else if (isHovered) emissive = 2236962;
+        if (tile.modelUrl) {
+          return /* @__PURE__ */ jsx(
+            "group",
+            {
+              position,
+              onClick: (e) => handleTileClick(tile, e),
+              onPointerEnter: (e) => handleTileHover(tile, e),
+              onPointerLeave: (e) => handleTileHover(null, e),
+              userData: { type: "tile", tileId: tile.id, gridX: tile.x, gridZ: tile.z ?? tile.y },
+              children: /* @__PURE__ */ jsx(
+                ModelLoader,
+                {
+                  url: tile.modelUrl,
+                  scale: 0.95,
+                  fallbackGeometry: "box",
+                  castShadow: true,
+                  receiveShadow: true
+                }
+              )
+            }
+          );
+        }
         return /* @__PURE__ */ jsxs(
           "mesh",
           {
@@ -2526,17 +2548,30 @@ var GameCanvas3D = forwardRef(
                 /* @__PURE__ */ jsx("ringGeometry", { args: [0.4, 0.5, 32] }),
                 /* @__PURE__ */ jsx("meshBasicMaterial", { color: "#ffff00", transparent: true, opacity: 0.8 })
               ] }),
-              /* @__PURE__ */ jsxs("mesh", { position: [0, 0.3, 0], children: [
-                /* @__PURE__ */ jsx("cylinderGeometry", { args: [0.3, 0.3, 0.1, 8] }),
-                /* @__PURE__ */ jsx("meshStandardMaterial", { color })
-              ] }),
-              /* @__PURE__ */ jsxs("mesh", { position: [0, 0.6, 0], children: [
-                /* @__PURE__ */ jsx("capsuleGeometry", { args: [0.2, 0.4, 4, 8] }),
-                /* @__PURE__ */ jsx("meshStandardMaterial", { color })
-              ] }),
-              /* @__PURE__ */ jsxs("mesh", { position: [0, 0.9, 0], children: [
-                /* @__PURE__ */ jsx("sphereGeometry", { args: [0.12, 8, 8] }),
-                /* @__PURE__ */ jsx("meshStandardMaterial", { color })
+              unit.modelUrl ? (
+                /* GLB unit model (box fallback while loading / on error) */
+                /* @__PURE__ */ jsx(
+                  ModelLoader,
+                  {
+                    url: unit.modelUrl,
+                    scale: 0.5,
+                    fallbackGeometry: "box",
+                    castShadow: true
+                  }
+                )
+              ) : /* @__PURE__ */ jsxs(Fragment, { children: [
+                /* @__PURE__ */ jsxs("mesh", { position: [0, 0.3, 0], children: [
+                  /* @__PURE__ */ jsx("cylinderGeometry", { args: [0.3, 0.3, 0.1, 8] }),
+                  /* @__PURE__ */ jsx("meshStandardMaterial", { color })
+                ] }),
+                /* @__PURE__ */ jsxs("mesh", { position: [0, 0.6, 0], children: [
+                  /* @__PURE__ */ jsx("capsuleGeometry", { args: [0.2, 0.4, 4, 8] }),
+                  /* @__PURE__ */ jsx("meshStandardMaterial", { color })
+                ] }),
+                /* @__PURE__ */ jsxs("mesh", { position: [0, 0.9, 0], children: [
+                  /* @__PURE__ */ jsx("sphereGeometry", { args: [0.12, 8, 8] }),
+                  /* @__PURE__ */ jsx("meshStandardMaterial", { color })
+                ] })
               ] }),
               unit.health !== void 0 && unit.maxHealth !== void 0 && /* @__PURE__ */ jsxs("group", { position: [0, 1.2, 0], children: [
                 /* @__PURE__ */ jsxs("mesh", { position: [-0.25, 0, 0], children: [

package/dist/components/game/organisms/types/isometric.d.ts

@@ -51,6 +51,8 @@ export type IsometricUnit = {
     z?: number;
     /** Static sprite URL (used when no sprite sheet animation) */
     sprite?: AssetUrl;
+    /** 3D model URL (GLB format) for GameCanvas3D — rendered via ModelLoader with box fallback */
+    modelUrl?: AssetUrl;
     /** Unit archetype key for sprite resolution */
     unitType?: string;
     /** Hero identifier for sprite sheet lookup */