@jgengine/assets 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -11,6 +11,53 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
+## 0.8.0
+
+Transport-agnostic multiplayer (socket.io, WebRTC p2p, LAN/Fly adapters) plus grid/voxel
+and puzzle primitives, HUD-only presentation, cumulative leveling, and a round of
+controller/camera/sensor additions. **Breaking:** the `gameui` component kit moved out of
+`@jgengine/react` onto the shadcn registry.
+
+### Migrate
+
+- Bump every `@jgengine/*` dependency to `^0.8.0` (the eight packages version in lockstep).
+- Additive only, except for `gameui` — every other 0.7.0 API is unchanged; opt into any of the below by importing it directly.
+- **Breaking:** replace any `@jgengine/react/gameui` import with the equivalent registry component (`npx shadcn@latest add https://jgengine.com/r/<name>.json`), and swap `GameUiThemeProvider` for `--jg-*` CSS variables on a wrapper element. `GameIcon` and friends moved to `@jgengine/react/gameIcons`.
+- `leveling({ thresholdMode: 'cumulative' })` is opt-in; the default `perLevel` behavior is unchanged.
+- `defineGame.physics.gravity`/`jumpVelocity` are now read by the built-in kinematics controller every frame — if a game already set them expecting a no-op, jump/fall now actually reflects them; omit both to keep the previous defaults.
+
+### Added
+
+- Cumulative leveling — `leveling({ thresholdMode: 'cumulative' })` tracks xp as a lifetime total that resolves upward across levels and clamps at the max-level threshold once capped (#12).
+- Direction-aware pool depletion — `EffectSystem.canReceive(instanceId, effect, magnitude?)` takes an optional signed magnitude; negative checks the opposite direction and returns `pools-depleted` only when every stat in the receive order is already at max, so heals reach fully-depleted targets (#168).
+- Puzzle primitives — `puzzle/cellGrid` (uniform-cell boards: line-clear, match-3 cascade, run detection) and `puzzle/fallingPiece` (rotation-state shapes, ghost drop, lock delay, classic gravity/level/score curves) for Tetris/match-3 games (#166).
+- Voxel field — `world/voxelField` (`createVoxelField`, chunked block lattice, neighbors/exposedFaces, 3D DDA raycast, dirty-tracked `chunkVersion`) for voxel games and instanced renderers; assert on `field.summary()` the way environment worlds assert on `summarizeEnvironment` (#166).
+- `defineGame` games may omit `assets` (an empty catalog is injected); `PlayableGame.presentation: 'hud'` mounts no 3D canvas/camera/pointer for board/card/menu games; an `environment()` world auto-renders as the shell's backdrop when `PlayableGame.environment` is unset (#166).
+- Declared-action intent board — `turn/intent` `createIntentBoard` for one-turn-ahead intents (Slay-the-Spire style): declare/peek/all/consume/clear (#168).
+- `turnLoop` lifecycle hooks — `config.onTurnStart`/`onTurnEnd` fire on every `advanceTurn()`; `ctx.game.turn.loop(id, config)` lazily creates/returns a notify-wrapped `TurnLoop` so every mutation (`advanceTurn`/`advancePhase`/`advanceRound`/`spend`/`gain`/`refill`/`setOrder`/...) auto-bumps `ctx.version()` with no manual wiring (#163/#168).
+- `ctx.game.store` — a reactive per-game keyed store (`set`/`delete`/`get`/`has`/`subscribe`/`mapSnapshot`/`arraySnapshot`) plus `@jgengine/react`'s `useGameStore` selector hook, replacing hand-rolled module-level stores for ad-hoc reactive game state; `ctx.game.cards.pile(id, config?)` lazily creates/returns a notify-wrapped `CardPile` the same way; `createCardPile` gained an `onChange` hook for headless use; `CommandDefinition.apply` may return void for side-effect-only commands (#163).
+- Camera — `sideScroll` rig (fixed lateral follow for 2.5D platformers/beat-'em-ups), a `none` rig (no camera mounted; pairs with `PlayableGame.presentation: 'hud'`), `rts.pan: false` (static backdrop camera: no pan/edge-scroll/rotate/zoom, still re-centers on the follow target), and the `observer` rig now defaults to the local player when `bind` is unset (#167).
+- Sensors + session — `sensor/concealment` (`colorDistance`/`concealmentScore`/`createConcealmentSensor`), `sensor/freezeMonitor` (`createFreezeMonitor`), `session/roles` (`assignRoles`); `createRoundState`'s `RoundConfig.teams` accepts per-team roles and an optional `winCondition` that `evaluate()` checks each tick, and takes an optional `phaseOrder` for arbitrary named phase cycles (`concludeRound`/`evaluate` settle only while the current phase is neither the first nor the last entry) (#151).
+- Appearance replication — presence rows carry an optional per-slot appearance channel (cosmetic ids, hex tints, model keys) alongside pose, riding the existing pose message with no protocol bump; wire `ctx.player.cosmetics.get(userId)` into the outgoing pose (#151).
+- `ctx.input` — a per-frame held-action snapshot (`publish(held)`/`isDown(action)`/`held()`) without bumping `ctx.version()`; action bindings gained `repeatMs` (repeat-fire while held); every command resolved from a bound action now carries `aim`; `pointer.secondaryCommand` runs a command on right-click off the same raycast as move/ping (#164).
+- Object spatial queries + entity patching — `ctx.scene.object.at`/`inBox`/`raycast`/`raycastAll` over unit-box objects; `ctx.scene.entity.update(id, patch)` for name/position/rotation/role/movement/behaviors/meta; per-instance `renderObject`/`objectStyles` overrides; `pointerService.worldHitCenter()` + pointer-lock center-ray aiming (#165).
+- Controller movement config — `PlayerMovementConfig` (`mode`: free/axis/grid, `axis`, `cellSize`, `collideObjects`, `beforeCommit` pre-commit hook) for the shell-driven walk controller; `defineGame.physics.gravity`/`jumpVelocity` are honored by the built-in walk controller (distinct from the standalone `physics/physicsWorld` rigid-body sim); `ctx.player.motion.impulse`/`setVerticalVelocity`/`setY`/`takePending` (`MotionIntents`); `entity.spawnPoseOf`/`resetToSpawn`/`resetAllToSpawn` (#162).
+- Model material/animation + paint — `ModelConfig.tint`/`metalness`/`roughness`/`animation` (GLTF clip playback, paused pose holds); `PointerHit.uv` + `pointerService.sampleSurface()` for material-aware picking; `ctx.scene.entity.paint` runtime paint layer, auto-rendered via a per-instance canvas texture with no per-game wiring; remote-player appearance tint recolors the shell's default capsule (#151).
+- **Transport pipe seam** (`@jgengine/ws/pipe`) — `createWsBackend` runs over any bidirectional string channel, not just a raw `WebSocket`: `TransportPipe`/`TransportPipeHandlers`/`TransportPipeFactory`, with `webSocketPipe(url, webSocketFactory?)` as the default. `createWsBackend({ userId, url?, pipe? })` — `url` stays the common case, `pipe` opens the seam to socket.io, WebRTC, and in-process loopback below.
+- **Browser-safe authoritative host** — `createGameHost` and `memoryPersistence` moved from `@jgengine/node` to `@jgengine/ws/host` (zero Node dependencies; `@jgengine/node` re-exports both unchanged from `@jgengine/node/host` / `@jgengine/node/persistence`, so existing imports keep working). `@jgengine/ws/hostRouter`'s `createHostRouter({ host, authenticate?, poseRules?, positionHistoryMs?, chatRateLimit?, chatHistoryLimit?, chatMaxBodyLength?, now? })` extracts the ws wire-protocol session logic out of `createGameWsServer` into a transport-agnostic `HostRouter` (`connect(transport) → { handleRaw, close }`, `rewind`, `close`); `@jgengine/node`'s `createGameWsServer` is now a thin binding of this router onto the `ws` npm package, same public API. `loopbackPipe(router): TransportPipeFactory` connects a `createWsBackend` straight into an in-process router.
+- **Socket.IO transport** — `@jgengine/ws/socketIoPipe` (`SocketIoLikeSocket` structural type, `socketIoPipe(socket)`, `createSocketIoBackend({ socket, userId, … })`) and `@jgengine/node/socketIoServer` (`attachGameSocketIoServer({ io, host, …router options }): { rewind, close }`, structural `SocketIoLikeServer`/`SocketIoLikeServerSocket`) ride the existing ws JSON protocol over socket.io's `send`/`message` frames — no socket.io dependency in either package's types. New `socketIo({ topology?, url? })` adapter in `@jgengine/core/runtime/adapter`.
+- **WebRTC peer-to-peer** (`@jgengine/ws/peer`) — one browser tab hosts, authoritatively, with no server process. `createPeerHost({ userId, host?, runtimes?, persistence?, tickMs?, router?, rtc? })` runs a `GameHost` + `HostRouter` in the host tab (`backend` is the host player's own loopback connection, `accept(offerCode) → Promise<answerCode>` per guest); `createPeerGuest({ userId, token?, rtc? })` offers/connects from the joining side. `encodePeerSignal`/`decodePeerSignal` turn SDP into copy-pasteable base64url codes for manual cross-machine signaling; `broadcastChannelSignaling(room)` automates it for same-origin multi-tab play, with `announcePeerHost`/`joinPeerSession` wiring host/guest to a `PeerSignaling` in one call. New `p2p({ topology?, room? })` adapter (topology defaults `"private"`).
+- **LAN adapter + Fly sugar** — `lan({ topology?, port?, path? })` in `@jgengine/core/runtime/adapter` resolves through `@jgengine/shell/multiplayer`'s `resolveShellMultiplayer` to `ws(s)://<page hostname>:<port ?? 8080><path ?? /ws>` derived from `window.location`, so any browser on the LAN auto-connects to whichever machine served the page — no URL configuration. `fly({ app, topology?, path? })` is `ws` sugar for a Fly.io deploy: resolves to `wss://<app>.fly.dev<path ?? "/ws">`. `apps/dev`'s Vite server now listens on the network (`server: { host: true }`) and exposes `?p2p=host` / `?p2p=join` query params wired through the new `resolvePeerShellMultiplayer({ gameId, role, room?, userId?, feedActions? })`.
+- `ws()` (`@jgengine/core/runtime/adapter`) gained an optional `url` field, carried through by `resolveShellMultiplayer` (`args.url ?? adapter.url ?? default`).
+
+### Removed
+
+- **The `gameui` component kit** (`@jgengine/react/gameui`) — the themed HUD kit (bars, slots, feedback, meters, panels, screens, reticles, icons) and its `GameUiThemeProvider`/`useGameUiTheme` theming have been removed. **Breaking** for anyone importing `@jgengine/react/gameui` (or its subpaths/barrel). The components now ship as installable shadcn registry items at `https://jgengine.com/r/<name>.json` (`npx shadcn@latest add https://jgengine.com/r/<name>.json`), styled with Tailwind + `--jg-*` CSS variables instead of a theme object. The icon catalog (`GameIcon`, `iconForAction`, `iconForItemId`, `isGameIconName`, `GameIconName`) moved to `@jgengine/react/gameIcons`. To theme, set the `--jg-*` variables on a wrapper element (the registry's `jg-theme` presets mirror the old `ember`/`synthwave`/`fieldkit` palettes) instead of wrapping in `GameUiThemeProvider`.
+
+### Docs
+
+- Added [CREDITS.md](CREDITS.md) crediting [achrefelouafi](https://github.com/achrefelouafi) for the MIT Three.js reference projects behind the procedural building, water, rain, and snow renderers, with links from the root, `@jgengine/core`, and `@jgengine/shell` READMEs.
+
 ## 0.7.0
 
 The engine-gaps release — 22 system-level additions across turn/tactics, cards & boards,

package/README.md

@@ -23,7 +23,8 @@ Everything collapses into the core `AssetCatalog` via `buildCatalog({ basePath }
 ```
 assets list [--category <c>] [--source <s>]   # browse the generated index
 assets search <term>                          # grep the index
-assets pull <source-id> [--dir public]        # download + extract GLBs into <dir>/models/<source>/
+assets pull <source-id> [--dir public] [--mirror <baseUrl>] [--offline]
+                                               # download + extract GLBs into <dir>/models/<source>/
 assets add <path|url> --category <c> --license <l> [--author <a>]
 assets reindex [public/models]                # regenerate generated/*.json from pulled packs
 assets verify                                 # license + alias-integrity gate
@@ -31,6 +32,23 @@ assets verify                                 # license + alias-integrity gate
 
 Run in-repo with `bun run --cwd packages/assets src/cli/pull.ts <verb> …`.
 
+### Mirror fallback and offline pulls
+
+`pull` never has just one path to the bytes. For a given `source-id` it tries, in order, until one succeeds:
+
+1. **Mirror base override** — `--mirror <baseUrl>` (or the `JGENGINE_ASSETS_MIRROR` env var if `--mirror` is not passed) — the archive is expected at `<baseUrl>/<provider>/<source-id>.zip`, e.g. `https://my-mirror.example.com/kenney/kenney-nature.zip`.
+2. **The primary provider path** — the source's pinned `{ url, sha256? }` or, for providers that rotate URLs (Kenney), a scrape of the asset page.
+3. **The pack's own `mirror`** — an optional direct archive URL set on the `AssetSource` entry itself (`src/sources/*.ts`), tried as a last resort.
+
+If every attempt fails, `pull` throws one aggregated error naming every URL it tried and why each one failed. Whenever the source's `download` is pinned with a `sha256`, the downloaded bytes are hashed and checked against it **no matter which of the three paths supplied them** — a mirror serving stale or tampered bytes is rejected and the next source in the chain is tried instead.
+
+`--offline` skips the network entirely: it succeeds immediately if `<dir>/models/<source-id>/` already has files in it, and otherwise fails fast with a message telling you to pull once on a connected machine or point `--mirror`/`JGENGINE_ASSETS_MIRROR` at a reachable archive — useful for CI scripts that should error in seconds instead of hanging on a blocked fetch.
+
+**Network-restricted environments** — pull once on a machine that can reach the providers, then either:
+
+- commit (or otherwise host) the resulting `public/models/<source-id>/` directory so restricted environments read it straight off disk and use `assets pull --offline` as a fast, honest no-op check, or
+- host your own mirror of the zip archives at `<baseUrl>/<provider>/<source-id>.zip` and set `JGENGINE_ASSETS_MIRROR=<baseUrl>` (or pass `--mirror <baseUrl>`) so `pull` fetches from it instead of the original provider.
+
 ## Adding assets
 
 **A whole new pack** — add one entry to the matching `src/sources/*.ts` (this is the layer contributors PR). No filenames are hand-typed; `reindex` reads the real `.glb` names out of the extracted pack, so entries can't silently 404.
@@ -46,7 +64,7 @@ bun src/cli/pull.ts reindex ../../apps/dev/public/models           # regenerate
 bun src/cli/pull.ts verify                                         # license + alias gate
 ```
 
-A **new provider** is just a new `src/sources/<provider>.ts` added to the `sources` array in `src/sources/index.ts`. Pinned providers use `download: { url, sha256? }`; providers that rotate URLs (Kenney) use `download: { scrape: <page> }`.
+A **new provider** is just a new `src/sources/<provider>.ts` added to the `sources` array in `src/sources/index.ts`. Pinned providers use `download: { url, sha256? }`; providers that rotate URLs (Kenney) use `download: { scrape: <page> }`. Any entry can also carry an optional top-level `mirror: <archiveUrl>` — a direct URL `pull` falls back to if both a `--mirror`/`JGENGINE_ASSETS_MIRROR` override and the primary path fail (see "Mirror fallback and offline pulls" above).
 
 **A single one-off** — no code edit, zero bytes stored (URL) or copied into `local/` (path):
 
@@ -78,7 +96,7 @@ export const game: PlayableGame = {
 };
 ```
 
-`buildCatalog({ sources: ["kenney-nature"] })` restricts to chosen packs; `includeAliases` / `includeSingles` default true. Discover ids with `assets search <term>` / `assets list --category <c>` instead of memorizing them. See `packages/games/asset-showcase` for a full working example.
+`buildCatalog({ sources: ["kenney-nature"] })` restricts to chosen packs; `includeAliases` / `includeSingles` default true. Discover ids with `assets search <term>` / `assets list --category <c>` instead of memorizing them. See `Games/asset-showcase` for a full working example.
 
 ### Serving the bytes
 
@@ -94,3 +112,4 @@ bun src/cli/pull.ts pull kenney-nature --dir ../../apps/dev/public   # → apps/
 
 - Kenney rotates download URLs, so its sources `scrape` the asset page at pull time.
 - Quaternius / KayKit pages gate downloads behind JS; automated `pull` falls back to a clear error when no archive link is found — download those manually into the staging dir, then `reindex`.
+- `pull`'s mirror fallback and `--offline` guard exist for network-restricted environments (CI, sandboxes without provider access); see "Mirror fallback and offline pulls" above.

package/dist/cli/pull.d.ts

@@ -1,2 +1,4 @@
 #!/usr/bin/env node
-export {};
+export declare function flag(argv: string[], name: string): string | undefined;
+export declare function isPopulated(dir: string): boolean;
+export declare function cmdPull(argv: string[]): Promise<void>;

package/dist/cli/pull.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { downloadArchive, extractGlbs, extractTextures, resolveArchiveUrl, sha256Hex } from "../download.js";
+import { downloadPackArchive, extractGlbs, extractTextures } from "../download.js";
 import { generatedIndex } from "../generated/index.js";
 import { reindex } from "../indexGen.js";
 import { isScrapeDownload } from "../manifest.js";
@@ -15,7 +15,7 @@ const generatedDir = join(srcDir, "generated");
 const singlesJson = join(srcDir, "singles.json");
 const localDir = join(pkgRoot, "local");
 const CDN_BASE = "https://cdn.jsdelivr.net/gh/Noisemaker111/jgengine@main/packages/assets/local";
-function flag(argv, name) {
+export function flag(argv, name) {
     const index = argv.indexOf(`--${name}`);
     return index >= 0 ? argv[index + 1] : undefined;
 }
@@ -46,25 +46,33 @@ function cmdSearch(argv) {
     }
     console.log(`— ${Math.min(rows.length, limit)} of ${rows.length} matches for "${term}"`);
 }
-async function cmdPull(argv) {
+export function isPopulated(dir) {
+    return existsSync(dir) && readdirSync(dir).length > 0;
+}
+export async function cmdPull(argv) {
     const sourceId = argv[0];
-    if (sourceId === undefined)
-        fail("usage: pull <source-id> [--dir <dir>]");
+    if (sourceId === undefined) {
+        fail("usage: pull <source-id> [--dir <dir>] [--mirror <baseUrl>] [--offline]");
+    }
     const source = sourceById.get(sourceId);
     if (source === undefined)
         fail(`unknown source: ${sourceId}`);
     const outRoot = resolve(flag(argv, "dir") ?? "public");
     const outDir = join(outRoot, "models", sourceId);
-    console.log(`resolving ${sourceId}${isScrapeDownload(source.download) ? " (scrape)" : ""}…`);
-    const url = await resolveArchiveUrl(source);
-    console.log(`downloading ${url}`);
-    const archive = await downloadArchive(url);
-    if (!isScrapeDownload(source.download) && source.download.sha256 !== undefined) {
-        const actual = await sha256Hex(archive);
-        if (actual !== source.download.sha256) {
-            fail(`sha256 mismatch for ${sourceId}: expected ${source.download.sha256}, got ${actual}`);
+    const offline = argv.includes("--offline");
+    const mirrorBase = flag(argv, "mirror") ?? process.env.JGENGINE_ASSETS_MIRROR;
+    if (offline) {
+        if (!isPopulated(outDir)) {
+            fail(`--offline set but ${outDir} is empty; pull it once on a connected machine (or via ` +
+                `--mirror/JGENGINE_ASSETS_MIRROR) and commit/host that directory before running offline`);
         }
+        console.log(`offline: ${outDir} already populated, skipping network`);
+        return;
     }
+    console.log(`resolving ${sourceId}${isScrapeDownload(source.download) ? " (scrape)" : ""}` +
+        `${mirrorBase !== undefined ? ` [mirror override: ${mirrorBase}]` : ""}…`);
+    const { archive, url, attempted } = await downloadPackArchive(source, { mirrorBase });
+    console.log(`downloaded ${url}${attempted.length > 1 ? ` (after ${attempted.length - 1} failed attempt(s))` : ""}`);
     const glbs = extractGlbs(archive);
     if (glbs.length === 0)
         fail(`no .glb files found in ${sourceId} archive`);
@@ -143,28 +151,30 @@ function cmdVerify() {
         console.error(`  ✗ ${error}`);
     fail(`verify failed with ${result.errors.length} problem(s)`);
 }
-const [command, ...rest] = process.argv.slice(2);
-switch (command) {
-    case "list":
-        cmdList(rest);
-        break;
-    case "search":
-        cmdSearch(rest);
-        break;
-    case "pull":
-        await cmdPull(rest);
-        break;
-    case "add":
-        cmdAdd(rest);
-        break;
-    case "reindex":
-        cmdReindex(rest);
-        break;
-    case "verify":
-        cmdVerify();
-        break;
-    default:
-        console.log("usage: assets <list|search|pull|add|reindex|verify> [...args]");
-        if (command !== undefined && command !== "help")
-            process.exit(1);
+if (import.meta.main) {
+    const [command, ...rest] = process.argv.slice(2);
+    switch (command) {
+        case "list":
+            cmdList(rest);
+            break;
+        case "search":
+            cmdSearch(rest);
+            break;
+        case "pull":
+            await cmdPull(rest);
+            break;
+        case "add":
+            cmdAdd(rest);
+            break;
+        case "reindex":
+            cmdReindex(rest);
+            break;
+        case "verify":
+            cmdVerify();
+            break;
+        default:
+            console.log("usage: assets <list|search|pull|add|reindex|verify> [...args]");
+            if (command !== undefined && command !== "help")
+                process.exit(1);
+    }
 }

package/dist/download.d.ts

@@ -1,4 +1,5 @@
 import { type AssetSource } from "./manifest.js";
+export type FetchLike = typeof fetch;
 export interface ExtractedGlb {
     file: string;
     bytes: Uint8Array;
@@ -9,8 +10,35 @@ export interface ExtractedTexture {
     bytes: Uint8Array;
 }
 export declare function findArchiveUrl(html: string, pageUrl: string): string | null;
-export declare function resolveArchiveUrl(source: AssetSource): Promise<string>;
-export declare function downloadArchive(url: string): Promise<Uint8Array>;
+export declare function resolveArchiveUrl(source: AssetSource, fetchImpl?: FetchLike): Promise<string>;
+export declare function downloadArchive(url: string, fetchImpl?: FetchLike): Promise<Uint8Array>;
+/**
+ * Layout for the `--mirror` / `JGENGINE_ASSETS_MIRROR` base URL override: the
+ * archive for a pack is expected at `<baseUrl>/<provider>/<packId>.zip`, e.g.
+ * `https://my-mirror.example.com/kenney/kenney-nature.zip`.
+ */
+export declare function mirrorOverrideUrl(baseUrl: string, source: AssetSource): string;
+export interface DownloadPackOptions {
+    /** Explicit mirror base override (CLI `--mirror` / `JGENGINE_ASSETS_MIRROR`), tried before the primary provider path. */
+    mirrorBase?: string;
+    fetchImpl?: FetchLike;
+}
+export interface DownloadPackResult {
+    archive: Uint8Array;
+    url: string;
+    /** Every URL attempted, in order, ending with the one that succeeded. */
+    attempted: readonly string[];
+}
+/**
+ * Resolves and downloads a pack's archive, trying sources in order until one
+ * succeeds: (1) the mirror base override at `mirrorOverrideUrl`, (2) the
+ * primary provider path (`resolveArchiveUrl`: scrape or pinned URL), (3) the
+ * pack's own `mirror` URL. A pinned `sha256` is verified against whichever
+ * source supplied the bytes; a mismatch is treated as a failed attempt so the
+ * next source in the chain is tried. Throws with every attempted URL and its
+ * failure reason when all sources fail.
+ */
+export declare function downloadPackArchive(source: AssetSource, options?: DownloadPackOptions): Promise<DownloadPackResult>;
 export declare function extractGlbs(archive: Uint8Array): ExtractedGlb[];
 export declare function extractTextures(archive: Uint8Array): ExtractedTexture[];
 export declare function sha256Hex(bytes: Uint8Array): Promise<string>;

package/dist/download.js

@@ -26,11 +26,11 @@ function score(candidate) {
         value += 1;
     return value;
 }
-export async function resolveArchiveUrl(source) {
+export async function resolveArchiveUrl(source, fetchImpl = fetch) {
     const download = source.download;
     if (!isScrapeDownload(download))
         return download.url;
-    const response = await fetch(download.scrape, { redirect: "follow" });
+    const response = await fetchImpl(download.scrape, { redirect: "follow" });
     if (!response.ok)
         throw new Error(`scrape ${download.scrape} -> HTTP ${response.status}`);
     const html = await response.text();
@@ -40,12 +40,79 @@ export async function resolveArchiveUrl(source) {
     }
     return url;
 }
-export async function downloadArchive(url) {
-    const response = await fetch(url, { redirect: "follow" });
+export async function downloadArchive(url, fetchImpl = fetch) {
+    const response = await fetchImpl(url, { redirect: "follow" });
     if (!response.ok)
         throw new Error(`download ${url} -> HTTP ${response.status}`);
     return new Uint8Array(await response.arrayBuffer());
 }
+/**
+ * Layout for the `--mirror` / `JGENGINE_ASSETS_MIRROR` base URL override: the
+ * archive for a pack is expected at `<baseUrl>/<provider>/<packId>.zip`, e.g.
+ * `https://my-mirror.example.com/kenney/kenney-nature.zip`.
+ */
+export function mirrorOverrideUrl(baseUrl, source) {
+    const base = baseUrl.replace(/\/+$/, "");
+    return `${base}/${source.provider}/${source.id}.zip`;
+}
+async function verifyPinnedSha(source, archive) {
+    const download = source.download;
+    if (isScrapeDownload(download) || download.sha256 === undefined)
+        return;
+    const actual = await sha256Hex(archive);
+    if (actual !== download.sha256) {
+        throw new Error(`sha256 mismatch: expected ${download.sha256}, got ${actual}`);
+    }
+}
+/**
+ * Resolves and downloads a pack's archive, trying sources in order until one
+ * succeeds: (1) the mirror base override at `mirrorOverrideUrl`, (2) the
+ * primary provider path (`resolveArchiveUrl`: scrape or pinned URL), (3) the
+ * pack's own `mirror` URL. A pinned `sha256` is verified against whichever
+ * source supplied the bytes; a mismatch is treated as a failed attempt so the
+ * next source in the chain is tried. Throws with every attempted URL and its
+ * failure reason when all sources fail.
+ */
+export async function downloadPackArchive(source, options = {}) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const attempted = [];
+    const errors = [];
+    const tryUrl = async (url) => {
+        attempted.push(url);
+        try {
+            const archive = await downloadArchive(url, fetchImpl);
+            await verifyPinnedSha(source, archive);
+            return { archive, url, attempted };
+        }
+        catch (error) {
+            errors.push(`${url}: ${error instanceof Error ? error.message : String(error)}`);
+            return undefined;
+        }
+    };
+    if (options.mirrorBase !== undefined) {
+        const result = await tryUrl(mirrorOverrideUrl(options.mirrorBase, source));
+        if (result !== undefined)
+            return result;
+    }
+    try {
+        const primaryUrl = await resolveArchiveUrl(source, fetchImpl);
+        const result = await tryUrl(primaryUrl);
+        if (result !== undefined)
+            return result;
+    }
+    catch (error) {
+        const label = isScrapeDownload(source.download) ? source.download.scrape : source.download.url;
+        errors.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+        attempted.push(label);
+    }
+    if (source.mirror !== undefined) {
+        const result = await tryUrl(source.mirror);
+        if (result !== undefined)
+            return result;
+    }
+    throw new Error(`failed to download ${source.id} from all ${attempted.length} source(s):\n` +
+        errors.map((line) => `  - ${line}`).join("\n"));
+}
 export function extractGlbs(archive) {
     const entries = unzipSync(archive, {
         filter: (file) => /\.glb$/i.test(file.name),

package/dist/manifest.d.ts

@@ -19,6 +19,8 @@ export interface AssetSource {
     categories: readonly string[];
     download: AssetDownload;
     homepage?: string;
+    /** Direct archive URL tried as a last resort when the primary provider path fails; see `downloadPackArchive`. */
+    mirror?: string;
 }
 export interface IndexEntry {
     id: string;