@jgengine/assets 0.25.0 → 0.27.0

package/CHANGELOG.md

@@ -26,6 +26,115 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.27.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.27.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.24.0`; `@jgengine/github` is `0.14.0`.
+
+### Added
+
+- `rollLoot` (`@jgengine/core/loot/lootGen`) rolls a named item from a caller `LootCatalog`: bases with mount slots, parts, affix pools, weighted rarity tiers, manufacturer personalities and a `levelScale` curve. Stats are `base × rarity.statScale × levelScale`, then part stats/multipliers, maker `bias`/`scale`, then additive and multiplicative affixes; additive affix rolls scale with level, multiplicative ones do not.
+- `createLootRoller` wraps a validated catalog with roll counts per rarity, `snapshot()`/`restore()`/`reset()` and an optional devtools probe; `assertLootCatalog` rejects duplicate ids, unresolvable pools, empty item slots and a non-ascending level curve at construction.
+- `validateLootItem` returns coded issues (`unknown-base`, `manufacturer-base`, `missing-slot-part`, `part-category`, `unknown-affix`, `empty-name`, …) and `compareLootItems` returns sorted per-stat deltas plus a weighted score with caller-named `lowerIsBetter` stats.
+- `lootWeaponDefinition` (`@jgengine/core/loot/lootWeapon`) projects a rolled item onto a `WeaponDefinition` through a caller stat map, so a generated gun runs in `createWeaponSystem` after `assertWeaponDefinition`.
+- `defineXpCurve` (`@jgengine/core/gameplay`) resolves one authored growth rule (`flat`, `linear`, `power`, `geometric`, `table`) plus a `maxLevel` cap into per-level thresholds, lifetime totals, a plain-words rule string and a `leveling` track.
+- `createSkillTree` spends and refunds points over authored nodes with `cost`, `requires`, `excludes`, passives, actives and multi-node `synergies`; `resolved()` returns the stat modifiers and actions, and state snapshots/restores as `{ points, ranks }`.
+- `gearScore` / `compareGearSets` score a whole loadout from stat weights, level, rarity and slot coverage.
+- `lootStatContributions` and `scoreLootStats` expose the weight policy `compareLootItems` already used.
+- `createEquipment` (`@jgengine/core/inventory/equipment`) wears gear by slot: slot defs declare accepted kinds and the slots they block, item defs declare the slots an item may occupy, a filled slot swaps and hands back the replaced item, and a two-handed item and the slot it blocks cannot both be filled. `state()` / `restore()` round-trip the worn set; a devtools probe reports filled slots.
+- `characterLoad` and `canCarry` (`@jgengine/core/inventory/carryLoad`) weigh carried inventories plus worn gear against a capacity and hand back the shared encumbrance bands (tier, `moveMultiplier`, sprint/jump gates, `remaining`), so a stash left out of `carried` adds no weight.
+- `fitShapedItem` (`@jgengine/core/inventory/shapedGrid`) places a shaped item at its first fit or names why not: `too-large` (with both sizes), `no-space`, `budget-exceeded`.
+- `InventorySet.snapshot()` / `restore()` / `reset()` (`@jgengine/core/inventory/inventoryModel`) save and reload every declared inventory as detached plain data, so a bag and a stash never share live slots.
+- `splitStack` takes an optional stack `limit`, rejecting `over-stack` instead of merging past the max stack.
+- `createLaneGraph` and `laneGraphFromDocument` (`@jgengine/core/world`) read an authored lane graph out of the scene document: `traffic_lane` paths are one directed span each, `road` paths (the street bake) become a lane per direction split where streets cross, `traffic_intersection` markers carry signal phases and right-of-way in `meta`, and `traffic_parking` markers place kerbside spots.
+- `createTraffic` (`@jgengine/core/world`) runs cars on that graph: IDM car following and braking, one car at a time through each intersection box behind a signal phase or first-come right-of-way, lane changes across authored neighbours, parking that reserves a spot, deterministic injected variety, `snapshot`/`restore`, and a devtools probe.
+- `Traffic.setDemand(count)` is the fleet target; the time-of-day curve stays the caller's policy.
+- `applyVehicleParts` (`@jgengine/core/world`) composes data-driven tuning parts onto a `KinematicVehicleTuning` — stat multipliers/addends applied in install order plus an optional tire grip curve — and returns the composed tuning, the installed ids, and a `VehicleFeel` (top speed, drive, brakes, turn rate, handbrake grip, and the grip curve's peak/slide). `withPart` swaps a part within its slot and `feelOf` reads the numbers out of any tuning.
+- `createVehicleDamage` (`@jgengine/core/world`) is fixed-zone crash damage wired to handling and visuals: impacts accumulate into discrete stages, each stage costs grip/drive/brakes/top speed/drag and pulls the steering (`effect`), and each zone shows one bounded dent (`deformation`) that never exceeds its authored `deform`. Parts can detach at a set stage, a total impulse can disable the vehicle, and `snapshot`/`restore` resume mid-crash. `damagedTuning` and `damagedAxis` fold the effect into a tuning or an input, and `modifiers()` carries it as per-tick overrides.
+- `KinematicVehicleTuning.weightTransfer` (`@jgengine/core/world`) adds load-transfer grip: longitudinal transfer under braking/traction and lateral transfer under cornering cut the tire grip curve (tire load sensitivity), so braking into a corner holds less slide than coasting through it. Each tick reports `weightTransfer` and `loadGrip`; omitting the block keeps the previous flat-grip model exactly.
+- `KinematicVehicleModifiers.gripScale` scales the grip curve for one tick, mirroring `VehicleDynamicsModifiers.gripScale` so a damage layer drives either sim.
+- `decal` scene kind (`@jgengine/core/world/decalKind`) and its renderer (`@jgengine/shell/scene/DecalRenderer`): dirt, cracks, paint and blood decals authored as placed markers, draped on the live terrain or standing on an authored tilt, with a deterministic procedural texture per style+seed.
+- `TerrainMaterialLayer.material` (`@jgengine/core/world/terraform`): a material library name whose scanned color map paints that terrain layer. The runtime samples up to four layer maps at each layer's `tiling` and blends them through the authored mask weights (`createTerrainDetailMaterial`'s `layerMaps`), so painted terrain blends between authored layers instead of tiling one flat map.
+- `grass_field` volumes now paint a ground-cover mat under their blades (`groundCover` rule, `@jgengine/shell/terrain/GrassCover`), so an authored patch reads as turf rather than bare ground with stubble. `GrassEnvironmentConfig.groundCover` does the same for `grass()` patches.
+- `ModelConfig.wind` (`@jgengine/core/game/playableGame`) and `applyModelWind` (`@jgengine/shell/render/modelWind`): per-model foliage sway with height-ramped travel, shared gust clock and per-model strength/speed/direction.
+
+### Fixed
+
+- The player shell re-renders only for the ctx slices it reads — the possessed entity and the touch control mode — instead of on every `ctx` write. Subscribing the shell root to the raw ctx version reconciled the canvas, the whole actor tree and the HUD on each per-frame entity pose write, which is what `subscribeMembership` and the markers' imperative `useFrame` pose reads exist to avoid (#625). Scrap Signal: 86.6 ms → 16.7 ms per frame at the same 621 draws; Harbor Heat: 102.8 ms → 46.2 ms at the same ~7.2k draws.
+- The `ocean()` environment feature passes the live ground to its shader, so the sea shades shallow→deep and its shoreline foam band lands where the bed meets the surface.
+
+### Numbers
+
+- Test catalog (60/25/10/4/1 rarity weights) over 10,000 drops at level 20, fixed seed: common 59.41% (target 60%), uncommon 25.66% (25%), rare 9.58% (10%), epic 4.20% (4%), legendary 1.15% (1%); every tier inside its 4σ binomial bound. All 10,000 items validated with zero issues and composed names (e.g. `Voss Rare Long Keen Lightframe of Reach`, `Tallow Long Lightframe`, `Voss Snub Lightframe of Steadying`).
+- Level curve `[[1,1],[15,1.6],[30,2.4],[60,4]]`: a level-60 roll's base and additive affix values are 4× the same seed at level 1; maker personalities move the same roll (`Voss` +power/−cadence, `Tallow` the reverse).
+- A rolled epic projects to a hitscan `WeaponDefinition` (rate, damage, integer magazine capacity, spread, range), passes `assertWeaponDefinition`, and its first `tick` fires one shot and one impact through `createDamageRuntime` with the rolled capacity spent.
+
+## 0.26.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.26.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.23.0`; `@jgengine/github` is `0.13.0`.
+
+### Added
+
+- `createLogBus` (`@jgengine/core/devtools/logBus`): a fixed-capacity ring of log lines tagged by owning system, with a separate ring for warnings and errors so a crash line is never pushed out by info traffic. `devtools.logs` now writes through it (`write(level, system, message)`, `snapshot()`, `counts()`, `dropped()`); `DevtoolsLogEntry` gained `system`.
+- `devtools.probes.registerSystem(id, { counters, timers, state })`: a system reports its own counters, named timings and one state line in a few lines, with no shell wiring. Readings surface as `systems` in `devtools.snapshot()`, in `debug_snapshot`, and in every perf record.
+- `PerfReport` (`@jgengine/core/devtools/report`): the one perf record shape shared by `bun run perf` and the in-page report.
+- The shell samples frame telemetry in-page in dev builds: `window.__JG.report()` returns that record, and the page pushes it about once a second to the dev server's `GET/POST /__jgengine/report` route. `bun run debug <game>` prints the record of a game already open and exits non-zero on a budget breach in `scripts/perf-budget.json`.
+- `createNeedSet` (`@jgengine/core/gameplay`) drains named needs on game time and reads them by index — decaying hunger, energy, fun with snapshot/restore and per-need rate retuning.
+- `createUtilityBrain` (`@jgengine/core/world`) picks an action from decaying-need appeal: linear, quadratic, logistic, exponential and threshold response curves, candidate cost (travel, queues, price), a switch margin plus minimum hold (hysteresis), declared interrupts, optional seeded jitter, and a devtools probe string.
+- `createNavRuntime` (`@jgengine/core/world`) consumes an editor-baked nav mesh: reads the `nav` bake off a scene document (`navMeshFromBake`), routes with the mesh query, resolves authored doors, ladders and jumps (`AuthoredNavLink`, priced by kind) onto the current surface, and swaps in a new bake after an edit while matching polygon identity by geometry — `applyMesh` returns a `remap` so only routes over changed polygons need re-planning.
+- `createNavCrowd` (`@jgengine/core/world`) moves many agents across that mesh: plans a corridor, follows the funnel-smoothed waypoints, keeps agents apart with reciprocal velocity obstacle avoidance, bounds path searches per tick by count and milliseconds, fans converging agents out with `spread`, and round-trips through `snapshot`/`restore`.
+- `createRvoCrowd` (`@jgengine/core/world`) is the avoidance solver on its own: RVO/ORCA half-plane solve over a uniform-grid neighbour search capped at `maxNeighbors`, deterministic tie-breaking, overlap relief, retunable `timeHorizon`/`neighborDist`/`maxNeighbors`/`sideBias`/`overlapRelief`, and `snapshot`/`restore` for saves and replays.
+- `resolveRoutine` (`@jgengine/core/gameplay`) resolves an authored day into real arrival and departure times against the world clock. Travel time is injected per stop or as a callback, so a stop departs early enough to walk to the next one and an arrival that runs late slips instead of teleporting; `phaseAt(time)` returns the held place, the walking leg and its progress, and `nextChangeAfter(time)` drives a scheduler. A day whose walks cannot fit its cycle throws at construction.
+- `createOffScreenWorld` (`@jgengine/core/gameplay`) keeps a whole population without simulating it: residents beyond the injected radius are cheap state (position, routine phase, needs) that only moves when the clock crosses a routine boundary, and they spawn into the game's own near simulation through a `NearAgents` interface when they come close. The radius, an optional per-agent cost model, a near budget and a per-tick switch budget are all injected; `snapshot`/`restore` round-trip the whole population, and crossing the boundary preserves identity, schedule progress, need values and position.
+- `createNearAgents` (`@jgengine/core/gameplay`) is the default near half of that seam: a nav crowd with a need set and utility brain per agent, goal-tracking as routines move residents between places, and a decision counter for tests and probes.
+- `createPerception` shares squad knowledge: `squadMates(observerId)` names an observer's roster, and a sighting one member makes is written into every mate's memory with `sourceId` (who saw it) and `sourceTick` (the observe pass it was recorded on). A mate's own sighting at the same instant replaces the hand-off. `maxSharesPerTick` (default 64, per observer pass) bounds a large roster and reports elided shares.
+- Perception memory is auditable without guessing: `memoryOf(observerId, targetId)` returns the one remembered target with its confidence right now or `null` once it has faded, and `stats()` counts pair checks, range prunes, cone tests, line-of-sight calls, sightings, heard stimuli, shares and dropped shares. The check order is range → cone → line of sight, so occlusion work only sees the pruned set. `resetStats()` opens a measurement window; `memories` are pruned per observer so a 200-observer pass does not rescan every memory.
+- `devtoolsName` registers a probe showing observers, remembered targets and the work counters, and `dispose()` removes it.
+- `createCoverField` and `coverPointsFromSolids` (`@jgengine/core/combat`) derive stand-able cover from authored solid boxes instead of a coordinate list: one row of points per vertical face, clear of the corners, filtered by an injected `walkable` test, rebuilt when the world is edited, and queried through a bounded `near(position, radius, limit)`. `CoverSource` is the seam, so a game with its own spatial index can supply cover without the box generator.
+- `selectCover` / `scoreCoverPoint` choose cover by threat: `hidden` is the confidence-weighted share of remembered threats whose line of sight the point (and a body-sized footprint at it) blocks, scored against the role's preferred fighting range, flank angle around the threat, distance, a squadmate's claim on the point, and whether the walk to it is a detour. Fading memories stop steering at `minConfidence`, and a point that hides from only one of two shooters is not cover.
+- `createSquadCombat` (`@jgengine/core/combat`) drives a squad over existing seams: role-driven cover selection, fire discipline (hold, lean out, shoot), suppression from `underFire()`, retreat below a role's health threshold, and relocation under sustained fire. Threat comes only from `threatsFromMemory`, i.e. the perception memory the game already keeps; movement goes through `NavCrowd` with a tighter arrival tolerance so a body actually reaches the stand point. Serializable through `snapshot()`/`restore()` (member decisions, crowd, tuning), retunable, and a `devtoolsName` probe reports pins, peeks, shots and the worst exposure.
+- `assignSquadRoles` and `threatsFromMemory` (`@jgengine/core/combat`): deterministic role assignment over a caller-authored `SquadComposition` (role ids, counts, ranges, flank angles, retreat thresholds and cover weights are all content), and a bounded, confidence-ranked threat list from one observer's memory.
+- A 2v4 arena soak proves the behavior: 90 simulated seconds, 2700 ticks, 4 squad members against 2 scripted raiders, worst exposure 2.33 s (bar 3 s), 0 of 38 exposure spells over 3 s, per-tick cost p50 0.05 ms / p95 0.19 ms.
+- `createDamageRuntime` (`@jgengine/core/combat`) composes a damage table, hit zones, the armor curve and carried statuses into one stateful model: `hit()` returns every stage of the number (`base × zone multiplier × type multiplier × (1 − armor mitigation)`), `tick()` runs status effects through the same table and armor, `timeToKill()` quotes a fight, and `table()` reads the whole chart. `snapshot()`/`restore()` carry registered targets and carried statuses; `retune()` swaps table, zones or status definitions without dropping either; a `devtoolsName` probe reports hits, crits, ticks and the last hit.
+- A damage table (`combat/damageTable`) of damage type × resistance class, with `armor / (armor + halfValue)` mitigation — armor equal to the half value halves the hit — a per-type `bypassArmor`, and `readDamageTable` / `formatDamageTable` to read every row at given armor values. An unknown damage type throws instead of silently dealing 1×.
+- Hit zones and crits (`combat/hitZones`): a zone carries a normal multiplier and an optional crit multiplier, `resolveHitZone` rolls once and returns one multiplier, and a crit replaces the zone multiplier rather than compounding with it. `hitZoneMultiplier` quotes the same number without a roll.
+- `createStatusRuntime` (`combat/statusRuntime`): data-defined statuses with the existing `StatusStackPolicy` (`refresh`, stack to `max`, `replace`, `ignore`) as the only thing that changes stacks, per-tick effects of `{ kind: "damage", channel }` or `{ kind: "stat", stat }`, damage routed through an injected `applyDamage` so resistances and armor still apply, bounded ticks per call, and plain-data state out and back.
+- Numbers from the tests: 25 base kinetic against a 150 HP target, 0.15 s between shots — 8 shots / 1.05 s unarmored, 20 shots / 2.85 s at 60 armor, 36 shots / 5.25 s at 200 armor; two stacked burns of 4 per tick deal 8, not 16; a 1.5× head zone with a 2.5× crit multiplier deals 2.5×, not 3.75×.
+- `createWeaponSystem` (`@jgengine/core/combat`) runs one `WeaponDefinition`: single, automatic or burst fire, hitscan or ballistic projectiles, recoil that moves the aim the shot flies down, spread bloom, interrupted/resumed reloads, a readable ammo economy (`ammo()`, `stats()`), `snapshot()`/`restore()` and a devtools probe. Every hit, hitscan or projectile, resolves through `createDamageRuntime`. Pellet work is bounded per tick (`maxShotsPerTick`, default 4) and per weapon (`maxInFlight`, default 32).
+- `WeaponDefinition` (`@jgengine/core/combat/weaponDefinition`) as plain JSON — rate, fire mode, delivery, magazine, handling, damage, falloff — with `assertWeaponDefinition`, `weaponIntervalMs`, `weaponDamageAt` and `weaponMaxInFlight`. A generated gun is the same shape.
+- `Magazine.pauseReload()` / `resumeReload()` / `isPaused()` suspend a reload and keep its progress; a paused reload is not `isReloading()`, does not advance in `tick`, and round-trips through `snapshot()`/`restore()`.
+- `environment.grading` on the scene document authors a per-game colour grade: shadow/midtone/highlight swatches plus tint, saturation and contrast bake into a small display-space LUT (`lutCubeFromGrading`, `colorGradeFromDocument` in `@jgengine/core/editor/environment`), edited in the Lighting workspace. The shell applies it from `editorLayers`, and a graded game needs no LUT asset or hardcoded pass.
+- Clamped auto-exposure: `postProcessing.autoExposure: { min, max, adaptationSeconds } | false` meters the pre-tone-map frame every four frames toward 18% grey and stays inside the authored range. `WHITE_POINT` and `MID_GREY` in `@jgengine/core/render/colorPipeline` are the single documented calibration the pipeline uses.
+- `GradeConfig.lut` also accepts a baked `{ cube: { size, data } }` LUT, sampled trilinearly after the numeric grade.
+- `MATERIAL_LIBRARY` (`@jgengine/assets/catalogs/materialLibrary`) names 56 PBR surfaces — wet asphalt, painted metal, stucco, brick, wood, foliage with cut-out coverage and sheen, glass, water, sand, concrete and more — each mapping a name to an ambientCG source, a world tile size in metres and a physical response. `libraryMaterialAsset("asphalt/wet")` returns the editable `MaterialAsset` those names resolve to, and `filterLibraryMaterials` backs pickers. `assets pull library` pulls every pinned map set.
+- `TriplanarAssetMaterial` / `useTriplanarAssetMaterial` / `applyTriplanarProjection` (`@jgengine/shell/render/triplanarMaterial`) render a material asset from world position, so world geometry without a `uv` attribute still gets colour, normal, roughness and AO maps. Tile size is world metres; instanced meshes project in instanced space.
+- The editor's Materials workspace browses the library by name and writes the chosen entry into the document's material assets.
+
+### Changed
+
+- `createPerception` (`@jgengine/core/world`, also `@jgengine/core/sensor/perception`) takes `isSegmentClear` instead of `occluded`: the game supplies collision as a "nothing blocks this segment" test, and it is only called for pairs already inside range and cone. **Migration:** flip the predicate — a `occluded: (from, to) => blocked(from, to)` becomes `isSegmentClear: (from, to) => !blocked(from, to)`.
+- `MagazineSnapshot` gains an optional `paused: true` field, present only while a reload is suspended, so existing snapshots and idle shapes are unchanged.
+- AgX is the pipeline's tone map: `postProcessing.toneMapping` defaults to `"agx"`, and the `cinematic`, `photoreal`, `comic`, `retro` and `STUDIO_STAGE_POST` configs now pick it too. `"toon"` keeps `"linear"` on purpose. Games that authored `"aces"` explicitly are unchanged.
+- The grade pass samples LUT tiles at texel centres and blends the blue axis by hand, so a supplied strip LUT no longer bleeds across slices.
+
+### Fixed
+
+- `bun run debug <game>` now finds the server `bun dev` started. The website dev server publishes the same checkout marker the runner does (`scripts/devServerMarker.ts`, written at listen, removed on shutdown, dev builds only), and the marker records the host that answers, since Vite's default `localhost` can be IPv6-only where `127.0.0.1` hangs.
+- The website dev server serves `GET/POST /__jgengine/report` too, so a game opened at `/games/<id>` reports from the `/play` runner it embeds.
+- The in-page sampler installs when the dev report route answers, not on a build-time `PROD` check: the `/play` runner is a production build, so the old check silently disabled the report on `bun dev`.
+- A report taken inside the sampler's warmup is no longer judged on link/framebuffer counts, which only mean something after the warmup baseline exists.
+- `extractMaterialMaps` and `buildMaterialCatalog` now recognise ambientCG's `_Opacity` map, so cut-out foliage and decal scans keep their coverage instead of rendering as solid cards.
+- Capture runs no longer leak a ~150 MB temp Chrome profile each. `shoot`, `drive` and `perf` delete their profile on every exit path — success, throw, watchdog and SIGINT — `bun run shoot` reclaims profiles a killed run left untouched for three hours, the capture guard sweeps the profile of a run it force-kills, and the generated `browser.mjs` harness for game repos removes its own. A capture also refuses to start when the temp drive has less free space than it needs.
+- The post-processing chain, graphics settings and textured terrain material keep a stable identity across renders. Before, every render rebuilt the effect composer and recompiled shaders, which dropped games to single-digit FPS.
+
+### Numbers
+
+- Test fixture at 600 rpm, 30-round magazine: 2.9 s to empty; 17.0° pitch and 3.1° yaw climb over the magazine; back to half climb in 0.37 s and within 5% in 0.6 s; bloom 2.0 → 8.0 → 12.0 mrad (cap) by the tenth shot, settling to base 0.63 s after the last shot.
+- A hitscan and a projectile contact at the same distance return the same damage (20 body, 30 on a 1.5x head zone) through one damage model; a 60 m/s projectile crosses 20 m in 0.33 s and drops 2.45 m in 0.5 s at 9.81 m/s².
+
 ## 0.25.0
 
 ### Migrate

package/dist/catalogs/materialLibrary.d.ts

@@ -0,0 +1,61 @@
+import { type MaterialAsset, type MaterialSurfaceParameters, type MaterialTextureMetadata, type MaterialTextureRole } from "@jgengine/core/material/materialAsset";
+/** How a library surface renders: an ordinary PBR surface, cut-out foliage, glass or water. */
+export type LibrarySurface = "opaque" | "foliage" | "glass" | "water";
+/** Browse groups the library browser and `assets list` share. */
+export type LibraryGroup = "asphalt" | "concrete" | "stucco" | "brick" | "tile" | "metal" | "wood" | "foliage" | "ground" | "fabric" | "stone" | "glass" | "water";
+/**
+ * One named material a game or the editor selects by name. `source` names the ambientCG catalog
+ * entry whose pulled maps it uses; glass and water carry response parameters only, because
+ * ambientCG publishes no scanned glass or water material and both are shader surfaces.
+ */
+export interface LibraryMaterial {
+    /** Stable name, e.g. `asphalt/wet`. Names are the data contract; source ids and URLs are not. */
+    name: string;
+    /** Human label for pickers and contact sheets. */
+    title: string;
+    group: LibraryGroup;
+    /** ambientCG source id in the material catalog, whose maps `assets pull <id>` writes. */
+    source?: string;
+    surface: LibrarySurface;
+    /** Metres one texture tile covers on world geometry. */
+    tileMetres: number;
+    /** Sparse physical response merged over the imported or authored slot. */
+    response: MaterialSurfaceParameters;
+}
+/**
+ * The shared library: 40+ ambientCG PBR materials plus the glass and water surfaces that need a
+ * shader rather than a scan. `satisfies` keeps every entry complete, so a missing tile size or
+ * response is a type error instead of a silently grey surface.
+ */
+export declare const MATERIAL_LIBRARY: readonly LibraryMaterial[];
+/** Map roles a library scan can carry: the PBR set plus cut-out coverage. */
+export type LibraryMapRole = "color" | "normal" | "roughness" | "ao" | "opacity";
+/** Resolve a library name; unknown names return `null` so a caller can report them by name. */
+export declare function findLibraryMaterial(name: string): LibraryMaterial | null;
+/** Every library name, in authored order. */
+export declare function libraryMaterialNames(): readonly string[];
+/** Map roles the pinned archive of `entry` actually ships, from its catalog source declaration. */
+export declare function libraryMaterialRoles(entry: LibraryMaterial): readonly LibraryMapRole[];
+/** Options for {@link libraryMaterialMaps} and {@link libraryMaterialAsset}. */
+export interface LibraryMaterialOptions {
+    /** URL prefix `assets pull` writes under; defaults to `/materials`. */
+    basePath?: string;
+    /** How one texture tile is projected: authored UVs, or world-space triplanar for geometry without UVs. */
+    projection?: "uv" | "triplanar";
+}
+/**
+ * Serialized runtime map URLs for a library material, matching what `assets pull <source>` writes
+ * into `<basePath>/<source-id>/`. Roles the archive does not ship are omitted, never invented.
+ */
+export declare function libraryMaterialMaps(entry: LibraryMaterial, options?: LibraryMaterialOptions): Partial<Record<MaterialTextureRole, MaterialTextureMetadata>>;
+/**
+ * Build the editable, serializable material asset for a library name: maps, response and
+ * CC0 attribution in one value the editor can save into `editor.scene.json` and the shell renders.
+ * `projection` records whether those maps should sample authored UVs or world-space triplanar.
+ */
+export declare function libraryMaterialAsset(name: string, options?: LibraryMaterialOptions): MaterialAsset;
+/**
+ * Filter the library for a picker: case-insensitive match on name, title, group or source.
+ * Empty query returns everything, so a browser can render the full library first.
+ */
+export declare function filterLibraryMaterials(query: string, group?: LibraryGroup): readonly LibraryMaterial[];

package/dist/catalogs/materialLibrary.js

@@ -0,0 +1,173 @@
+import { MATERIAL_TEXTURE_SEMANTICS, materialCapabilitiesForAsset, validateMaterialAsset, } from "@jgengine/core/material/materialAsset";
+import { MATERIAL_MAP_FILES } from "../materialMapFiles.js";
+import { sourceById } from "../sources/index.js";
+const MATTE = { metalness: 0, roughness: 0.85 };
+/**
+ * The shared library: 40+ ambientCG PBR materials plus the glass and water surfaces that need a
+ * shader rather than a scan. `satisfies` keeps every entry complete, so a missing tile size or
+ * response is a type error instead of a silently grey surface.
+ */
+export const MATERIAL_LIBRARY = [
+    // Asphalt and road — wet asphalt is the same scan with a low roughness, not a second download.
+    { name: "asphalt/wet", title: "Wet asphalt", group: "asphalt", source: "ambientcg-asphalt025c", surface: "opaque", tileMetres: 4, response: { metalness: 0, roughness: 0.34, color: "#8f9498" } },
+    { name: "asphalt/dry", title: "Dry asphalt", group: "asphalt", source: "ambientcg-asphalt003", surface: "opaque", tileMetres: 4, response: { metalness: 0, roughness: 0.82 } },
+    { name: "asphalt/patch", title: "Patched asphalt", group: "asphalt", source: "ambientcg-asphalt021", surface: "opaque", tileMetres: 3.2, response: { metalness: 0, roughness: 0.74 } },
+    { name: "road/tarmac", title: "Tarmac road", group: "asphalt", source: "ambientcg-road001", surface: "opaque", tileMetres: 6, response: { metalness: 0, roughness: 0.7 } },
+    { name: "road/marked", title: "Marked road", group: "asphalt", source: "ambientcg-road008a", surface: "opaque", tileMetres: 8, response: { metalness: 0, roughness: 0.62 } },
+    // Concrete.
+    { name: "concrete/smooth", title: "Smooth concrete", group: "concrete", source: "ambientcg-concrete006", surface: "opaque", tileMetres: 3, response: { metalness: 0, roughness: 0.78 } },
+    { name: "concrete/poured", title: "Poured concrete", group: "concrete", source: "ambientcg-concrete013", surface: "opaque", tileMetres: 3.5, response: { metalness: 0, roughness: 0.88 } },
+    { name: "concrete/rough", title: "Rough concrete", group: "concrete", source: "ambientcg-concrete025", surface: "opaque", tileMetres: 2.6, response: { metalness: 0, roughness: 0.94 } },
+    // Stucco and plaster.
+    { name: "stucco/painted", title: "Painted stucco", group: "stucco", source: "ambientcg-paintedplaster006", surface: "opaque", tileMetres: 2.2, response: { metalness: 0, roughness: 0.9 } },
+    { name: "stucco/warm", title: "Warm stucco", group: "stucco", source: "ambientcg-paintedplaster010", surface: "opaque", tileMetres: 2.2, response: { metalness: 0, roughness: 0.88 } },
+    { name: "plaster/interior", title: "Interior plaster", group: "stucco", source: "ambientcg-plaster001", surface: "opaque", tileMetres: 2, response: { metalness: 0, roughness: 0.92 } },
+    // Brick.
+    { name: "brick/red", title: "Red brick", group: "brick", source: "ambientcg-bricks004", surface: "opaque", tileMetres: 1.6, response: { metalness: 0, roughness: 0.86 } },
+    { name: "brick/painted", title: "Painted brick", group: "brick", source: "ambientcg-paintedbricks002", surface: "opaque", tileMetres: 1.6, response: { metalness: 0, roughness: 0.8 } },
+    { name: "brick/whitewash", title: "Whitewashed brick", group: "brick", source: "ambientcg-paintedbricks005", surface: "opaque", tileMetres: 1.6, response: { metalness: 0, roughness: 0.84 } },
+    // Tile, paving and roof.
+    { name: "tile/ceramic", title: "Ceramic tile", group: "tile", source: "ambientcg-tiles007", surface: "opaque", tileMetres: 1.2, response: { metalness: 0, roughness: 0.32 } },
+    { name: "paving/stone", title: "Stone paving", group: "tile", source: "ambientcg-pavingstones002", surface: "opaque", tileMetres: 2.4, response: { metalness: 0, roughness: 0.83 } },
+    { name: "paving/sett", title: "Setts", group: "tile", source: "ambientcg-pavingstones020", surface: "opaque", tileMetres: 1.8, response: { metalness: 0, roughness: 0.8 } },
+    { name: "roof/tiles", title: "Roof tiles", group: "tile", source: "ambientcg-roofingtiles006", surface: "opaque", tileMetres: 1.4, response: { metalness: 0, roughness: 0.78 } },
+    // Metal.
+    { name: "metal/painted", title: "Painted metal", group: "metal", source: "ambientcg-paintedmetal006", surface: "opaque", tileMetres: 1.2, response: { metalness: 0.75, roughness: 0.44 } },
+    { name: "metal/chipped", title: "Chipped paint", group: "metal", source: "ambientcg-paintedmetal002", surface: "opaque", tileMetres: 1, response: { metalness: 0.8, roughness: 0.5 } },
+    { name: "metal/steel", title: "Bare steel", group: "metal", source: "ambientcg-metal007", surface: "opaque", tileMetres: 1, response: { metalness: 0.95, roughness: 0.42 } },
+    { name: "metal/brushed", title: "Brushed metal", group: "metal", source: "ambientcg-metal032", surface: "opaque", tileMetres: 1, response: { metalness: 1, roughness: 0.3 } },
+    { name: "metal/corrugated", title: "Corrugated steel", group: "metal", source: "ambientcg-corrugatedsteel009", surface: "opaque", tileMetres: 2, response: { metalness: 0.9, roughness: 0.55 } },
+    { name: "metal/diamond-plate", title: "Diamond plate", group: "metal", source: "ambientcg-diamondplate005a", surface: "opaque", tileMetres: 1.2, response: { metalness: 0.92, roughness: 0.38 } },
+    { name: "metal/rust", title: "Rusted metal", group: "metal", source: "ambientcg-rust007", surface: "opaque", tileMetres: 1.4, response: { metalness: 0.35, roughness: 0.88 } },
+    { name: "metal/plate", title: "Steel plate", group: "metal", source: "ambientcg-metalplates001", surface: "opaque", tileMetres: 1.6, response: { metalness: 0.85, roughness: 0.5 } },
+    // Wood.
+    { name: "wood/oak", title: "Oak", group: "wood", source: "ambientcg-wood026", surface: "opaque", tileMetres: 1.4, response: { metalness: 0, roughness: 0.66 } },
+    { name: "wood/floor", title: "Wood floor", group: "wood", source: "ambientcg-woodfloor009", surface: "opaque", tileMetres: 1.8, response: { metalness: 0, roughness: 0.46 } },
+    { name: "wood/deck", title: "Deck planks", group: "wood", source: "ambientcg-planks003", surface: "opaque", tileMetres: 1.6, response: { metalness: 0, roughness: 0.75 } },
+    { name: "wood/painted", title: "Painted wood", group: "wood", source: "ambientcg-paintedwood006a", surface: "opaque", tileMetres: 1.2, response: { metalness: 0, roughness: 0.6 } },
+    { name: "wood/siding", title: "Wood siding", group: "wood", source: "ambientcg-woodsiding005", surface: "opaque", tileMetres: 1.4, response: { metalness: 0, roughness: 0.72 } },
+    { name: "wood/bark", title: "Tree bark", group: "wood", source: "ambientcg-bark002", surface: "opaque", tileMetres: 1, response: { metalness: 0, roughness: 0.92 } },
+    // Foliage — cut-out cards over a warm, backlit response.
+    { name: "foliage/leaf", title: "Leaf card", group: "foliage", source: "ambientcg-leaf001", surface: "foliage", tileMetres: 0.8, response: { metalness: 0, roughness: 0.55, alphaMode: "mask", alphaCutoff: 0.45, doubleSided: true, sheen: 0.6, sheenColor: "#c8d18a", sheenRoughness: 0.7 } },
+    { name: "foliage/leaf-dense", title: "Dense leaf card", group: "foliage", source: "ambientcg-leaf003", surface: "foliage", tileMetres: 1, response: { metalness: 0, roughness: 0.6, alphaMode: "mask", alphaCutoff: 0.45, doubleSided: true, sheen: 0.55, sheenColor: "#b9cc7d", sheenRoughness: 0.75 } },
+    { name: "foliage/grass", title: "Grass ground", group: "foliage", source: "ambientcg-grass001", surface: "opaque", tileMetres: 2, response: { metalness: 0, roughness: 0.9 } },
+    { name: "foliage/grass-dry", title: "Dry grass", group: "foliage", source: "ambientcg-grass004", surface: "opaque", tileMetres: 2, response: { metalness: 0, roughness: 0.92 } },
+    { name: "foliage/moss", title: "Moss", group: "foliage", source: "ambientcg-moss001", surface: "opaque", tileMetres: 1.2, response: { metalness: 0, roughness: 0.95 } },
+    { name: "foliage/leaf-litter", title: "Leaf litter", group: "foliage", source: "ambientcg-scatteredleaves008", surface: "opaque", tileMetres: 2.4, response: { metalness: 0, roughness: 0.88 } },
+    // Ground and nature.
+    { name: "ground/dirt", title: "Forest floor", group: "ground", source: "ambientcg-ground037", surface: "opaque", tileMetres: 2.4, response: { metalness: 0, roughness: 0.9 } },
+    { name: "ground/sand", title: "Beach sand", group: "ground", source: "ambientcg-ground055s", surface: "opaque", tileMetres: 2, response: { metalness: 0, roughness: 0.88 } },
+    { name: "ground/sand-dark", title: "Dark sand", group: "ground", source: "ambientcg-ground080", surface: "opaque", tileMetres: 2, response: { metalness: 0, roughness: 0.86 } },
+    { name: "ground/mud", title: "Wet mud", group: "ground", source: "ambientcg-ground095b", surface: "opaque", tileMetres: 2, response: { metalness: 0, roughness: 0.52 } },
+    { name: "ground/gravel", title: "Gravel", group: "ground", source: "ambientcg-gravel002", surface: "opaque", tileMetres: 1.6, response: { metalness: 0, roughness: 0.88 } },
+    { name: "ground/rock", title: "Rock face", group: "ground", source: "ambientcg-rock022", surface: "opaque", tileMetres: 3, response: { metalness: 0, roughness: 0.86 } },
+    { name: "ground/ice", title: "Ice", group: "ground", source: "ambientcg-ice001", surface: "opaque", tileMetres: 1.8, response: { metalness: 0, roughness: 0.18 } },
+    { name: "ground/snow", title: "Snow", group: "ground", source: "ambientcg-snow006", surface: "opaque", tileMetres: 2.4, response: { metalness: 0, roughness: 0.72 } },
+    // Fabric, plastic and stone fittings.
+    { name: "fabric/canvas", title: "Canvas", group: "fabric", source: "ambientcg-fabric007", surface: "opaque", tileMetres: 1, response: { ...MATTE } },
+    { name: "fabric/weave", title: "Woven fabric", group: "fabric", source: "ambientcg-fabric009", surface: "opaque", tileMetres: 0.8, response: { metalness: 0, roughness: 0.82, sheen: 0.3, sheenColor: "#ffffff", sheenRoughness: 0.8 } },
+    { name: "plastic/matte", title: "Matte plastic", group: "fabric", source: "ambientcg-plastic006", surface: "opaque", tileMetres: 0.8, response: { metalness: 0, roughness: 0.5 } },
+    { name: "stone/marble", title: "Marble", group: "stone", source: "ambientcg-marble001", surface: "opaque", tileMetres: 1.8, response: { metalness: 0, roughness: 0.22 } },
+    { name: "stone/terrazzo", title: "Terrazzo", group: "stone", source: "ambientcg-terrazzo005", surface: "opaque", tileMetres: 1.6, response: { metalness: 0, roughness: 0.3 } },
+    // Glass: transmission and roughness carry the look. The smudged variant adds a scanned
+    // fingerprint normal so glass is not a mathematically clean sheet.
+    { name: "glass/clear", title: "Clear glass", group: "glass", surface: "glass", tileMetres: 2, response: { metalness: 0, roughness: 0.03, transmission: 1, ior: 1.52, thickness: 0.01, alphaMode: "opaque" } },
+    { name: "glass/frosted", title: "Frosted glass", group: "glass", surface: "glass", tileMetres: 2, response: { metalness: 0, roughness: 0.42, transmission: 1, ior: 1.52, thickness: 0.01, alphaMode: "opaque" } },
+    { name: "glass/smudged", title: "Smudged glass", group: "glass", source: "ambientcg-fingerprints001", surface: "glass", tileMetres: 0.7, response: { metalness: 0, roughness: 0.12, transmission: 1, ior: 1.52, thickness: 0.01, alphaMode: "opaque" } },
+    // Water: the shell's ocean/puddle shader owns ripples; these entries carry the response and the
+    // depth tint so a game selects water by name like any other surface.
+    { name: "water/ocean", title: "Ocean water", group: "water", surface: "water", tileMetres: 8, response: { metalness: 0.02, roughness: 0.05, alphaMode: "opaque" } },
+    { name: "water/puddle", title: "Puddle", group: "water", surface: "water", tileMetres: 3, response: { metalness: 0, roughness: 0.06, alphaMode: "opaque" } },
+];
+const byName = new Map(MATERIAL_LIBRARY.map((entry) => [entry.name, entry]));
+/** Every readable map role a library material can carry, in load order. */
+const LIBRARY_ROLES = ["color", "normal", "roughness", "ao", "opacity"];
+/** Resolve a library name; unknown names return `null` so a caller can report them by name. */
+export function findLibraryMaterial(name) {
+    return byName.get(name) ?? null;
+}
+/** Every library name, in authored order. */
+export function libraryMaterialNames() {
+    return MATERIAL_LIBRARY.map((entry) => entry.name);
+}
+/** Map roles the pinned archive of `entry` actually ships, from its catalog source declaration. */
+export function libraryMaterialRoles(entry) {
+    if (entry.source === undefined)
+        return [];
+    const source = sourceById.get(entry.source);
+    if (source === undefined)
+        return [];
+    return LIBRARY_ROLES.filter((role) => source.materialMaps?.includes(role) === true);
+}
+/**
+ * Serialized runtime map URLs for a library material, matching what `assets pull <source>` writes
+ * into `<basePath>/<source-id>/`. Roles the archive does not ship are omitted, never invented.
+ */
+export function libraryMaterialMaps(entry, options = {}) {
+    const base = `${(options.basePath ?? "/materials").replace(/\/+$/, "")}/${entry.source ?? ""}`;
+    const source = entry.source === undefined ? undefined : sourceById.get(entry.source);
+    const textures = {};
+    for (const role of libraryMaterialRoles(entry)) {
+        const target = role === "opacity" ? "alpha" : role;
+        textures[target] = {
+            url: `${base}/${MATERIAL_MAP_FILES[role]}`,
+            colorSpace: MATERIAL_TEXTURE_SEMANTICS[target].colorSpace,
+            channel: MATERIAL_TEXTURE_SEMANTICS[target].channel,
+            physicalSize: [entry.tileMetres, entry.tileMetres],
+            ...(role === "normal" ? { normalConvention: "opengl" } : {}),
+            sampler: { anisotropy: 8 },
+            ...(source === undefined
+                ? {}
+                : { provenance: { author: source.author, license: source.license, ...(source.homepage === undefined ? {} : { sourceUrl: source.homepage }) } }),
+        };
+    }
+    return textures;
+}
+/**
+ * Build the editable, serializable material asset for a library name: maps, response and
+ * CC0 attribution in one value the editor can save into `editor.scene.json` and the shell renders.
+ * `projection` records whether those maps should sample authored UVs or world-space triplanar.
+ */
+export function libraryMaterialAsset(name, options = {}) {
+    const entry = findLibraryMaterial(name);
+    if (entry === null)
+        throw new TypeError(`Unknown library material "${name}"`);
+    const source = entry.source === undefined ? undefined : sourceById.get(entry.source);
+    if (entry.source !== undefined && source === undefined)
+        throw new TypeError(`Library material "${name}" names unknown source "${entry.source}"`);
+    const textures = libraryMaterialMaps(entry, options);
+    const id = `library/${entry.name.replace(/\//g, "-")}`;
+    const asset = {
+        schemaVersion: 1,
+        id,
+        name: entry.title,
+        family: entry.surface === "glass" ? "glass" : "standard",
+        surface: { ...entry.response },
+        capabilities: materialCapabilitiesForAsset({ surface: entry.response, textures }),
+        provenance: {
+            author: source?.author ?? "ambientCG",
+            license: source?.license ?? "CC0-1.0",
+            ...(source?.homepage === undefined ? {} : { sourceUrl: source.homepage }),
+            description: `ambientCG ${source === undefined ? entry.name : source.title.replace(/ \(PBR material\)$/, "")} 1K-JPG PBR maps, selected by the shared jgengine material library.`,
+        },
+        ...(Object.keys(textures).length === 0 ? {} : { textures }),
+    };
+    const errors = validateMaterialAsset(asset).filter((diagnostic) => diagnostic.severity === "error");
+    if (errors.length > 0)
+        throw new TypeError(`${errors[0].path}: ${errors[0].message}`);
+    return asset;
+}
+/**
+ * Filter the library for a picker: case-insensitive match on name, title, group or source.
+ * Empty query returns everything, so a browser can render the full library first.
+ */
+export function filterLibraryMaterials(query, group) {
+    const needle = query.trim().toLowerCase();
+    return MATERIAL_LIBRARY.filter((entry) => {
+        if (group !== undefined && entry.group !== group)
+            return false;
+        if (needle.length === 0)
+            return true;
+        return `${entry.name} ${entry.title} ${entry.group} ${entry.source ?? ""}`.toLowerCase().includes(needle);
+    });
+}

package/dist/cli/pull.js

@@ -4,6 +4,7 @@ import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFi
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createAssetBudgetReport } from "../assetBudget.js";
+import { MATERIAL_LIBRARY } from "../catalogs/materialLibrary.js";
 import { downloadPackArchive, extractGlbs, extractSpriteFiles } from "../download.js";
 import { rankAssets } from "../find.js";
 import { generatedIndex } from "../generated/index.js";
@@ -144,6 +145,19 @@ export async function cmdPull(argv) {
         console.log(`starter: ${STARTER_SOURCE_PACKS.length} pack(s) ready`);
         return;
     }
+    // `library` pulls every map the shared material library pins, so one command gives a game the
+    // surfaces its names resolve to (roughly 360 MB of 1K-JPG archives for the whole set).
+    if (sourceId === "library") {
+        const pulled = new Set();
+        for (const entry of MATERIAL_LIBRARY) {
+            if (entry.source === undefined || pulled.has(entry.source))
+                continue;
+            pulled.add(entry.source);
+            await cmdPull([entry.source, ...argv.slice(1)]);
+        }
+        console.log(`library: ${pulled.size} material(s) ready`);
+        return;
+    }
     const source = sourceById.get(sourceId);
     if (source === undefined)
         fail(`unknown source: ${sourceId}`);

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export { generatedIndex, generatedBySource } from "./generated/index.js";
 export { generatedSpriteIndex, generatedSpriteBySource } from "./generated-sprites/index.js";
 export { readGlbDims } from "./dims.js";
 export { buildCatalog, entryUrl, type BuildCatalogOptions } from "./catalogs/build.js";
+export { MATERIAL_LIBRARY, filterLibraryMaterials, findLibraryMaterial, libraryMaterialAsset, libraryMaterialMaps, libraryMaterialNames, libraryMaterialRoles, type LibraryGroup, type LibraryMaterial, type LibraryMaterialOptions, type LibrarySurface, } from "./catalogs/materialLibrary.js";
 export { classifyAssetFile, validateImportSpec, type AssetImportKind, type AssetImportSpec, type ImportSpecValidation } from "./importSpec.js";
 export { buildSpriteCatalog, type BuildSpriteCatalogOptions } from "./catalogs/buildSprites.js";
 export { createStarterCatalog } from "./catalogs/starter.js";

package/dist/index.js

@@ -9,6 +9,7 @@ export { generatedIndex, generatedBySource } from "./generated/index.js";
 export { generatedSpriteIndex, generatedSpriteBySource } from "./generated-sprites/index.js";
 export { readGlbDims } from "./dims.js";
 export { buildCatalog, entryUrl } from "./catalogs/build.js";
+export { MATERIAL_LIBRARY, filterLibraryMaterials, findLibraryMaterial, libraryMaterialAsset, libraryMaterialMaps, libraryMaterialNames, libraryMaterialRoles, } from "./catalogs/materialLibrary.js";
 export { classifyAssetFile, validateImportSpec } from "./importSpec.js";
 export { buildSpriteCatalog } from "./catalogs/buildSprites.js";
 export { createStarterCatalog } from "./catalogs/starter.js";

package/dist/materialMapFiles.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Normalized filenames a pulled material directory contains, keyed by map role. Kept in its own
+ * module so catalogs and editors can name a pulled file without loading the archive reader.
+ */
+export declare const MATERIAL_MAP_FILES: {
+    readonly color: "color.jpg";
+    readonly normal: "normal.jpg";
+    readonly roughness: "roughness.jpg";
+    readonly ao: "ao.jpg";
+    readonly opacity: "opacity.jpg";
+    readonly displacement: "displacement.jpg";
+    readonly ktx2: "material.ktx2";
+};
+/** One PBR map's role within a material, including an optional compressed KTX2 asset. */
+export type MaterialMapRole = keyof typeof MATERIAL_MAP_FILES;

package/dist/materialMapFiles.js

@@ -0,0 +1,13 @@
+/**
+ * Normalized filenames a pulled material directory contains, keyed by map role. Kept in its own
+ * module so catalogs and editors can name a pulled file without loading the archive reader.
+ */
+export const MATERIAL_MAP_FILES = {
+    color: "color.jpg",
+    normal: "normal.jpg",
+    roughness: "roughness.jpg",
+    ao: "ao.jpg",
+    opacity: "opacity.jpg",
+    displacement: "displacement.jpg",
+    ktx2: "material.ktx2",
+};

package/dist/materials.d.ts

@@ -1,15 +1,6 @@
 import type { AssetAlias } from "./manifest.js";
-/** Normalized filenames a pulled material directory contains, keyed by map role. */
-export declare const MATERIAL_MAP_FILES: {
-    readonly color: "color.jpg";
-    readonly normal: "normal.jpg";
-    readonly roughness: "roughness.jpg";
-    readonly ao: "ao.jpg";
-    readonly displacement: "displacement.jpg";
-    readonly ktx2: "material.ktx2";
-};
-/** One PBR map's role within a material, including an optional compressed KTX2 asset. */
-export type MaterialMapRole = keyof typeof MATERIAL_MAP_FILES;
+import { type MaterialMapRole } from "./materialMapFiles.js";
+export { MATERIAL_MAP_FILES, type MaterialMapRole } from "./materialMapFiles.js";
 /** One normalized map pulled out of a material archive by `extractMaterialMaps`. */
 export interface ExtractedMaterialMap {
     /** Normalized output filename (`color.jpg`, `normal.jpg`, …). */
@@ -23,12 +14,14 @@ export interface ExtractedMaterialMap {
  * URLs never depend on the provider's naming or the pulled resolution.
  */
 export declare function extractMaterialMaps(archive: Uint8Array): ExtractedMaterialMap[];
-/** URLs of one material's PBR maps; `ao`/`roughness`/`ktx2` appear only when declared by its source. */
+/** URLs of one material's PBR maps; `ao`/`roughness`/`opacity`/`ktx2` appear only when declared by its source. */
 export interface MaterialMaps {
     color: string;
     normal: string;
     roughness?: string;
     ao?: string;
+    /** Cut-out coverage map, present on foliage and decal-style scans. */
+    opacity?: string;
     displacement: string;
     ktx2?: string;
 }

package/dist/materials.js

@@ -1,19 +1,13 @@
 import { unzipSync } from "fflate";
+import { MATERIAL_MAP_FILES } from "./materialMapFiles.js";
 import { materialSources, sourceById } from "./sources/index.js";
-/** Normalized filenames a pulled material directory contains, keyed by map role. */
-export const MATERIAL_MAP_FILES = {
-    color: "color.jpg",
-    normal: "normal.jpg",
-    roughness: "roughness.jpg",
-    ao: "ao.jpg",
-    displacement: "displacement.jpg",
-    ktx2: "material.ktx2",
-};
+export { MATERIAL_MAP_FILES } from "./materialMapFiles.js";
 const MAP_SUFFIXES = [
     { role: "color", pattern: /_Color\.(jpe?g|png)$/i },
     { role: "normal", pattern: /_NormalGL\.(jpe?g|png)$/i },
     { role: "roughness", pattern: /_Roughness\.(jpe?g|png)$/i },
     { role: "ao", pattern: /_AmbientOcclusion\.(jpe?g|png)$/i },
+    { role: "opacity", pattern: /_Opacity\.(jpe?g|png)$/i },
     { role: "displacement", pattern: /_Displacement\.(jpe?g|png)$/i },
 ];
 /**
@@ -67,6 +61,7 @@ function refFor(source, basePath) {
             normal: `${base}/${MATERIAL_MAP_FILES.normal}`,
             ...(source.materialMaps?.includes("roughness") ? { roughness: `${base}/${MATERIAL_MAP_FILES.roughness}` } : {}),
             ...(source.materialMaps?.includes("ao") ? { ao: `${base}/${MATERIAL_MAP_FILES.ao}` } : {}),
+            ...(source.materialMaps?.includes("opacity") ? { opacity: `${base}/${MATERIAL_MAP_FILES.opacity}` } : {}),
             displacement: `${base}/${MATERIAL_MAP_FILES.displacement}`,
             ...(source.materialMaps?.includes("ktx2") ? { ktx2: `${base}/${MATERIAL_MAP_FILES.ktx2}` } : {}),
         },

package/dist/sources/ambientcg.d.ts

@@ -1,5 +1,11 @@
 import type { AssetSource } from "../manifest.js";
+/** Upstream asset id pinned to a material source id, so the reverse lookup never guesses a variant. */
+export declare const AMBIENTCG_PINNED_ASSET_IDS: ReadonlyMap<string, string>;
 /** Upstream asset id (`Grass001`) for a material source id (`ambientcg-grass001`). */
 export declare function ambientcgAssetId(source: AssetSource): string;
-/** Every ambientCG material source, generated per family (`ambientcg-grass001` … ). */
+/**
+ * Every ambientCG material source: the generated family sweep plus the pinned variants the shared
+ * library needs. A pinned id the family sweep already covers stays with the sweep, so catalog ids
+ * never appear twice.
+ */
 export declare const ambientcgSources: readonly AssetSource[];

package/dist/sources/ambientcg.js

@@ -40,8 +40,67 @@ const FAMILIES = [
     { family: "Paper", count: 3, categories: ["paper", "prop"], ao: [] },
     { family: "RoofingTiles", count: 8, categories: ["roof", "tile", "building"], ao: [6, 7, 8] },
 ];
+const PINNED = [
+    { assetId: "Asphalt003", categories: ["asphalt", "road", "urban"], maps: ["roughness", "ao"] },
+    { assetId: "Asphalt021", categories: ["asphalt", "road", "urban"], maps: ["roughness", "ao"] },
+    { assetId: "Asphalt025C", categories: ["asphalt", "road", "urban", "wet"], maps: ["roughness", "ao"] },
+    { assetId: "Road001", categories: ["road", "asphalt", "urban"], maps: ["roughness"] },
+    { assetId: "Road008A", categories: ["road", "asphalt", "urban", "marking"], maps: ["roughness", "ao"] },
+    { assetId: "Concrete006", categories: ["concrete", "urban"], maps: ["roughness", "ao"] },
+    { assetId: "Concrete013", categories: ["concrete", "urban"], maps: ["roughness", "ao"] },
+    { assetId: "Concrete025", categories: ["concrete", "urban"], maps: ["roughness", "ao"] },
+    { assetId: "PaintedPlaster006", categories: ["plaster", "stucco", "wall", "exterior"], maps: ["roughness", "ao"] },
+    { assetId: "PaintedPlaster010", categories: ["plaster", "stucco", "wall", "exterior"], maps: ["roughness", "ao"] },
+    { assetId: "Plaster001", categories: ["plaster", "stucco", "wall", "interior"], maps: ["roughness"] },
+    { assetId: "Bricks004", categories: ["brick", "wall"], maps: ["roughness", "ao"] },
+    { assetId: "PaintedBricks002", categories: ["brick", "wall", "painted"], maps: ["roughness", "ao"] },
+    { assetId: "PaintedBricks005", categories: ["brick", "wall", "painted"], maps: ["roughness", "ao"] },
+    { assetId: "Tiles007", categories: ["tile", "floor", "interior"], maps: ["roughness", "ao"] },
+    { assetId: "PavingStones002", categories: ["paving", "stone", "path"], maps: ["roughness", "ao"] },
+    { assetId: "PavingStones020", categories: ["paving", "stone", "path"], maps: ["roughness", "ao"] },
+    { assetId: "RoofingTiles006", categories: ["roof", "tile", "building"], maps: ["roughness", "ao"] },
+    { assetId: "PaintedMetal002", categories: ["metal", "painted", "prop"], maps: ["roughness", "opacity"] },
+    { assetId: "PaintedMetal006", categories: ["metal", "painted", "prop"], maps: ["roughness", "ao"] },
+    { assetId: "Metal007", categories: ["metal"], maps: ["roughness"] },
+    { assetId: "Metal032", categories: ["metal", "brushed"], maps: ["roughness"] },
+    { assetId: "CorrugatedSteel009", categories: ["metal", "corrugated", "industrial"], maps: ["roughness", "ao"] },
+    { assetId: "DiamondPlate005A", categories: ["metal", "industrial", "floor"], maps: ["roughness", "ao"] },
+    { assetId: "Rust007", categories: ["metal", "rust", "derelict"], maps: ["roughness", "ao"] },
+    { assetId: "MetalPlates001", categories: ["metal", "plates", "industrial"], maps: ["roughness"] },
+    { assetId: "Wood026", categories: ["wood", "planks"], maps: ["roughness"] },
+    { assetId: "WoodFloor009", categories: ["wood", "floor", "interior"], maps: ["roughness", "ao"] },
+    { assetId: "Planks003", categories: ["wood", "planks", "deck"], maps: ["roughness", "ao"] },
+    { assetId: "PaintedWood006A", categories: ["wood", "painted", "exterior"], maps: ["roughness", "ao"] },
+    { assetId: "WoodSiding005", categories: ["wood", "siding", "building"], maps: ["roughness", "ao"] },
+    { assetId: "Bark002", categories: ["bark", "wood", "nature"], maps: ["roughness", "ao"] },
+    { assetId: "Leaf001", categories: ["foliage", "leaf", "nature"], maps: ["roughness", "opacity", "ao"] },
+    { assetId: "Leaf003", categories: ["foliage", "leaf", "nature"], maps: ["roughness", "opacity", "ao"] },
+    { assetId: "Grass001", categories: ["ground", "grass", "nature"], maps: ["roughness", "ao"] },
+    { assetId: "Grass004", categories: ["ground", "grass", "nature"], maps: ["roughness", "ao"] },
+    { assetId: "Moss001", categories: ["moss", "nature"], maps: ["roughness", "ao"] },
+    { assetId: "ScatteredLeaves008", categories: ["foliage", "leaf", "ground"], maps: ["roughness", "ao"] },
+    { assetId: "Ground037", categories: ["ground", "dirt", "forest"], maps: ["roughness", "ao"] },
+    { assetId: "Ground055S", categories: ["ground", "sand", "beach"], maps: ["roughness", "ao"] },
+    { assetId: "Ground080", categories: ["ground", "sand", "beach"], maps: ["roughness", "ao"] },
+    { assetId: "Ground095B", categories: ["ground", "mud", "wet"], maps: ["roughness", "ao"] },
+    { assetId: "Gravel002", categories: ["ground", "gravel"], maps: ["roughness"] },
+    { assetId: "Rock022", categories: ["rock", "stone"], maps: ["roughness", "ao"] },
+    { assetId: "Ice001", categories: ["ice", "winter"], maps: ["roughness"] },
+    { assetId: "Snow006", categories: ["ground", "snow", "winter"], maps: ["roughness", "ao"] },
+    { assetId: "Fabric007", categories: ["fabric", "cloth"], maps: ["roughness", "ao"] },
+    { assetId: "Fabric009", categories: ["fabric", "cloth", "canvas"], maps: ["roughness", "ao"] },
+    { assetId: "Plastic006", categories: ["plastic"], maps: ["roughness"] },
+    { assetId: "Marble001", categories: ["marble", "stone", "interior"], maps: ["roughness"] },
+    { assetId: "Terrazzo005", categories: ["terrazzo", "floor", "interior"], maps: ["roughness"] },
+    { assetId: "Fingerprints001", categories: ["glass", "smudge", "overlay"], maps: ["roughness", "opacity"], displacement: false },
+];
+/** Upstream asset id pinned to a material source id, so the reverse lookup never guesses a variant. */
+export const AMBIENTCG_PINNED_ASSET_IDS = new Map(PINNED.map((entry) => [`ambientcg-${entry.assetId.toLowerCase()}`, entry.assetId]));
 /** Upstream asset id (`Grass001`) for a material source id (`ambientcg-grass001`). */
 export function ambientcgAssetId(source) {
+    const pinned = AMBIENTCG_PINNED_ASSET_IDS.get(source.id);
+    if (pinned !== undefined)
+        return pinned;
     const suffix = source.id.replace(/^ambientcg-/, "");
     const digits = suffix.match(/\d+$/)?.[0] ?? "";
     const family = FAMILIES.find((entry) => entry.family.toLowerCase() === suffix.slice(0, suffix.length - digits.length));
@@ -66,5 +125,35 @@ function materialSource(family, index) {
         homepage: `https://ambientcg.com/view?id=${assetId}`,
     };
 }
-/** Every ambientCG material source, generated per family (`ambientcg-grass001` … ). */
-export const ambientcgSources = FAMILIES.flatMap((family) => Array.from({ length: family.count }, (_, index) => materialSource(family, index + 1)));
+function pinnedSource(entry) {
+    const optional = entry.maps ?? ["roughness"];
+    return {
+        id: `ambientcg-${entry.assetId.toLowerCase()}`,
+        kind: "material",
+        provider: "ambientcg",
+        title: `${entry.assetId.replace(/(\d+)([A-Z]*)$/, " $1 $2").replace(/\s+/g, " ").trim()} (PBR material)`,
+        license: "CC0-1.0",
+        author: "ambientCG",
+        categories: entry.categories,
+        materialMaps: [
+            "color", "normal",
+            ...(entry.displacement === false ? [] : ["displacement"]),
+            ...(optional.includes("roughness") ? ["roughness"] : []),
+            ...(optional.includes("ao") ? ["ao"] : []),
+            ...(optional.includes("opacity") ? ["opacity"] : []),
+        ],
+        download: { url: `https://ambientcg.com/get?file=${entry.assetId}_${RESOLUTION}.zip` },
+        homepage: `https://ambientcg.com/view?id=${entry.assetId}`,
+    };
+}
+const generatedSources = FAMILIES.flatMap((family) => Array.from({ length: family.count }, (_, index) => materialSource(family, index + 1)));
+const generatedIds = new Set(generatedSources.map((source) => source.id));
+/**
+ * Every ambientCG material source: the generated family sweep plus the pinned variants the shared
+ * library needs. A pinned id the family sweep already covers stays with the sweep, so catalog ids
+ * never appear twice.
+ */
+export const ambientcgSources = [
+    ...generatedSources,
+    ...PINNED.filter((entry) => !generatedIds.has(`ambientcg-${entry.assetId.toLowerCase()}`)).map(pinnedSource),
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/assets",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Self-generating, license-verified index of thousands of CC0 3D models for JGengine. Sources fetch from providers' own CDNs at pull time; the npm tarball ships only the typed index and CLI (no GLB bytes).",
   "license": "Apache-2.0",
   "type": "module",
@@ -38,7 +38,7 @@
     "@gltf-transform/core": "4.2.1",
     "@gltf-transform/extensions": "4.2.1",
     "@gltf-transform/functions": "4.2.1",
-    "@jgengine/core": "^0.25.0",
+    "@jgengine/core": "^0.27.0",
     "fflate": "^0.8.2"
   },
   "devDependencies": {

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.25.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.27.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -82,25 +82,42 @@
 - `Devtools` (interface): interface Devtools — Top-level devtools facade aggregating frame, profile, render, logs, latency, controls, discover, overrides, and probes.
 - `DevtoolsControl` (interface): interface DevtoolsControl — Registered tunable control with its resolved schema metadata and read/write/reset accessors.
 - `DevtoolsControlKind` (type): type DevtoolsControlKind = | "slider" | "toggle" | "color" | "select" | "text" | "vec2" | "vec3" | "vec4" | "interval" | "angle" | "enum" — ⚠ undocumented
-- `DevtoolsLogEntry` (interface): interface DevtoolsLogEntry — A single captured log line with timestamp, level, and formatted message.
+- `DevtoolsLogEntry` (interface): interface DevtoolsLogEntry — A single captured log line with timestamp, level, owning system tag, and formatted message.
 - `DevtoolsLogLevel` (type): type DevtoolsLogLevel = "log" | "info" | "warn" | "error" — Severity level for a captured devtools log entry.
+- `DevtoolsLogs` (interface): interface DevtoolsLogs — Bounded log ring with per-system tags, a warning/error ring, and lifetime counts.
 - `DevtoolsOverrides` (interface): interface DevtoolsOverrides { version: number; enabled: string[]; values: Record<string, unknown>; schemas?: Record<string, {kind: DevtoolsControlKind; schemaVersion?: number}> } — ⚠ undocumented
 - `DevtoolsSnapshot` (interface): interface DevtoolsSnapshot — Serializable point-in-time snapshot of devtools state: frame, render, latency, logs, controls, and discovered fields.
 - `DiscoveredEntry` (interface): interface DiscoveredEntry — A control auto-discovered by scanning an object/table, with its binding metadata and current reader.
 - `DiscoverySkip` (interface): interface DiscoverySkip { readonly path: string; readonly reason: string } — ⚠ undocumented
 - `FrameRecordSample` (interface): interface FrameRecordSample — Per-frame timing input recorded by callers: total frame time, sim time, and optional named phase durations.
 - `FrameStats` (interface): interface FrameStats — Aggregated frame-timing statistics over the recent sampling window, including per-phase breakdown.
-- `LONG_FRAME_MS` (const): const LONG_FRAME_MS: 33.4 — Frame duration in milliseconds above which a frame is recorded as a long-frame spike (~30fps budget).
+- `FrameWindow` (interface): interface FrameWindow — Frame timings over the measured window, as the player sees them.
+- `GlReport` (interface): interface GlReport — GPU-object creation counts. `total` is since the page loaded, the named fields since warmup.
+- `LONG_FRAME_MS` (const): const LONG_FRAME_MS: 33.4 — The one perf record shape. `bun run perf` (CDP, out of process) and the in-page telemetry report (`window.__JG.report()`, the dev-server route, `bun run debug`) both produce exactly this object, so a budget check and a diff read either one.
 - `LatencyStats` (interface): interface LatencyStats — Aggregated latency statistics (last/avg/min/max) over recorded latency samples.
+- `LogBusCounts` (interface): interface LogBusCounts — Lifetime totals per level, plus how many lines the ring dropped.
+- `LogBusEntry` (interface): interface LogBusEntry — One captured line: when, how bad, which system said it, and what it said.
+- `LogBusSnapshot` (interface): interface LogBusSnapshot — Read-out of the log bus: newest-window entries, the warning/error ring, totals, and evictions.
 - `LongFrameEvent` (interface): interface LongFrameEvent — Recorded spike event for a frame that exceeded the long-frame threshold, with culprit attribution.
 - `NormalizedColor` (interface): interface NormalizedColor { readonly hex: string; readonly rgb: string; readonly alpha: number; readonly hasAlpha: boolean } — ⚠ undocumented
 - `OVERRIDES_FORMAT_VERSION` (const): const OVERRIDES_FORMAT_VERSION: 1 — ⚠ undocumented
 - `OverrideApplyDiagnostic` (interface): interface OverrideApplyDiagnostic { readonly id: string; readonly reason: string } — ⚠ undocumented
 - `OverrideApplyResult` (interface): interface OverrideApplyResult — Outcome of applying a devtools overrides payload: counts of applied and skipped entries plus diagnostics.
+- `PerfQuality` (type): type PerfQuality = "full" | "draft" — Graphics tier the record was measured at.
+- `PerfReport` (interface): interface PerfReport — One measured window of one game: the record `bun run perf`, `window.__JG.report()` and `bun run debug` print.
 - `PhaseStats` (interface): interface PhaseStats — Timing summary for a single named profiling phase across the sampling window.
+- `ProfileEntry` (interface): interface ProfileEntry — One sampled stack frame reduced to a readable key and its self time.
+- `ProfileReport` (interface): interface ProfileReport — CPU profile summary; only the CDP harness can produce one.
+- `RenderReport` (interface): interface RenderReport — Renderer-side counts for the measured window; `null` where the source could not read them.
 - `RenderSample` (interface): interface RenderSample — Snapshot of renderer resource counts (draw calls, triangles, geometries, textures) for a frame.
+- `ReportLogLine` (interface): interface ReportLogLine — One log line as it appears in the report.
+- `ReportLogs` (interface): interface ReportLogs — Bounded log read-out carried by the report: warn/error lines survive even a flood of info logs.
+- `ReportTelemetry` (interface): interface ReportTelemetry — Who produced the report, and how much producing it cost.
 - `ScanFieldMeta` (interface): interface ScanFieldMeta extends TunableOptions { kind?: DevtoolsControlKind } — ⚠ undocumented
 - `ScanMeta` (type): type ScanMeta = Readonly<Record<string, ScanFieldMeta>> — ⚠ undocumented
+- `SceneNodeSource` (type): type SceneNodeSource = "scene-graph" | "heap-object3d" | "unavailable" — Where the scene-node count came from: the live scene graph, a heap walk, or nowhere.
+- `SystemProbe` (interface): interface SystemProbe — What one system reports about itself: totals it keeps anyway, named timings, and one state line.
+- `SystemProbeReading` (interface): interface SystemProbeReading — One system's probe read out on demand; missing sections stay empty rather than absent.
 - `Tunable` (interface): interface Tunable<T> — Typed handle to a registered control, exposing its live value and subscribe/set/reset operations.
 - `TunableAccessor` (interface): interface TunableAccessor — Get/set accessor pair plus initial value used to bind a discovered field to a control.
 - `TunableChoice` (interface): interface TunableChoice<T = unknown> { readonly value: T; readonly label?: string } — ⚠ undocumented
@@ -139,9 +156,20 @@
 ## @jgengine/core/devtools/frame
 
 - `FrameModule` (interface): interface FrameModule — Frame subsystem exposing the frame-timing, profiling, and render-sample facades.
-- `LONG_FRAME_MS` (const): const LONG_FRAME_MS: 33.4 — Frame duration in milliseconds above which a frame is recorded as a long-frame spike (~30fps budget).
 - `createFrameModule` (const): const createFrameModule: (deps: { readProbes: () => Record<string, unknown>; }) => FrameModule — Create the frame subsystem that records frame/sim/phase timings, computes stats, and captures long-frame events.
 
+## @jgengine/core/devtools/logBus
+
+- `LOG_BUS_CAPACITY` (const): const LOG_BUS_CAPACITY: 200 — Default measured window for the log ring; older lines are evicted, never grown.
+- `LOG_BUS_MESSAGE_MAX` (const): const LOG_BUS_MESSAGE_MAX: 400 — Longest kept message; a longer one is cut once, at write time.
+- `LOG_BUS_SEVERE_CAPACITY` (const): const LOG_BUS_SEVERE_CAPACITY: 64 — Warnings and errors also land in their own ring, so an error is never pushed out by info traffic.
+- `LogBus` (interface): interface LogBus — A fixed-capacity ring of log lines tagged by owning system. `write` reuses a preallocated slot — no array growth, no splice, no per-write object — so a hot path can call it and only the message string (already built by the caller) costs an allocation.
+- `LogBusCounts` (interface): interface LogBusCounts — Lifetime totals per level, plus how many lines the ring dropped.
+- `LogBusEntry` (interface): interface LogBusEntry — One captured line: when, how bad, which system said it, and what it said.
+- `LogBusOptions` (interface): interface LogBusOptions — Tunables for the log ring: capacity, the severity ring's capacity, and the clock.
+- `LogBusSnapshot` (interface): interface LogBusSnapshot — Read-out of the log bus: newest-window entries, the warning/error ring, totals, and evictions.
+- `createLogBus` (function): function createLogBus(options: LogBusOptions = {}): LogBus — Create the bounded log bus the devtools log facade writes through.
+
 ## @jgengine/core/devtools/logs
 
 - `LogsModule` (interface): interface LogsModule — Logs subsystem exposing the log-capture and latency-tracking facades.
@@ -153,6 +181,27 @@
 - `OverridesModule` (interface): interface OverridesModule — Overrides subsystem exposing the export/apply facade for persisting and restoring control values.
 - `createOverridesModule` (const): const createOverridesModule: (deps: { signal: ChangeSignal; controlRecords: Map<string, ControlRecord>; writeControl: (record: ControlRecord, raw: unknown) => boolean; discoveredRecords: Map<string, DiscoveredRecord>; enableDiscovered: (id: string) => void; }) => OverridesModule — Create the overrides subsystem that serializes changed control values and re-applies a saved overrides payload.
 
+## @jgengine/core/devtools/report
+
+- `FrameWindow` (interface): interface FrameWindow — Frame timings over the measured window, as the player sees them.
+- `GlReport` (interface): interface GlReport — GPU-object creation counts. `total` is since the page loaded, the named fields since warmup.
+- `LONG_FRAME_MS` (const): const LONG_FRAME_MS: 33.4 — The one perf record shape. `bun run perf` (CDP, out of process) and the in-page telemetry report (`window.__JG.report()`, the dev-server route, `bun run debug`) both produce exactly this object, so a budget check and a diff read either one.
+- `PerfQuality` (type): type PerfQuality = "full" | "draft" — Graphics tier the record was measured at.
+- `PerfReport` (interface): interface PerfReport — One measured window of one game: the record `bun run perf`, `window.__JG.report()` and `bun run debug` print.
+- `ProfileEntry` (interface): interface ProfileEntry — One sampled stack frame reduced to a readable key and its self time.
+- `ProfileReport` (interface): interface ProfileReport — CPU profile summary; only the CDP harness can produce one.
+- `RenderReport` (interface): interface RenderReport — Renderer-side counts for the measured window; `null` where the source could not read them.
+- `ReportLogLine` (interface): interface ReportLogLine — One log line as it appears in the report.
+- `ReportLogs` (interface): interface ReportLogs — Bounded log read-out carried by the report: warn/error lines survive even a flood of info logs.
+- `ReportTelemetry` (interface): interface ReportTelemetry — Who produced the report, and how much producing it cost.
+- `SceneNodeSource` (type): type SceneNodeSource = "scene-graph" | "heap-object3d" | "unavailable" — Where the scene-node count came from: the live scene graph, a heap walk, or nowhere.
+
+## @jgengine/core/devtools/reportEndpoint
+
+- `REPORT_ENDPOINT_PATH` (const): const REPORT_ENDPOINT_PATH: "/__jgengine/report" — The dev-only route a running game pushes its in-page report to, and that `bun run debug <game>` reads back. One process: the page gathers, the dev server holds the newest record per game, the CLI fetches it. Nothing here ships in a production build — the Vite plugin mounts it under `apply: "serve"`.
+- `ReportPushBody` (interface): interface ReportPushBody — Body the page POSTs: the game it measured and the record itself.
+- `ReportRouteError` (interface): interface ReportRouteError — Body sent when there is nothing to return yet.
+
 ## @jgengine/core/devtools/rewriteTunables
 
 - `TunableDelta` (interface): interface TunableDelta — One changed tunable to write back into game source: which table, key path, and new value.
@@ -203,8 +252,10 @@
 
 - `Devtools` (interface): interface Devtools — Top-level devtools facade aggregating frame, profile, render, logs, latency, controls, discover, overrides, and probes.
 - `DevtoolsControl` (interface): interface DevtoolsControl — Registered tunable control with its resolved schema metadata and read/write/reset accessors.
-- `DevtoolsLogEntry` (interface): interface DevtoolsLogEntry — A single captured log line with timestamp, level, and formatted message.
+- `DevtoolsLatency` (interface): interface DevtoolsLatency — Latency samples recorded by instrumented transport methods.
+- `DevtoolsLogEntry` (interface): interface DevtoolsLogEntry — A single captured log line with timestamp, level, owning system tag, and formatted message.
 - `DevtoolsLogLevel` (type): type DevtoolsLogLevel = "log" | "info" | "warn" | "error" — Severity level for a captured devtools log entry.
+- `DevtoolsLogs` (interface): interface DevtoolsLogs — Bounded log ring with per-system tags, a warning/error ring, and lifetime counts.
 - `DevtoolsSnapshot` (interface): interface DevtoolsSnapshot — Serializable point-in-time snapshot of devtools state: frame, render, latency, logs, controls, and discovered fields.
 - `DiscoveredEntry` (interface): interface DiscoveredEntry — A control auto-discovered by scanning an object/table, with its binding metadata and current reader.
 - `FrameRecordSample` (interface): interface FrameRecordSample — Per-frame timing input recorded by callers: total frame time, sim time, and optional named phase durations.
@@ -214,6 +265,8 @@
 - `OverrideApplyResult` (interface): interface OverrideApplyResult — Outcome of applying a devtools overrides payload: counts of applied and skipped entries plus diagnostics.
 - `PhaseStats` (interface): interface PhaseStats — Timing summary for a single named profiling phase across the sampling window.
 - `RenderSample` (interface): interface RenderSample — Snapshot of renderer resource counts (draw calls, triangles, geometries, textures) for a frame.
+- `SystemProbe` (interface): interface SystemProbe — What one system reports about itself: totals it keeps anyway, named timings, and one state line.
+- `SystemProbeReading` (interface): interface SystemProbeReading — One system's probe read out on demand; missing sections stay empty rather than absent.
 - `Tunable` (interface): interface Tunable<T> — Typed handle to a registered control, exposing its live value and subscribe/set/reset operations.
 - `TunableAccessor` (interface): interface TunableAccessor — Get/set accessor pair plus initial value used to bind a discovered field to a control.
 
@@ -232,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.25.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.27.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine/capabilities.md

@@ -48,6 +48,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `defineSystem` (function) · `import { defineSystem } from "@jgengine/shell/gameKit"`
 
+## devtools-log-bus — a bounded, per-system-tagged log ring a system writes to and a report reads
+
+- `LogBus` (interface) · `import { LogBus } from "@jgengine/core/devtools/logBus"`
+
 ## editor-catalogs — Export typed gameplay catalogs for in-editor tuning.
 
 - `EditorCatalogDefinition` (interface) · `import { EditorCatalogDefinition } from "@jgengine/shell/gameKit"`

package/skills/jgengine-assets/SKILL.md

@@ -54,7 +54,16 @@ After package publication and the shared consumer upgrade, delete the equivalent
 
 A model resolved from a catalog string id is stamped `animation: "auto"`: the shell derives speed-driven `idle`/`walk`/`run` states plus `hit`/`death`/`attack` one-shots from the loaded GLB's own clip names via semantic clip roles (`@jgengine/core/game/clipRoles` — `classifyClip`, `defaultAnimationForClips`, exported `DEFAULT_CLIP_ROLE_TABLE` covering KayKit/Quaternius/Mixamo naming). No game-side clip strings needed; a clipless model is unaffected. An explicit `ModelConfig.animation`/`style.animation` always wins, and `animation: "none"` opts a placement back to the bind pose. Games rendering cloned scenes themselves get the same driver from `@jgengine/shell/render/useModelAnimation` instead of hand-rolling an `AnimationMixer`.
 
-Material sources declare the map roles in their pinned archive through `AssetSource.materialMaps`; `pull` checks those declarations before writing. `buildMaterialCatalog` omits absent `ao`, `roughness`, and `ktx2` URLs. Pass the returned maps directly to model, building, or terrain seams, or explicitly supply a game-owned map. Do not construct optional map filenames or fill every material with synthetic AO. Check the actual archive when changing availability; ambientCG API map metadata covers the catalog, while byte verification covers the downloaded variants.
+Material sources declare the map roles in their pinned archive through `AssetSource.materialMaps`; `pull` checks those declarations before writing. `buildMaterialCatalog` omits absent `ao`, `roughness`, `opacity`, and `ktx2` URLs. Pass the returned maps directly to model, building, or terrain seams, or explicitly supply a game-owned map. Do not construct optional map filenames or fill every material with synthetic AO. Check the actual archive when changing availability; ambientCG API map metadata covers the catalog, while byte verification covers the downloaded variants.
+
+## Material library
+
+`@jgengine/assets/catalogs/materialLibrary` is the shared palette: `MATERIAL_LIBRARY` names 56 surfaces (`asphalt/wet`, `metal/painted`, `stucco/painted`, `brick/red`, `wood/oak`, `foliage/leaf`, `glass/clear`, `water/ocean`, `ground/sand`, `concrete/smooth`, …), each with its ambientCG source, world tile size in metres and physical response. Select by name — never by source id or filename.
+
+- `assets pull library --dir <public>` pulls every pinned map set (about 360 MB of 1K-JPG archives; each pulled material is then 5–7 MB beside its name). Pull into a game's `public/materials` and build assets with `libraryMaterialAsset(name)`; the returned `MaterialAsset` is the same editable value the editor writes into `editor.scene.json`.
+- Clear and frosted glass, ocean and puddle carry no scan: ambientCG publishes no glass or water material, so those four are response parameters. `glass/smudged` adds ambientCG's fingerprint normal.
+- Geometry without a `uv` attribute renders through `@jgengine/shell/render/triplanarMaterial` (`TriplanarAssetMaterial`, `useTriplanarAssetMaterial`, or `applyTriplanarProjection` on an owned material). It projects colour, normal, roughness and AO from world position at the asset's tile size, and instanced meshes project in instanced space. Use it for generated or imported world geometry; keep UV-mapped models on the ordinary path.
+- Metals need an environment to reflect. A metal entry under a bare clear colour reads as coloured chrome — pair `metal/*` with `EnvironmentLighting` or an authored sky.
 
 ## Source rules
 

package/skills/jgengine-assets/api.md

@@ -14,7 +14,7 @@
 - `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 { id: string; kind?: AssetSourceKind; provider: AssetProvider; title: string; license: string; author: string; categories: readonly string[]; download: AssetDownload; homepage?: string; materialMaps?: readonly MaterialMapRole[]; mirror?: st… — ⚠ undocumented · used by `ambientcgSources`: Every ambientCG material source, generated per family (`ambientcg-grass001` … ).
+- `AssetSource` (interface): interface AssetSource { id: string; kind?: AssetSourceKind; provider: AssetProvider; title: string; license: string; author: string; categories: readonly string[]; download: AssetDownload; homepage?: string; materialMaps?: readonly MaterialMapRole[]; mirror?: st… — ⚠ undocumented · used by `ambientcgSources`: Every ambientCG material source: the generated family sweep plus the pinned variants the shared library needs.
 - `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 { basePath?: string; sources?: readonly string[]; includeAliases?: boolean; includeSingles?: boolean; extras?: readonly CatalogExtra[] } — ⚠ undocumented · used by `buildCatalog`: Builds a game's asset catalog from the generated CC0 pack index plus singles, extras, and aliases.
@@ -28,10 +28,15 @@
 - `GlbTextureMetrics` (interface): interface GlbTextureMetrics — Dimensions and encoded bytes for one glTF image, including images referenced by texture extensions.
 - `ImportSpecValidation` (type): type ImportSpecValidation = { ok: true; entry: AssetImportSpec } | { ok: false; reason: string } — Result of validating an import description; a successful entry is an independent JSON snapshot.
 - `IndexEntry` (interface): interface IndexEntry — A source-owned model or sprite id, with optional offline model measurements.
-- `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"; readonly ktx2: "material.ktx2"; } — Normalized filenames a pulled material directory contains, keyed by map role.
+- `LibraryGroup` (type): type LibraryGroup = | "asphalt" | "concrete" | "stucco" | "brick" | "tile" | "metal" | "wood" | "foliage" | "ground" | "fabric" | "stone" | "glass" | "water" — Browse groups the library browser and `assets list` share.
+- `LibraryMaterial` (interface): interface LibraryMaterial — One named material a game or the editor selects by name. `source` names the ambientCG catalog entry whose pulled maps it uses; glass and water carry response parameters only, because ambientCG publishes no scanned glass or water material and both are shader surfaces.
+- `LibraryMaterialOptions` (interface): interface LibraryMaterialOptions — Options for {@link libraryMaterialMaps} and {@link libraryMaterialAsset}.
+- `LibrarySurface` (type): type LibrarySurface = "opaque" | "foliage" | "glass" | "water" — How a library surface renders: an ordinary PBR surface, cut-out foliage, glass or water.
+- `MATERIAL_LIBRARY` (const): const MATERIAL_LIBRARY: readonly LibraryMaterial[] — The shared library: 40+ ambientCG PBR materials plus the glass and water surfaces that need a shader rather than a scan. `satisfies` keeps every entry complete, so a missing tile size or response is a type error instead of a silently grey surface.
+- `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 opacity: "opacity.jpg"; readonly displacement: "displacement.jpg"; readonly ktx2: "material.ktx2"; } — Normalized filenames a pulled material directory contains, keyed by map role. Kept in its own module so catalogs and editors can name a pulled file without loading the archive reader.
 - `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, including an optional compressed KTX2 asset.
-- `MaterialMaps` (interface): interface MaterialMaps — URLs of one material's PBR maps; `ao`/`roughness`/`ktx2` appear only when declared by its source.
+- `MaterialMaps` (interface): interface MaterialMaps — URLs of one material's PBR maps; `ao`/`roughness`/`opacity`/`ktx2` appear only when declared by its source.
 - `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 { basePath?: string; seam?: "objectModels" | "entityModels" } — ⚠ undocumented · used by `modelWiringSnippet`: Copy-paste wiring for a pulled GLB id: resolve through the catalog, drop into a model seam.
@@ -54,7 +59,7 @@
 - `ValidateAssetReferencesResult` (interface): interface ValidateAssetReferencesResult — The aggregate result of validating a set of references against the provisioning contract.
 - `VerifyResult` (interface): interface VerifyResult { ok: boolean; errors: string[] } — ⚠ 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` … ).
+- `ambientcgSources` (const): const ambientcgSources: readonly AssetSource[] — Every ambientCG material source: the generated family sweep plus the pinned variants the shared library needs. A pinned id the family sweep already covers stays with the sweep, so catalog ids never appear twice.
 - `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 }`.
@@ -65,7 +70,9 @@
 - `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.
+- `filterLibraryMaterials` (function): function filterLibraryMaterials(query: string, group?: LibraryGroup): readonly LibraryMaterial[] — Filter the library for a picker: case-insensitive match on name, title, group or source. Empty query returns everything, so a browser can render the full library first.
 - `findAssets` (function): function findAssets(query: string, options: FindOptions = {}): AssetMatch[] — The ranked matches for a query — models, packs, HUD components, and icons in one list.
+- `findLibraryMaterial` (function): function findLibraryMaterial(name: string): LibraryMaterial | null — Resolve a library name; unknown names return `null` so a caller can report them by name.
 - `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
@@ -76,6 +83,10 @@
 - `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.
+- `libraryMaterialAsset` (function): function libraryMaterialAsset(name: string, options: LibraryMaterialOptions = {}): MaterialAsset — Build the editable, serializable material asset for a library name: maps, response and CC0 attribution in one value the editor can save into `editor.scene.json` and the shell renders. `projection` records whether those maps should sample authored UVs or world-space triplanar.
+- `libraryMaterialMaps` (function): function libraryMaterialMaps(entry: LibraryMaterial, options: LibraryMaterialOptions = {}): Partial<Record<MaterialTextureRole, MaterialTextureMetadata>> — Serialized runtime map URLs for a library material, matching what `assets pull <source>` writes into `<basePath>/<source-id>/`. Roles the archive does not ship are omitted, never invented.
+- `libraryMaterialNames` (function): function libraryMaterialNames(): readonly string[] — Every library name, in authored order.
+- `libraryMaterialRoles` (function): function libraryMaterialRoles(entry: LibraryMaterial): readonly LibraryMapRole[] — Map roles the pinned archive of `entry` actually ships, from its catalog source declaration.
 - `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.
@@ -122,6 +133,21 @@
 - `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/materialLibrary
+
+- `LibraryGroup` (type): type LibraryGroup = | "asphalt" | "concrete" | "stucco" | "brick" | "tile" | "metal" | "wood" | "foliage" | "ground" | "fabric" | "stone" | "glass" | "water" — Browse groups the library browser and `assets list` share.
+- `LibraryMapRole` (type): type LibraryMapRole = "color" | "normal" | "roughness" | "ao" | "opacity" — Map roles a library scan can carry: the PBR set plus cut-out coverage.
+- `LibraryMaterial` (interface): interface LibraryMaterial — One named material a game or the editor selects by name. `source` names the ambientCG catalog entry whose pulled maps it uses; glass and water carry response parameters only, because ambientCG publishes no scanned glass or water material and both are shader surfaces.
+- `LibraryMaterialOptions` (interface): interface LibraryMaterialOptions — Options for {@link libraryMaterialMaps} and {@link libraryMaterialAsset}.
+- `LibrarySurface` (type): type LibrarySurface = "opaque" | "foliage" | "glass" | "water" — How a library surface renders: an ordinary PBR surface, cut-out foliage, glass or water.
+- `MATERIAL_LIBRARY` (const): const MATERIAL_LIBRARY: readonly LibraryMaterial[] — The shared library: 40+ ambientCG PBR materials plus the glass and water surfaces that need a shader rather than a scan. `satisfies` keeps every entry complete, so a missing tile size or response is a type error instead of a silently grey surface.
+- `filterLibraryMaterials` (function): function filterLibraryMaterials(query: string, group?: LibraryGroup): readonly LibraryMaterial[] — Filter the library for a picker: case-insensitive match on name, title, group or source. Empty query returns everything, so a browser can render the full library first.
+- `findLibraryMaterial` (function): function findLibraryMaterial(name: string): LibraryMaterial | null — Resolve a library name; unknown names return `null` so a caller can report them by name.
+- `libraryMaterialAsset` (function): function libraryMaterialAsset(name: string, options: LibraryMaterialOptions = {}): MaterialAsset — Build the editable, serializable material asset for a library name: maps, response and CC0 attribution in one value the editor can save into `editor.scene.json` and the shell renders. `projection` records whether those maps should sample authored UVs or world-space triplanar.
+- `libraryMaterialMaps` (function): function libraryMaterialMaps(entry: LibraryMaterial, options: LibraryMaterialOptions = {}): Partial<Record<MaterialTextureRole, MaterialTextureMetadata>> — Serialized runtime map URLs for a library material, matching what `assets pull <source>` writes into `<basePath>/<source-id>/`. Roles the archive does not ship are omitted, never invented.
+- `libraryMaterialNames` (function): function libraryMaterialNames(): readonly string[] — Every library name, in authored order.
+- `libraryMaterialRoles` (function): function libraryMaterialRoles(entry: LibraryMaterial): readonly LibraryMapRole[] — Map roles the pinned archive of `entry` actually ships, from its catalog source declaration.
+
 ## @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}.
@@ -225,7 +251,7 @@
 - `AssetAlias` (interface): interface AssetAlias { key: string; target: string } — ⚠ undocumented · used by `aliases` (@jgengine/assets): Semantic keys → live catalog ids.
 - `AssetDownload` (type): type AssetDownload = PinnedDownload | ScrapeDownload — ⚠ undocumented
 - `AssetProvider` (type): type AssetProvider = | "quaternius" | "kaykit" | "polypizza" | "itch" | "ambientcg" | "gameicons" | "custom" — ⚠ undocumented
-- `AssetSource` (interface): interface AssetSource { id: string; kind?: AssetSourceKind; provider: AssetProvider; title: string; license: string; author: string; categories: readonly string[]; download: AssetDownload; homepage?: string; materialMaps?: readonly MaterialMapRole[]; mirror?: st… — ⚠ undocumented · used by `ambientcgSources` (@jgengine/assets): Every ambientCG material source, generated per family (`ambientcg-grass001` … ).
+- `AssetSource` (interface): interface AssetSource { id: string; kind?: AssetSourceKind; provider: AssetProvider; title: string; license: string; author: string; categories: readonly string[]; download: AssetDownload; homepage?: string; materialMaps?: readonly MaterialMapRole[]; mirror?: st… — ⚠ undocumented · used by `ambientcgSources` (@jgengine/assets): Every ambientCG material source: the generated family sweep plus the pinned variants the shared library needs.
 - `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.
@@ -236,14 +262,19 @@
 - `SingleAsset` (interface): interface SingleAsset { id: string; url: string; license: string; author: string; categories: readonly string[] } — ⚠ undocumented
 - `isScrapeDownload` (function): function isScrapeDownload(download: AssetDownload): download is ScrapeDownload — ⚠ undocumented
 
+## @jgengine/assets/materialMapFiles
+
+- `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 opacity: "opacity.jpg"; readonly displacement: "displacement.jpg"; readonly ktx2: "material.ktx2"; } — Normalized filenames a pulled material directory contains, keyed by map role. Kept in its own module so catalogs and editors can name a pulled file without loading the archive reader.
+- `MaterialMapRole` (type): type MaterialMapRole = keyof typeof MATERIAL_MAP_FILES — One PBR map's role within a material, including an optional compressed KTX2 asset.
+
 ## @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"; readonly ktx2: "material.ktx2"; } — Normalized filenames a pulled material directory contains, keyed by map role.
+- `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 opacity: "opacity.jpg"; readonly displacement: "displacement.jpg"; readonly ktx2: "material.ktx2"; } — Normalized filenames a pulled material directory contains, keyed by map role. Kept in its own module so catalogs and editors can name a pulled file without loading the archive reader.
 - `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, including an optional compressed KTX2 asset.
-- `MaterialMaps` (interface): interface MaterialMaps — URLs of one material's PBR maps; `ao`/`roughness`/`ktx2` appear only when declared by its source.
+- `MaterialMaps` (interface): interface MaterialMaps — URLs of one material's PBR maps; `ao`/`roughness`/`opacity`/`ktx2` appear only when declared by its source.
 - `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.
@@ -292,7 +323,7 @@
 
 ## @jgengine/assets/sources
 
-- `ambientcgSources` (const): const ambientcgSources: readonly AssetSource[] — Every ambientCG material source, generated per family (`ambientcg-grass001` … ).
+- `ambientcgSources` (const): const ambientcgSources: readonly AssetSource[] — Every ambientCG material source: the generated family sweep plus the pinned variants the shared library needs. A pinned id the family sweep already covers stays with the sweep, so catalog ids never appear twice.
 - `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`.
@@ -304,8 +335,9 @@
 
 ## @jgengine/assets/sources/ambientcg
 
+- `AMBIENTCG_PINNED_ASSET_IDS` (const): const AMBIENTCG_PINNED_ASSET_IDS: ReadonlyMap<string, string> — Upstream asset id pinned to a material source id, so the reverse lookup never guesses a variant.
 - `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` … ).
+- `ambientcgSources` (const): const ambientcgSources: readonly AssetSource[] — Every ambientCG material source: the generated family sweep plus the pinned variants the shared library needs. A pinned id the family sweep already covers stays with the sweep, so catalog ids never appear twice.
 
 ## @jgengine/assets/sources/gameicons