@almadar/ui 5.94.1 → 5.95.0

package/dist/avl/index.js

@@ -13370,6 +13370,76 @@ var init_StateGraph = __esm({
     init_TransitionArrow();
   }
 });
+
+// components/game/shared/atlasSlice.ts
+function isTilesheet(a) {
+  return typeof a.tileWidth === "number";
+}
+function getAtlas(url, onReady) {
+  if (atlasCache.has(url)) return atlasCache.get(url) ?? void 0;
+  atlasCache.set(url, void 0);
+  fetch(url).then((r2) => r2.json()).then((json) => {
+    atlasCache.set(url, json);
+    onReady();
+  }).catch(() => {
+    atlasCache.set(url, null);
+  });
+  return void 0;
+}
+function subRectFor(atlas, sprite) {
+  if (isTilesheet(atlas)) {
+    let col;
+    let row;
+    if (sprite.includes(",")) {
+      const [c, r2] = sprite.split(",").map((n) => Number(n.trim()));
+      col = c;
+      row = r2;
+    } else {
+      const i = Number(sprite);
+      if (!Number.isFinite(i)) return null;
+      col = i % atlas.columns;
+      row = Math.floor(i / atlas.columns);
+    }
+    if (!Number.isFinite(col) || !Number.isFinite(row) || col < 0 || row < 0 || col >= atlas.columns || row >= atlas.rows) return null;
+    const margin = atlas.margin ?? 0;
+    const spacing = atlas.spacing ?? 0;
+    return {
+      sx: margin + col * (atlas.tileWidth + spacing),
+      sy: margin + row * (atlas.tileHeight + spacing),
+      sw: atlas.tileWidth,
+      sh: atlas.tileHeight
+    };
+  }
+  const st = atlas.subTextures[sprite];
+  if (!st) return null;
+  return { sx: st.x, sy: st.y, sw: st.width, sh: st.height };
+}
+function isAtlasAsset(asset) {
+  return !!asset && typeof asset.atlas === "string" && typeof asset.sprite === "string";
+}
+function resolveAssetSource(img, asset, onReady) {
+  if (isAtlasAsset(asset)) {
+    const atlas = getAtlas(asset.atlas, onReady);
+    if (!atlas) return null;
+    const rect = subRectFor(atlas, asset.sprite);
+    if (!rect) return null;
+    return { img, rect, aspect: rect.sw / rect.sh };
+  }
+  const natW = img.naturalWidth || 1;
+  const natH = img.naturalHeight || 1;
+  return { img, rect: null, aspect: natW / natH };
+}
+function blit(ctx, src, dx, dy, dw, dh) {
+  if (src.rect) ctx.drawImage(src.img, src.rect.sx, src.rect.sy, src.rect.sw, src.rect.sh, dx, dy, dw, dh);
+  else ctx.drawImage(src.img, dx, dy, dw, dh);
+}
+var atlasCache;
+var init_atlasSlice = __esm({
+  "components/game/shared/atlasSlice.ts"() {
+    "use client";
+    atlasCache = /* @__PURE__ */ new Map();
+  }
+});
 function useCamera() {
   const cameraRef = useRef({ x: 0, y: 0, zoom: 1 });
   const targetCameraRef = useRef(null);
@@ -13941,15 +14011,18 @@ function SideView({
         const platType = plat.type ?? "ground";
         const spriteAsset = tSprites?.[platType];
         const tileImg = spriteAsset ? loadImage(spriteAsset.url) : null;
-        if (tileImg) {
-          const tileW = tileImg.naturalWidth;
-          const tileH = tileImg.naturalHeight;
+        const tileSrc = tileImg ? resolveAssetSource(tileImg, spriteAsset, NOOP) : null;
+        if (tileSrc) {
+          const originX = tileSrc.rect ? tileSrc.rect.sx : 0;
+          const originY = tileSrc.rect ? tileSrc.rect.sy : 0;
+          const tileW = tileSrc.rect ? tileSrc.rect.sw : tileImg.naturalWidth;
+          const tileH = tileSrc.rect ? tileSrc.rect.sh : tileImg.naturalHeight;
           const scaleH = plat.height / tileH;
           const scaledW = tileW * scaleH;
           for (let tx = 0; tx < plat.width; tx += scaledW) {
             const drawW = Math.min(scaledW, plat.width - tx);
             const srcW = drawW / scaleH;
-            ctx.drawImage(tileImg, 0, 0, srcW, tileH, platX + tx, platY, drawW, plat.height);
+            ctx.drawImage(tileImg, originX, originY, srcW, tileH, platX + tx, platY, drawW, plat.height);
           }
         } else {
           const color = PLATFORM_COLORS[platType] ?? PLATFORM_COLORS.ground;
@@ -13983,14 +14056,15 @@ function SideView({
       const ppy = py - camY;
       const facingRight = auth.facingRight ?? true;
       const playerImg = pSprite ? loadImage(pSprite.url) : null;
-      if (playerImg) {
+      const playerSrc = playerImg ? resolveAssetSource(playerImg, pSprite, NOOP) : null;
+      if (playerSrc) {
         ctx.save();
         if (!facingRight) {
           ctx.translate(ppx + pw, ppy);
           ctx.scale(-1, 1);
-          ctx.drawImage(playerImg, 0, 0, pw, ph);
+          blit(ctx, playerSrc, 0, 0, pw, ph);
         } else {
-          ctx.drawImage(playerImg, ppx, ppy, pw, ph);
+          blit(ctx, playerSrc, ppx, ppy, pw, ph);
         }
         ctx.restore();
       } else {
@@ -14191,10 +14265,11 @@ function Canvas2D({
   const attackTargetSet = useMemo(() => new Set(attackTargets.map((p) => `${p.x},${p.y}`)), [attackTargets]);
   const spriteUrls = useMemo(() => {
     const urls = [];
+    const toUrl = (x) => typeof x === "string" ? x : x?.url;
     for (const tile of sortedTiles) {
       if (tile.terrainSprite) urls.push(tile.terrainSprite.url);
       else if (getTerrainSprite) {
-        const url = getTerrainSprite(tile.terrain ?? "");
+        const url = toUrl(getTerrainSprite(tile.terrain ?? ""));
         if (url) urls.push(url);
       } else {
         const url = assetManifest?.terrains?.[tile.terrain ?? ""]?.url;
@@ -14204,7 +14279,7 @@ function Canvas2D({
     for (const feature of features) {
       if (feature.sprite) urls.push(feature.sprite.url);
       else if (getFeatureSprite) {
-        const url = getFeatureSprite(feature.type);
+        const url = toUrl(getFeatureSprite(feature.type));
         if (url) urls.push(url);
       } else {
         const url = assetManifest?.features?.[feature.type]?.url;
@@ -14214,7 +14289,7 @@ function Canvas2D({
     for (const unit of units) {
       if (unit.sprite) urls.push(unit.sprite.url);
       else if (getUnitSprite) {
-        const url = getUnitSprite(unit);
+        const url = toUrl(getUnitSprite(unit));
         if (url) urls.push(url);
       } else if (unit.unitType) {
         const url = assetManifest?.units?.[unit.unitType]?.url;
@@ -14255,14 +14330,25 @@ function Canvas2D({
     screenToWorld,
     lerpToTarget
   } = useCamera();
-  const resolveTerrainSpriteUrl = useCallback((tile) => {
-    return tile.terrainSprite?.url || getTerrainSprite?.(tile.terrain ?? "") || assetManifest?.terrains?.[tile.terrain ?? ""]?.url;
+  const [, setAtlasVersion] = useState(0);
+  const bumpAtlas = useCallback(() => setAtlasVersion((v) => v + 1), []);
+  const resolveTerrainAsset = useCallback((tile) => {
+    if (tile.terrainSprite) return tile.terrainSprite;
+    const s = getTerrainSprite?.(tile.terrain ?? "");
+    if (s) return typeof s === "string" ? { url: s } : s;
+    return assetManifest?.terrains?.[tile.terrain ?? ""];
   }, [getTerrainSprite, assetManifest]);
-  const resolveFeatureSpriteUrl = useCallback((featureType) => {
-    return getFeatureSprite?.(featureType) || assetManifest?.features?.[featureType]?.url;
+  const resolveFeatureAsset = useCallback((feature) => {
+    if (feature.sprite) return feature.sprite;
+    const s = getFeatureSprite?.(feature.type);
+    if (s) return typeof s === "string" ? { url: s } : s;
+    return assetManifest?.features?.[feature.type];
   }, [getFeatureSprite, assetManifest]);
-  const resolveUnitSpriteUrl = useCallback((unit) => {
-    return unit.sprite?.url || getUnitSprite?.(unit) || (unit.unitType ? assetManifest?.units?.[unit.unitType]?.url : void 0);
+  const resolveUnitAsset = useCallback((unit) => {
+    if (unit.sprite) return unit.sprite;
+    const s = getUnitSprite?.(unit);
+    if (s) return typeof s === "string" ? { url: s } : s;
+    return unit.unitType ? assetManifest?.units?.[unit.unitType] : void 0;
   }, [getUnitSprite, assetManifest]);
   const miniMapTiles = useMemo(() => {
     if (!showMinimap) return [];
@@ -14326,18 +14412,17 @@ function Canvas2D({
       if (pos.x + scaledTileWidth < visLeft || pos.x > visRight || pos.y + scaledTileHeight < visTop || pos.y > visBottom) {
         continue;
       }
-      const spriteUrl = resolveTerrainSpriteUrl(tile);
-      const img = spriteUrl ? getImage(spriteUrl) : null;
-      if (img) {
-        if (img.naturalWidth === 0) {
-          ctx.drawImage(img, pos.x, pos.y, scaledTileWidth, scaledTileHeight);
-        } else {
-          const drawW = scaledTileWidth;
-          const drawH = scaledTileWidth * (img.naturalHeight / img.naturalWidth);
-          const drawX = pos.x;
-          const drawY = flatLike ? pos.y : pos.y + scaledTileHeight - drawH;
-          ctx.drawImage(img, drawX, drawY, drawW, drawH);
-        }
+      const terrainAsset = resolveTerrainAsset(tile);
+      const img = terrainAsset?.url ? getImage(terrainAsset.url) : null;
+      const src = img ? resolveAssetSource(img, terrainAsset, bumpAtlas) : null;
+      if (src) {
+        const drawW = scaledTileWidth;
+        const drawH = scaledTileWidth / src.aspect;
+        const drawX = pos.x;
+        const drawY = flatLike ? pos.y : pos.y + scaledTileHeight - drawH;
+        blit(ctx, src, drawX, drawY, drawW, drawH);
+      } else if (img && img.naturalWidth === 0) {
+        ctx.drawImage(img, pos.x, pos.y, scaledTileWidth, scaledTileHeight);
       } else {
         const centerX = pos.x + scaledTileWidth / 2;
         const topY = pos.y + scaledDiamondTopY;
@@ -14391,15 +14476,16 @@ function Canvas2D({
       if (pos.x + scaledTileWidth < visLeft || pos.x > visRight || pos.y + scaledTileHeight < visTop || pos.y > visBottom) {
         continue;
       }
-      const spriteUrl = feature.sprite?.url || resolveFeatureSpriteUrl(feature.type);
-      const img = spriteUrl ? getImage(spriteUrl) : null;
+      const featureAsset = resolveFeatureAsset(feature);
+      const img = featureAsset?.url ? getImage(featureAsset.url) : null;
+      const src = img ? resolveAssetSource(img, featureAsset, bumpAtlas) : null;
       const centerX = pos.x + scaledTileWidth / 2;
       const featureGroundY = pos.y + scaledDiamondTopY + scaledFloorHeight * 0.5;
       const isCastle = feature.type === "castle";
       const featureDrawH = isCastle ? scaledFloorHeight * 3.5 : scaledFloorHeight * 1.6;
       const maxFeatureW = isCastle ? scaledTileWidth * 1.8 : scaledTileWidth * 0.7;
-      if (img) {
-        const ar = img.naturalWidth / img.naturalHeight;
+      if (src) {
+        const ar = src.aspect;
         let drawH = featureDrawH;
         let drawW = featureDrawH * ar;
         if (drawW > maxFeatureW) {
@@ -14408,7 +14494,7 @@ function Canvas2D({
         }
         const drawX = centerX - drawW / 2;
         const drawY = featureGroundY - drawH;
-        ctx.drawImage(img, drawX, drawY, drawW, drawH);
+        blit(ctx, src, drawX, drawY, drawW, drawH);
       } else {
         const color = FEATURE_COLORS[feature.type] || FEATURE_COLORS.default;
         ctx.beginPath();
@@ -14437,17 +14523,18 @@ function Canvas2D({
       const centerX = pos.x + scaledTileWidth / 2;
       const groundY = pos.y + scaledDiamondTopY + scaledFloorHeight * 0.5;
       const breatheOffset = 0;
-      const unitSpriteUrl = resolveUnitSpriteUrl(unit);
-      const img = unitSpriteUrl ? getImage(unitSpriteUrl) : null;
+      const unitAsset = resolveUnitAsset(unit);
+      const img = unitAsset?.url ? getImage(unitAsset.url) : null;
       const unitDrawH = scaledFloorHeight * spriteHeightRatio * unitScale;
       const maxUnitW = scaledTileWidth * spriteMaxWidthRatio * unitScale;
       const unitIsSheet = unit.spriteSheet?.url !== void 0;
+      const unitSrc = img && !unitIsSheet ? resolveAssetSource(img, unitAsset, bumpAtlas) : null;
       const SHEET_ROWS = 5;
       const sheetFrameW = img ? img.naturalWidth / SHEET_COLUMNS : 0;
       const sheetFrameH = img ? img.naturalHeight / SHEET_ROWS : 0;
       const frameW = unitIsSheet ? sheetFrameW : img?.naturalWidth ?? 1;
       const frameH = unitIsSheet ? sheetFrameH : img?.naturalHeight ?? 1;
-      const ar = frameW / (frameH || 1);
+      const ar = unitIsSheet ? sheetFrameW / (sheetFrameH || 1) : unitSrc ? unitSrc.aspect : frameW / (frameH || 1);
       let drawH = unitDrawH;
       let drawW = unitDrawH * ar;
       if (drawW > maxUnitW) {
@@ -14463,6 +14550,8 @@ function Canvas2D({
         if (img) {
           if (unitIsSheet) {
             ctx.drawImage(img, 0, 0, sheetFrameW, sheetFrameH, ghostCenterX - drawW / 2, ghostGroundY - drawH, drawW, drawH);
+          } else if (unitSrc) {
+            blit(ctx, unitSrc, ghostCenterX - drawW / 2, ghostGroundY - drawH, drawW, drawH);
           } else {
             ctx.drawImage(img, ghostCenterX - drawW / 2, ghostGroundY - drawH, drawW, drawH);
           }
@@ -14511,6 +14600,8 @@ function Canvas2D({
         const drawUnit = (x) => {
           if (unitIsSheet) {
             ctx.drawImage(img, 0, 0, sheetFrameW, sheetFrameH, x, spriteY, drawW, drawH);
+          } else if (unitSrc) {
+            blit(ctx, unitSrc, x, spriteY, drawW, drawH);
           } else {
             ctx.drawImage(img, x, spriteY, drawW, drawH);
           }
@@ -14561,11 +14652,12 @@ function Canvas2D({
     flatLike,
     scale,
     debug2,
-    resolveTerrainSpriteUrl,
-    resolveFeatureSpriteUrl,
-    resolveUnitSpriteUrl,
+    resolveTerrainAsset,
+    resolveFeatureAsset,
+    resolveUnitAsset,
     resolveFrameForUnit,
     getImage,
+    bumpAtlas,
     baseOffsetX,
     scaledTileWidth,
     scaledTileHeight,
@@ -14879,7 +14971,7 @@ function Canvas2D({
     }
   );
 }
-var PLATFORM_COLORS, PLAYER_COLOR, PLAYER_EYE_COLOR, SKY_GRADIENT_TOP, SKY_GRADIENT_BOTTOM, GRID_COLOR, DEFAULT_PLATFORMS;
+var PLATFORM_COLORS, NOOP, PLAYER_COLOR, PLAYER_EYE_COLOR, SKY_GRADIENT_TOP, SKY_GRADIENT_BOTTOM, GRID_COLOR, DEFAULT_PLATFORMS;
 var init_Canvas2D = __esm({
   "components/game/2d/molecules/Canvas2D.tsx"() {
     "use client";
@@ -14893,6 +14985,7 @@ var init_Canvas2D = __esm({
     init_MiniMap();
     init_HealthBar();
     init_useImageCache();
+    init_atlasSlice();
     init_useCamera();
     init_useCanvasGestures();
     init_useRenderInterpolation();
@@ -14906,6 +14999,8 @@ var init_Canvas2D = __esm({
       hazard: "#c0392b",
       goal: "#f1c40f"
     };
+    NOOP = () => {
+    };
     PLAYER_COLOR = "#3498db";
     PLAYER_EYE_COLOR = "#ffffff";
     SKY_GRADIENT_TOP = "#1a1a2e";
@@ -19564,6 +19659,153 @@ var init_ComponentPatterns = __esm({
     AlertPattern.displayName = "AlertPattern";
   }
 });
+var DEFAULT_BAR_COLOR, DEFAULT_CELL_COLOR, DEFAULT_POINTER_COLOR, POINTER_BAND, TOP_PAD, AlgorithmCanvas;
+var init_AlgorithmCanvas = __esm({
+  "components/learning/molecules/AlgorithmCanvas.tsx"() {
+    "use client";
+    init_atoms();
+    init_Stack();
+    init_LearningCanvas();
+    DEFAULT_BAR_COLOR = "#3b82f6";
+    DEFAULT_CELL_COLOR = "#e5e7eb";
+    DEFAULT_POINTER_COLOR = "#dc2626";
+    POINTER_BAND = 34;
+    TOP_PAD = 12;
+    AlgorithmCanvas = ({
+      className,
+      width = 600,
+      height = 400,
+      title,
+      backgroundColor,
+      bars = [],
+      cells = [],
+      pointers = [],
+      shapes = [],
+      interactive = false,
+      animate = false,
+      onShapeClick,
+      isLoading,
+      error
+    }) => {
+      const derivedShapes = useMemo(() => {
+        const out = [];
+        if (bars.length > 0) {
+          const slot = width / bars.length;
+          const barW = slot * 0.8;
+          const gap = slot * 0.1;
+          const baseline = height - POINTER_BAND;
+          const usableH = baseline - TOP_PAD;
+          const maxV = Math.max(1, ...bars.map((b) => Number.isFinite(b.value) ? b.value : 0));
+          bars.forEach((bar, i) => {
+            const v = Number.isFinite(bar.value) ? bar.value : 0;
+            const bh = Math.max(0, v / maxV * usableH);
+            const x = i * slot + gap;
+            const color = bar.color ?? DEFAULT_BAR_COLOR;
+            out.push({
+              type: "rect",
+              id: `bar-${i}`,
+              x,
+              y: baseline - bh,
+              width: barW,
+              height: bh,
+              color,
+              fill: color
+            });
+            const label = bar.label ?? (bars.length <= 24 ? String(v) : void 0);
+            if (label) {
+              out.push({
+                type: "text",
+                x: x + barW / 2,
+                y: baseline - bh - 8,
+                text: label,
+                color: "#374151",
+                fontSize: 11,
+                align: "center"
+              });
+            }
+          });
+          pointers.forEach((p) => {
+            if (p.index < 0 || p.index >= bars.length) return;
+            const cx = p.index * slot + slot / 2;
+            const color = p.color ?? DEFAULT_POINTER_COLOR;
+            out.push({
+              type: "arrow",
+              x1: cx,
+              y1: height - 6,
+              x2: cx,
+              y2: baseline + 4,
+              color,
+              lineWidth: 2
+            });
+            if (p.label) {
+              out.push({
+                type: "text",
+                x: cx,
+                y: height - 22,
+                text: p.label,
+                color,
+                fontSize: 11,
+                align: "center"
+              });
+            }
+          });
+        }
+        if (cells.length > 0) {
+          const maxCol = Math.max(0, ...cells.map((c) => c.col)) + 1;
+          const maxRow = Math.max(0, ...cells.map((c) => c.row)) + 1;
+          const cw = width / maxCol;
+          const ch = height / maxRow;
+          cells.forEach((c, i) => {
+            const x = c.col * cw;
+            const y = c.row * ch;
+            const color = c.color ?? DEFAULT_CELL_COLOR;
+            out.push({
+              type: "rect",
+              id: `cell-${i}`,
+              x: x + 1,
+              y: y + 1,
+              width: cw - 2,
+              height: ch - 2,
+              color: "#9ca3af",
+              fill: color
+            });
+            const label = c.label ?? (c.value != null ? String(c.value) : void 0);
+            if (label && cw >= 18 && ch >= 14) {
+              out.push({
+                type: "text",
+                x: x + cw / 2,
+                y: y + ch / 2,
+                text: label,
+                color: "#111827",
+                fontSize: 12,
+                align: "center"
+              });
+            }
+          });
+        }
+        out.push(...shapes);
+        return out;
+      }, [bars, cells, pointers, shapes, width, height]);
+      return /* @__PURE__ */ jsx(Card, { className, children: /* @__PURE__ */ jsxs(VStack, { gap: "sm", children: [
+        title ? /* @__PURE__ */ jsx(Typography, { variant: "h4", children: title }) : null,
+        /* @__PURE__ */ jsx(
+          LearningCanvas,
+          {
+            width,
+            height,
+            backgroundColor,
+            shapes: derivedShapes,
+            interactive,
+            animate,
+            onShapeClick,
+            isLoading,
+            error
+          }
+        )
+      ] }) });
+    };
+  }
+});
 var AuthLayout;
 var init_AuthLayout = __esm({
   "components/marketing/templates/AuthLayout.tsx"() {
@@ -48019,6 +48261,7 @@ var init_component_registry_generated = __esm({
     init_ActionTile();
     init_ActivationBlock();
     init_ComponentPatterns();
+    init_AlgorithmCanvas();
     init_AnimatedCounter();
     init_AnimatedGraphic();
     init_AnimatedReveal();
@@ -48317,6 +48560,7 @@ var init_component_registry_generated = __esm({
       "ActivationBlock": ActivationBlock,
       "Alert": AlertPattern,
       "AlertPattern": AlertPattern,
+      "AlgorithmCanvas": AlgorithmCanvas,
       "AnimatedCounter": AnimatedCounter,
       "AnimatedGraphic": AnimatedGraphic,
       "AnimatedReveal": AnimatedReveal,

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

@@ -56,6 +56,7 @@ export { MathCanvas, type MathCanvasProps, type MathCurve, type MathPoint, type
 export { PhysicsCanvas, type PhysicsCanvasProps, type LearningPhysicsBody, type LearningPhysicsConstraint, } from '../../learning/molecules/PhysicsCanvas';
 export { BiologyCanvas, type BiologyCanvasProps, type BiologyNode, type BiologyEdge, } from '../../learning/molecules/BiologyCanvas';
 export { ChemistryCanvas, type ChemistryCanvasProps, type ChemistryAtom, type ChemistryBond, type ChemistryArrow, } from '../../learning/molecules/ChemistryCanvas';
+export { AlgorithmCanvas, type AlgorithmCanvasProps, type AlgorithmBar, type AlgorithmCell, type AlgorithmPointer, } from '../../learning/molecules/AlgorithmCanvas';
 export { GraphView, type GraphViewProps, type GraphViewNode, type GraphViewEdge } from './GraphView';
 export { MapView, type MapViewProps, type MapMarkerData, type MapRouteData, type MapRouteWaypoint } from './MapView';
 export { NumberStepper, type NumberStepperProps, type NumberStepperSize } from './NumberStepper';

package/dist/components/game/2d/molecules/Canvas2D.d.ts

@@ -134,12 +134,12 @@ export interface Canvas2DProps {
     spriteMaxWidthRatio?: number;
     /** Override for the diamond-top Y offset within the tile sprite. */
     diamondTopY?: number;
-    /** Resolve terrain sprite URL from terrain key */
-    getTerrainSprite?: (terrain: string) => string | undefined;
-    /** Resolve feature sprite URL from feature type key */
-    getFeatureSprite?: (featureType: string) => string | undefined;
-    /** Resolve unit static sprite URL */
-    getUnitSprite?: (unit: IsometricUnit) => string | undefined;
+    /** Resolve terrain sprite from terrain key — a bare URL or an Asset (atlas sub-texture ref). */
+    getTerrainSprite?: (terrain: string) => string | Asset | undefined;
+    /** Resolve feature sprite from feature type key — a bare URL or an Asset. */
+    getFeatureSprite?: (featureType: string) => string | Asset | undefined;
+    /** Resolve unit static sprite — a bare URL or an Asset. */
+    getUnitSprite?: (unit: IsometricUnit) => string | Asset | undefined;
     /** Resolve animated sprite sheet frame for a unit */
     resolveUnitFrame?: (unitId: string) => ResolvedFrame | null;
     /** Additional sprite URLs to preload (e.g., effect sprites) */

package/dist/components/game/shared/atlasSlice.d.ts

@@ -0,0 +1,58 @@
+/**
+ * atlasSlice — the ONLY place a packed sheet is cut at runtime.
+ *
+ * An `Asset` may carry `{ url: <sheet.png>, atlas: <atlas.json>, sprite: <name|index> }`. This
+ * module fetches + caches the atlas JSON (a `TextureAtlas` of named sub-rects or a uniform
+ * `Tilesheet`) and resolves the source rectangle for a `sprite`, so the canvas can `drawImage`
+ * exactly that sub-region of the sheet. Coexists with the whole-PNG path (an Asset with no
+ * `atlas`/`sprite` draws the whole image) and the `useUnitSpriteAtlas` animation path.
+ *
+ * See `docs/Almadar_Std_Assets.md` §2, §7.
+ *
+ * @packageDocumentation
+ */
+import type { TextureAtlas, Tilesheet } from '@almadar/core';
+/** The minimal draw-relevant projection of an `Asset` — a sheet URL plus an optional atlas
+ *  sub-texture reference. A full `@almadar/core` `Asset` is structurally assignable. */
+export interface SpriteRef {
+    url?: string;
+    atlas?: string;
+    sprite?: string;
+}
+type ParsedAtlas = TextureAtlas | Tilesheet;
+/**
+ * Get a parsed atlas by URL, fetching+caching on first request. Returns undefined until loaded;
+ * `onReady` fires once when the fetch resolves so the caller can trigger a re-render.
+ */
+export declare function getAtlas(url: string, onReady: () => void): ParsedAtlas | undefined;
+export interface SubRect {
+    sx: number;
+    sy: number;
+    sw: number;
+    sh: number;
+}
+/**
+ * Resolve the source rect for `sprite` in `atlas`.
+ * - `TextureAtlas`: `sprite` is a SubTexture name (e.g. `"blockBrown.png"`).
+ * - `Tilesheet`: `sprite` is `"col,row"` or a flat index into the row-major grid.
+ * Returns null if the name/index doesn't resolve.
+ */
+export declare function subRectFor(atlas: ParsedAtlas, sprite: string): SubRect | null;
+/** True when the asset points into a sheet (needs slicing) rather than being a whole PNG. */
+export declare function isAtlasAsset(asset: SpriteRef | undefined | null): boolean;
+export interface AssetSource {
+    img: HTMLImageElement;
+    /** Sub-rect to blit; null = draw the whole image. */
+    rect: SubRect | null;
+    /** Source aspect ratio (width/height) — sub-rect for a slice, natural otherwise. */
+    aspect: number;
+}
+/**
+ * Resolve what to draw for `asset` given its loaded sheet `img`. Returns null when the asset is
+ * an atlas ref whose JSON isn't loaded yet (or whose sprite name doesn't resolve) — `onReady`
+ * will trigger a re-render once the fetch lands. Callers use `.aspect` to size, then `blit`.
+ */
+export declare function resolveAssetSource(img: HTMLImageElement, asset: SpriteRef | undefined | null, onReady: () => void): AssetSource | null;
+/** Draw a resolved source at `(dx,dy,dw,dh)` — sliced sub-rect or whole image. */
+export declare function blit(ctx: CanvasRenderingContext2D, src: AssetSource, dx: number, dy: number, dw: number, dh: number): void;
+export {};