@jgengine/assets 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -11,6 +11,42 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
+## 0.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
+
+### Added
+
+- Mobile HUD fit — design-resolution UI scaling now applies to every game by default: `HudCanvas` measures the live viewport and scales the whole HUD from `PlayableGame.hudFit.designSize` (default 1600×900, clamps `minScale`/`maxScale` 0.4–1) so desktop-authored layouts shrink to fit a phone instead of overflowing it; `hudFit.mobile` overrides tune the phone fit separately. Pure math lives in `@jgengine/core/ui/hudScale` (`hudScaleForViewport`, `resolveHudFit`, `rectOverflow`, `overflowingPanels`); the shell mounts `@jgengine/react`'s `HudViewportProvider` around `GameUI` so games need no wiring.
+- Graphics → UI scale — a player-facing `graphics.uiScale` slider (0.5–1.5, default 1) multiplies the computed HUD scale on every platform; the same resolution system drives desktop preference and mobile shrink.
+- HUD overflow gate — `HudCanvas` measures every `HudPanel` against the viewport at runtime and reports offenders on a `data-hud-overflow` attribute (plus a console warning); `bun run shoot <game> --device mobile|both` now exits non-zero naming the panels that escape the viewport.
+- Automatic visibility & streaming defaults — an engine-level `VisibilitySystem` (exported from `@jgengine/core`) gives every scene renderer-agnostic culling and asset-streaming policy with no per-object wiring: distance culling, preload margins, hysteresis, delayed unloading, multi-camera awareness (including cameras excluded from streaming), and per-object overrides (always-visible, never-unload, disabled culling/streaming, custom render distance and preload margin).
+- Self-hosted asset mirror — `DEFAULT_RELEASE_BASE` now points at this repo's rolling `packs` release instead of the upstream host; a catalog-driven `mirror-assets` workflow (weekly cron + manual dispatch) keeps the mirror in sync with the asset catalog.
+
+### Changed
+
+- Mobile HUD fit is on by default — design-resolution HUD scaling now applies to every game with no config change (previously opt-in via `platforms: ["web", "mobile"]`). A desktop-only game keeps the legacy fixed 0.85 compact zoom by declaring `platforms: ["web"]` (without `"mobile"`).
+
 ## 0.8.0
 
 Transport-agnostic multiplayer (socket.io, WebRTC p2p, LAN/Fly adapters) plus grid/voxel

package/README.md

@@ -18,33 +18,54 @@ A self-generating, license-verified index of thousands of CC0 3D models — host
 
 Everything collapses into the core `AssetCatalog` via `buildCatalog({ basePath })`.
 
+## `add` — 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.
+
+```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
+```
+
+- 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.
+
+The same ranking is available programmatically: `import { findAssets } from "@jgengine/assets"`.
+
 ## CLI
 
 ```
+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
 assets pull <source-id> [--dir public] [--mirror <baseUrl>] [--offline]
-                                               # download + extract GLBs into <dir>/models/<source>/
-assets add <path|url> --category <c> --license <l> [--author <a>]
+                                               # download + extract a whole pack's GLBs into <dir>/models/<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 verify                                 # license + alias-integrity gate
 ```
 
-Run in-repo with `bun run --cwd packages/assets src/cli/pull.ts <verb> …`.
+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`.)
 
 ### Mirror fallback and offline pulls
 
 `pull` never has just one path to the bytes. For a given `source-id` it tries, in order, until one succeeds:
 
 1. **Mirror base override** — `--mirror <baseUrl>` (or the `JGENGINE_ASSETS_MIRROR` env var if `--mirror` is not passed) — the archive is expected at `<baseUrl>/<provider>/<source-id>.zip`, e.g. `https://my-mirror.example.com/kenney/kenney-nature.zip`.
-2. **The primary provider path** — the source's pinned `{ url, sha256? }` or, for providers that rotate URLs (Kenney), a scrape of the asset page.
-3. **The pack's own `mirror`** — an optional direct archive URL set on the `AssetSource` entry itself (`src/sources/*.ts`), tried as a last resort.
+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.
 
-If every attempt fails, `pull` throws one aggregated error naming every URL it tried and why each one failed. Whenever the source's `download` is pinned with a `sha256`, the downloaded bytes are hashed and checked against it **no matter which of the three paths supplied them** — a mirror serving stale or tampered bytes is rejected and the next source in the chain is tried instead.
+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.
 
 `--offline` skips the network entirely: it succeeds immediately if `<dir>/models/<source-id>/` already has files in it, and otherwise fails fast with a message telling you to pull once on a connected machine or point `--mirror`/`JGENGINE_ASSETS_MIRROR` at a reachable archive — useful for CI scripts that should error in seconds instead of hanging on a blocked fetch.
 
-**Network-restricted environments** — pull once on a machine that can reach the providers, then either:
+**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:
 
 - 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.
@@ -96,7 +117,7 @@ export const game: PlayableGame = {
 };
 ```
 
-`buildCatalog({ sources: ["kenney-nature"] })` restricts to chosen packs; `includeAliases` / `includeSingles` default true. Discover ids with `assets search <term>` / `assets list --category <c>` instead of memorizing them. See `Games/asset-showcase` for a full working example.
+`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.
 
 ### Serving the bytes
 

package/dist/cli/paths.d.ts

@@ -0,0 +1,4 @@
+/** Sibling of `cli/` under `src/` (dev) or `dist/` (published) so reindex writes the tree consumers import. */
+export declare function resolveGeneratedDir(cliDir: string): string;
+export declare function resolvePackageTreeRoot(cliDir: string): string;
+export declare function resolvePackageRoot(cliDir: string): string;

package/dist/cli/paths.js

@@ -0,0 +1,11 @@
+import { join, resolve } from "node:path";
+/** Sibling of `cli/` under `src/` (dev) or `dist/` (published) so reindex writes the tree consumers import. */
+export function resolveGeneratedDir(cliDir) {
+    return join(resolve(cliDir, ".."), "generated");
+}
+export function resolvePackageTreeRoot(cliDir) {
+    return resolve(cliDir, "..");
+}
+export function resolvePackageRoot(cliDir) {
+    return resolve(cliDir, "..", "..");
+}

package/dist/cli/pull.d.ts

@@ -1,4 +1,8 @@
 #!/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;
+export { resolveGeneratedDir } from "./paths.js";
 export declare function flag(argv: string[], name: string): string | undefined;
+export declare function describeNetworkFailure(error: unknown): string;
 export declare function isPopulated(dir: string): boolean;
 export declare function cmdPull(argv: string[]): Promise<void>;

package/dist/cli/pull.js

@@ -3,16 +3,22 @@ import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFi
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { downloadPackArchive, extractGlbs, extractTextures } from "../download.js";
+import { rankAssets } from "../find.js";
 import { generatedIndex } from "../generated/index.js";
 import { reindex } from "../indexGen.js";
 import { isScrapeDownload } from "../manifest.js";
+import { registryCatalog } from "../registry.js";
+import { componentWiringSnippet, iconWiringSnippet, modelWiringSnippet } from "../snippet.js";
 import { sourceById } from "../sources/index.js";
 import { verifyManifest } from "../verify.js";
+import { resolveGeneratedDir, resolvePackageRoot, resolvePackageTreeRoot } from "./paths.js";
 const here = dirname(fileURLToPath(import.meta.url));
-const pkgRoot = resolve(here, "..", "..");
-const srcDir = join(pkgRoot, "src");
-const generatedDir = join(srcDir, "generated");
-const singlesJson = join(srcDir, "singles.json");
+const packageTreeRoot = resolvePackageTreeRoot(here);
+const pkgRoot = resolvePackageRoot(here);
+/** Sibling of `cli/` under `src/` (dev) or `dist/` (published) so reindex writes the tree consumers import. */
+export const generatedDir = resolveGeneratedDir(here);
+export { resolveGeneratedDir } from "./paths.js";
+const singlesJson = join(packageTreeRoot, "singles.json");
 const localDir = join(pkgRoot, "local");
 const CDN_BASE = "https://cdn.jsdelivr.net/gh/Noisemaker111/jgengine@main/packages/assets/local";
 export function flag(argv, name) {
@@ -23,6 +29,19 @@ function fail(message) {
     console.error(`error: ${message}`);
     process.exit(1);
 }
+export function describeNetworkFailure(error) {
+    const chain = [];
+    let current = error;
+    while (current instanceof Error) {
+        chain.push(current.message);
+        current = current.cause;
+    }
+    const text = chain.length > 0 ? chain.join(" — ") : String(error);
+    const looksPolicyBlocked = /\b403\b|CONNECT|proxy|ENOTFOUND|ECONNREFUSED|ETIMEDOUT|fetch failed/i.test(text);
+    return looksPolicyBlocked
+        ? `${text}\nhint: a 403/CONNECT failure here usually means the sandbox network policy blocks this host — not a transient error, retrying won't help. Allowlist the host in the environment settings, point JGENGINE_ASSETS_MIRROR at a reachable mirror, or build with procedural geometry.`
+        : text;
+}
 function cmdList(argv) {
     const category = flag(argv, "category");
     const source = flag(argv, "source");
@@ -69,13 +88,19 @@ export async function cmdPull(argv) {
         console.log(`offline: ${outDir} already populated, skipping network`);
         return;
     }
-    console.log(`resolving ${sourceId}${isScrapeDownload(source.download) ? " (scrape)" : ""}` +
-        `${mirrorBase !== undefined ? ` [mirror override: ${mirrorBase}]` : ""}…`);
-    const { archive, url, attempted } = await downloadPackArchive(source, { mirrorBase });
+    const result = await fetchPackInto(source, outRoot, { mirrorBase });
+    const textureNote = result.textures > 0 ? ` + ${result.textures} texture(s)` : "";
+    console.log(`pulled ${result.models} models${textureNote} -> ${result.outDir}`);
+}
+async function fetchPackInto(source, outRoot, options) {
+    const outDir = join(outRoot, "models", source.id);
+    console.log(`resolving ${source.id}${isScrapeDownload(source.download) ? " (scrape)" : ""}` +
+        `${options.mirrorBase !== undefined ? ` [mirror override: ${options.mirrorBase}]` : ""}…`);
+    const { archive, url, attempted } = await downloadPackArchive(source, { mirrorBase: options.mirrorBase });
     console.log(`downloaded ${url}${attempted.length > 1 ? ` (after ${attempted.length - 1} failed attempt(s))` : ""}`);
     const glbs = extractGlbs(archive);
     if (glbs.length === 0)
-        fail(`no .glb files found in ${sourceId} archive`);
+        fail(`no .glb files found in ${source.id} archive`);
     mkdirSync(outDir, { recursive: true });
     for (const glb of glbs)
         writeFileSync(join(outDir, glb.file), glb.bytes);
@@ -85,8 +110,7 @@ export async function cmdPull(argv) {
         mkdirSync(dirname(dest), { recursive: true });
         writeFileSync(dest, texture.bytes);
     }
-    const textureNote = textures.length > 0 ? ` + ${textures.length} texture(s)` : "";
-    console.log(`pulled ${glbs.length} models${textureNote} -> ${outDir}`);
+    return { outDir, models: glbs.length, textures: textures.length, url };
 }
 function readSingles() {
     if (!existsSync(singlesJson))
@@ -96,10 +120,11 @@ function readSingles() {
 function writeSingles(list) {
     writeFileSync(singlesJson, `${JSON.stringify(list, null, 2)}\n`);
 }
-function cmdAdd(argv) {
+function cmdRegisterSingle(argv) {
     const target = argv[0];
-    if (target === undefined)
-        fail("usage: add <path|url> --category <c> --license <l> [--author <a>] [--id <id>]");
+    if (target === undefined) {
+        fail("usage: register <path|url> --category <c> --license <l> [--author <a>] [--id <id>]");
+    }
     const license = flag(argv, "license");
     if (license === undefined)
         fail("add requires --license");
@@ -132,6 +157,95 @@ function cmdAdd(argv) {
     writeSingles(singles);
     console.log(`added single ${id} -> ${url}${isUrl ? " (0 bytes stored)" : " (copied to local/)"}`);
 }
+const KINDS = ["model", "pack", "component", "icon"];
+function describeMatch(match) {
+    switch (match.kind) {
+        case "model":
+            return `[model]     ${match.id}${match.via === "alias" ? "  (alias)" : match.via === "single" ? "  (single)" : ""}`;
+        case "pack":
+            return `[pack]      ${match.source} — ${match.title}`;
+        case "component":
+            return `[component] ${match.name} — ${match.title}`;
+        case "icon":
+            return `[icon]      ${match.name}`;
+    }
+}
+async function performAdd(match, argv) {
+    if (match.kind === "component") {
+        const component = registryCatalog.components.find((entry) => entry.name === match.name);
+        if (component === undefined)
+            fail(`component vanished from catalog: ${match.name}`);
+        console.log(`component: ${component.title} — ${component.description}\n`);
+        console.log(componentWiringSnippet(component));
+        return;
+    }
+    if (match.kind === "icon") {
+        console.log(`icon: ${match.name}\n`);
+        console.log(iconWiringSnippet(match.name));
+        return;
+    }
+    const source = sourceById.get(match.source);
+    if (source === undefined)
+        fail(`match resolves to unknown source: ${match.source}`);
+    const outRoot = resolve(flag(argv, "dir") ?? "public");
+    const outDir = join(outRoot, "models", match.source);
+    const mirrorBase = flag(argv, "mirror") ?? process.env.JGENGINE_ASSETS_MIRROR;
+    if (isPopulated(outDir)) {
+        console.log(`${match.source} already present in ${outDir}`);
+    }
+    else {
+        const result = await fetchPackInto(source, outRoot, { mirrorBase });
+        const textureNote = result.textures > 0 ? ` + ${result.textures} texture(s)` : "";
+        console.log(`pulled ${result.models} models${textureNote} -> ${result.outDir}`);
+    }
+    const result = reindex(join(outRoot, "models"), generatedDir);
+    console.log(`reindexed ${result.total} entries -> ${generatedDir}`);
+    if (match.kind === "model") {
+        console.log(`\nwire it in (characters/enemies go in entityModels instead):\n`);
+        console.log(modelWiringSnippet(match.id));
+    }
+    else {
+        console.log(`\n${match.title}: browse ids with \`assets list --source ${match.source}\`, then wire like:\n`);
+        console.log(modelWiringSnippet(`${match.source}/<model>`));
+    }
+}
+async function cmdAdd(argv) {
+    const query = argv[0];
+    if (query === undefined) {
+        fail("usage: add <query> [--kind model|pack|component|icon] [--dir <dir>] [--mirror <baseUrl>] [--json]\n" +
+            "       add <path|url> --license <l> [--category <c>]   (register a one-off single into the shipped index)");
+    }
+    // Back-compat: the old `add` registered a one-off single, always with --license.
+    if (flag(argv, "license") !== undefined) {
+        cmdRegisterSingle(argv);
+        return;
+    }
+    const kindFlag = flag(argv, "kind");
+    if (kindFlag !== undefined && !KINDS.includes(kindFlag)) {
+        fail(`--kind must be one of ${KINDS.join(", ")}`);
+    }
+    const kind = kindFlag;
+    const ranked = rankAssets(query, { kind, limit: Number(flag(argv, "limit") ?? "12") });
+    if (ranked.length === 0) {
+        fail(`no asset matches "${query}" — try a broader term or \`assets search <term>\``);
+    }
+    if (argv.includes("--json")) {
+        console.log(JSON.stringify(ranked, null, 2));
+        return;
+    }
+    const top = ranked[0];
+    const runnerUp = ranked[1]?.score ?? 0;
+    const decisive = ranked.length === 1 || kind !== undefined || top.score - runnerUp >= 20;
+    if (!decisive) {
+        console.log(`several matches for "${query}" — narrow with --kind or a more specific term:\n`);
+        for (const entry of ranked.slice(0, 8))
+            console.log(`  ${describeMatch(entry.match)}`);
+        console.log(`\nthen re-run, e.g. \`assets add "${query}" --kind ${top.match.kind}\``);
+        return;
+    }
+    console.log(`→ ${describeMatch(top.match)}\n`);
+    await performAdd(top.match, argv);
+}
 function cmdReindex(argv) {
     const modelsDir = resolve(argv[0] ?? join("public", "models"));
     if (!existsSync(modelsDir))
@@ -161,10 +275,13 @@ if (import.meta.main) {
             cmdSearch(rest);
             break;
         case "pull":
-            await cmdPull(rest);
+            await cmdPull(rest).catch((error) => fail(describeNetworkFailure(error)));
             break;
         case "add":
-            cmdAdd(rest);
+            await cmdAdd(rest).catch((error) => fail(describeNetworkFailure(error)));
+            break;
+        case "register":
+            cmdRegisterSingle(rest);
             break;
         case "reindex":
             cmdReindex(rest);
@@ -173,7 +290,7 @@ if (import.meta.main) {
             cmdVerify();
             break;
         default:
-            console.log("usage: assets <list|search|pull|add|reindex|verify> [...args]");
+            console.log("usage: assets <add|list|search|pull|register|reindex|verify> [...args]");
             if (command !== undefined && command !== "help")
                 process.exit(1);
     }

package/dist/download.d.ts

@@ -18,6 +18,19 @@ export declare function downloadArchive(url: string, fetchImpl?: FetchLike): Pro
  * `https://my-mirror.example.com/kenney/kenney-nature.zip`.
  */
 export declare function mirrorOverrideUrl(baseUrl: string, source: AssetSource): string;
+/**
+ * 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`.
+ */
+export declare const DEFAULT_RELEASE_BASE = "https://github.com/Noisemaker111/jgengine/releases/download/packs";
+/** URL of `source`'s archive on the default GitHub-release mirror. */
+export declare function defaultReleaseUrl(source: AssetSource): string;
 export interface DownloadPackOptions {
     /** Explicit mirror base override (CLI `--mirror` / `JGENGINE_ASSETS_MIRROR`), tried before the primary provider path. */
     mirrorBase?: string;
@@ -32,8 +45,10 @@ export interface DownloadPackResult {
 /**
  * Resolves and downloads a pack's archive, trying sources in order until one
  * succeeds: (1) the mirror base override at `mirrorOverrideUrl`, (2) the
- * primary provider path (`resolveArchiveUrl`: scrape or pinned URL), (3) the
- * pack's own `mirror` URL. A pinned `sha256` is verified against whichever
+ * default GitHub-release mirror at `defaultReleaseUrl` (skipped when
+ * `JGENGINE_ASSETS_NO_DEFAULT_MIRROR=1`), (3) the primary provider path
+ * (`resolveArchiveUrl`: scrape or pinned URL), (4) the pack's own `mirror`
+ * URL. A pinned `sha256` is verified against whichever
  * source supplied the bytes; a mismatch is treated as a failed attempt so the
  * next source in the chain is tried. Throws with every attempted URL and its
  * failure reason when all sources fail.

package/dist/download.js

@@ -55,6 +55,21 @@ export function mirrorOverrideUrl(baseUrl, source) {
     const base = baseUrl.replace(/\/+$/, "");
     return `${base}/${source.provider}/${source.id}.zip`;
 }
+/**
+ * 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`.
+ */
+export const DEFAULT_RELEASE_BASE = "https://github.com/Noisemaker111/jgengine/releases/download/packs";
+/** URL of `source`'s archive on the default GitHub-release mirror. */
+export function defaultReleaseUrl(source) {
+    return `${DEFAULT_RELEASE_BASE}/${source.provider}-${source.id}.zip`;
+}
 async function verifyPinnedSha(source, archive) {
     const download = source.download;
     if (isScrapeDownload(download) || download.sha256 === undefined)
@@ -67,8 +82,10 @@ async function verifyPinnedSha(source, archive) {
 /**
  * Resolves and downloads a pack's archive, trying sources in order until one
  * succeeds: (1) the mirror base override at `mirrorOverrideUrl`, (2) the
- * primary provider path (`resolveArchiveUrl`: scrape or pinned URL), (3) the
- * pack's own `mirror` URL. A pinned `sha256` is verified against whichever
+ * default GitHub-release mirror at `defaultReleaseUrl` (skipped when
+ * `JGENGINE_ASSETS_NO_DEFAULT_MIRROR=1`), (3) the primary provider path
+ * (`resolveArchiveUrl`: scrape or pinned URL), (4) the pack's own `mirror`
+ * URL. A pinned `sha256` is verified against whichever
  * source supplied the bytes; a mismatch is treated as a failed attempt so the
  * next source in the chain is tried. Throws with every attempted URL and its
  * failure reason when all sources fail.
@@ -94,6 +111,11 @@ export async function downloadPackArchive(source, options = {}) {
         if (result !== undefined)
             return result;
     }
+    if (process.env.JGENGINE_ASSETS_NO_DEFAULT_MIRROR !== "1") {
+        const result = await tryUrl(defaultReleaseUrl(source));
+        if (result !== undefined)
+            return result;
+    }
     try {
         const primaryUrl = await resolveArchiveUrl(source, fetchImpl);
         const result = await tryUrl(primaryUrl);

package/dist/find.d.ts

@@ -0,0 +1,35 @@
+export type AssetKind = "model" | "pack" | "component" | "icon";
+export type AssetMatch = {
+    kind: "model";
+    id: string;
+    source: string;
+    file?: string;
+    via: "index" | "alias" | "single";
+} | {
+    kind: "pack";
+    source: string;
+    title: string;
+    categories: readonly string[];
+} | {
+    kind: "component";
+    name: string;
+    title: string;
+    description: string;
+} | {
+    kind: "icon";
+    name: string;
+};
+export interface FindOptions {
+    /** Restrict results to one kind. */
+    kind?: AssetKind;
+    /** Cap the number of matches returned (default 12). */
+    limit?: number;
+}
+export interface RankedMatch {
+    match: AssetMatch;
+    score: number;
+}
+/** Rank every catalog entry — models, packs, HUD components, icons — against one query. */
+export declare function rankAssets(query: string, options?: FindOptions): RankedMatch[];
+/** The ranked matches for a query — models, packs, HUD components, and icons in one list. */
+export declare function findAssets(query: string, options?: FindOptions): AssetMatch[];

package/dist/find.js

@@ -0,0 +1,147 @@
+import { aliases } from "./aliases.js";
+import { generatedIndex } from "./generated/index.js";
+import { keyFromFile } from "./indexGen.js";
+import { registryCatalog } from "./registry.js";
+import { singles } from "./singles.js";
+import { sources } from "./sources/index.js";
+function normalize(value) {
+    return value.toLowerCase().replace(/[\s_/-]+/g, " ").trim();
+}
+function tokenScore(token, hay, words) {
+    if (words.includes(token))
+        return 70;
+    if (hay.startsWith(token))
+        return 55;
+    if (words.some((word) => word.startsWith(token)))
+        return 45;
+    if (hay.includes(token))
+        return 30;
+    return 0;
+}
+/**
+ * 0 (no match) … 100 (exact). Single-word queries reward whole-word and prefix
+ * hits over loose substrings; a multi-word query ("mana bar") scores by the mean
+ * of its tokens and only counts when *every* token lands in the field.
+ */
+function scoreText(needle, hay) {
+    const n = normalize(needle);
+    const h = normalize(hay);
+    if (n.length === 0 || h.length === 0)
+        return 0;
+    if (h === n)
+        return 100;
+    const words = h.split(" ");
+    const tokens = n.split(" ").filter((token) => token.length > 0);
+    if (tokens.length <= 1)
+        return tokenScore(n, h, words);
+    let sum = 0;
+    for (const token of tokens) {
+        const score = tokenScore(token, h, words);
+        if (score === 0)
+            return 0;
+        sum += score;
+    }
+    return Math.min(90, Math.round(sum / tokens.length));
+}
+function best(needle, ...hays) {
+    let top = 0;
+    for (const hay of hays) {
+        if (hay === undefined)
+            continue;
+        top = Math.max(top, scoreText(needle, hay));
+    }
+    return top;
+}
+function sourceOf(id) {
+    const slash = id.indexOf("/");
+    return slash === -1 ? id : id.slice(0, slash);
+}
+/** Rank every catalog entry — models, packs, HUD components, icons — against one query. */
+export function rankAssets(query, options = {}) {
+    const q = query.trim();
+    const ranked = [];
+    const push = (score, match) => {
+        if (score > 0)
+            ranked.push({ score, match });
+    };
+    if (options.kind === undefined || options.kind === "model") {
+        for (const entry of generatedIndex) {
+            push(best(q, entry.id, keyFromFile(entry.file), ...entry.categories), {
+                kind: "model",
+                id: entry.id,
+                source: entry.source,
+                file: entry.file,
+                via: "index",
+            });
+        }
+        for (const alias of aliases) {
+            push(best(q, alias.key, alias.target), {
+                kind: "model",
+                id: alias.target,
+                source: sourceOf(alias.target),
+                via: "alias",
+            });
+        }
+        for (const single of singles) {
+            push(best(q, single.id, ...single.categories), {
+                kind: "model",
+                id: single.id,
+                source: sourceOf(single.id),
+                via: "single",
+            });
+        }
+    }
+    if (options.kind === undefined || options.kind === "pack") {
+        for (const source of sources) {
+            push(best(q, source.id, source.title, source.provider, ...source.categories), {
+                kind: "pack",
+                source: source.id,
+                title: source.title,
+                categories: source.categories,
+            });
+        }
+    }
+    if (options.kind === undefined || options.kind === "component") {
+        for (const component of registryCatalog.components) {
+            push(best(q, component.name, component.title, component.description), {
+                kind: "component",
+                name: component.name,
+                title: component.title,
+                description: component.description,
+            });
+        }
+    }
+    if (options.kind === undefined || options.kind === "icon") {
+        for (const icon of registryCatalog.icons) {
+            push(best(q, icon), { kind: "icon", name: icon });
+        }
+    }
+    ranked.sort((a, b) => b.score - a.score || matchKey(a.match).localeCompare(matchKey(b.match)));
+    return dedupe(ranked).slice(0, options.limit ?? 12);
+}
+function matchKey(match) {
+    switch (match.kind) {
+        case "model":
+            return `model:${match.id}`;
+        case "pack":
+            return `pack:${match.source}`;
+        default:
+            return `${match.kind}:${match.name}`;
+    }
+}
+function dedupe(ranked) {
+    const seen = new Set();
+    const out = [];
+    for (const entry of ranked) {
+        const key = matchKey(entry.match);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(entry);
+    }
+    return out;
+}
+/** The ranked matches for a query — models, packs, HUD components, and icons in one list. */
+export function findAssets(query, options = {}) {
+    return rankAssets(query, options).map((entry) => entry.match);
+}

package/dist/index.d.ts

@@ -6,4 +6,7 @@ export { generatedIndex, generatedBySource } from "./generated/index.js";
 export { readGlbDims } from "./dims.js";
 export { buildCatalog, entryUrl, type BuildCatalogOptions } from "./catalogs/build.js";
 export { createStarterCatalog } from "./catalogs/starter.js";
+export { findAssets, rankAssets, type AssetKind, type AssetMatch, type FindOptions, type RankedMatch, } from "./find.js";
+export { registryCatalog, componentInstallUrl, type RegistryCatalog, type RegistryComponent } from "./registry.js";
+export { modelWiringSnippet, componentWiringSnippet, iconWiringSnippet, type ModelSnippetOptions } from "./snippet.js";
 export { verifyManifest, type VerifyResult } from "./verify.js";

package/dist/index.js

@@ -6,4 +6,7 @@ export { generatedIndex, generatedBySource } from "./generated/index.js";
 export { readGlbDims } from "./dims.js";
 export { buildCatalog, entryUrl } from "./catalogs/build.js";
 export { createStarterCatalog } from "./catalogs/starter.js";
+export { findAssets, rankAssets, } from "./find.js";
+export { registryCatalog, componentInstallUrl } from "./registry.js";
+export { modelWiringSnippet, componentWiringSnippet, iconWiringSnippet } from "./snippet.js";
 export { verifyManifest } from "./verify.js";