@jgengine/assets 0.10.0 → 0.12.0

package/skills/jgengine/capabilities.md

@@ -0,0 +1,131 @@
+<!-- GENERATED by scripts/gen-capability-index.ts — do not edit. Regenerate: bun run gen:capabilities -->
+
+# jgengine — capability index
+
+Reach for these before hand-rolling. Each row is *the thing you need* → *the primitive that already does it*.
+
+## authored-spawn — read spawn points and markers from the editor document
+
+- `authoredSpawnPosition` (function) · `import { authoredSpawnPosition } from "@jgengine/shell/gameKit"`
+
+## authored-triggers — schema'd on/action vocabulary on volumes and markers with runtime dispatch
+
+- `collectAuthoredTriggers` (function) · `import { collectAuthoredTriggers } from "@jgengine/shell/gameKit"`
+
+## collider-autofit — hitboxes and physical bodies fit each kind's rendered model bounds automatically — no hand-tuned sizes
+
+- `GameContextModels` (interface) · `import { GameContextModels } from "@jgengine/core/runtime/gameContext"`
+
+## define-game — single public game-authoring path — compose systems, world, presentation, and authored scene in one definition
+
+- `defineGame` (function) · `import { defineGame } from "@jgengine/shell/gameKit"`
+
+## define-system — composable game behavior — pure data + hooks the engine schedules; pass via `defineGame({ systems })`
+
+- `defineSystem` (function) · `import { defineSystem } from "@jgengine/shell/gameKit"`
+
+## editor-catalogs — Export typed gameplay catalogs for in-editor tuning.
+
+- `EditorCatalogDefinition` (interface) · `import { EditorCatalogDefinition } from "@jgengine/shell/gameKit"`
+
+## game-system — declare a composable capability with its own schedule and lifecycle
+
+- `SystemDefinition` (interface) · `import { SystemDefinition } from "@jgengine/shell/gameKit"`
+
+## headless-runner — play a real game loop with no renderer — tick, feed input, read the world snapshot
+
+- `HeadlessRunner` (interface) · `import { HeadlessRunner } from "@jgengine/core/runtime/headlessRunner"`
+
+## host-join-code-gate — membership-or-code gate for private hosted servers
+
+- `canJoinPrivateServer` (function) · `import { canJoinPrivateServer } from "@jgengine/core/runtime/hostPolicy"`
+
+## host-listing-filter — exclude private sessions from public browse results
+
+- `isListablePublicly` (function) · `import { isListablePublicly } from "@jgengine/core/runtime/hostPolicy"`
+
+## hud-canvas — the HUD root surface — design-resolution scaling plus live panel-placement editing (F2+C)
+
+- `HudCanvas` (function) · `import { HudCanvas } from "@jgengine/shell/gameKit"`
+
+## hud-clock — in-game time-of-day readout bound to the sim clock
+
+- `Clock` (function) · `import { Clock } from "@jgengine/shell/gameKit"`
+
+## hud-coins — currency counter widget bound to a currency id
+
+- `Coins` (function) · `import { Coins } from "@jgengine/shell/gameKit"`
+
+## hud-hotbar — optional inventory hotbar building block — games own slot chrome
+
+- `Hotbar` (function) · `import { Hotbar } from "@jgengine/shell/gameKit"`
+
+## hud-layout — persistent, live-editable HUD panel layout state for `HudCanvas`
+
+- `useHudLayout` (function) · `import { useHudLayout } from "@jgengine/shell/gameKit"`
+
+## hud-panel — anchored HUD slot — drop any widget in a named, player-movable panel
+
+- `HudPanel` (function) · `import { HudPanel } from "@jgengine/shell/gameKit"`
+
+## hud-stat-bar — optional stat-bound bar building block (health, mana, stamina) — prefer game-owned chrome
+
+- `StatBar` (function) · `import { StatBar } from "@jgengine/shell/gameKit"`
+
+## loot-table — validate a loot table definition for use with the registry
+
+- `lootTable` (function) · `import { lootTable } from "@jgengine/core/authoring"`
+
+## mount-game — mount a defined game in the browser — `<GameHost playable={game} editor={() => import("@jgengine/editor")} />`
+
+- `GameHost` (function) · `import { GameHost } from "@jgengine/shell/gameKit"`
+
+## multiplayer-offline — explicit solo adapter — omit `multiplayer` instead; offline is the shell default
+
+- `offline` (function) · `import { offline } from "@jgengine/shell/gameKit"`
+
+## multiplayer-p2p — serverless co-op over WebRTC — `multiplayer: p2p({ room })`
+
+- `p2p` (function) · `import { p2p } from "@jgengine/core/runtime/adapter"`
+
+## multiplayer-ws — server-hosted shared world over WebSocket — `multiplayer: ws({ authority: "server" })`
+
+- `ws` (function) · `import { ws } from "@jgengine/core/runtime/adapter"`
+
+## render-fallback-diagnostics — Enable/disable the dev-only placeholder-fallback probe.
+
+- `armFallbackSeams` (function) · `import { armFallbackSeams } from "@jgengine/core/devtools/fallbackSeams"`
+- `fallbackSeamsSnapshot` (function) · `import { fallbackSeamsSnapshot } from "@jgengine/core/devtools/fallbackSeams"`
+- `reportFallbackSeam` (function) · `import { reportFallbackSeam } from "@jgengine/core/devtools/fallbackSeams"`
+
+## runtime-save — save/load the whole game world through a pluggable backend, autosave or save points
+
+- `createRuntimeSave` (function) · `import { createRuntimeSave } from "@jgengine/core/runtime/runtimeSave"`
+
+## scene-ownership — audit a whole ownership manifest for boundary violations
+
+- `auditManifest` (function) · `import { auditManifest } from "@jgengine/core/authoring"`
+- `classifyOwnership` (function) · `import { classifyOwnership } from "@jgengine/core/authoring"`
+- `collectOwnershipDiagnostics` (function) · `import { collectOwnershipDiagnostics } from "@jgengine/core/authoring"`
+- `isSceneOwnershipManifest` (function) · `import { isSceneOwnershipManifest } from "@jgengine/core/authoring"`
+- `ownershipKey` (function) · `import { ownershipKey } from "@jgengine/core/authoring"`
+
+## seeded-random — injected deterministic randomness for game logic — never `Math.random` in a simulation
+
+- `seededRng` (function) · `import { seededRng } from "@jgengine/shell/gameKit"`
+
+## typed-keyed-store — a cast-free typed handle onto a per-owner keyed family of reactive game-store slots, replayable and host-authoritative
+
+- `defineKeyedStore` (function) · `import { defineKeyedStore } from "@jgengine/shell/gameKit"`
+
+## typed-store — a cast-free typed handle onto one reactive game-store slot, replayable and host-authoritative
+
+- `defineStore` (function) · `import { defineStore } from "@jgengine/shell/gameKit"`
+
+## world-convergence — derive environment coordinate content from the scene document
+
+- `environmentContentFromDocument` (function) · `import { environmentContentFromDocument } from "@jgengine/shell/gameKit"`
+
+## world-environment — compose editor/preset-derived outdoor dressing — terrain, weather, water, structures — into a legacy environment feature
+
+- `environment` (function) · `import { environment } from "@jgengine/shell/gameKit"`

package/skills/jgengine/recipes/minimal-game.md

@@ -0,0 +1,88 @@
+# Recipe — minimal game (scaffold → authored scene → win)
+
+**What this wires:** the default end-to-end path from nothing to a complete, genre-free
+walk/interact/win game: a scaffold, one `defineGame` config off the happy-path kit, an
+authored scene edited in the browser, one system, one store slot, an empty-canvas HUD,
+and a win condition. Every new game starts here; add combat, multiplayer, or deeper
+world features only after this loop plays.
+
+## 1. Scaffold
+
+`npx jgengine create <name>` (inside the engine monorepo: `bun run new:game "<id-or-title>"`).
+The file set is thin and already runs:
+
+- `src/main.tsx` — mounts `GameHost` with `editor={() => import("@jgengine/editor")}`; the
+  host owns the F2+E / `?mode=editor` editor summon and the dev save endpoint.
+- `src/game.config.ts` — the whole game definition (below).
+- `src/editor.scene.json` + `src/editorLayers.ts` — the authored scene document, normalized
+  with `normalizeEditorLayers`. All placement lives here, never as coordinates in code.
+- `src/loop.ts` and `src/game/ui/GameUI.tsx` — systems and HUD.
+
+## 2. Define the game — one import surface
+
+```ts
+// game.config.ts — everything below comes from the kit; deeper paths are for outgrowing it.
+import { defineGame } from "@jgengine/shell/gameKit";
+
+import { editorLayers } from "./editorLayers";
+import { GameUI } from "./game/ui/GameUI";
+import { onNewPlayer, systems } from "./loop";
+
+export const game = defineGame({
+  name: "my-game",
+  // Binding movement actions makes the shell drive the walk controller — the game walks day one.
+  input: { moveForward: ["KeyW"], moveBack: ["KeyS"], moveLeft: ["KeyA"], moveRight: ["KeyD"], interact: ["KeyE"] },
+  systems,
+  loop: { onNewPlayer },
+  GameUI,
+  editorLayers, // the authored scene auto-mounts; the player spawns at its player_spawn marker
+});
+// Solo game: omit `multiplayer` entirely — offline is the shell default.
+```
+
+**World is optional and thin.** Omitting `world` is valid — a pure UI/rules game is not a
+spatial place. When the game *is* a place, declare only substrate + laws with `world()` from
+`@jgengine/core/world/place` (e.g. `{ id, ground: { mode: "flat", size: { x: Infinity, z: Infinity } }, physics: { gravity: -24 } }`,
+or `mode: "board"` for 2D). Never seed, sky, or vegetation in `world` — the engine renders its
+default sky until you author one in the editor, and foliage is editor scatter over the ground.
+
+
+```ts
+// loop.ts — one store slot for run state, one system for the rules tick.
+import { defineStore, defineSystem, authoredSpawnPosition, type GameContext } from "@jgengine/shell/gameKit";
+
+import { editorLayers } from "./editorLayers";
+
+export const run = defineStore("run", { collected: 0, won: false });
+
+export const systems = [
+  defineSystem({
+    id: "rules",
+    tick: { type: "fixed" },
+    update(ctx: GameContext) {
+      // System-check win alternative: read/update `run` here (e.g. win at collected >= 3).
+      if (run.read(ctx).collected >= 3) run.update(ctx, (s) => ({ ...s, won: true }));
+    },
+  }),
+];
+
+export function onNewPlayer(ctx: GameContext): void {
+  ctx.scene.entity.spawn("player", { id: ctx.player.userId, position: authoredSpawnPosition(editorLayers) ?? [0, 0, 0] });
+}
+```
+
+`GameUI` starts as an empty `HudCanvas` (`useHudLayout` + `HudCanvas` from the kit). That is
+intentional: **every game owns its UI**. Write a short UI art direction, then build custom
+panels for this pitch — do not ship stock drop-in widgets (`StatBar`, `Hotbar`, `Coins`, glass
+frames) as the product face. Reach for engine pieces only as headless data, layout, or
+interaction models under game-owned chrome (see `jgengine-ui`).
+
+## 3. Author, play, win
+
+1. `bun dev`, then F2+E opens the editor on `editor.scene.json` — move the spawn, place
+   props and trigger markers, Ctrl+S saves back to the document.
+2. The starter scene ships a goal marker with `{ on: "enter", action: "win" }` — walking
+   into it wins with zero game code. Author more rules the same way (triggers in the
+   editor), or read volumes yourself via the kit's `collectAuthoredTriggers(editorLayers)`.
+3. Prove it: `bun test` asserts the document (spawn, goal), and `jgengine-verify` covers
+   screenshot and gameplay evidence before any "it works" claim.

package/skills/jgengine-assets/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: jgengine-assets
+description: Source, license, catalog, and resolve game-ready media assets.
+---
+
+# JGengine assets
+
+## Ownership
+
+This skill owns model, sprite, texture/material, and audio-file discovery; licensing; catalog metadata; pull/index workflows; and runtime asset references. Placement belongs to `jgengine-editor`, spatial audio behavior to `jgengine-world`, and rendering/UI composition to their respective domains.
+
+Search [capabilities.md](capabilities.md) before adding a resolver or catalog path. Use [api.md](api.md) for exact exports.
+
+## Canonical workflow
+
+1. Prefer existing catalog entries and typed asset refs.
+2. Verify source license and attribution requirements before download.
+3. Record canonical facing, source units, pivot, footprint, bounds, and placement policy in metadata.
+4. Pull/index through shared tooling; do not commit remote-library bulk bytes when the catalog is designed to resolve them.
+5. Preview through the same resolver runtime will use.
+6. Add required credit in the same PR.
+
+## Reference integrity
+
+Every logical asset id has a declared owner: `committed` (a single's shipped URL, resolves on a clean clone), `provisioned` (a pack index entry whose GLB is fetched by `assets pull <source>`), or `dangling` (nothing owns it — a broken contract). Resolve one id with `resolveProvenance(id)`; gate a set of references with `validateAssetReferences(refs)`, which fails on any dangling reference and reports the exact `assets pull <source>` steps a clean checkout still needs. `assets provenance <id>...` exposes the same contract on the CLI and exits non-zero on a dangling id. This resolves references structurally against the catalog — never grep source text as the long-term contract.
+
+A game's catalog is `buildCatalog(...)` over the generated pack index, singles, and aliases; `extras` is its durable escape hatch for assets that aren't in a pack. An editor asset import into a **promoted** game project writes into that `extras` array in `src/game/assets.ts` (bytes land in `public/<basePath>/imported/`), registered after packs (last-writer-wins) and before aliases (so an alias can target one — see `jgengine-editor`). At runtime an extra resolves to exactly its `{ url }`; the `label` is human-facing only and never enters the catalog.
+
+At load time the shell classifies a model fetch before parsing via `classifyAssetResponse` (`@jgengine/core/scene/assetDiagnostics`), so a missing file, a dev-server HTML fallback, corrupt bytes, or a non-model format surface as an actionable diagnostic naming the URL — not an opaque GLTF parse error.
+
+Reindex measures every GLB's `dims`; assets listed in `COLLISION_MESH_ASSET_IDS` (`collisionMeshAssets.ts`) additionally ship a compact quantized triangle mesh (`collisionMesh` on the index entry) that collider auto-fit raycasts instead of the fitted box — opt in only concave models whose box lies (archways, rings, frames), because each entry adds real index bytes and per-ray BVH cost.
+
+## Source rules
+
+- Never use or reference Kenney.nl assets.
+- Prefer Quaternius or KayKit for CC0 3D, game-icons.net for icons, and ambientCG for PBR.
+- Preserve third-party license and attribution data with the catalog entry.
+- A permissive source allows copying assets, not transplanting another game's implementation.
+
+## Traps
+
+- Fix wrong scale/facing/pivot upstream in catalog metadata, never with per-game corrective transforms.
+- Asset ids and metadata are stable data contracts; filenames and URLs are implementation details.
+- Missing attribution is a release blocker even when the code works.
+

package/skills/jgengine-assets/api.md

@@ -0,0 +1,282 @@
+<!-- GENERATED by scripts/gen-skill-api.ts — do not edit. Regenerate: bun run gen:skill-api -->
+
+# jgengine-assets — exported API surface
+
+## @jgengine/assets
+
+- `AssetAlias` (interface): interface AssetAlias — ⚠ undocumented
+- `AssetDownload` (type): type AssetDownload = PinnedDownload | ScrapeDownload — ⚠ undocumented
+- `AssetKind` (type): type AssetKind = "model" | "pack" | "material" | "component" | "icon" | "sprite" | "spritePack" — ⚠ undocumented
+- `AssetMatch` (type): type AssetMatch = | { kind: "model"; id: string; source: string; file?: string; via: "index" | "alias" | "single" } | { kind: "pack"; source: string; title: string; categories: readonly string[] } | { kind: "material"; id: string; title: string; categories: readonly string[] } | { kind: "component";… — ⚠ undocumented
+- `AssetProvenance` (interface): interface AssetProvenance — The resolved ownership of one logical asset id — the provisioning contract for that id.
+- `AssetProvenanceKind` (type): type AssetProvenanceKind = "committed" | "provisioned" | "dangling" — How an asset id's bytes reach a clean checkout: - `committed` — resolves to a self-hosted / remote URL carried in the shipped index (a {@link SingleAsset}); no pull step, available immediately. - `provisioned` — a pack {@link IndexEntry}; the id is declared but its GLB is fetched on demand by `assets pull <source>` into the consumer's served dir. - `dangling` — nothing in the index, singles, or aliases owns the id, so no provisioning step exists and it can never resolve on a clean clone.
+- `AssetProvider` (type): type AssetProvider = | "quaternius" | "kaykit" | "polypizza" | "itch" | "ambientcg" | "gameicons" | "custom" — ⚠ undocumented
+- `AssetReference` (interface): interface AssetReference — A logical asset id referenced by some consumer (a game, scene, or config), for validation.
+- `AssetSource` (interface): interface AssetSource — ⚠ undocumented
+- `AssetSourceKind` (type): type AssetSourceKind = "model" | "material" | "sprite" — What a source's archive contains: GLB models (default), one PBR material's texture maps, or a pack of individual 2D sprite/icon files (SVG/PNG).
+- `AssetSpace` (interface): interface AssetSpace — Catalog-level asset-space metadata: how a model is authored relative to the engine, owned by the catalog entry rather than re-derived per game. Every field is optional so an unmeasured asset stays valid; {@link resolveFacingRotationY}/{@link assetUnitScale}/{@link resolveAnchorOffset} supply the documented defaults.
+- `BuildCatalogOptions` (interface): interface BuildCatalogOptions — ⚠ undocumented
+- `BuildMaterialCatalogOptions` (interface): interface BuildMaterialCatalogOptions — Options for `buildMaterialCatalog`.
+- `BuildSpriteCatalogOptions` (interface): interface BuildSpriteCatalogOptions — Options for `buildSpriteCatalog`.
+- `CollisionMeshData` (interface): interface CollisionMeshData — Compact, serializable triangle collision mesh measured at asset reindex — the renderer-free source of mesh-accurate hitboxes. Positions are welded onto a 16-bit grid spanning `min`..`max` (model space) and stored base64-encoded, so an opted-in catalog asset ships its collision triangles inside the generated index without the runtime ever touching the rendered scene graph.
+- `ExtractedMaterialMap` (interface): interface ExtractedMaterialMap — One normalized map pulled out of a material archive by `extractMaterialMaps`.
+- `ExtractedSpriteFile` (interface): interface ExtractedSpriteFile — One SVG/PNG file pulled out of a sprite/icon-pack archive by `extractSpriteFiles`.
+- `FindOptions` (interface): interface FindOptions — ⚠ undocumented
+- `IndexEntry` (interface): interface IndexEntry — ⚠ undocumented
+- `MATERIAL_MAP_FILES` (const): const MATERIAL_MAP_FILES: { readonly color: "color.jpg"; readonly normal: "normal.jpg"; readonly roughness: "roughness.jpg"; readonly ao: "ao.jpg"; readonly displacement: "displacement.jpg"; } — Normalized filenames a pulled material directory contains, keyed by map role.
+- `MaterialCatalog` (interface): interface MaterialCatalog — Resolves material ids and `material/…` aliases to `MaterialRef`s.
+- `MaterialMapRole` (type): type MaterialMapRole = keyof typeof MATERIAL_MAP_FILES — One PBR map's role within a material: color, normal, roughness, ao, or displacement.
+- `MaterialMaps` (interface): interface MaterialMaps — URLs of one material's PBR maps; `ao`/`displacement` files may be absent from a rare pack.
+- `MaterialRef` (interface): interface MaterialRef — A resolved material: identity, attribution, and its normalized map URLs.
+- `ModelDims` (interface): interface ModelDims — Measured horizontal footprint, footprint center, and lowest Y of a model in model space.
+- `ModelSnippetOptions` (interface): interface ModelSnippetOptions — ⚠ undocumented
+- `PinnedDownload` (interface): interface PinnedDownload — ⚠ undocumented
+- `RankedMatch` (interface): interface RankedMatch — ⚠ undocumented
+- `ReferenceValidation` (interface): interface ReferenceValidation — The verdict for one {@link AssetReference}.
+- `RegistryCatalog` (interface): interface RegistryCatalog — ⚠ undocumented
+- `RegistryComponent` (interface): interface RegistryComponent — ⚠ undocumented
+- `ReindexSpritesResult` (interface): interface ReindexSpritesResult — Per-source and total counts returned by `reindexSprites`.
+- `ResolveProvenanceOptions` (interface): interface ResolveProvenanceOptions — Override the data {@link resolveProvenance} resolves against; every field defaults to the shipped catalog.
+- `STARTER_ASSETS` (const): const STARTER_ASSETS: readonly StarterAsset[] — Flat list of every curated starter asset across themes.
+- `STARTER_PACKS` (const): const STARTER_PACKS: Readonly<Record<StarterTheme, readonly StarterAsset[]>> — Theme → assets table for browse/docs (`STARTER_PACKS.people`, …).
+- `STARTER_SOURCE_PACKS` (const): const STARTER_SOURCE_PACKS: readonly string[] — Source pack ids a game must pull so every starter asset URL resolves on disk.
+- `STARTER_THEMES` (const): const STARTER_THEMES: readonly StarterTheme[] — Ordered starter theme ids: people, props, nature, urban.
+- `ScrapeDownload` (interface): interface ScrapeDownload — ⚠ undocumented
+- `SingleAsset` (interface): interface SingleAsset — ⚠ undocumented
+- `StarterAsset` (interface): interface StarterAsset — One curated starter model: short id, theme, live catalog target, license, suggested height.
+- `StarterTheme` (type): type StarterTheme = "people" | "props" | "nature" | "urban" — Curated drop-in starter themes for new games. Each entry maps a short semantic id (also registered as `asset:<id>`) to a live catalog GLB that is already measured (dims/anchor flow from the generated index via the alias target). Games wire them as `entityModels: { guest: "asset:person_casual" }`. Never Kenney — Quaternius / KayKit only.
+- `ValidateAssetReferencesOptions` (interface): interface ValidateAssetReferencesOptions extends ResolveProvenanceOptions — Options for {@link validateAssetReferences}: the resolution data plus an optional on-disk `present` check.
+- `ValidateAssetReferencesResult` (interface): interface ValidateAssetReferencesResult — The aggregate result of validating a set of references against the provisioning contract.
+- `VerifyResult` (interface): interface VerifyResult — ⚠ undocumented
+- `aliases` (const): const aliases: readonly AssetAlias[] — 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}.
+- `ambientcgSources` (const): const ambientcgSources: readonly AssetSource[] — Every ambientCG material source, generated per family (`ambientcg-grass001` … ).
+- `buildCatalog` (function): function buildCatalog(options: BuildCatalogOptions = {}): AssetCatalog — Builds a game's asset catalog from the generated CC0 pack index plus singles, extras, and aliases. Registration order is packs → singles → {@link BuildCatalogOptions.extras | extras} → aliases: packs and singles come first, extras override them last-writer-wins, and aliases resolve last so they can target an extra. See {@link BuildCatalogOptions} for filtering and opt-outs.
+- `buildMaterialCatalog` (function): function buildMaterialCatalog(options: BuildMaterialCatalogOptions = {}): MaterialCatalog — A resolvable catalog over every `kind: "material"` source. Ids are source ids (`ambientcg-grass001`) plus the `material/…` aliases; every resolve returns the normalized map URLs under `basePath`, matching what `assets pull` writes into `<dir>/materials/<id>/`.
+- `buildSpriteCatalog` (function): function buildSpriteCatalog(options: BuildSpriteCatalogOptions = {}): AssetCatalog — Resolves individual pulled sprite/icon ids (e.g. `gameicons-icons/sword`) to `{ url }`.
+- `componentInstallUrl` (function): function componentInstallUrl(name: string): string — The `shadcn add` URL for a HUD component, e.g. `https://jgengine.com/r/vital-bar.json`.
+- `componentWiringSnippet` (function): function componentWiringSnippet(component: RegistryComponent): string — Copy-paste wiring for a HUD component: the `shadcn add` command plus import + usage.
+- `createStarterCatalog` (function): function createStarterCatalog(options: BuildCatalogOptions = {}): AssetCatalog<ModelAssetRef> — 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}.
+- `entryForSpriteFile` (function): function entryForSpriteFile(source: AssetSource, file: string): IndexEntry — Builds one sprite/icon `IndexEntry` — same shape as a model entry, minus `dims`.
+- `entryUrl` (function): function entryUrl(basePath: string, entry: IndexEntry): string — ⚠ undocumented
+- `extractMaterialMaps` (function): function extractMaterialMaps(archive: Uint8Array): ExtractedMaterialMap[] — Pulls the recognized PBR maps out of a material archive (ambientCG's flat `<Asset>_<Res>_<Map>.jpg` layout) and normalizes their names so resolved URLs never depend on the provider's naming or the pulled resolution.
+- `findAssets` (function): function findAssets(query: string, options: FindOptions = {}): AssetMatch[] — The ranked matches for a query — models, packs, HUD components, and icons in one list.
+- `gameiconsSources` (const): const gameiconsSources: readonly AssetSource[] — game-icons.net (https://game-icons.net) — ~4,000 CC BY 3.0 SVG item/ability icons from 40+ contributing artists, mirrored as one GitHub repo (github.com/game-icons/icons). `HEAD` resolves the default branch without pinning a name or commit, so this always mirrors the current set; the per-artist `license.txt` files inside the repo carry the individual credits behind this pack's single collective `author` field.
+- `generatedBySource` (const): const generatedBySource: Record<string, IndexEntry[]> — ⚠ undocumented
+- `generatedIndex` (const): const generatedIndex: IndexEntry[] — ⚠ undocumented
+- `generatedSpriteBySource` (const): const generatedSpriteBySource: Record<string, IndexEntry[]> — Pulled sprite/icon entries grouped by source id.
+- `generatedSpriteIndex` (const): const generatedSpriteIndex: IndexEntry[] — Every pulled sprite/icon entry across all sources, flattened.
+- `iconWiringSnippet` (function): function iconWiringSnippet(name: string): string — Copy-paste wiring for a HUD glyph from the registry `game-icon` catalog.
+- `indexSpriteSourceDir` (function): function indexSpriteSourceDir(source: AssetSource, dir: string): IndexEntry[] — Walks a pulled sprite-pack directory and returns one `IndexEntry` per SVG/PNG, deduped by filename.
+- `isScrapeDownload` (function): function isScrapeDownload(download: AssetDownload): download is ScrapeDownload — ⚠ undocumented
+- `kaykitSources` (const): const kaykitSources: readonly AssetSource[] — ⚠ undocumented
+- `keyFromSpriteFile` (function): function keyFromSpriteFile(file: string): string — Strips the `.svg`/`.png` extension off a pulled sprite/icon filename to get its id suffix.
+- `materialAliases` (const): const materialAliases: readonly AssetAlias[] — Semantic keys onto the ambientCG catalog, mirroring the model alias layer.
+- `materialSources` (const): const materialSources: readonly AssetSource[] — Every `kind: "material"` source — one CC0 PBR material each, resolvable via `buildMaterialCatalog`.
+- `materialWiringSnippet` (function): function materialWiringSnippet(id: string, basePath = "/materials"): string — Copy-paste wiring for a pulled PBR material: resolve the map URLs through the material catalog, then apply them onto terrain or a model.
+- `modelSources` (const): const modelSources: readonly AssetSource[] — Every source whose archive holds GLB models (Quaternius, KayKit packs).
+- `modelWiringSnippet` (function): function modelWiringSnippet(id: string, options: ModelSnippetOptions = {}): string — Copy-paste wiring for a pulled GLB id: resolve through the catalog, drop into a model seam.
+- `quaterniusSources` (const): const quaterniusSources: readonly AssetSource[] — ⚠ undocumented
+- `rankAssets` (function): function rankAssets(query: string, options: FindOptions = {}): RankedMatch[] — Rank every catalog entry — models, packs, HUD components, icons — against one query.
+- `readGlbDims` (function): function readGlbDims(bytes: Uint8Array): ModelDims | null — ⚠ undocumented
+- `registryCatalog` (const): const registryCatalog: RegistryCatalog — ⚠ undocumented
+- `reindexSprites` (function): function reindexSprites(spritesDir: string, outDir: string): ReindexSpritesResult — Same shape as `reindex` (models) but walks SVG/PNG files and skips dims measurement — sprites have no footprint.
+- `resolveProvenance` (function): function resolveProvenance(id: string, options: ResolveProvenanceOptions = {}): AssetProvenance — Resolve one logical asset id (a pack id, a single id, or an alias key) to its {@link AssetProvenance}. Aliases are followed one hop to their target. An id that matches no declared owner is `dangling` — the signal a clean-clone gate turns into a hard failure, because no provisioning step can ever satisfy it.
+- `singles` (const): const singles: readonly SingleAsset[] — ⚠ undocumented
+- `sourceById` (const): const sourceById: ReadonlyMap<string, AssetSource> — ⚠ undocumented
+- `sources` (const): const sources: readonly AssetSource[] — ⚠ undocumented
+- `spriteSources` (const): const spriteSources: readonly AssetSource[] — Every `kind: "sprite"` source — a pack of individual 2D icon/UI files, resolvable via `buildSpriteCatalog`.
+- `spriteWiringSnippet` (function): function spriteWiringSnippet(id: string, basePath = "/sprites"): string — Copy-paste wiring for a pulled sprite/icon-pack file: resolve through the sprite catalog.
+- `validateAssetReferences` (function): function validateAssetReferences(references: readonly AssetReference[], options: ValidateAssetReferencesOptions = {}): ValidateAssetReferencesResult — Validate that every {@link AssetReference} resolves against the declared provisioning contract — not by grepping source text, but by resolving each logical id to its committed / provisioned / dangling owner. A `dangling` reference fails with the referencing consumer, the logical id, the (null) resolved path, and the missing provisioning step; a `provisioned` reference passes and contributes its `assets pull <source>` step to `provisioning` (unless `present` is supplied and reports the bytes absent).
+- `verifyManifest` (function): function verifyManifest(): VerifyResult — ⚠ undocumented
+
+## @jgengine/assets/aliases
+
+- `aliases` (const): const aliases: readonly AssetAlias[] — 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}.
+
+## @jgengine/assets/catalogs/build
+
+- `BuildCatalogOptions` (interface): interface BuildCatalogOptions — ⚠ undocumented
+- `CatalogExtra` (interface): interface CatalogExtra — A durable, hand-or-tool authored catalog entry that is not part of the generated pack index, singles, or aliases — the shape the editor writes into a promoted game's `src/game/assets.ts` when an asset is imported. `label` is human-facing only and is intentionally not registered into the catalog (it mirrors how a single asset's author/license live only in the source literal), so at runtime an extra resolves to exactly `{ url }`.
+- `buildCatalog` (function): function buildCatalog(options: BuildCatalogOptions = {}): AssetCatalog — Builds a game's asset catalog from the generated CC0 pack index plus singles, extras, and aliases. Registration order is packs → singles → {@link BuildCatalogOptions.extras | extras} → aliases: packs and singles come first, extras override them last-writer-wins, and aliases resolve last so they can target an extra. See {@link BuildCatalogOptions} for filtering and opt-outs.
+- `entryUrl` (function): function entryUrl(basePath: string, entry: IndexEntry): string — ⚠ undocumented
+
+## @jgengine/assets/catalogs/buildSprites
+
+- `BuildSpriteCatalogOptions` (interface): interface BuildSpriteCatalogOptions — Options for `buildSpriteCatalog`.
+- `buildSpriteCatalog` (function): function buildSpriteCatalog(options: BuildSpriteCatalogOptions = {}): AssetCatalog — Resolves individual pulled sprite/icon ids (e.g. `gameicons-icons/sword`) to `{ url }`.
+
+## @jgengine/assets/catalogs/starter
+
+- `createStarterCatalog` (function): function createStarterCatalog(options: BuildCatalogOptions = {}): AssetCatalog<ModelAssetRef> — 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}.
+
+## @jgengine/assets/cli/pull
+
+- `cliFetch` (const): const cliFetch: typeof fetch — 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.
+- `generatedDir` (const): const generatedDir: string — Sibling of `cli/` under `src/` (dev) or `dist/` (published) so reindex writes the tree consumers import.
+- `generatedSpritesDir` (const): const generatedSpritesDir: string — Sprite-pack counterpart of `generatedDir`.
+
+## @jgengine/assets/collisionMeshAssets
+
+- `COLLISION_MESH_ASSET_IDS` (const): const COLLISION_MESH_ASSET_IDS: ReadonlySet<string> — Catalog assets that ship a collision mesh in the generated index. Opt-in only: each entry adds ~10-30KB of quantized triangles to the index and a BVH raycast per query, so list only concave models whose fitted box lies (archways, rings, frames).
+
+## @jgengine/assets/dims
+
+- `ModelDims` (interface): interface ModelDims — Measured horizontal footprint, footprint center, and lowest Y of a model in model space.
+- `readGlbCollisionMesh` (function): function readGlbCollisionMesh(bytes: Uint8Array): CollisionMeshData | null — Extract a model-space collision triangle soup from a GLB and compress it with {@link encodeCollisionMesh}. Walks the default scene, transforming each TRIANGLES primitive's float32 VEC3 positions by the node's world matrix, and returns `null` for a JSON-only GLB or when no triangle survives quantization.
+- `readGlbDims` (function): function readGlbDims(bytes: Uint8Array): ModelDims | null — ⚠ undocumented
+
+## @jgengine/assets/download
+
+- `DEFAULT_RELEASE_BASE` (const): const DEFAULT_RELEASE_BASE: "https://github.com/Noisemaker111/jgengine/releases/download/packs" — Default asset mirror: this repo's own GitHub Releases, reachable from every cloud sandbox without network-policy changes (github.com is on the default allowlist). Assets live on the rolling `packs` release, one flat zip per pack named `<provider>-<packId>.zip`, kept in sync with the source catalog by `.github/workflows/mirror-assets.yml` — adding a catalog entry is the whole publishing step. Override the chain with `--mirror` / `JGENGINE_ASSETS_MIRROR`, or disable this hop with `JGENGINE_ASSETS_NO_DEFAULT_MIRROR=1`.
+- `DownloadPackOptions` (interface): interface DownloadPackOptions — ⚠ undocumented
+- `DownloadPackResult` (interface): interface DownloadPackResult — ⚠ undocumented
+- `ExtractedGlb` (interface): interface ExtractedGlb — ⚠ undocumented
+- `ExtractedPack` (interface): interface ExtractedPack — What `extractGlbs` pulls out of a pack archive: the models plus the textures they reference.
+- `ExtractedPackImage` (interface): interface ExtractedPackImage — An image a pack's models reference, shipped flat beside the `.glb` files.
+- `ExtractedSpriteFile` (interface): interface ExtractedSpriteFile — One SVG/PNG file pulled out of a sprite/icon-pack archive by `extractSpriteFiles`.
+- `FetchLike` (type): type FetchLike = typeof fetch — ⚠ undocumented
+- `MAX_ARCHIVE_COMPRESSION_RATIO` (const): const MAX_ARCHIVE_COMPRESSION_RATIO: 100 — Max allowed originalSize/size ratio for a single archive entry — past this it's treated as a zip bomb.
+- `MAX_ARCHIVE_DOWNLOAD_BYTES` (const): const MAX_ARCHIVE_DOWNLOAD_BYTES: number — Max size of a downloaded (still-compressed) archive, in bytes. Provider zips run tens of MB; this leaves headroom without buffering an unbounded response.
+- `MAX_ARCHIVE_ENTRY_COUNT` (const): const MAX_ARCHIVE_ENTRY_COUNT: 20000 — Max number of entries this module will extract out of one archive.
+- `MAX_ARCHIVE_UNCOMPRESSED_BYTES` (const): const MAX_ARCHIVE_UNCOMPRESSED_BYTES: number — Max total uncompressed size this module will inflate out of one archive, in bytes.
+
+## @jgengine/assets/find
+
+- `AssetKind` (type): type AssetKind = "model" | "pack" | "material" | "component" | "icon" | "sprite" | "spritePack" — ⚠ undocumented
+- `AssetMatch` (type): type AssetMatch = | { kind: "model"; id: string; source: string; file?: string; via: "index" | "alias" | "single" } | { kind: "pack"; source: string; title: string; categories: readonly string[] } | { kind: "material"; id: string; title: string; categories: readonly string[] } | { kind: "component";… — ⚠ undocumented
+- `FindOptions` (interface): interface FindOptions — ⚠ undocumented
+- `RankedMatch` (interface): interface RankedMatch — ⚠ undocumented
+- `findAssets` (function): function findAssets(query: string, options: FindOptions = {}): AssetMatch[] — The ranked matches for a query — models, packs, HUD components, and icons in one list.
+- `rankAssets` (function): function rankAssets(query: string, options: FindOptions = {}): RankedMatch[] — Rank every catalog entry — models, packs, HUD components, icons — against one query.
+
+## @jgengine/assets/generated
+
+- `generatedBySource` (const): const generatedBySource: Record<string, IndexEntry[]> — ⚠ undocumented
+- `generatedIndex` (const): const generatedIndex: IndexEntry[] — ⚠ undocumented
+
+## @jgengine/assets/generated-sprites
+
+- `generatedSpriteBySource` (const): const generatedSpriteBySource: Record<string, IndexEntry[]> — Pulled sprite/icon entries grouped by source id.
+- `generatedSpriteIndex` (const): const generatedSpriteIndex: IndexEntry[] — Every pulled sprite/icon entry across all sources, flattened.
+
+## @jgengine/assets/indexGen
+
+- `ReindexResult` (interface): interface ReindexResult — ⚠ undocumented
+- `entryForFile` (function): function entryForFile(source: AssetSource, file: string, dims?: ModelDims, collisionMesh?: CollisionMeshData): IndexEntry — ⚠ undocumented
+- `indexSourceDir` (function): function indexSourceDir(source: AssetSource, dir: string): IndexEntry[] — ⚠ undocumented
+- `keyFromFile` (function): function keyFromFile(file: string): string — ⚠ undocumented
+- `reindex` (function): function reindex(modelsDir: string, outDir: string): ReindexResult — ⚠ undocumented
+
+## @jgengine/assets/manifest
+
+- `AssetAlias` (interface): interface AssetAlias — ⚠ undocumented
+- `AssetDownload` (type): type AssetDownload = PinnedDownload | ScrapeDownload — ⚠ undocumented
+- `AssetProvider` (type): type AssetProvider = | "quaternius" | "kaykit" | "polypizza" | "itch" | "ambientcg" | "gameicons" | "custom" — ⚠ undocumented
+- `AssetSource` (interface): interface AssetSource — ⚠ undocumented
+- `AssetSourceKind` (type): type AssetSourceKind = "model" | "material" | "sprite" — What a source's archive contains: GLB models (default), one PBR material's texture maps, or a pack of individual 2D sprite/icon files (SVG/PNG).
+- `AssetSpace` (interface): interface AssetSpace — Catalog-level asset-space metadata: how a model is authored relative to the engine, owned by the catalog entry rather than re-derived per game. Every field is optional so an unmeasured asset stays valid; {@link resolveFacingRotationY}/{@link assetUnitScale}/{@link resolveAnchorOffset} supply the documented defaults.
+- `CollisionMeshData` (interface): interface CollisionMeshData — Compact, serializable triangle collision mesh measured at asset reindex — the renderer-free source of mesh-accurate hitboxes. Positions are welded onto a 16-bit grid spanning `min`..`max` (model space) and stored base64-encoded, so an opted-in catalog asset ships its collision triangles inside the generated index without the runtime ever touching the rendered scene graph.
+- `IndexEntry` (interface): interface IndexEntry — ⚠ undocumented
+- `ModelDims` (interface): interface ModelDims — Measured horizontal footprint, footprint center, and lowest Y of a model in model space.
+- `PinnedDownload` (interface): interface PinnedDownload — ⚠ undocumented
+- `ScrapeDownload` (interface): interface ScrapeDownload — ⚠ undocumented
+- `SingleAsset` (interface): interface SingleAsset — ⚠ undocumented
+- `isScrapeDownload` (function): function isScrapeDownload(download: AssetDownload): download is ScrapeDownload — ⚠ undocumented
+
+## @jgengine/assets/materials
+
+- `BuildMaterialCatalogOptions` (interface): interface BuildMaterialCatalogOptions — Options for `buildMaterialCatalog`.
+- `ExtractedMaterialMap` (interface): interface ExtractedMaterialMap — One normalized map pulled out of a material archive by `extractMaterialMaps`.
+- `MATERIAL_MAP_FILES` (const): const MATERIAL_MAP_FILES: { readonly color: "color.jpg"; readonly normal: "normal.jpg"; readonly roughness: "roughness.jpg"; readonly ao: "ao.jpg"; readonly displacement: "displacement.jpg"; } — Normalized filenames a pulled material directory contains, keyed by map role.
+- `MaterialCatalog` (interface): interface MaterialCatalog — Resolves material ids and `material/…` aliases to `MaterialRef`s.
+- `MaterialMapRole` (type): type MaterialMapRole = keyof typeof MATERIAL_MAP_FILES — One PBR map's role within a material: color, normal, roughness, ao, or displacement.
+- `MaterialMaps` (interface): interface MaterialMaps — URLs of one material's PBR maps; `ao`/`displacement` files may be absent from a rare pack.
+- `MaterialRef` (interface): interface MaterialRef — A resolved material: identity, attribution, and its normalized map URLs.
+- `buildMaterialCatalog` (function): function buildMaterialCatalog(options: BuildMaterialCatalogOptions = {}): MaterialCatalog — A resolvable catalog over every `kind: "material"` source. Ids are source ids (`ambientcg-grass001`) plus the `material/…` aliases; every resolve returns the normalized map URLs under `basePath`, matching what `assets pull` writes into `<dir>/materials/<id>/`.
+- `extractMaterialMaps` (function): function extractMaterialMaps(archive: Uint8Array): ExtractedMaterialMap[] — Pulls the recognized PBR maps out of a material archive (ambientCG's flat `<Asset>_<Res>_<Map>.jpg` layout) and normalizes their names so resolved URLs never depend on the provider's naming or the pulled resolution.
+- `materialAliases` (const): const materialAliases: readonly AssetAlias[] — Semantic keys onto the ambientCG catalog, mirroring the model alias layer.
+
+## @jgengine/assets/packs/starter
+
+- `STARTER_ASSETS` (const): const STARTER_ASSETS: readonly StarterAsset[] — Flat list of every curated starter asset across themes.
+- `STARTER_PACKS` (const): const STARTER_PACKS: Readonly<Record<StarterTheme, readonly StarterAsset[]>> — Theme → assets table for browse/docs (`STARTER_PACKS.people`, …).
+- `STARTER_SOURCE_PACKS` (const): const STARTER_SOURCE_PACKS: readonly string[] — Source pack ids a game must pull so every starter asset URL resolves on disk.
+- `STARTER_THEMES` (const): const STARTER_THEMES: readonly StarterTheme[] — Ordered starter theme ids: people, props, nature, urban.
+- `StarterAsset` (interface): interface StarterAsset — One curated starter model: short id, theme, live catalog target, license, suggested height.
+- `StarterTheme` (type): type StarterTheme = "people" | "props" | "nature" | "urban" — Curated drop-in starter themes for new games. Each entry maps a short semantic id (also registered as `asset:<id>`) to a live catalog GLB that is already measured (dims/anchor flow from the generated index via the alias target). Games wire them as `entityModels: { guest: "asset:person_casual" }`. Never Kenney — Quaternius / KayKit only.
+
+## @jgengine/assets/provisioning
+
+- `AssetProvenance` (interface): interface AssetProvenance — The resolved ownership of one logical asset id — the provisioning contract for that id.
+- `AssetProvenanceKind` (type): type AssetProvenanceKind = "committed" | "provisioned" | "dangling" — How an asset id's bytes reach a clean checkout: - `committed` — resolves to a self-hosted / remote URL carried in the shipped index (a {@link SingleAsset}); no pull step, available immediately. - `provisioned` — a pack {@link IndexEntry}; the id is declared but its GLB is fetched on demand by `assets pull <source>` into the consumer's served dir. - `dangling` — nothing in the index, singles, or aliases owns the id, so no provisioning step exists and it can never resolve on a clean clone.
+- `AssetReference` (interface): interface AssetReference — A logical asset id referenced by some consumer (a game, scene, or config), for validation.
+- `ReferenceValidation` (interface): interface ReferenceValidation — The verdict for one {@link AssetReference}.
+- `ResolveProvenanceOptions` (interface): interface ResolveProvenanceOptions — Override the data {@link resolveProvenance} resolves against; every field defaults to the shipped catalog.
+- `ValidateAssetReferencesOptions` (interface): interface ValidateAssetReferencesOptions extends ResolveProvenanceOptions — Options for {@link validateAssetReferences}: the resolution data plus an optional on-disk `present` check.
+- `ValidateAssetReferencesResult` (interface): interface ValidateAssetReferencesResult — The aggregate result of validating a set of references against the provisioning contract.
+- `resolveProvenance` (function): function resolveProvenance(id: string, options: ResolveProvenanceOptions = {}): AssetProvenance — Resolve one logical asset id (a pack id, a single id, or an alias key) to its {@link AssetProvenance}. Aliases are followed one hop to their target. An id that matches no declared owner is `dangling` — the signal a clean-clone gate turns into a hard failure, because no provisioning step can ever satisfy it.
+- `validateAssetReferences` (function): function validateAssetReferences(references: readonly AssetReference[], options: ValidateAssetReferencesOptions = {}): ValidateAssetReferencesResult — Validate that every {@link AssetReference} resolves against the declared provisioning contract — not by grepping source text, but by resolving each logical id to its committed / provisioned / dangling owner. A `dangling` reference fails with the referencing consumer, the logical id, the (null) resolved path, and the missing provisioning step; a `provisioned` reference passes and contributes its `assets pull <source>` step to `provisioning` (unless `present` is supplied and reports the bytes absent).
+
+## @jgengine/assets/registry
+
+- `RegistryCatalog` (interface): interface RegistryCatalog — ⚠ undocumented
+- `RegistryComponent` (interface): interface RegistryComponent — ⚠ undocumented
+- `componentInstallUrl` (function): function componentInstallUrl(name: string): string — The `shadcn add` URL for a HUD component, e.g. `https://jgengine.com/r/vital-bar.json`.
+- `registryCatalog` (const): const registryCatalog: RegistryCatalog — ⚠ undocumented
+
+## @jgengine/assets/singles
+
+- `singles` (const): const singles: readonly SingleAsset[] — ⚠ undocumented
+
+## @jgengine/assets/snippet
+
+- `ModelSnippetOptions` (interface): interface ModelSnippetOptions — ⚠ undocumented
+- `componentWiringSnippet` (function): function componentWiringSnippet(component: RegistryComponent): string — Copy-paste wiring for a HUD component: the `shadcn add` command plus import + usage.
+- `iconWiringSnippet` (function): function iconWiringSnippet(name: string): string — Copy-paste wiring for a HUD glyph from the registry `game-icon` catalog.
+- `materialWiringSnippet` (function): function materialWiringSnippet(id: string, basePath = "/materials"): string — Copy-paste wiring for a pulled PBR material: resolve the map URLs through the material catalog, then apply them onto terrain or a model.
+- `modelWiringSnippet` (function): function modelWiringSnippet(id: string, options: ModelSnippetOptions = {}): string — Copy-paste wiring for a pulled GLB id: resolve through the catalog, drop into a model seam.
+- `spriteWiringSnippet` (function): function spriteWiringSnippet(id: string, basePath = "/sprites"): string — Copy-paste wiring for a pulled sprite/icon-pack file: resolve through the sprite catalog.
+
+## @jgengine/assets/sources
+
+- `ambientcgSources` (const): const ambientcgSources: readonly AssetSource[] — Every ambientCG material source, generated per family (`ambientcg-grass001` … ).
+- `gameiconsSources` (const): const gameiconsSources: readonly AssetSource[] — game-icons.net (https://game-icons.net) — ~4,000 CC BY 3.0 SVG item/ability icons from 40+ contributing artists, mirrored as one GitHub repo (github.com/game-icons/icons). `HEAD` resolves the default branch without pinning a name or commit, so this always mirrors the current set; the per-artist `license.txt` files inside the repo carry the individual credits behind this pack's single collective `author` field.
+- `kaykitSources` (const): const kaykitSources: readonly AssetSource[] — ⚠ undocumented
+- `materialSources` (const): const materialSources: readonly AssetSource[] — Every `kind: "material"` source — one CC0 PBR material each, resolvable via `buildMaterialCatalog`.
+- `modelSources` (const): const modelSources: readonly AssetSource[] — Every source whose archive holds GLB models (Quaternius, KayKit packs).
+- `quaterniusSources` (const): const quaterniusSources: readonly AssetSource[] — ⚠ undocumented
+- `sourceById` (const): const sourceById: ReadonlyMap<string, AssetSource> — ⚠ undocumented
+- `sources` (const): const sources: readonly AssetSource[] — ⚠ undocumented
+- `spriteSources` (const): const spriteSources: readonly AssetSource[] — Every `kind: "sprite"` source — a pack of individual 2D icon/UI files, resolvable via `buildSpriteCatalog`.
+
+## @jgengine/assets/sources/ambientcg
+
+- `ambientcgAssetId` (function): function ambientcgAssetId(source: AssetSource): string — Upstream asset id (`Grass001`) for a material source id (`ambientcg-grass001`).
+- `ambientcgSources` (const): const ambientcgSources: readonly AssetSource[] — Every ambientCG material source, generated per family (`ambientcg-grass001` … ).
+
+## @jgengine/assets/sources/gameicons
+
+- `gameiconsSources` (const): const gameiconsSources: readonly AssetSource[] — game-icons.net (https://game-icons.net) — ~4,000 CC BY 3.0 SVG item/ability icons from 40+ contributing artists, mirrored as one GitHub repo (github.com/game-icons/icons). `HEAD` resolves the default branch without pinning a name or commit, so this always mirrors the current set; the per-artist `license.txt` files inside the repo carry the individual credits behind this pack's single collective `author` field.
+
+## @jgengine/assets/sources/kaykit
+
+- `kaykitSources` (const): const kaykitSources: readonly AssetSource[] — ⚠ undocumented
+
+## @jgengine/assets/sources/quaternius
+
+- `quaterniusSources` (const): const quaterniusSources: readonly AssetSource[] — ⚠ undocumented
+
+## @jgengine/assets/spriteIndexGen
+
+- `ReindexSpritesResult` (interface): interface ReindexSpritesResult — Per-source and total counts returned by `reindexSprites`.
+- `entryForSpriteFile` (function): function entryForSpriteFile(source: AssetSource, file: string): IndexEntry — Builds one sprite/icon `IndexEntry` — same shape as a model entry, minus `dims`.
+- `indexSpriteSourceDir` (function): function indexSpriteSourceDir(source: AssetSource, dir: string): IndexEntry[] — Walks a pulled sprite-pack directory and returns one `IndexEntry` per SVG/PNG, deduped by filename.
+- `keyFromSpriteFile` (function): function keyFromSpriteFile(file: string): string — Strips the `.svg`/`.png` extension off a pulled sprite/icon filename to get its id suffix.
+- `reindexSprites` (function): function reindexSprites(spritesDir: string, outDir: string): ReindexSpritesResult — Same shape as `reindex` (models) but walks SVG/PNG files and skips dims measurement — sprites have no footprint.
+
+## @jgengine/assets/verify
+
+- `VerifyInput` (interface): interface VerifyInput — ⚠ undocumented
+- `VerifyResult` (interface): interface VerifyResult — ⚠ undocumented
+- `verifyData` (function): function verifyData(input: VerifyInput): VerifyResult — ⚠ undocumented
+- `verifyManifest` (function): function verifyManifest(): VerifyResult — ⚠ undocumented

package/skills/jgengine-assets/capabilities.md

@@ -0,0 +1,13 @@
+<!-- GENERATED by scripts/gen-capability-index.ts — do not edit. Regenerate: bun run gen:capabilities -->
+
+# jgengine-assets — capability index
+
+Reach for these before hand-rolling. Each row is *the thing you need* → *the primitive that already does it*.
+
+## asset-reference-integrity — validate asset references against the provisioning contract (dangling / committed / provisioned)
+
+- `validateAssetReferences` (function) · `import { validateAssetReferences } from "@jgengine/assets"`
+
+## starter-packs — themed CC0 model ids (people/props/nature/urban) ready for entityModels
+
+- `StarterTheme` (type) · `import { StarterTheme } from "@jgengine/assets"`