@almadar/ui 5.148.0 → 5.149.0

package/dist/avl/index.js

@@ -14041,9 +14041,10 @@ function Canvas({
       drawables: [...drawables ?? [], ...childDrawables],
       isLoading,
       cameraMode: to3DCameraMode(camera?.mode),
-      ...zoom !== void 0 ? { scale: zoom } : {},
+      ...zoom !== void 0 ? { zoom } : {},
       ...camera?.fov !== void 0 ? { fov: camera.fov } : {},
       ...camera?.azimuth !== void 0 ? { azimuth: camera.azimuth } : {},
+      ...camera?.elevation !== void 0 ? { elevation: camera.elevation } : {},
       ...camera?.target !== void 0 ? { followTarget: camera.target } : {},
       unitScale,
       backgroundColor,
@@ -17095,23 +17096,188 @@ var init_AuthLayout = __esm({
     AuthLayout.displayName = "AuthLayout";
   }
 });
-var BiologyCanvas;
+function LearningScene3D({
+  className,
+  width = 600,
+  height = 400,
+  title,
+  backgroundColor,
+  drawables,
+  camera,
+  lighting,
+  post,
+  showGrid = false,
+  shadows,
+  interactive,
+  isLoading,
+  error,
+  onItemClick
+}) {
+  const instanceId = useId().replace(/[^a-zA-Z0-9]/g, "");
+  const clickEvent = onItemClick ? `LEARNING_SCENE_3D.ITEM_CLICK.${instanceId}` : void 0;
+  const onItemClickRef = useRef(onItemClick);
+  onItemClickRef.current = onItemClick;
+  useEventListener(`UI:${clickEvent ?? "LEARNING_SCENE_3D.ITEM_CLICK.__disabled"}`, (event) => {
+    const unitId = event.payload?.unitId;
+    if (typeof unitId === "string") onItemClickRef.current?.(unitId);
+  });
+  const props3d = {
+    drawables,
+    isLoading,
+    error: error ? error.message : null,
+    cameraMode: camera?.mode ?? "perspective",
+    ...camera?.zoom !== void 0 ? { zoom: camera.zoom } : {},
+    ...camera?.fov !== void 0 ? { fov: camera.fov } : {},
+    ...camera?.azimuth !== void 0 ? { azimuth: camera.azimuth } : {},
+    ...camera?.elevation !== void 0 ? { elevation: camera.elevation } : {},
+    ...camera?.target !== void 0 ? { followTarget: camera.target } : {},
+    backgroundColor,
+    showGrid,
+    ...shadows !== void 0 ? { shadows } : {},
+    ...interactive !== void 0 ? { controlsEnabled: interactive } : {},
+    lighting,
+    post,
+    ...clickEvent !== void 0 ? { unitClickEvent: clickEvent } : {}
+  };
+  return /* @__PURE__ */ jsx(Card, { className, children: /* @__PURE__ */ jsxs(VStack, { gap: "sm", children: [
+    title ? /* @__PURE__ */ jsx(Typography, { variant: "h4", children: title }) : null,
+    /* @__PURE__ */ jsx("div", { style: { width, height, display: "flex" }, children: /* @__PURE__ */ jsx(Suspense, { fallback: null, children: /* @__PURE__ */ jsx(Canvas3DHost2, { ...props3d }) }) })
+  ] }) });
+}
+function meshSphere(id, x, y, z, radius, color, opts) {
+  return {
+    type: "draw-mesh",
+    ...id !== void 0 ? { id } : {},
+    shape: opts?.shape ?? "sphere",
+    position: { x, y, z },
+    radius,
+    pivot: "center",
+    segments: opts?.segments ?? 24,
+    material: { color, ...opts?.material },
+    ...opts?.opacity !== void 0 ? { opacity: opts.opacity } : {}
+  };
+}
+function axisRotation(from, to) {
+  const wx = to[0] - from[0];
+  const wy = to[2] - from[2];
+  const wz = to[1] - from[1];
+  const len = Math.sqrt(wx * wx + wy * wy + wz * wz);
+  const tilt = Math.acos(Math.min(1, Math.max(-1, len > 0 ? wy / len : 1)));
+  return [0, Math.atan2(wz, -wx), tilt];
+}
+function segmentLength(from, to) {
+  const dx = to[0] - from[0];
+  const dy = to[1] - from[1];
+  const dz = to[2] - from[2];
+  return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+function cylinderBetween(from, to, radius, color) {
+  const len = segmentLength(from, to);
+  if (len < 1e-6) return null;
+  return {
+    type: "draw-mesh",
+    shape: "cylinder",
+    position: { x: (from[0] + to[0]) / 2, y: (from[1] + to[1]) / 2, z: (from[2] + to[2]) / 2 },
+    radius,
+    height: len,
+    rotation: axisRotation(from, to),
+    pivot: "center",
+    segments: 12,
+    material: { color }
+  };
+}
+function arrowBetween(from, to, color, shaftRadius = 0.08) {
+  const len = segmentLength(from, to);
+  if (len < 1e-6) return null;
+  const tipLen = Math.min(shaftRadius * 8, len * 0.35);
+  const k = (len - tipLen) / len;
+  const delta = [to[0] - from[0], to[1] - from[1], to[2] - from[2]];
+  const shaftEnd = [delta[0] * k, delta[1] * k, delta[2] * k];
+  const tipStart = shaftEnd;
+  const tipEnd = delta;
+  const shaft = cylinderBetween([0, 0, 0], shaftEnd, shaftRadius, color);
+  const tipLenActual = segmentLength(tipStart, tipEnd);
+  const tip = {
+    type: "draw-mesh",
+    shape: "cone",
+    position: {
+      x: (tipStart[0] + tipEnd[0]) / 2,
+      y: (tipStart[1] + tipEnd[1]) / 2,
+      z: (tipStart[2] + tipEnd[2]) / 2
+    },
+    radius: shaftRadius * 3,
+    height: tipLenActual,
+    rotation: axisRotation(tipStart, tipEnd),
+    pivot: "center",
+    segments: 12,
+    material: { color }
+  };
+  return {
+    type: "draw-group",
+    position: { x: from[0], y: from[1], z: from[2] },
+    items: tipLenActual < 1e-6 ? shaft ? [shaft] : [] : shaft ? [shaft, tip] : [tip]
+  };
+}
+function billboardLabel(text, x, y, z, opts) {
+  return {
+    type: "draw-text",
+    text,
+    position: { x, y, z },
+    color: opts?.color ?? "#111827"
+  };
+}
+function labelColorForBackground(backgroundColor) {
+  const m = /^#(?:([0-9a-f]{3})|([0-9a-f]{6}))$/i.exec(backgroundColor ?? "");
+  if (!m) return "#111827";
+  const hex = m[1] !== void 0 ? m[1].split("").map((c) => c + c).join("") : m[2];
+  const r2 = parseInt(hex.slice(0, 2), 16) / 255;
+  const g = parseInt(hex.slice(2, 4), 16) / 255;
+  const b = parseInt(hex.slice(4, 6), 16) / 255;
+  const luminance = 0.2126 * r2 + 0.7152 * g + 0.0722 * b;
+  return luminance < 0.5 ? "#e5e7eb" : "#111827";
+}
+function get3DClickPayload(onShapeClick, idToIndex) {
+  if (!onShapeClick) return void 0;
+  return (id) => onShapeClick({ id, index: idToIndex.get(id) ?? -1 });
+}
+var Canvas3DHost2;
+var init_learningScene3D = __esm({
+  "components/learning/molecules/learningScene3D.tsx"() {
+    "use client";
+    init_atoms();
+    init_Stack();
+    init_useEventBus();
+    Canvas3DHost2 = lazy(
+      () => import('@almadar/ui/components/molecules/game/three').then((m) => ({ default: m.Canvas3DHost }))
+    );
+    LearningScene3D.displayName = "LearningScene3D";
+  }
+});
+var biologyLog, BiologyCanvas;
 var init_BiologyCanvas = __esm({
   "components/learning/molecules/BiologyCanvas.tsx"() {
     "use client";
     init_atoms();
     init_Stack();
     init_LearningCanvas();
+    init_learningScene3D();
+    biologyLog = createLogger("almadar:ui:biology-canvas");
     BiologyCanvas = ({
       className,
       width = 600,
       height = 400,
       title,
       backgroundColor,
+      mode = "2d",
+      camera,
+      lighting,
+      post,
       nodes = [],
       edges = [],
       shapes = [],
-      interactive = false,
+      showGrid,
+      shadows,
+      interactive,
       animate = false,
       onShapeClick,
       isLoading,
@@ -17172,6 +17338,75 @@ var init_BiologyCanvas = __esm({
         out.push(...shapes);
         return out;
       }, [nodes, edges, shapes]);
+      const drawables3D = useMemo(() => {
+        if (mode !== "3d") return [];
+        if (shapes.length > 0) {
+          biologyLog.debug("shapes ignored in 3D mode (pixel-authored 2D vocabulary)", { count: shapes.length });
+        }
+        const out = [];
+        const labelColor = labelColorForBackground(backgroundColor);
+        const nodeById = /* @__PURE__ */ new Map();
+        for (const n of nodes) {
+          if (n.id) nodeById.set(n.id, n);
+        }
+        for (const e of edges) {
+          const a = nodeById.get(e.from);
+          const b = nodeById.get(e.to);
+          if (!a || !b) continue;
+          const edgeRadius = Math.max(0.04, Math.min(a.radius ?? 0.5, b.radius ?? 0.5) * 0.12);
+          const edge = cylinderBetween([a.x, a.y, a.z ?? 0], [b.x, b.y, b.z ?? 0], edgeRadius, e.color ?? "#9ca3af");
+          if (edge) out.push(edge);
+          if (e.label) {
+            out.push(
+              billboardLabel(
+                e.label,
+                (a.x + b.x) / 2,
+                (a.y + b.y) / 2,
+                ((a.z ?? 0) + (b.z ?? 0)) / 2,
+                { color: labelColor }
+              )
+            );
+          }
+        }
+        for (const n of nodes) {
+          const radius = n.radius ?? 0.5;
+          const nz = n.z ?? 0;
+          out.push(meshSphere(n.id, n.x, n.y, nz, radius, n.color ?? "#16a34a", { shape: n.shape, ...n.opacity !== void 0 ? { opacity: n.opacity } : {} }));
+          if (n.label) {
+            out.push(billboardLabel(n.label, n.x, n.y, nz + radius, { color: labelColor }));
+          }
+        }
+        return out;
+      }, [mode, nodes, edges, shapes, backgroundColor]);
+      const nodeIndexById = useMemo(() => {
+        const m = /* @__PURE__ */ new Map();
+        nodes.forEach((n, i) => {
+          if (n.id) m.set(n.id, i);
+        });
+        return m;
+      }, [nodes]);
+      if (mode === "3d") {
+        return /* @__PURE__ */ jsx(
+          LearningScene3D,
+          {
+            className,
+            width,
+            height,
+            title,
+            backgroundColor,
+            drawables: drawables3D,
+            camera,
+            lighting,
+            post,
+            showGrid,
+            shadows,
+            interactive,
+            isLoading,
+            error,
+            onItemClick: get3DClickPayload(onShapeClick, nodeIndexById)
+          }
+        );
+      }
       return /* @__PURE__ */ jsx(Card, { className, children: /* @__PURE__ */ jsxs(VStack, { gap: "sm", children: [
         title ? /* @__PURE__ */ jsx(Typography, { variant: "h4", children: title }) : null,
         /* @__PURE__ */ jsx(
@@ -17181,7 +17416,7 @@ var init_BiologyCanvas = __esm({
             height,
             backgroundColor,
             shapes: derivedShapes,
-            interactive,
+            interactive: interactive ?? false,
             animate,
             onShapeClick,
             isLoading,
@@ -24021,24 +24256,41 @@ var init_ChatBar = __esm({
     ChatBar.displayName = "ChatBar";
   }
 });
-var ChemistryCanvas;
+function bondPerpendicular(a, b) {
+  const dx = b[0] - a[0];
+  const dy = b[1] - a[1];
+  const px = dy;
+  const py = -dx;
+  const len = Math.sqrt(px * px + py * py);
+  if (len < 1e-6) return [1, 0, 0];
+  return [px / len, py / len, 0];
+}
+var chemistryLog, ChemistryCanvas;
 var init_ChemistryCanvas = __esm({
   "components/learning/molecules/ChemistryCanvas.tsx"() {
     "use client";
     init_atoms();
     init_Stack();
     init_LearningCanvas();
+    init_learningScene3D();
+    chemistryLog = createLogger("almadar:ui:chemistry-canvas");
     ChemistryCanvas = ({
       className,
       width = 600,
       height = 400,
       title,
       backgroundColor,
+      mode = "2d",
+      camera,
+      lighting,
+      post,
       atoms = [],
       bonds = [],
       arrows = [],
       shapes = [],
-      interactive = false,
+      showGrid,
+      shadows,
+      interactive,
       animate = false,
       onShapeClick,
       isLoading,
@@ -24117,6 +24369,88 @@ var init_ChemistryCanvas = __esm({
         out.push(...shapes);
         return out;
       }, [atoms, bonds, arrows, shapes]);
+      const drawables3D = useMemo(() => {
+        if (mode !== "3d") return [];
+        if (shapes.length > 0) {
+          chemistryLog.debug("shapes ignored in 3D mode (pixel-authored 2D vocabulary)", { count: shapes.length });
+        }
+        const out = [];
+        const labelColor = labelColorForBackground(backgroundColor);
+        const atomById = /* @__PURE__ */ new Map();
+        for (const a of atoms) {
+          if (a.id) atomById.set(a.id, a);
+        }
+        for (const b of bonds) {
+          const a = atomById.get(b.from);
+          const c = atomById.get(b.to);
+          if (!a || !c) continue;
+          const color = b.color ?? "#6b7280";
+          const from = [a.x, a.y, a.z ?? 0];
+          const to = [c.x, c.y, c.z ?? 0];
+          const perp = bondPerpendicular(from, to);
+          const bondRadius = Math.max(0.06, Math.min(a.radius ?? 0.45, c.radius ?? 0.45) * 0.22);
+          const step = bondRadius * 2.2;
+          const offsets = b.type === "double" ? [-step, step] : b.type === "triple" ? [-step, 0, step] : [0];
+          for (const off of offsets) {
+            const bond = cylinderBetween(
+              [from[0] + perp[0] * off, from[1] + perp[1] * off, from[2] + perp[2] * off],
+              [to[0] + perp[0] * off, to[1] + perp[1] * off, to[2] + perp[2] * off],
+              bondRadius,
+              color
+            );
+            if (bond) out.push(bond);
+          }
+        }
+        for (const a of arrows) {
+          const angle = (a.angle ?? 0) * (Math.PI / 180);
+          const len = a.length ?? 60;
+          const x2 = a.x + Math.cos(angle) * len;
+          const y2 = a.y + Math.sin(angle) * len;
+          const arrow = arrowBetween([a.x, a.y, 0], [x2, y2, 0], a.color ?? "#dc2626");
+          if (arrow) out.push(arrow);
+          if (a.label) {
+            out.push(billboardLabel(a.label, (a.x + x2) / 2, (a.y + y2) / 2, 0, { color: labelColor }));
+          }
+        }
+        for (const a of atoms) {
+          const radius = a.radius ?? 0.45;
+          const az = a.z ?? 0;
+          out.push(meshSphere(a.id, a.x, a.y, az, radius, a.color ?? "#2563eb"));
+          if (a.element) {
+            out.push(billboardLabel(a.element, a.x, a.y, az + radius, { color: labelColor }));
+          }
+        }
+        return out;
+      }, [mode, atoms, bonds, arrows, shapes, backgroundColor]);
+      const atomIndexById = useMemo(() => {
+        const m = /* @__PURE__ */ new Map();
+        atoms.forEach((a, i) => {
+          if (a.id) m.set(a.id, i);
+        });
+        return m;
+      }, [atoms]);
+      if (mode === "3d") {
+        return /* @__PURE__ */ jsx(
+          LearningScene3D,
+          {
+            className,
+            width,
+            height,
+            title,
+            backgroundColor,
+            drawables: drawables3D,
+            camera,
+            lighting,
+            post,
+            showGrid,
+            shadows,
+            interactive,
+            isLoading,
+            error,
+            onItemClick: get3DClickPayload(onShapeClick, atomIndexById)
+          }
+        );
+      }
       return /* @__PURE__ */ jsx(Card, { className, children: /* @__PURE__ */ jsxs(VStack, { gap: "sm", children: [
         title ? /* @__PURE__ */ jsx(Typography, { variant: "h4", children: title }) : null,
         /* @__PURE__ */ jsx(
@@ -24126,7 +24460,7 @@ var init_ChemistryCanvas = __esm({
             height,
             backgroundColor,
             shapes: derivedShapes,
-            interactive,
+            interactive: interactive ?? false,
             animate,
             onShapeClick,
             isLoading,
@@ -30431,19 +30765,25 @@ var init_MathCanvas = __esm({
     };
   }
 });
-var PhysicsCanvas;
+var physicsLog2, PhysicsCanvas;
 var init_PhysicsCanvas = __esm({
   "components/learning/molecules/PhysicsCanvas.tsx"() {
     "use client";
     init_atoms();
     init_Stack();
     init_LearningCanvas();
+    init_learningScene3D();
+    physicsLog2 = createLogger("almadar:ui:physics-canvas");
     PhysicsCanvas = ({
       className,
       width = 600,
       height = 400,
       title,
       backgroundColor,
+      mode = "2d",
+      camera,
+      lighting,
+      post,
       bodies = [],
       constraints = [],
       showVelocity = true,
@@ -30451,7 +30791,9 @@ var init_PhysicsCanvas = __esm({
       velocityScale = 20,
       forceScale = 20,
       shapes = [],
-      interactive = false,
+      showGrid,
+      shadows,
+      interactive,
       animate = false,
       onShapeClick,
       isLoading,
@@ -30523,6 +30865,89 @@ var init_PhysicsCanvas = __esm({
         out.push(...shapes);
         return out;
       }, [bodies, constraints, showVelocity, showForces, velocityScale, forceScale, shapes]);
+      const drawables3D = useMemo(() => {
+        if (mode !== "3d") return [];
+        if (shapes.length > 0) {
+          physicsLog2.debug("shapes ignored in 3D mode (pixel-authored 2D vocabulary)", { count: shapes.length });
+        }
+        const out = [];
+        const labelColor = labelColorForBackground(backgroundColor);
+        const bodyById = /* @__PURE__ */ new Map();
+        for (const b of bodies) {
+          if (b.id) bodyById.set(b.id, b);
+        }
+        for (const c of constraints) {
+          const a = bodyById.get(c.from);
+          const b = bodyById.get(c.to);
+          if (!a || !b) continue;
+          const rodRadius = Math.max(0.05, Math.min(a.radius ?? 0.5, b.radius ?? 0.5) * 0.15);
+          const rod = cylinderBetween([a.x, a.y, a.z ?? 0], [b.x, b.y, b.z ?? 0], rodRadius, c.color ?? "#9ca3af");
+          if (rod) out.push(rod);
+        }
+        for (const b of bodies) {
+          const radius = b.radius ?? 0.5;
+          const bz = b.z ?? 0;
+          out.push(meshSphere(b.id, b.x, b.y, bz, radius, b.color ?? "#2563eb"));
+          if (b.label) {
+            out.push(billboardLabel(b.label, b.x, b.y, bz + radius, { color: labelColor }));
+          }
+          const vx = b.vx ?? 0;
+          const vy = b.vy ?? 0;
+          const vz = b.vz ?? 0;
+          const arrowRadius = Math.max(0.05, radius * 0.15);
+          if (showVelocity && (vx !== 0 || vy !== 0 || vz !== 0)) {
+            const arrow = arrowBetween(
+              [b.x, b.y, bz],
+              [b.x + vx * velocityScale, b.y + vy * velocityScale, bz + vz * velocityScale],
+              "#16a34a",
+              arrowRadius
+            );
+            if (arrow) out.push(arrow);
+          }
+          const fx = b.fx ?? 0;
+          const fy = b.fy ?? 0;
+          const fz = b.fz ?? 0;
+          if (showForces && (fx !== 0 || fy !== 0 || fz !== 0)) {
+            const arrow = arrowBetween(
+              [b.x, b.y, bz],
+              [b.x + fx * forceScale, b.y + fy * forceScale, bz + fz * forceScale],
+              "#dc2626",
+              arrowRadius
+            );
+            if (arrow) out.push(arrow);
+          }
+        }
+        return out;
+      }, [mode, bodies, constraints, showVelocity, showForces, velocityScale, forceScale, shapes, backgroundColor]);
+      const bodyIndexById = useMemo(() => {
+        const m = /* @__PURE__ */ new Map();
+        bodies.forEach((b, i) => {
+          if (b.id) m.set(b.id, i);
+        });
+        return m;
+      }, [bodies]);
+      if (mode === "3d") {
+        return /* @__PURE__ */ jsx(
+          LearningScene3D,
+          {
+            className,
+            width,
+            height,
+            title,
+            backgroundColor,
+            drawables: drawables3D,
+            camera,
+            lighting,
+            post,
+            showGrid,
+            shadows,
+            interactive,
+            isLoading,
+            error,
+            onItemClick: get3DClickPayload(onShapeClick, bodyIndexById)
+          }
+        );
+      }
       return /* @__PURE__ */ jsx(Card, { className, children: /* @__PURE__ */ jsxs(VStack, { gap: "sm", children: [
         title ? /* @__PURE__ */ jsx(Typography, { variant: "h4", children: title }) : null,
         /* @__PURE__ */ jsx(
@@ -30532,7 +30957,7 @@ var init_PhysicsCanvas = __esm({
             height,
             backgroundColor,
             shapes: derivedShapes,
-            interactive,
+            interactive: interactive ?? false,
             animate,
             onShapeClick,
             isLoading,
@@ -31150,12 +31575,12 @@ var init_MapView = __esm({
         shadowSize: [41, 41]
       });
       L.Marker.prototype.options.icon = defaultIcon;
-      const { useEffect: useEffect64, useRef: useRef64, useCallback: useCallback96, useState: useState100 } = React94__default;
+      const { useEffect: useEffect64, useRef: useRef65, useCallback: useCallback96, useState: useState100 } = React94__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 }) {
         const map = useMap();
-        const prevRef = useRef64({ centerLat, centerLng, zoom });
+        const prevRef = useRef65({ centerLat, centerLng, zoom });
         useEffect64(() => {
           const prev = prevRef.current;
           if (prev.centerLat !== centerLat || prev.centerLng !== centerLng || prev.zoom !== zoom) {
@@ -41569,7 +41994,7 @@ function getEnumOptions(field) {
     }));
   }
   const validation = field.validation;
-  if (validation?.enum && Array.isArray(validation.enum)) {
+  if (validation?.enum && validation.enum.length > 0) {
     return validation.enum.map((v) => ({
       value: v,
       label: v.charAt(0).toUpperCase() + v.slice(1).replace(/_/g, " ")

package/dist/{avl-schema-parser-DVmrgdwc.d.cts → avl-schema-parser-CVzkNzg7.d.cts}

@@ -1,7 +1,7 @@
 import { AnimationName, Asset, ScenePos, EventEmit, JsonObject, JsonValue } from '@almadar/core';
 import React__default from 'react';
 import * as THREE from 'three';
-import { D as DrawableNode } from './paintDispatch-Cb_hQj4Y.cjs';
+import { D as DrawableNode } from './paintDispatch-BjZjUbcb.cjs';
 
 /**
  * Sprite Sheet Animation Types
@@ -307,10 +307,11 @@ interface CameraState {
  * (forwarded as `followTarget`), falling back to the scene centre.
  *
  * Interaction: keyboard maps to semantic events (device-agnostic input). Pointer
- * click/hover on neutral drawables needs a per-entity id + a scene-space raycast
- * the descriptors don't yet carry — that hit-test is a tracked fork
- * (docs/Almadar_Std_Game_V2_PLAN.md); the click/hover event props are accepted but
- * not yet emitted from a raycast.
+ * click on a tagged drawable (a descriptor carrying `DrawableBase.id`) raycasts to
+ * the mesh and walks up to the tagged ancestor → `unitClickEvent {unitId,x,z}`;
+ * a click that hits no tagged mesh falls back to the ground-plane cell raycast →
+ * `tileClickEvent`. Pointer hover/feature events are accepted but not yet
+ * emitted (docs/Almadar_Std_Gaps.md S-CANVAS3D-HOVER-DEAD).
  *
  * @packageDocumentation
  */
@@ -422,8 +423,9 @@ interface Canvas3DHostProps {
         terrain?: string;
         elevation?: number;
     }>;
-    /** Declarative event: unit click. Emitted `{ unitId, x, z }` when the raycast lands on a
-     *  cell whose descriptor carries an `id` (a tagged unit sprite). */
+    /** Declarative event: unit click. Emitted `{ unitId, x, z }` when the raycast hits a
+     *  mesh tagged with a descriptor `id` (or lands on a ground cell whose descriptor
+     *  carries an `id`). */
     unitClickEvent?: EventEmit<{
         unitId: string;
         x: number;
@@ -477,8 +479,12 @@ interface Canvas3DHostProps {
     loadingMessage?: string;
     /** Unit draw-size multiplier (accepted for API parity; sizing is drawable-authored). */
     unitScale?: number;
-    /** Board zoom (accepted for API parity; 3D zoom is camera-driven, not group-scaled). */
-    scale?: number;
+    /** Board zoom — the neutral `Camera.zoom`. Dollies the camera: the framing
+     *  distance is divided by `zoom` (undefined/1 = default framing; <= 0 ignored). */
+    zoom?: number;
+    /** Enable the orbit camera controls. Default true; `follow`/`chase` modes always
+     *  disable them (the follow camera is authoritative). */
+    controlsEnabled?: boolean;
     /** Maps a keydown `e.code` → the board's SEMANTIC event (device-agnostic input). */
     keyMap?: Record<string, string>;
     /** Maps a keyup `e.code` → the board's SEMANTIC event. */
@@ -494,6 +500,9 @@ interface Canvas3DHostProps {
     fov?: number;
     /** Orbit the mode's framing position around the vertical axis through the target, in radians — the neutral `Camera.azimuth`. */
     azimuth?: number;
+    /** Orbit height angle above the ground plane, in radians — the neutral `Camera.elevation`
+     *  (perspective mode). Omitted → the mode's fixed framing height. */
+    elevation?: number;
     /** 3D scene light rig as data — ambient/directional/hemisphere/point lights + optional
      *  'room' environment. Omitted → the standard fixed rig (this host's current
      *  hardcoded lights, unchanged). */