@jgengine/core 0.18.1 → 0.21.0

package/skills/jgengine-gameplay/capabilities.md

@@ -12,6 +12,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `advanceLedger` (function) · `import { advanceLedger } from "@jgengine/core/gameplay"`
 
+## affix-roller — roll randomized gear (guns, armor, loot) with rarity tiers, stat scaling and prefix/suffix affixes from a seed
+
+- `createAffixRoller` (function) · `import { createAffixRoller } from "@jgengine/core/gameplay"`
+
 ## auction-book — timed bid auctions with escrowed bids, buyout, anti-snipe close extension, and collection-box settlement
 
 - `createAuctionBook` (function) · `import { createAuctionBook } from "@jgengine/core/gameplay"`
@@ -40,6 +44,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `totalLoad` (function) · `import { totalLoad } from "@jgengine/core/inventory/encumbrance"`
 
+## cell-grid — immutable 2D board of cells with row clears, gravity collapse, and match runs
+
+- `createCellGrid` (function) · `import { createCellGrid } from "@jgengine/core/puzzle/cellGrid"`
+
 ## clip-roles — map a rigged asset's pack-specific clip name to its semantic animation role
 
 - `classifyClip` (function) · `import { classifyClip } from "@jgengine/core/game/clipRoles"`
@@ -57,6 +65,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createItemUse` (function) · `import { createItemUse } from "@jgengine/core/gameplay"`
 
+## content-progression-validation — diagnose unavailable sources and blocked cross-content progression under explicit game-owned rules without rejecting intentional seeded cycles
+
+- `validateContentProgression` (function) · `import { validateContentProgression } from "@jgengine/core/game/contentValidation"`
+
+## content-reference-validation — locate duplicate content ids and broken references across game-owned catalog namespaces with repair guidance
+
+- `validateContentReferences` (function) · `import { validateContentReferences } from "@jgengine/core/game/contentValidation"`
+
+## control-suspension — Suspend player input across overlapping menus without stopping shared simulation.
+
+- `suspendPlayControls` (function) · `import { suspendPlayControls } from "@jgengine/core/game/controlGate"`
+
 ## cosmetics — equip cosmetic skins and customizations by slot
 
 - `createCosmetics` (function) · `import { createCosmetics } from "@jgengine/core/gameplay"`
@@ -104,6 +124,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createGameDialogue` (function) · `import { createGameDialogue } from "@jgengine/core/gameplay"`
 
+## dialogue-graph-validation — diagnose duplicate ids, broken branches, unreachable dialogue, and nodes without a route to an ending before play
+
+- `validateDialogueGraph` (function) · `import { validateDialogueGraph } from "@jgengine/core/game/dialogueGraph"`
+
 ## dialogue-graph-view — select a conversation node's render-ready view (speaker, line, branching choices) from a serializable dialogue graph
 
 - `selectDialogueView` (function) · `import { selectDialogueView } from "@jgengine/core/gameplay"`
@@ -136,6 +160,26 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createEventTicker` (function) · `import { createEventTicker } from "@jgengine/core/gameplay"`
 
+## expedition-dispatch — dispatch a saveable timed away mission with finite supplies and a seeded RNG cursor
+
+- `dispatchExpedition` (function) · `import { dispatchExpedition } from "@jgengine/core/gameplay"`
+
+## expedition-recall — begin a safe fractional-time return after settling the pending expedition frontier
+
+- `recallExpedition` (function) · `import { recallExpedition } from "@jgengine/core/gameplay"`
+
+## expedition-return — complete an authorized instant return without skipping unsettled ticks or reviving death
+
+- `returnExpeditionNow` (function) · `import { returnExpeditionNow } from "@jgengine/core/gameplay"`
+
+## expedition-settle — settle bounded offline expedition ticks without losing supplies rewards or RNG continuity
+
+- `settleExpedition` (function) · `import { settleExpedition } from "@jgengine/core/gameplay"`
+
+## fire-input — bind a key or mouse button to a named action that runs the same-named command with the aim; repeatMs auto-fires while held
+
+- `ActionCodesMap` (type) · `import { ActionCodesMap } from "@jgengine/core/gameplay"`
+
 ## game-save — save/load game state with a pluggable backend, autosave, slots, and migration
 
 - `createSaveStore` (function) · `import { createSaveStore } from "@jgengine/core/gameplay"`
@@ -239,6 +283,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `localSaveBackend` (function) · `import { localSaveBackend } from "@jgengine/core/gameplay"`
 
+## loot-beams — rarity-colored loot beams and labels on dropped items via defineGame({ worldItem: { rarityStyle, beamHeight } })
+
+- `RarityStyle` (interface) · `import { RarityStyle } from "@jgengine/core/gameplay"`
+
 ## loot-filter — filter and highlight drops by rarity/name rules
 
 - `evaluateLootFilter` (function) · `import { evaluateLootFilter } from "@jgengine/core/gameplay"`
@@ -273,6 +321,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createNameGenerator` (function) · `import { createNameGenerator } from "@jgengine/core/gameplay"`
 
+## narrative-batch-validation — locate stale canon, oversized batches, explicit character/fact/chronology contradictions and dialogue graph issues for bounded repair
+
+- `validateNarrativeBatch` (function) · `import { validateNarrativeBatch } from "@jgengine/core/game/narrativeAuthoring"`
+
+## narrative-canon — freeze caller-reviewed character ids, facts and chronology for a narrative authoring revision
+
+- `freezeNarrativeCanon` (function) · `import { freezeNarrativeCanon } from "@jgengine/core/game/narrativeAuthoring"`
+
 ## notice-feed — serializable tone-tagged notice/event feed bounded by count and age (toasts, life events, killfeed)
 
 - `appendFeed` (function) · `import { appendFeed } from "@jgengine/core/gameplay"`
@@ -312,6 +368,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createPingSystem` (function) · `import { createPingSystem } from "@jgengine/core/gameplay"`
 
+## pointer-commands — click an entity or the ground to run a command (click-to-target, click-to-move, grab loot, marquee select)
+
+- `PointerConfig` (interface) · `import { PointerConfig } from "@jgengine/core/gameplay"`
+
 ## policy-annotate — tag a scheduled transaction's provenance without changing its value
 
 - `annotate` (function) · `import { annotate } from "@jgengine/core/gameplay"`
@@ -352,6 +412,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `evalCurve` (function) · `import { evalCurve } from "@jgengine/core/gameplay"`
 
+## quest-catalog-validation — diagnose authored quest ids, prerequisite and reward references, quantities, and blocked dependencies with caller-declared external unlocks
+
+- `validateQuestCatalog` (function) · `import { validateQuestCatalog } from "@jgengine/core/game/questCatalog"`
+
 ## quest-log — track accepted quests and their per-objective progress
 
 - `createQuestJournal` (function) · `import { createQuestJournal } from "@jgengine/core/gameplay"`
@@ -373,6 +437,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createRaceState` (function) · `import { createRaceState } from "@jgengine/core/gameplay"`
 
+## recipe-catalog-validation — locate broken crafting item/station/unlock references, duplicate inputs and invalid authored quantities with repair guidance
+
+- `validateRecipeCatalog` (function) · `import { validateRecipeCatalog } from "@jgengine/core/crafting/recipeCatalog"`
+
 ## resolve — the current tier/band label for a keyed or scalar value
 
 - `tierAt` (function) · `import { tierAt } from "@jgengine/core/gameplay"`
@@ -423,6 +491,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `setValue` (function) · `import { setValue } from "@jgengine/core/gameplay"`
 
+## shaped-grid — a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement
+
+- `canPlace` (function) · `import { canPlace } from "@jgengine/core/inventory/shapedGrid"`
+- `createShapedGrid` (function) · `import { createShapedGrid } from "@jgengine/core/inventory/shapedGrid"`
+- `moveShaped` (function) · `import { moveShaped } from "@jgengine/core/inventory/shapedGrid"`
+- `placeShaped` (function) · `import { placeShaped } from "@jgengine/core/inventory/shapedGrid"`
+- `removeShaped` (function) · `import { removeShaped } from "@jgengine/core/inventory/shapedGrid"`
+
+## shaped-placement — find a shaped inventory item's first fit with ordered rotations, row-major placement, and an explicit search budget
+
+- `findShapedPlacement` (function) · `import { findShapedPlacement } from "@jgengine/core/inventory/shapedGrid"`
+
 ## shop-grid — serializable vendor/shop stock with buy/sell over a caller-owned wallet — finite/unlimited qty, sell-back, restock/setPrice, snapshot/restore
 
 - `createShopStock` (function) · `import { createShopStock } from "@jgengine/core/gameplay"`
@@ -435,6 +515,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createSpawnPoints` (function) · `import { createSpawnPoints } from "@jgengine/core/gameplay"`
 
+## split-screen — Split the screen into one viewport per local seat, each with its own follow camera.
+
+- `splitViewports` (function) · `import { splitViewports } from "@jgengine/core/game/viewports"`
+
+## staffed-station-rate — turn bounded caller-owned worker stats and efficiency into a production rate
+
+- `stationOutputRate` (function) · `import { stationOutputRate } from "@jgengine/core/gameplay"`
+
 ## stat-graph — derive game-defined stats from named inputs with provenance and preview
 
 - `createStatGraph` (function) · `import { createStatGraph } from "@jgengine/core/gameplay"`
@@ -459,6 +547,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `tick` (function) · `import { tick } from "@jgengine/core/gameplay"`
 
+## time-scaled-loot — shape loot odds by elapsed hours with caller-authored curves and pipeline provenance
+
+- `timeScaledRarity` (function) · `import { timeScaledRarity } from "@jgengine/core/gameplay"`
+
 ## toast-feed — queue of transient self-expiring on-screen messages (toasts, announcer, kill-feed)
 
 - `appendToast` (function) · `import { appendToast } from "@jgengine/core/gameplay"`

package/skills/jgengine-gameplay/recipes/device-save-status.md

@@ -0,0 +1,46 @@
+# Truthful device saves
+
+Use `ctx.game.save` for the authoritative world or `createSaveStore` for a caller-owned,
+serializable checkpoint. Default offline context saves use strict local storage:
+denied reads, quota errors, unavailable storage, and denied removals report
+`status() === "error"`. Explicitly injected backends retain their own policy.
+
+For an existing Wayfarer/OddOrbit-style run checkpoint, keep the game's checkpoint
+schema and validation, and replace only its persistence adapter:
+
+```ts
+import { createSaveStore, localSaveBackend } from "@jgengine/core/game/saveStore";
+
+const checkpoint = createSaveStore({
+  key: "my-game:run",
+  initial: { roomId: "start", cleared: [] as string[] },
+  backend: localSaveBackend(undefined, { errorMode: "throw" }),
+  onError: (error) => console.error("Checkpoint storage failed", error),
+});
+
+checkpoint.set({ roomId: "harbor", cleared: ["intro"] });
+await checkpoint.save();
+const message = checkpoint.status() === "saved"
+  ? "Checkpoint saved"
+  : "Checkpoint could not be saved. Keep playing and retry.";
+```
+
+`save()` handles backend rejection; awaiting it alone does not prove success.
+Subscribe to status changes for autosave UI. A rejected payload write preserves
+the previous stored checkpoint while live edits remain available for retry.
+Denied load/remove leaves the current value intact. Whole-world load/hasSave/slot
+switches return false after a denied payload read and do not restore cached state. Slot metadata is a separate
+storage operation: a payload can be written before its slot index fails. That
+reports `error` too; there is no cross-key rollback or transaction guarantee.
+Async index updates after load also report through status and `onError`.
+
+`createKeyValueStore` and `localSaveBackend` preserve their legacy silent fallback
+by default. Set `errorMode: "throw"` when persistence must succeed; optionally
+provide `onError({ operation, key, error })` to observe reads, writes and removals.
+Strict key-value writes/removals preserve the prior cell on rejection. Observers
+must not throw. Shape validation and corruption recovery still belong to the
+game's checkpoint schema or a supplied deserializer.
+
+For intentional session-only/headless success, use `memorySaveBackend()`,
+`persist: { storage: "memory" }`, or a key-value cell with `storage: null`.
+Memory success does not promise persistence across reloads.

package/skills/jgengine-gameplay/recipes/expeditions.md

@@ -0,0 +1,108 @@
+# Timed away missions
+
+Use the pure transitions in `@jgengine/core/work/expedition` to orchestrate a timed
+away mission. The caller owns its clock, store, identities, authored content and
+policy. Core owns event ordering and the exploring → returning → home / dead
+lifecycle, not a scheduler, genre preset or persistence backend.
+
+All `*Ms` fields and log `at` timestamps are epoch milliseconds. Persist the entire
+`ExpeditionState`, including `cursor`, supplies, carried rewards and the completed
+tick frontier. `settleExpedition(config, state, nowMs)` uses `accrueSince` and
+`steppedCatchUp`; a multi-day gap follows the same loot → hazard → ordered supplies
+→ death → capacity recall sequence as incremental calls. Each callback is pure
+and receives the state at that event's time, with the persisted RNG stream.
+
+```ts
+import { createLootPipeline } from "@jgengine/core/game/lootPipeline";
+import { timeScaledRarity } from "@jgengine/core/game/lootModifiers";
+import {
+  dispatchExpedition, settleExpedition, recallExpedition, returnExpeditionNow,
+  type ExpeditionConfig, type ExpeditionState,
+} from "@jgengine/core/work/expedition";
+import { defineStore } from "@jgengine/core/store/defineStore";
+import { defineSystem } from "@jgengine/core/game/defineSystem";
+
+const rewards = createLootPipeline<{ elapsedMs: number }>({
+  id: "survey-rewards",
+  stages: [{ id: "survey", table: {
+    id: "survey-pool", entries: [
+      { item: "sample", count: 1, weight: 9 },
+      { item: "artifact", count: 1, weight: 1 },
+    ],
+  }, modifiers: [timeScaledRarity({
+    id: "survey-depth",
+    ramp: (entry, hours) => entry.item === "artifact" ? 1 + hours : 1,
+  })] }],
+});
+const survey: ExpeditionConfig<{ elapsedMs: number }> = {
+  tickMs: 20 * 60_000,
+  loot: rewards,
+  lootCtx: state => ({ elapsedMs: state.elapsedMs }),
+  maxHp: state => Math.max(1, 100 - state.exposure),
+  hazard: (_state, rng) => ({ damage: rng() < 0.25 ? 4 : 1, exposure: 1 }),
+  supplies: [
+    { key: "filter", when: state => state.exposure >= 10, clearExposure: 10 },
+    { key: "medicine", when: state => state.hp < 30, restoreHp: 25 },
+  ],
+  returnFraction: 0.5,
+  carryCap: 100,
+  maxTicksPerSettle: 1000,
+  logLimit: 200,
+  describe: event => `Survey: ${event.kind}`, // Replace with authored/localized prose.
+};
+
+export function awayMission(nowMs: () => number) {
+  const mission = defineStore<ExpeditionState | null>("away-mission", null);
+  const dispatch = () => dispatchExpedition({
+    id: "surveyor", startAtMs: nowMs(), hp: 100,
+    supplies: { medicine: 5, filter: 2 }, seed: "caller-campaign:surveyor",
+  });
+  const system = defineSystem({
+    id: "away-mission", tick: { type: "frame" },
+    create(ctx) { mission.write(ctx, dispatch()); },
+    update(ctx) { mission.update(ctx, state => state === null ? null : settleExpedition(survey, state, nowMs())); },
+    reset(ctx) { mission.write(ctx, dispatch()); },
+  });
+  return { mission, system, recallExpedition, returnExpeditionNow };
+}
+```
+
+Install the returned system with `defineGame({ systems: [system] })`. Store writes
+and `ctx.state()` / `ctx.restore()` keep the ordinary native save boundary; no
+expedition-specific backend is required. A caller-owned store may instead call
+the same pure transitions and atomically persist each returned value. Decode and
+validate your saved schema at that boundary. Keep policy callbacks free of side
+effects; a rejected policy transition does not write through the pure API.
+
+A courier composition can use a parcel-only loot pipeline, no exposure,
+`maxHp: () => 20`, rations restoring health, and `returnFraction: 0.25`. Both
+compositions use the same orchestration. Item names, encounter notices, quality
+curves, hazard magnitudes, immunity and supply thresholds are authored data and
+callbacks; they are not SDK content presets. `timeScaledRarity` multiplies weighted
+odds or independent chances (clamped to one) and preserves the loot pipeline's
+original/effective odds and modifier ids. There is no built-in rarity taxonomy.
+
+`carryCap` counts **item units**, not drop records. Rolled item quantities are
+admitted in pipeline order up to the remaining cap; currency does not consume
+item capacity and is carried in full. Carried counts merge by identity. Each loot
+event's `drops` contains accepted quantities, while `loot` contains the full rolled
+resolution and provenance, including quantities excluded by capacity. Core starts
+auto-return at the event time that filled capacity. Returning never rolls rewards,
+consumes supplies or takes hazard damage. Arrival is recorded at its exact deadline
+even when one offline call observes it much later. Dead missions never revive.
+
+`maxTicksPerSettle` bounds work without dropping elapsed ticks. If the budget runs
+out, the completed frontier remains behind `nowMs`. Recall and instant return use
+that same settlement pipeline and postpone the transition while due ticks remain;
+repeat at the same target until caught up. The caller owns instant-return payment
+and authorization. Count-bound `appendFeed` keeps the newest log events without
+discarding carried rewards or RNG progress. Supply rules run in array order and
+spend one unit only when restoration/cleansing changes a vital; health can recover
+from zero during that tick before the death decision.
+
+Configuration is runtime policy, never saved into state. Retuning applies the
+current policy to unsettled ticks; a changed cadence anchors at the last completed
+tick. Persist a policy/version id alongside your state if historical policy must
+be replayed exactly. A lower carry cap preserves already-owned rewards and recalls
+after the next due event (or immediately when no tick is due). Monotonic settlement
+does not replay time when the caller's clock moves backward.

package/skills/jgengine-gameplay/recipes/narrative-authoring.md

@@ -0,0 +1,76 @@
+# Repair dialogue batches against reviewed canon
+
+`npx jgengine recipe narrative-authoring` prints an SDK-typechecked function with
+injected `generate` and `review` callbacks. Use it for a bounded chapter's
+conversations, then stage the accepted batch for playtesting. It selects no
+model, network service, assets or genre.
+
+The author supplies a chapter brief: intended experience, voices, prerequisites,
+player choices and their consequences. Keep reviewed canon separate from draft
+prose. `freezeNarrativeCanon` detaches and freezes a revision, character ids,
+exact string facts and a strict event order. Include only events whose order is
+settled; branching or uncertain chronology belongs in semantic review. A new
+fact or changed fact requires a separately reviewed canon revision.
+
+```ts
+import {
+  freezeNarrativeCanon,
+  validateNarrativeBatch,
+  type NarrativeBatch,
+} from "@jgengine/core/game/narrativeAuthoring";
+
+const canon = freezeNarrativeCanon({
+  revision: "inquiry-r7",
+  characterIds: ["diver"],
+  facts: { hatch: "sealed" },
+  eventIds: ["descent", "alarm"],
+});
+const candidate: NarrativeBatch = {
+  canonRevision: canon.revision,
+  dialogues: [{
+    id: "deposition",
+    graph: {
+      start: "witness",
+      nodes: [{ id: "witness", speaker: "Witness 4", text: "The hatch stayed sealed." }],
+    },
+    claims: [{ nodeId: "witness", kind: "fact", factId: "hatch", value: "sealed" }],
+  }],
+};
+const issues = validateNarrativeBatch(canon, candidate, {
+  maxDialogues: 1, maxNodes: 20, maxChoices: 40, maxClaims: 30, maxTextCharacters: 6000,
+});
+```
+
+These numbers and content demonstrate caller choices. A procedural undersea
+inquiry can hinge on preserving a witness's anonymity versus publishing evidence.
+An absurd rooftop tea negotiation can hinge on saluting a pigeon's ceremonial
+hat versus offering biscuits. Each game writes its own canon, voices, style and
+consequences; neither slice supplies a reusable story preset.
+
+The typed batch contains graphs plus explicit node-attached `character`, `fact`
+and `before` claims. `validateNarrativeBatch` checks those claims and reuses
+`validateDialogueGraph` for topology. Diagnostics include a JSON-pointer path,
+for example `/dialogues/0/claims/1/value` or
+`/dialogues/0/graph/nodes/2/choices/0/to`. Speaker labels and prose remain display
+data. Omitted or misleading claims cannot prove prose is coherent.
+
+The CLI function snapshots canon, limits, brief and callback selection before
+awaiting generation. It checks revision and budgets before copying a returned
+candidate; oversized and stale candidates are discarded with diagnostics.
+Within-budget drafts and repair diagnostics are detached and frozen across
+callbacks. Fix the located candidate, preserving the reviewed canon. Attempts
+stop at the caller's positive `maxAttempts`; exhausting it returns `needs-review`.
+
+Generators return typed `NarrativeBatch` data. Decode external JSON before this
+boundary and enforce response byte/token budgets in the generator adapter; the
+SDK's node/choice/claim/text limits are not a transport-size limiter. Callback
+failures propagate. A pending reviewer stays pending, and rejection never implies
+approval. A reviewer must return `approved: true` and no error diagnostics for
+acceptance. Review topology warnings explicitly against intended play.
+
+Semantic review compares the actual prose with canon and the chapter brief,
+including unannotated statements, character motivations, causality, chronology,
+lasting consequences and meaningful playable choices. Return located issues to
+the next repair attempt. Play representative branches before promoting accepted
+drafts to the game's authored catalog. Acceptance stages data; this function
+never publishes content or replaces canon.

package/skills/jgengine-gameplay/recipes/paged-item-storage.md

@@ -0,0 +1,101 @@
+# Save generated items in bounded pages
+
+Use this recipe when an existing project owns generated item storage and wants
+runtime ids and incremental save export without mirroring its items into another
+registry. The interface is synchronous; it does not provide a database adapter.
+
+```ts
+import {
+  createItemInstanceRegistry,
+  type ItemInstanceStorage,
+  type ItemInstanceRegistryState,
+} from "@jgengine/core/item/itemInstanceRegistry";
+
+type RolledItem = { damage: number; affixes: string[] };
+
+let existingItems = new Map<string, RolledItem>();
+const storage: ItemInstanceStorage<RolledItem> = {
+  get: (id) => existingItems.get(id),
+  has: (id) => existingItems.has(id),
+  set: (id, definition) => void existingItems.set(id, definition),
+  delete: (id) => void existingItems.delete(id),
+  count: () => existingItems.size,
+  entries: () => existingItems.entries(),
+  replace(entries) {
+    const staged = new Map(entries);
+    existingItems = staged;
+  },
+};
+
+const registry = createItemInstanceRegistry("rolled", { storage });
+const runtimeId = registry.register("blade", { damage: 17, affixes: ["keen"] });
+const item = registry.get(runtimeId);
+```
+
+The example adapter stages replacement in another Map. A larger caller-owned
+store can stage in its own transaction or generation and switch on success.
+`replace` must consume the entire iterable synchronously and preserve old data
+when iteration, cloning, validation, or commit fails. Do not clear live data and
+then populate it. Stream `entries()` in stable order; materializing all entries
+inside the adapter defeats bounded export.
+
+## Export and restore
+
+```ts
+function saveItems(writePage: (json: string) => void): void {
+  for (const page of registry.statePages(256)) {
+    writePage(JSON.stringify(page));
+  }
+}
+
+function restoreItems(readPages: Iterable<string>): boolean {
+  function* decodedPages(): IterableIterator<ItemInstanceRegistryState<RolledItem>> {
+    for (const json of readPages) {
+      yield JSON.parse(json) as ItemInstanceRegistryState<RolledItem>;
+    }
+  }
+  return registry.restorePages(decodedPages());
+}
+```
+
+Each page retains the existing `{ prefix, sequence, entries }` save shape.
+An empty registry exports one empty page so released ids still retain their
+allocation sequence. Every restored page must have the same prefix and sequence.
+Each page's definitions are detached independently; cross-page object identity
+is not preserved. Keep definitions JSON-compatible for JSON saves.
+
+`statePages` captures the allocator when called, reads at most `pageSize` entries
+per step, and clones only that batch. Registry mutations invalidate the export
+and the next step throws. Abandoning an iterator never blocks writes; call its
+`return()` when stopping early to release adapter resources. Keep direct writes
+to injected storage and definition objects quiescent during export: the registry
+cannot detect them. The caller owns immutable capture or staging if saves must
+overlap live changes. Publish a set of pages only after the complete export
+succeeds; discard partial saves on failure.
+
+`restorePages` returns false for an empty iterable or an invalid first header.
+Later inconsistent headers, clone failures, and storage failures throw. A
+conforming adapter keeps both the old collection and allocator intact on failure.
+Restore consumes and clones one input page at a time; storage staging cost belongs
+to the adapter. Existing `state()` and `restore(state)` remain whole-collection
+operations and retain their original save shape.
+
+## Reattach existing storage
+
+If the caller restores storage separately, persist the page's allocator header
+alongside it and attach with its original prefix and sequence:
+
+```ts
+function reattach(savedHeader: { prefix: string; sequence: number }) {
+  return createItemInstanceRegistry(savedHeader.prefix, {
+    storage,
+    sequence: savedHeader.sequence,
+  });
+}
+```
+
+Never derive sequence from count: released ids must remain consumed. Allocation
+checks collisions against attached storage, but saving the real sequence avoids
+searching through old ids. Allocation stops at `Number.MAX_SAFE_INTEGER` instead
+of reusing ids through numeric rounding. The default registry remains in memory;
+injected storage owns retention, indexing, transaction policy, and persistence.

package/skills/jgengine-gameplay/recipes/quest-authoring.md

@@ -0,0 +1,63 @@
+# Validate generated quest batches against reviewed facts
+
+Run `npx jgengine recipe quest-authoring` for the SDK-typechecked composition.
+Supply your reviewed canonical facts, established quests, catalog ids, external
+unlock sources, and authoring limits. Inject your generator as the async callback;
+the recipe does not choose a model, story, genre, or assets.
+
+The generator receives detached, deeply frozen snapshots of the facts, established
+definitions, and limits for each bounded batch. Mutating caller inputs while the
+generator awaits cannot change the reviewed revision or reference lookups. It returns only new quest definitions. Decode untrusted JSON
+into `QuestDef` before returning it; this validator checks authored structure, not
+arbitrary JSON shape. The recipe rejects oversized quest/objective/reference
+batches before structural validation. Keep the existing catalog bounded too;
+partition larger worlds into reviewed dependency-complete catalogs.
+
+```ts
+import { validateQuestCatalog } from "@jgengine/core/game/questCatalog";
+import type { QuestDef } from "@jgengine/core/game/quest";
+
+function reviewBatch(existing: readonly QuestDef[], generated: readonly QuestDef[]) {
+  return validateQuestCatalog([...existing, ...generated], {
+    externalUnlocks: ["caller-declared-world-entry"],
+  });
+}
+```
+
+The CLI recipe returns `factsRevision`, `candidate`, `diagnostics`, and `repair`.
+`candidate` is null when structural errors exist. Each issue includes a JSON
+Pointer into the combined catalog, such as `/4/rewards/quests/0`, plus a stable
+code, severity, and referenced id when relevant. Send `repair` with the same
+canonical facts and definitions to your generator for a bounded correction;
+correct the identified fields and validate the whole candidate again. Never
+replace reviewed facts with a model's remembered version. The recipe leaves all
+warnings visible for review before registering the candidate with the journal.
+
+Declare unlock ids that other game systems may grant in `externalUnlocks`.
+Unlocks produced by catalog quest rewards are recognized automatically.
+`externallyStartedQuests` declares catalog quests your game may grant active,
+bypassing acceptance prerequisites. These declarations describe possible entry
+points, without asserting when they happen. A requirement may be fulfilled by
+completion of that quest id **or** an unlock with the same id; every requirement
+must be met. Any eligible quest may be accepted directly, so a quest does not
+need an incoming reward follow-up to be reachable.
+
+Blocked prerequisites and cycles are warnings under this potential-progression
+model. Objectives are assumed completable; external grants, custom acceptance
+rules, or unavailable objectives can change actual play. Unknown requirement and
+follow-up ids are errors: declare legitimate external unlock ids rather than
+silencing missing references. Use `hasReference` for item, target, inventory, and
+currency namespaces. Its objective context lets a game route custom objective
+kinds to different catalogs. Omitted lookup policy leaves those ids unchecked.
+
+Objective and item counts may be fractional or zero; zero can mean an already
+complete objective or a no-op reward. Negative/nonfinite counts and nonfinite
+reward amounts reject. Discrete quantity rules, XP loss, economy balance, story
+contradictions, character motivation, chronology, and consequences remain
+caller-owned review. Play representative paths before treating a valid catalog
+as a coherent world.
+
+For item supply and skill gates outside the quest journal, compose the
+[content validation](../reference-content-validation.md) checks. Declare source
+rules explicitly rather than assuming every defined item is obtainable or that
+catalog order proves an item reward can precede a collection objective.

package/skills/jgengine-gameplay/recipes/shaped-inventory.md

@@ -0,0 +1,50 @@
+# Place shaped inventory items
+
+Use `@jgengine/core/inventory/shapedGrid` for discrete cell footprints, including
+rectangles and irregular shapes. Item definitions, values, authored dimensions,
+save schemas, drag controls, and presentation stay in the game.
+
+```ts
+import {
+  createShapedGrid,
+  findShapedPlacement,
+  moveShaped,
+  placeShaped,
+  type ShapedItem,
+} from "@jgengine/core/inventory/shapedGrid";
+
+const item: ShapedItem<{ name: string }> = {
+  id: "probe-7",
+  value: { name: "Survey probe" },
+  footprint: [[0, 0], [0, 1], [1, 1]],
+};
+const board = createShapedGrid<{ name: string }>(4, 3);
+const fit = findShapedPlacement(board, item.footprint, {
+  rotations: [0, 1],
+  maxChecks: 24,
+});
+if (fit.status === "found") {
+  const placed = placeShaped(board, item, fit.origin, fit.rotation);
+  if (placed.status === "ok") moveShaped(placed.grid, item.id, [1, 0], 1);
+}
+```
+
+Rotations are quarter turns. Search visits the supplied rotation order, then
+rows and columns; the default rotation order is `[0, 1, 2, 3]`. Coordinates and
+dimensions must be finite safe integers; dimensions are positive and footprints
+are nonempty. Footprints normalize their minimum cell to `[0, 0]` after rotation.
+`canPlace` reports invalid cells before bounds and overlap checks. Pass `ignoreId`
+to either check or search when repositioning an existing item.
+
+Search indexes current occupancy once and limits candidate origins to
+`maxChecks` (default 4096). `budget-exceeded` means the search is incomplete;
+`no-space` means every requested origin and rotation was checked. Do not report
+a full bag for an exhausted budget. Indexing and footprint checks scale with
+the caller's board data; the budget does not limit their cell count.
+
+Placement operations return new board data. Serialize that data in the caller's
+save format; the engine does not keep a parallel bag or impose item nouns.
+Deepward's prepared adopter maps its existing rectangular item sizes and saved
+`x`, `y`, `rotated` fields into this contract, preserving its `[0, 1]` rotation
+preference and row-major packing. Its UI and extraction rules remain local.
+The prepared patch waits for a coordinator-verified containing package release.