@jgengine/assets 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,7 +1,8 @@
 # Changelog
 
-All eight `@jgengine/*` packages are versioned in lockstep, so this one file
-covers every release. Format follows [Keep a Changelog](https://keepachangelog.com);
+The lockstep game SDK set is `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`
+(this file’s 0.x.y releases). The CLI package `jgengine` and `@jgengine/github` use
+**separate** version lines and may lag. Format follows [Keep a Changelog](https://keepachangelog.com);
 each release **leads with a Migrate block** — the concrete steps to move a game
 from the previous version onto the new APIs — because the point of a bump is to
 let consumers pick up the better stuff, not just to list what moved.
@@ -11,7 +12,37 @@ 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.
 
-## Unreleased
+## 0.11.0
+
+### Migrate
+
+- **Nothing required** — classic `loop.onTick` fan-out still runs after systems. Prefer moving per-frame work into `defineGame({ systems: [...] })` with `defineSystem` (`@jgengine/core/game/defineSystem`); install a system with `feature: "quest"` (etc.) instead of a redundant `features` flag. See skill `jgengine` → [reference-systems.md](.claude/skills/jgengine/reference-systems.md).
+
+### Added
+
+- **Composable game systems** (#842) — `defineSystem` / `compileSystemSchedule` / `composeGameLoop` / `installSystems`. `defineGame({ systems })` is the single authoring path: fixed / frame / interval / event-only / manual ticks, multi-subscribe channels, deterministic stage order + optional `before`/`after`/`dependsOn`, system-owned save / replicate / reset / dispose. Installing a system activates its `feature` without a separate flag. `GameLoop` gains optional `onReset` / `onDispose`. `ctx.game.registerSave` / `registerReplicate` for system modules. Adopters: tower-guard, claudecraft (runtime without a giant tick fan-out).
+
+## 0.10.0
+
+### Migrate
+
+- **Nothing to change for existing games** — the shared mobile-composition system (viewport allocation, region collision, `--jg-*` viewport vars) is wired automatically by the shell for every game; `HudPanel`s inside a `HudCanvas` register themselves. Legacy `orientation: "landscape" | "portrait"` keeps its advisory dismissible-hint behavior unchanged.
+- **Opt a driving/landscape game into the strict gate**: replace the advisory `orientation` with the contract form — `orientation: { mobile: "landscape-required" }` (rules: `any` · `portrait`/`landscape` advisory · `portrait-required`/`landscape-required` · `unsupported`). In portrait the engine now shows a polished `RotateDeviceScreen`, suppresses input, freezes the sim, and unmounts the HUD/controls until the device is landscape.
+- **Declare HUD intent** where useful: `HudPanel` gains `priority` (`critical`/`secondary`/`tertiary`), `mobileBehavior` (`hidden` unmounts on phones, `transient` softens collision, …), `allowOverlapWith`, and `collisionGroup`. Optional — omitting them keeps prior behavior.
+- **Mobile validation now also fails on overlap**: `bun run shoot <game> --device mobile|mobile-landscape|both` exits non-zero on forbidden inter-element collisions (not just viewport overflow), naming both regions.
+
+### Added
+
+- Shared mobile layout composition — `@jgengine/core/ui/gameLayout` (pure geometry: `resolveLayoutMode`, `intersects`, `overlapArea`, `detectLayoutCollisions`, `computeGameplayRect`, `LayoutRegion`, `GameViewportLayout`) and `@jgengine/core/ui/orientation` (`resolveOrientationRequirement`, `orientationGateActive`, `MobileOrientationRule`). `@jgengine/react` adds `GameViewportProvider` (mounted by the shell), hooks (`useGameViewportLayout`, `useGameLayoutMode`, `useGameOrientation`, `useReservedControlZones`, `useLayoutCollisions`, `useRegisterLayoutRegion`), and a headless `RotateDeviceScreen`. The provider tracks `window.visualViewport`, publishes `--jg-viewport-*` / `--jg-visual-viewport-*` / `--jg-safe-*` CSS vars, resolves the explicit layout mode, and detects forbidden region overlaps (dev `data-jg-layout-collision` + console diagnostic).
+- Mandatory orientation contract — `PlayableGame.orientation` accepts `{ mobile: <rule> }`; `landscape-required`/`portrait-required` render an engine-owned rotate gate that blocks gameplay (input suppressed, simulation frozen, HUD/controls unmounted), self-correcting when the device is turned. Reduced-motion and safe-area respected; `visualViewport`-sized for mobile Safari/PWA.
+- Reserved touch-control zones — the touch dock registers its joystick / action-cluster / utility rectangles (runtime-measured) as `control` regions, so HUD placement and collision validation know exactly where controls sit.
+- HUD placement metadata — `HudPanel` gains `priority`, `mobileBehavior`, `allowOverlapWith`, `collisionGroup`, and registers as a collision-tracked layout region.
+- Mobile-landscape shoot device — `bun run shoot --device mobile-landscape` (844×390) plus collision-gate reads that fail mobile validation on forbidden overlaps.
+- Canyon Chase migrated as the reference landscape-required game — declares `orientation: { mobile: "landscape-required" }`, composes its HUD through coordinated `HudPanel` regions (pursuit distance critical, border secondary, survey map hidden on mobile, radio transient) instead of independent fixed corners.
+
+### Changed
+
+- First-person projectile tracers now originate from the weapon muzzle instead of the camera/eye centerline. Hit detection is unchanged (still crosshair-accurate) — only the drawn tracer's start point moved to the viewmodel muzzle, which tracks full aim yaw and pitch. Non-viewmodel games and enemy tracers are unaffected.
 
 ## 0.9.0
 

package/README.md

@@ -1,37 +1,45 @@
 # @jgengine/assets
 
-A self-generating, license-verified index of thousands of CC0 3D models — hosted at **zero cost**. No GLB bytes ship in the npm tarball; every byte comes from infrastructure you don't pay for:
+A self-generating, license-verified index of thousands of CC0 3D models, PBR materials, **and 2D sprite/icon packs** G�� hosted at **zero cost**. No GLB, texture, or sprite bytes ship in the npm tarball; every byte comes from infrastructure you don't pay for:
 
 | What | Where it lives | Whose bandwidth |
 |------|----------------|-----------------|
-| Pack GLBs (Kenney, Quaternius, KayKit…) | Fetched at `pull` time from the provider's CDN | Provider's |
+| Pack GLBs (Quaternius, KayKitGǪ) | Fetched at `pull` time from the provider's CDN | Provider's |
+| PBR materials (ambientCG) | Fetched at `pull` time (provider or the `packs` release mirror) | Provider's / GitHub's |
+| Sprite/icon packs (game-icons.net) | Fetched at `pull` time (provider or the `packs` release mirror) | Provider's / GitHub's |
 | The generated index (JSON) | Inside this npm package | npm (KB) |
 | Your one-off models | `packages/assets/local/`, served via jsDelivr-over-GitHub | GitHub + jsDelivr |
-| A consumer's downloaded bytes | Their `public/models/` (gitignored) | The consumer's |
+| A consumer's downloaded bytes | Their `public/models/` + `public/materials/` + `public/sprites/` (gitignored) | The consumer's |
 
 ## Layers
 
-1. **Sources** (`src/sources/*.ts`) — one entry per downloadable pack. Every entry carries required `license` + `author` and a `download` that is either a pinned `{ url, sha256? }` or a `{ scrape }` marker.
-2. **Generated index** (`src/generated/*.json`) — machine-produced from the real `.glb` filenames after a pack is extracted. Never hand-typed. Committed JSON; bytes are not.
-3. **Aliases** (`src/aliases.ts`) — hand-authored semantic keys (`nature/tree_pine → kenney-nature/tree_pineDefaultA`).
-4. **Singles** (`src/singles.json`) — long-tail one-offs (per-model `url` + `license`).
+1. **Sources** (`src/sources/*.ts`) G�� one entry per downloadable pack. Every entry carries required `license` + `author` and a `download` that is either a pinned `{ url, sha256? }` or a `{ scrape }` marker.
+2. **Generated index** (`src/generated/*.json`) G�� machine-produced from the real `.glb` filenames after a pack is extracted. Never hand-typed. Committed JSON; bytes are not.
+3. **Aliases** (`src/aliases.ts`) G�� hand-authored semantic keys (`nature/tree_pine G�� quaternius-stylized-nature/Pine_1`).
+4. **Singles** (`src/singles.json`) G�� long-tail one-offs (per-model `url` + `license`).
+5. **Materials** (`src/sources/ambientcg.ts` + `src/materials.ts`) G�� `kind: "material"` sources, one CC0 PBR material each (hundreds of ambientCG materials: grass, rock, wood, brick, metal, fabricGǪ). `pull` normalizes the maps to fixed filenames, so `buildMaterialCatalog({ basePath })` resolves ids and `material/GǪ` aliases to map URLs with no generated index at all.
+6. **Sprites** (`src/sources/gameicons.ts` + `src/spriteIndexGen.ts`) G�� `kind: "sprite"` sources, packs of individual SVG/PNG icon and UI files (game-icons.net's ~4,000 CC BY 3.0 icons as one mirrored repo). Same shape as models G�� `reindex-sprites` discovers real files after a pull and writes `src/generated-sprites/*.json`, resolved through `buildSpriteCatalog({ basePath })`.
 
-Everything collapses into the core `AssetCatalog` via `buildCatalog({ basePath })`.
+Model entries collapse into the core `AssetCatalog` via `buildCatalog({ basePath })`; materials resolve through `buildMaterialCatalog({ basePath })`; sprites/icons resolve through `buildSpriteCatalog({ basePath })`.
 
-## `add` — one command for anything
+## `add` G�� one command for anything
 
-`assets add <query>` is the front door. It fuzzy-searches **every** catalog at once — 3D models, whole packs, HUD components (the shadcn registry), and `game-icon` glyphs — then does the fetch and prints the exact copy-paste wiring. One mental model instead of four.
+`assets add <query>` is the front door. It fuzzy-searches **every** catalog at once G�� 3D models, whole packs, PBR materials, sprite/icon packs, HUD components (the shadcn registry), and `game-icon` glyphs G�� then does the fetch and prints the exact copy-paste wiring. One mental model instead of six.
 
 ```bash
-assets add astronaut --dir ../../apps/dev/public   # model → pull + reindex + print the assets.ts snippet
-assets add nature    --dir ../../apps/dev/public   # whole pack → pull + reindex + how to wire an id
-assets add "mana bar"                              # HUD component → the `npx shadcn add` cmd + <VitalBar/> usage
-assets add sword                                    # icon → the game-icon name to drop in a slot
+assets add astronaut --dir ../../apps/dev/public   # model G�� pull + reindex + print the assets.ts snippet
+assets add nature    --dir ../../apps/dev/public   # whole pack G�� pull + reindex + how to wire an id
+assets add grass --kind material --dir ../../apps/dev/public  # PBR material G�� pull maps + resolve snippet
+assets add "game icons" --dir ../../apps/dev/public  # sprite pack G�� pull + reindex-sprites + resolve snippet
+assets add "mana bar"                              # HUD component G�� the `npx shadcn add` cmd + <VitalBar/> usage
+assets add sword                                    # icon G�� the game-icon name to drop in a slot
 ```
 
 - A **model / pack** match is fully automated: if the pack isn't already in `<dir>/models/`, it's pulled and extracted, then `reindex` runs so the id is addressable, then the `buildCatalog` + model-seam snippet is printed.
-- A **component / icon** match prints the one-liner to run and the import + usage — no bytes to pull.
-- Ambiguous query? `add` lists the top matches across kinds; narrow with `--kind model|pack|component|icon` or a more specific term. `--json` emits the ranked matches for scripting.
+- A **material** match pulls the maps into `<dir>/materials/<id>/` with normalized names (`color.jpg`, `normal.jpg`, `roughness.jpg`, `ao.jpg`, `displacement.jpg`) and prints the `buildMaterialCatalog` resolve snippet G�� no reindex needed, the material catalog is fully static.
+- A **sprite / spritePack** match works like model/pack: if the pack isn't already in `<dir>/sprites/`, it's pulled and extracted, then `reindex-sprites` runs so individual SVG/PNG ids are addressable, then the `buildSpriteCatalog` snippet is printed.
+- A **component / icon** match prints the one-liner to run and the import + usage G�� no bytes to pull.
+- Ambiguous query? `add` lists the top matches across kinds; narrow with `--kind model|pack|material|component|icon|sprite|spritePack` or a more specific term. `--json` emits the ranked matches for scripting.
 
 The same ranking is available programmatically: `import { findAssets } from "@jgengine/assets"`.
 
@@ -39,98 +47,143 @@ The same ranking is available programmatically: `import { findAssets } from "@jg
 
 ```
 assets add <query> [--kind <k>] [--dir <dir>] [--mirror <baseUrl>] [--json]
-                                               # unified import: models, packs, components, icons
-assets list [--category <c>] [--source <s>]   # browse the generated index
-assets search <term>                          # grep the index
+                                               # unified import: models, packs, materials, sprites, components, icons
+assets list [--category <c>] [--source <s>] [--kind material|sprite|spritePack]
+                                               # browse the generated model/sprite index, or the material/sprite-pack catalog
+assets search <term>                          # grep the model index
 assets pull <source-id> [--dir public] [--mirror <baseUrl>] [--offline]
-                                               # download + extract a whole pack's GLBs into <dir>/models/<source>/
+                                               # download + extract a pack into <dir>/models|materials|sprites/<source>/
 assets register <path|url> --category <c> --license <l> [--author <a>]
                                                # register a one-off single into the shipped index
-assets reindex [public/models]                # regenerate generated/*.json from pulled packs
+assets reindex [public/models]                # regenerate generated/*.json from pulled model packs
+assets reindex-sprites [public/sprites]       # regenerate generated-sprites/*.json from pulled sprite packs
 assets verify                                 # license + alias-integrity gate
+assets provenance <id> [<id>...]              # resolve each id's owner (committed/provisioned/dangling); non-zero on any dangling
 ```
 
-Run in-repo with `bun run --cwd packages/assets src/cli/pull.ts <verb> …`. (`add <path|url> --license …` still works as an alias for `register`.)
+### Reference integrity
+
+Every logical asset id resolves to a declared **owner** through the provisioning contract (`resolveProvenance`): `committed` (a single's shipped URL — resolves on a clean clone with no pull), `provisioned` (a pack index entry whose GLB `assets pull <source>` fetches into the served dir), or `dangling` (nothing owns it, so it can never resolve). `validateAssetReferences(refs)` turns a set of `{ consumer, id }` references into a clean-clone gate: it fails on any dangling reference — naming the consumer, the logical id, and the null resolved path — and returns the exact `assets pull <source>` steps the checkout still needs so provisioning stays deterministic and `ensure-ready`-driven. It resolves references structurally against the catalog rather than grepping source text.
+
+At runtime the shell validates a model fetch *before* parsing (`classifyAssetResponse` in `@jgengine/core/scene/assetDiagnostics`): it checks HTTP status, content type, and the GLB/glTF signature, then reports `missing`, `html` (a dev-server fallback page served in place of the file), `corrupt`, or `unsupported` with the URL — replacing the opaque `Unexpected token <` GLTF parse error the old path produced when a model was absent.
+
+Run in-repo with `bun run --cwd packages/assets src/cli/pull.ts <verb> GǪ`. (`add <path|url> --license GǪ` still works as an alias for `register`.)
 
 ### 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 default GitHub-release mirror** — `https://github.com/Noisemaker111/jgengine/releases/download/packs/<provider>-<source-id>.zip`, on this repo's own rolling `packs` release (no separate assets repo). github.com is reachable from every cloud sandbox with no network-policy change, so zero-setup sessions still pull. `.github/workflows/mirror-assets.yml` (weekly cron + manual dispatch) keeps the release in sync with `src/sources/*.ts` automatically — adding a catalog entry is the whole publishing step, no manual upload. Skip this hop with `JGENGINE_ASSETS_NO_DEFAULT_MIRROR=1`.
-3. **The primary provider path** — the source's pinned `{ url, sha256? }` or, for providers that rotate URLs (Kenney), a scrape of the asset page.
-4. **The pack's own `mirror`** — an optional direct archive URL set on the `AssetSource` entry itself (`src/sources/*.ts`), tried as a last resort.
+1. **Mirror base override** G�� `--mirror <baseUrl>` (or the `JGENGINE_ASSETS_MIRROR` env var if `--mirror` is not passed) G�� the archive is expected at `<baseUrl>/<provider>/<source-id>.zip`, e.g. `https://my-mirror.example.com/quaternius/quaternius-stylized-nature.zip`.
+2. **The default GitHub-release mirror** G�� `https://github.com/Noisemaker111/jgengine/releases/download/packs/<provider>-<source-id>.zip`, on this repo's own rolling `packs` release (no separate assets repo). github.com is reachable from every cloud sandbox with no network-policy change, so zero-setup sessions still pull. `.github/workflows/mirror-assets.yml` (weekly cron + manual dispatch) keeps the release in sync with `src/sources/*.ts` automatically G�� adding a catalog entry is the whole publishing step, no manual upload. Skip this hop with `JGENGINE_ASSETS_NO_DEFAULT_MIRROR=1`. Model/sprite pack failures fail the job; individual ambientCG material 404s are soft (logged, non-fatal).
+3. **The primary provider path** G�� pinned `{ url, sha256? }` when stable: **KayKit** G�� `github.com/KayKit-Game-Assets/*/archive/GǪ/main.zip`; **Quaternius** free Standard packs G�� OpenGameArt direct zips (site pages JS-gate). Else scrape. `extractGlbs` packs co-located `.gltf`+`.bin` into `.glb`.
+4. **The pack's own `mirror`** G�� 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 path supplied them** — a mirror serving stale or tampered bytes is rejected and the next source in the chain is tried instead.
+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 path supplied them** G�� 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.
+`--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 G�� useful for CI scripts that should error in seconds instead of hanging on a blocked fetch.
 
-**Network-restricted environments** — a `403` on `CONNECT` from an outbound proxy means the environment's network policy blocks that provider host (common in sandboxed cloud sessions); it is a policy decision, not a transient failure, so retrying never helps. Either allowlist the host in the environment settings, or pull once on a machine that can reach the providers, then:
+**Network-restricted environments** G�� a `403` on `CONNECT` from an outbound proxy means the environment's network policy blocks that provider host (common in sandboxed cloud sessions); it is a policy decision, not a transient failure, so retrying never helps. Either allowlist the host in the environment settings, or pull once on a machine that can reach the providers, then:
 
 - 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.
+**A whole new pack** G�� 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.
 
 ```ts
-// src/sources/kenney.ts → KENNEY_PACKS
-{ id: "kenney-food", slug: "food-kit", title: "Food Kit", categories: ["food", "prop"] },
+// src/sources/quaternius.ts G�� QUATERNIUS_PACKS
+{ id: "quaternius-fantasy-props", slug: "fantasypropsmegakit", title: "Fantasy Props MegaKit", categories: ["fantasy", "prop"] },
 ```
 
 ```bash
-bun src/cli/pull.ts pull kenney-food --dir ../../apps/dev/public   # fetch + extract GLBs
-bun src/cli/pull.ts reindex ../../apps/dev/public/models           # regenerate generated/*.json + barrel
-bun src/cli/pull.ts verify                                         # license + alias gate
+bun src/cli/pull.ts pull quaternius-fantasy-props --dir ../../apps/dev/public   # fetch + extract GLBs
+bun src/cli/pull.ts reindex ../../apps/dev/public/models                        # regenerate generated/*.json + barrel
+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> }`. 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 **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 whose pages JS-gate the download and can't be pinned use `download: { scrape: <page> }`. Any entry can also carry an optional top-level `mirror: <archiveUrl>` G�� 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). Kenney.nl is not an eligible provider for this repo G�� see CLAUDE.md "Never Kenney".
+
+**A whole new sprite/icon pack** G�� same shape as a model pack, just `kind: "sprite"` and `reindex-sprites` instead of `reindex`; files are matched by `.svg`/`.png` extension, deduped by basename regardless of archive nesting, so no filenames are hand-typed here either. `src/sources/gameicons.ts` is the current example (`gameicons-icons`); a new sprite provider follows the same shape in its own `src/sources/<provider>.ts`.
+
+```bash
+bun src/cli/pull.ts pull gameicons-icons --dir ../../apps/dev/public        # fetch + extract SVG/PNG
+bun src/cli/pull.ts reindex-sprites ../../apps/dev/public/sprites           # regenerate generated-sprites/*.json + barrel
+```
 
-**A single one-off** — no code edit, zero bytes stored (URL) or copied into `local/` (path):
+**A single one-off** G�� no code edit, zero bytes stored (URL) or copied into `local/` (path):
 
 ```bash
-assets add "https://poly.pizza/…/model.glb" --category prop --license CC0-1.0 --author "Some Author"
+assets add "https://poly.pizza/GǪ/model.glb" --category prop --license CC0-1.0 --author "Some Author"
 ```
 
 ## Importing in code
 
-Build the catalog once, then address ids (or aliases) — resolve returns `{ url }`:
+Build the catalog once, then address ids (or aliases) G�� resolve returns `{ url }`:
 
 ```ts
 import { buildCatalog } from "@jgengine/assets";
 
 const catalog = buildCatalog({ basePath: "/models" });
 
-catalog.resolve("kenney-nature/tree_pineDefaultA"); // { url: "/models/kenney-nature/tree_pineDefaultA.glb" }
-catalog.resolve("nature/tree_pine");                // alias → same url
+catalog.resolve("quaternius-stylized-nature/Pine_1"); // { url: "/models/quaternius-stylized-nature/Pine_1.glb" }
+catalog.resolve("nature/tree_pine");                   // alias G�� same url
 
 // wire ids straight into a game's model seams:
 export const game: PlayableGame = {
-  // …
+  // GǪ
   objectModels: {
-    "kenney-nature/tree_pineDefaultA": { url: catalog.resolve("kenney-nature/tree_pineDefaultA")!.url, scale: 1.4 },
+    "quaternius-stylized-nature/Pine_1": { url: catalog.resolve("quaternius-stylized-nature/Pine_1")!.url, scale: 1.4 },
   },
   entityModels: {
-    hero: { url: catalog.resolve("kenney-space/astronautA")!.url, scale: 1.1 },
+    hero: { url: catalog.resolve("kaykit-adventurers/Barbarian")!.url, scale: 1.1 },
   },
 };
 ```
 
-`buildCatalog({ sources: ["kenney-nature"] })` restricts to chosen packs; `includeAliases` / `includeSingles` default true. Discover ids with `assets add <query>` (or `assets search <term>` / `assets list --category <c>`) instead of memorizing them.
+`buildCatalog({ sources: ["quaternius-stylized-nature"] })` restricts to chosen packs; `includeAliases` / `includeSingles` default true. Discover ids with `assets add <query>` (or `assets search <term>` / `assets list --category <c>`) instead of memorizing them.
+
+Materials resolve the same way G�� ids (or `material/GǪ` aliases) to normalized PBR map URLs:
+
+```ts
+import { buildMaterialCatalog } from "@jgengine/assets";
+
+const materials = buildMaterialCatalog({ basePath: "/materials" });
+
+materials.resolve("ambientcg-grass001")!.maps.color; // "/materials/ambientcg-grass001/color.jpg"
+materials.resolve("material/grass")!.maps.normal;    // alias G�� "/materials/ambientcg-grass001/normal.jpg"
+```
+
+Sprite/icon packs resolve the same way once pulled + reindexed G�� individual files, not whole packs:
+
+```ts
+import { buildSpriteCatalog } from "@jgengine/assets";
+
+const sprites = buildSpriteCatalog({ basePath: "/sprites" });
+
+sprites.resolve("gameicons-icons/sword")!.url; // "/sprites/gameicons-icons/sword.svg"
+```
 
 ### Serving the bytes
 
-A resolved id only yields a **URL** — the GLB must be somewhere your app serves. For a game, `pull` the packs into your app's `public/`, and line `basePath` up with it:
+A resolved id only yields a **URL** G�� the GLB must be somewhere your app serves. For a game, `pull` the packs into your app's `public/`, and line `basePath` up with it:
 
 ```bash
-bun src/cli/pull.ts pull kenney-nature --dir ../../apps/dev/public   # → apps/dev/public/models/kenney-nature/*.glb
+bun src/cli/pull.ts pull quaternius-stylized-nature --dir ../../apps/dev/public   # G�� apps/dev/public/models/quaternius-stylized-nature/*.glb
 ```
 
-`buildCatalog({ basePath: "/models" })` then resolves to `/models/kenney-nature/…`, which the dev server serves from `public/models/` (gitignored — the bytes are the consumer's, fetched once from the provider's CDN).
+`buildCatalog({ basePath: "/models" })` then resolves to `/models/quaternius-stylized-nature/GǪ`, which the dev server serves from `public/models/` (gitignored G�� the bytes are the consumer's, fetched once from the provider's CDN).
+
+Sprite/icon packs pull the same way, into `public/sprites/`:
+
+```bash
+bun src/cli/pull.ts pull gameicons-icons --dir ../../apps/dev/public        # G�� apps/dev/public/sprites/gameicons-icons/*.svg
+bun src/cli/pull.ts reindex-sprites ../../apps/dev/public/sprites           # G�� src/generated-sprites/gameicons-icons.json
+```
 
 ## Notes
 
-- 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`.
+- Quaternius / KayKit pages gate downloads behind JS; sources without a pinned OpenGameArt/GitHub zip `scrape` the pack page as a fallback, and automated `pull` falls back to a clear error when no archive link is found G�� 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.
+- `gameicons-icons` is **CC BY 3.0**, not CC0 G�� a game using it needs one credit line (source, "game-icons.net contributors", license) per the engine's asset-credit rule; the repo's own per-author `license.txt` files carry the individual credits behind this pack's single collective `author` field.
+- `src/generated-sprites/` starts empty for a brand-new sprite source G�� same as any brand-new model pack, the committed per-file index only exists after someone runs `pull` + `reindex-sprites` with real network access; until then the source is fully declared (and the weekly mirror job will fetch it) but has no individually-addressable ids yet.

package/dist/aliases.d.ts

@@ -1,2 +1,7 @@
 import type { AssetAlias } from "./manifest.js";
+/**
+ * Semantic keys → live catalog ids. Prefer these in games so re-homes only
+ * touch this table. Never point at kenney-*. Curated starter theme ids
+ * (`asset:person_casual`, `nature_tree`, …) come from {@link starterAliases}.
+ */
 export declare const aliases: readonly AssetAlias[];

package/dist/aliases.js

@@ -1,11 +1,30 @@
+import { starterAliases } from "./packs/starter.js";
+/**
+ * Semantic keys → live catalog ids. Prefer these in games so re-homes only
+ * touch this table. Never point at kenney-*. Curated starter theme ids
+ * (`asset:person_casual`, `nature_tree`, …) come from {@link starterAliases}.
+ */
 export const aliases = [
-    { key: "nature/tree_pine", target: "kenney-nature/tree_pineDefaultA" },
-    { key: "nature/tree", target: "kenney-nature/tree_blocks" },
-    { key: "nature/rock", target: "kenney-nature/cliff_block_rock" },
-    { key: "nature/mushroom", target: "kenney-nature/mushroom_red" },
-    { key: "nature/flower", target: "kenney-nature/flower_purpleA" },
-    { key: "weapon/blaster", target: "kenney-blaster/blaster-a" },
-    { key: "space/astronaut", target: "kenney-space/astronautA" },
-    { key: "space/ship", target: "kenney-space/craft_racer" },
-    { key: "space/rocket", target: "kenney-space/rocket_baseA" },
+    { key: "nature/tree_pine", target: "quaternius-stylized-nature/Pine_1" },
+    { key: "nature/tree_common", target: "quaternius-stylized-nature/CommonTree_1" },
+    { key: "nature/tree_dead", target: "quaternius-stylized-nature/DeadTree_1" },
+    { key: "nature/bush", target: "quaternius-stylized-nature/Bush_Common" },
+    { key: "nature/rock", target: "quaternius-stylized-nature/Rock_Medium_1" },
+    { key: "character/rogue", target: "kaykit-adventurers/Rogue" },
+    { key: "character/knight", target: "kaykit-adventurers/Knight" },
+    { key: "character/mage", target: "kaykit-adventurers/Mage" },
+    { key: "character/barbarian", target: "kaykit-adventurers/Barbarian" },
+    { key: "scifi/alien", target: "quaternius-modular-scifi/Alien_Cyclop" },
+    { key: "scifi/chest", target: "quaternius-modular-scifi/Prop_Chest" },
+    { key: "scifi/crate", target: "quaternius-modular-scifi/Prop_Crate3" },
+    { key: "scifi/computer", target: "quaternius-modular-scifi/Prop_Computer" },
+    { key: "dungeon/chest", target: "kaykit-dungeon/chest" },
+    { key: "furniture/bed", target: "kaykit-furniture/bed_double_A" },
+    { key: "furniture/couch", target: "kaykit-furniture/couch" },
+    { key: "furniture/table", target: "kaykit-furniture/table_medium" },
+    { key: "city/car_sedan", target: "kaykit-city-builder/car_sedan" },
+    { key: "city/car_police", target: "kaykit-city-builder/car_police" },
+    { key: "city/building_a", target: "kaykit-city-builder/building_A" },
+    { key: "city/streetlight", target: "kaykit-city-builder/streetlight" },
+    ...starterAliases(),
 ];

package/dist/catalogs/build.js

@@ -2,6 +2,7 @@ import { createAssetCatalog } from "@jgengine/core/scene/assetCatalog";
 import { aliases } from "../aliases.js";
 import { generatedIndex } from "../generated/index.js";
 import { singles } from "../singles.js";
+import { sources as declaredSources } from "../sources/index.js";
 export function entryUrl(basePath, entry) {
     return `${basePath.replace(/\/+$/, "")}/${entry.source}/${entry.file}`;
 }
@@ -10,6 +11,14 @@ export function buildCatalog(options = {}) {
     const includeAliases = options.includeAliases ?? true;
     const includeSingles = options.includeSingles ?? true;
     const sourceFilter = options.sources === undefined ? null : new Set(options.sources);
+    if (sourceFilter !== null) {
+        const knownSourceIds = new Set(declaredSources.map((source) => source.id));
+        for (const id of sourceFilter) {
+            if (!knownSourceIds.has(id)) {
+                throw new Error(`buildCatalog: unknown source id "${id}" — not declared in packages/assets/src/sources/*.ts`);
+            }
+        }
+    }
     const catalog = createAssetCatalog();
     for (const entry of generatedIndex) {
         if (sourceFilter !== null && !sourceFilter.has(entry.source))

package/dist/catalogs/buildSprites.d.ts

@@ -0,0 +1,10 @@
+import { type AssetCatalog } from "@jgengine/core/scene/assetCatalog";
+/** Options for `buildSpriteCatalog`. */
+export interface BuildSpriteCatalogOptions {
+    /** URL prefix where pulled sprite/icon files live (consumer's `public/sprites`). */
+    basePath?: string;
+    /** Restrict to these source ids; omit for all. */
+    sources?: readonly string[];
+}
+/** Resolves individual pulled sprite/icon ids (e.g. `gameicons-icons/sword`) to `{ url }`. */
+export declare function buildSpriteCatalog(options?: BuildSpriteCatalogOptions): AssetCatalog;

package/dist/catalogs/buildSprites.js

@@ -0,0 +1,15 @@
+import { createAssetCatalog } from "@jgengine/core/scene/assetCatalog";
+import { generatedSpriteIndex } from "../generated-sprites/index.js";
+import { entryUrl } from "./build.js";
+/** Resolves individual pulled sprite/icon ids (e.g. `gameicons-icons/sword`) to `{ url }`. */
+export function buildSpriteCatalog(options = {}) {
+    const basePath = options.basePath ?? "/sprites";
+    const sourceFilter = options.sources === undefined ? null : new Set(options.sources);
+    const catalog = createAssetCatalog();
+    for (const entry of generatedSpriteIndex) {
+        if (sourceFilter !== null && !sourceFilter.has(entry.source))
+            continue;
+        catalog.register(entry.id, { url: entryUrl(basePath, entry) });
+    }
+    return catalog;
+}

package/dist/catalogs/starter.d.ts

@@ -1,2 +1,7 @@
 import { type BuildCatalogOptions } from "./build.js";
+/**
+ * Catalog restricted to the curated starter packs (people/props/nature/urban).
+ * Prefer this for scaffolds and probes so `asset:person_casual` etc. resolve
+ * without pulling the whole library. Full index: {@link buildCatalog}.
+ */
 export declare function createStarterCatalog(options?: BuildCatalogOptions): import("@jgengine/core/scene/assetCatalog").AssetCatalog<import("@jgengine/core/scene/assetCatalog").ModelAssetRef>;

package/dist/catalogs/starter.js

@@ -1,4 +1,13 @@
+import { STARTER_SOURCE_PACKS } from "../packs/starter.js";
 import { buildCatalog } from "./build.js";
+/**
+ * Catalog restricted to the curated starter packs (people/props/nature/urban).
+ * Prefer this for scaffolds and probes so `asset:person_casual` etc. resolve
+ * without pulling the whole library. Full index: {@link buildCatalog}.
+ */
 export function createStarterCatalog(options = {}) {
-    return buildCatalog(options);
+    return buildCatalog({
+        ...options,
+        sources: options.sources ?? STARTER_SOURCE_PACKS,
+    });
 }

package/dist/cli/paths.d.ts

@@ -1,4 +1,12 @@
-/** Sibling of `cli/` under `src/` (dev) or `dist/` (published) so reindex writes the tree consumers import. */
+/** Sibling of `cli/` under `src/` (dev) or `dist/` (published) so reindex writes the tree consumers import.
+ * @internal
+ */
 export declare function resolveGeneratedDir(cliDir: string): string;
+/** Sprite-pack counterpart of `resolveGeneratedDir` — a separate generated tree, same sibling layout.
+ * @internal
+ */
+export declare function resolveGeneratedSpritesDir(cliDir: string): string;
+/** @internal */
 export declare function resolvePackageTreeRoot(cliDir: string): string;
+/** @internal */
 export declare function resolvePackageRoot(cliDir: string): string;

package/dist/cli/paths.js

@@ -1,11 +1,21 @@
 import { join, resolve } from "node:path";
-/** Sibling of `cli/` under `src/` (dev) or `dist/` (published) so reindex writes the tree consumers import. */
+/** Sibling of `cli/` under `src/` (dev) or `dist/` (published) so reindex writes the tree consumers import.
+ * @internal
+ */
 export function resolveGeneratedDir(cliDir) {
     return join(resolve(cliDir, ".."), "generated");
 }
+/** Sprite-pack counterpart of `resolveGeneratedDir` — a separate generated tree, same sibling layout.
+ * @internal
+ */
+export function resolveGeneratedSpritesDir(cliDir) {
+    return join(resolve(cliDir, ".."), "generated-sprites");
+}
+/** @internal */
 export function resolvePackageTreeRoot(cliDir) {
     return resolve(cliDir, "..");
 }
+/** @internal */
 export function resolvePackageRoot(cliDir) {
     return resolve(cliDir, "..", "..");
 }

package/dist/cli/pull.d.ts

@@ -1,8 +1,20 @@
 #!/usr/bin/env node
 /** Sibling of `cli/` under `src/` (dev) or `dist/` (published) so reindex writes the tree consumers import. */
 export declare const generatedDir: string;
+/** Sprite-pack counterpart of `generatedDir`. */
+export declare const generatedSpritesDir: string;
 export { resolveGeneratedDir } from "./paths.js";
+/** @internal */
 export declare function flag(argv: string[], name: string): string | undefined;
+/**
+ * The runtime's own fetch, with a curl fallback for hosts it cannot reach —
+ * some proxied sandboxes tear down bun's TLS stream to GitHub's release-asset
+ * host while curl (which honors SSL_CERT_FILE) gets through fine.
+ */
+export declare const cliFetch: typeof fetch;
+/** @internal */
 export declare function describeNetworkFailure(error: unknown): string;
+/** @internal */
 export declare function isPopulated(dir: string): boolean;
+/** @internal */
 export declare function cmdPull(argv: string[]): Promise<void>;