@jgengine/editor 0.19.0 → 0.21.0

package/skills/jgengine-editor/api.md

@@ -4,7 +4,7 @@
 
 ## @jgengine/core/editor
 
-- `ApplyDocumentPatchResult` (type): type ApplyDocumentPatchResult = | { ok: true; document: EditorDocument; revision: number; patch: DocumentPatch } | { ok: false; error: string } — Result of applying a {@link DocumentPatch} to a document + revision pair.
+- `ApplyDocumentPatchResult` (type): type ApplyDocumentPatchResult = | { ok: true; document: EditorDocument; revision: number; patch: DocumentPatch } | { ok: false; error: string; commandIndex?: number } — Result of applying a {@link DocumentPatch} to a document + revision pair.
 - `AsciiGridExportOptions` (interface): interface AsciiGridExportOptions — Options for rendering a grid layer back out as an ASCII/glyph map.
 - `AsciiGridImportOptions` (interface): interface AsciiGridImportOptions — Options for importing an ASCII/glyph map into a grid layer. Provide `glyphMap` (char → value id) or a `palette` whose entries carry `glyph`s (or both — `glyphMap` wins on conflict). Any glyph not mapped, and any short-row padding, resolves to `empty`.
 - `CURRENT_GRID_SCHEMA_VERSION` (const): const CURRENT_GRID_SCHEMA_VERSION: 1 — The grid-layer cell-schema version this build writes and migrates toward.
@@ -17,7 +17,7 @@
 - `DocumentBakeOptions` (interface): interface DocumentBakeOptions extends MinimapBakeOptions — Options for {@link bakeMinimapFromDocument}.
 - `DocumentLiveEvent` (interface): interface DocumentLiveEvent — Event emitted when the authoritative document changes on a {@link DocumentLiveSync}.
 - `DocumentLiveSync` (interface): interface DocumentLiveSync — Two-way live-sync bus: document patches out, runtime state deltas back.
-- `DocumentPatch` (type): type DocumentPatch = | { type: "snapshot"; revision?: number; baseRevision: number; document: EditorDocument; } | { type: "commands"; revision?: number; baseRevision: number; commands: readonly EditorCommand[]; } — One versioned document mutation on the live-sync stream. `snapshot` replaces the whole document; `commands` replays structural editor commands onto the current document. `baseRevision` must match the receiver's current revision unless `force` is set (document authority from the editor).
+- `DocumentPatch` (type): type DocumentPatch = | { type: "snapshot"; revision?: number; baseRevision: number; document: EditorDocument; } | { type: "commands"; revision?: number; baseRevision: number; commands: readonly EditorCommand[]; } — One versioned document mutation on the live-sync stream. `snapshot` replaces the whole document; `commands` replays structural editor commands onto the current document. `baseRevision` must match the receiver's current revision unless `force` is set (document authority from the editor). `revision` preserves the authority cursor when replaying: snapshots may jump forward for reconnect recovery; commands must be the next revision.
 - `ENTITY_CATALOG_ID` (const): const ENTITY_CATALOG_ID: "entities" — Well-known catalog id for authored entity definitions. A `mob`/`boss` marker's `catalogId` references an entry (row) in this catalog, and {@link entityEntryFromCatalog} turns that row into the runtime {@link GameContextEntityEntry} a spawn consumes — so an entity's stats and speed are authored in the editor Data tab, not hardcoded in game TS.
 - `EditorCatalogData` (interface): interface EditorCatalogData — Persisted values for one gameplay data catalog (weapons, waves, economy, …). Schemas are not stored here — they come from the game's `editorCatalogs` export and drive SchemaInspector.
 - `EditorCatalogDefinition` (interface): interface EditorCatalogDefinition — Game-exported catalog definition: a `ParamSchema` plus default entries. Schemas stay in code; entry values merge into `document.catalogs` and are what the editor/RPC edits and saves.
@@ -53,6 +53,7 @@
 - `EditorSessionState` (interface): interface EditorSessionState — The document plus current selection at a point in editor history.
 - `EditorSkyPreset` (type): type EditorSkyPreset = "day" | "dusk" | "night" — Named sky look stored on the scene document; matches runtime `SkyEnvironmentConfig.preset`.
 - `EditorTerrain` (type): type EditorTerrain = TerraformSnapshot — A sculpted heightfield authored in the editor: the {@link TerraformSnapshot} of offset deltas over the game's base ground. Serializes with the scene; a game rebuilds the field with `editableTerrainFromSnapshot`.
+- `EditorTransactionResult` (type): type EditorTransactionResult = | { ok: true; state: EditorSessionState; changed: boolean } | { ok: false; error: string; commandIndex?: number } — Atomic command-batch outcome; a failure identifies the zero-based command index.
 - `EditorUiDocument` (interface): interface EditorUiDocument — Scene-document HUD section: panel id → layout. Single source of truth for placement.
 - `EditorUiPanelLayout` (interface): interface EditorUiPanelLayout — Authored layout for one HUD panel inside `editor.scene.json` → `ui.panels`.
 - `EditorVec3` (type): type EditorVec3 = { x: number; y: number; z: number } — A world-space point used across editor markers, volumes, and paths.
@@ -166,6 +167,18 @@
 - `EditorDispatchOptions` (interface): interface EditorDispatchOptions — Per-dispatch options; `coalesce` merges consecutive same-key edits into one undo step.
 - `EditorSession` (interface): interface EditorSession — Stateful, undoable handle for driving scene edits from UI or an MCP agent.
 - `EditorSessionState` (interface): interface EditorSessionState — The document plus current selection at a point in editor history.
+- `EditorTransactionResult` (type): type EditorTransactionResult = | { ok: true; state: EditorSessionState; changed: boolean } | { ok: false; error: string; commandIndex?: number } — Atomic command-batch outcome; a failure identifies the zero-based command index.
+
+## @jgengine/core/editor/creatorStorage
+
+- `CreatorConfig` (interface): interface CreatorConfig<TPlayable> — Creator configuration shared by a host and its lazily loaded editor.
+- `CreatorDocument` (interface): interface CreatorDocument — A named scene save with a storage-format version and optimistic revision.
+- `CreatorDocumentStorage` (interface): interface CreatorDocumentStorage — Injected durable storage. Save rejects stale revisions; null creates a new id.
+- `CreatorPolicy` (interface): interface CreatorPolicy — Bounds and catalog permissions for player-authored documents.
+- `createCreatorDocumentStorage` (function): function createCreatorDocumentStorage(config: { storage: KeyValueStorage; key: string; policy: CreatorPolicy }): CreatorDocumentStorage — Durable browser-compatible adapter over injected key/value storage; one atomic catalog write.
+- `exportCreatorDocument` (function): function exportCreatorDocument(document: EditorDocument, policy: CreatorPolicy): string — Exports validated, schema-versioned scene JSON.
+- `importCreatorDocument` (function): function importCreatorDocument(json: string, policy: CreatorPolicy): EditorDocument — Imports scene JSON using the same validation as commands and durable saves.
+- `validateCreatorDocument` (function): function validateCreatorDocument(value: unknown, policy: CreatorPolicy): EditorDocument — Validates schema, finite work budgets, and approved catalog references before cloning.
 
 ## @jgengine/core/editor/directives
 
@@ -250,10 +263,10 @@
 
 ## @jgengine/core/editor/liveSync
 
-- `ApplyDocumentPatchResult` (type): type ApplyDocumentPatchResult = | { ok: true; document: EditorDocument; revision: number; patch: DocumentPatch } | { ok: false; error: string } — Result of applying a {@link DocumentPatch} to a document + revision pair.
+- `ApplyDocumentPatchResult` (type): type ApplyDocumentPatchResult = | { ok: true; document: EditorDocument; revision: number; patch: DocumentPatch } | { ok: false; error: string; commandIndex?: number } — Result of applying a {@link DocumentPatch} to a document + revision pair.
 - `DocumentLiveEvent` (interface): interface DocumentLiveEvent — Event emitted when the authoritative document changes on a {@link DocumentLiveSync}.
 - `DocumentLiveSync` (interface): interface DocumentLiveSync — Two-way live-sync bus: document patches out, runtime state deltas back.
-- `DocumentPatch` (type): type DocumentPatch = | { type: "snapshot"; revision?: number; baseRevision: number; document: EditorDocument; } | { type: "commands"; revision?: number; baseRevision: number; commands: readonly EditorCommand[]; } — One versioned document mutation on the live-sync stream. `snapshot` replaces the whole document; `commands` replays structural editor commands onto the current document. `baseRevision` must match the receiver's current revision unless `force` is set (document authority from the editor).
+- `DocumentPatch` (type): type DocumentPatch = | { type: "snapshot"; revision?: number; baseRevision: number; document: EditorDocument; } | { type: "commands"; revision?: number; baseRevision: number; commands: readonly EditorCommand[]; } — One versioned document mutation on the live-sync stream. `snapshot` replaces the whole document; `commands` replays structural editor commands onto the current document. `baseRevision` must match the receiver's current revision unless `force` is set (document authority from the editor). `revision` preserves the authority cursor when replaying: snapshots may jump forward for reconnect recovery; commands must be the next revision.
 - `RuntimeEntityState` (interface): interface RuntimeEntityState — One live entity row the runtime may stream to the editor (play-mode inspector feed).
 - `RuntimeStateDelta` (interface): interface RuntimeStateDelta — Incremental runtime state for the reverse channel. Entity rows upsert by id; `removeIds` drop rows; `tunables` shallow-merge. Ephemeral unless written back as a document patch.
 - `RuntimeStateSnapshot` (interface): interface RuntimeStateSnapshot — Full ephemeral runtime view held on the reverse channel — never mutates the document.
@@ -265,12 +278,38 @@
 - `runtimeEntityWriteBackCommand` (function): function runtimeEntityWriteBackCommand(document: EditorDocument, entity: RuntimeEntityState): EditorCommand | null — Builds an undoable document command from an ephemeral runtime entity row (write-back). Returns null when there is nothing to promote. Does not mutate document or clear the override — the caller dispatches the command and then clears the override.
 - `subscribeDocumentLiveSyncInstall` (function): function subscribeDocumentLiveSyncInstall(listener: () => void): () => void — Subscribe to install/uninstall of the global live-sync bus (AuthoredScene re-attaches when the editor host mounts over a running game).
 
+## @jgengine/core/editor/materialAuthoring
+
+- `authoredMaterialAssignments` (function): function authoredMaterialAssignments(meta: Record<string, unknown> | undefined): MaterialAssignment[] — Read named assignments from authored marker metadata without inferring whole-model overrides.
+- `modelWithAuthoredMaterials` (function): function modelWithAuthoredMaterials(model: ModelConfig | undefined, document: Pick<EditorDocument, "markers" | "materialAssets">, instanceId: string): ModelConfig | undefined — Apply authored references; document assets and selectors override model defaults of the same identity.
+- `parseEditorMaterialAsset` (function): function parseEditorMaterialAsset(value: unknown): MaterialAsset — Validate and copy a material asset at the editor boundary.
+
 ## @jgengine/core/editor/minimap
 
 - `DocumentBakeOptions` (interface): interface DocumentBakeOptions extends MinimapBakeOptions — Options for {@link bakeMinimapFromDocument}.
 - `bakeMinimapFromDocument` (function): function bakeMinimapFromDocument(doc: EditorDocument, sampleHeight: (x: number, z: number) => number, options: DocumentBakeOptions = {}): { background: string; mapBounds: MinimapBakeBounds } — Bakes a minimap image from a scene document plus a terrain height sampler: sizes the footprint to the authored objects (or an explicit `bounds`), tints biome-colored volumes, and rasterizes the terrain top-down. Returns `{ background, mapBounds }` for the `Minimap` props. The editor runs this as its bake action and stores the result on the document.
 - `documentBakeZones` (function): function documentBakeZones(doc: EditorDocument): MinimapBakeZone[] — The biome-tint zones a document contributes to a bake: every volume carrying a `color` becomes a polygon tint over its footprint. (The optional stretch from #1036 — a bare bake still reads as terrain without any.)
 
+## @jgengine/core/editor/modelNodeVisibility
+
+- `authoredHiddenNodes` (function): function authoredHiddenNodes(meta: Record<string, unknown> | undefined): readonly string[] | undefined — Read marker visibility metadata; an empty list clears model defaults.
+- `modelWithAuthoredNodeVisibility` (function): function modelWithAuthoredNodeVisibility(model: ModelConfig | undefined, marker: Pick<EditorMarker, "meta"> | undefined): ModelConfig | undefined — Apply a placement's authored visibility without erasing omitted game model defaults.
+- `parseModelHiddenNodes` (function): function parseModelHiddenNodes(value: unknown): readonly string[] | undefined — Validate and copy exact node names; an empty list selects no hidden subtrees.
+
+## @jgengine/core/editor/movementCatalog
+
+- `AuthoredMovementBinding` (interface): interface AuthoredMovementBinding — Stable runtime objects whose numeric getters resolve the current authored document.
+- `AuthoredMovementConfig` (interface): interface AuthoredMovementConfig — Only authored values, ready to overlay on a game's existing movement and physics policy.
+- `AuthoredMovementDefaults` (interface): interface AuthoredMovementDefaults — Game-owned callbacks, collision and physics settings retained beneath authored numeric controls.
+- `AuthoredMovementDiagnostic` (interface): interface AuthoredMovementDiagnostic — A persisted movement value rejected before it can replace the game's current setting.
+- `AuthoredMovementResult` (interface): interface AuthoredMovementResult — Valid partial tuning plus located rejected values; absent rows leave game defaults intact.
+- `AuthoredMovementValues` (interface): interface AuthoredMovementValues — Numeric character controls a game elects to author through its own named catalog rows.
+- `MovementCatalogDocumentLike` (interface): interface MovementCatalogDocumentLike — Structural authored catalog input; an immutable EditorDocument satisfies it.
+- `bindAuthoredMovement` (function): function bindAuthoredMovement(read: () => AuthoredMovementResult, defaults: AuthoredMovementDefaults): AuthoredMovementBinding — Binds live authored numeric controls onto stable runtime objects, preserving the game's callbacks, collision, backend and other policy. The movement controller reads these getters each step.
+- `createAuthoredMovementReader` (function): function createAuthoredMovementReader(getDocument: () => MovementCatalogDocumentLike, catalogId: string, entryId: string): () => AuthoredMovementResult — Memoizes movement resolution by immutable document identity; reads the latest document on every call while catalog lookup and diagnostics run only after authoring changes.
+- `createMovementSchema` (function): function createMovementSchema(defaults: AuthoredMovementValues): ParamSchema — Creates editor/RPC controls only for the values a game supplies, with those game's defaults. Gravity retains the game's sign convention; collision height is positive, other controls nonnegative. Jump release is bounded to 0..1; supplied deeper jump controls share a collapsed response group.
+- `readAuthoredMovement` (function): function readAuthoredMovement(document: MovementCatalogDocumentLike, catalogId: string, entryId: string): AuthoredMovementResult — Reads one game-named row as partial runtime tuning, retaining game defaults for omitted or invalid values. Rejected values include their document path and repair; no policy callbacks are replaced.
+
 ## @jgengine/core/editor/runtimeInspector
 
 - `RuntimeInspectorGetResult` (interface): interface RuntimeInspectorGetResult — One resolved runtime field returned by `runtime_get`.
@@ -284,6 +323,20 @@
 - `runtimeEntityMetaWriteBackCommand` (function): function runtimeEntityMetaWriteBackCommand(document: EditorDocument, entity: RuntimeEntityState): EditorCommand | null — Promotes ephemeral runtime `values` into an undoable meta patch on a document-linked object. Returns null when the id is not in the document or there are no values.
 - `summarizeRuntimeInspector` (function): function summarizeRuntimeInspector(snapshot: RuntimeStateSnapshot, overrides: Readonly<Record<string, RuntimeEntityState>>, play: RuntimePlayControl): RuntimeInspectorSummary — Builds the compact reverse-channel summary used by the play-mode inspector panel and the `runtime_summary` bridge RPC.
 
+## @jgengine/core/editor/simulation
+
+- `AuthoredEmitter` (interface): interface AuthoredEmitter — A named emitter authored in metres, with game-owned appearance and attachment ids.
+- `AuthoredFireArea` (interface): interface AuthoredFireArea — A bounded fire grid; fuel and damage policy remain game content.
+- `AuthoredFlockHabitat` (interface): interface AuthoredFlockHabitat — An authored habitat selects a game species and optionally follows a document path.
+- `EditorSimulation` (interface): interface EditorSimulation — Authored simulation inputs. Runtime particles, heat, accumulation and actors save separately.
+- `decodeEditorSimulation` (function): function decodeEditorSimulation(value: unknown, document?: Pick<EditorDocument, "paths">): EditorSimulation — Decode authoring inputs with located diagnostics and bounded work before any document mutation.
+
+## @jgengine/core/editor/staticPrefab
+
+- `StaticPrefabBake` (interface): interface StaticPrefabBake — Persisted static export settings; source parts remain editable in the prefab fragment.
+- `StaticPrefabBox` (interface): interface StaticPrefabBox — A solid or clearance volume in the prefab's unnormalized local asset space.
+- `parseStaticPrefabBake` (function): function parseStaticPrefabBake(value: unknown): StaticPrefabBake — Validate and copy static prefab export settings from document or RPC input.
+
 ## @jgengine/core/editor/streamer
 
 - `StreamUpdate` (interface): interface StreamUpdate — The residency change produced by one {@link WorldStreamer.update}.
@@ -393,13 +446,15 @@
 - `AssetBrowser` (function): function AssetBrowser({ assets, session, onPlace, }: { assets: readonly EditorAssetEntry[]; session: EditorSession; onPlace: (entry: EditorAssetEntry) => void; }): React.JSX.Element — Searchable panel for placing catalog assets or an empty marker into the scene.
 - `AssetImporter` (type): type AssetImporter = (file: File) => Promise<StandaloneAsset | null> — Persists a dropped model file through the editor host so it survives reload as a durable catalog asset, returning the host-assigned id/url (which the manifest scan re-lists on reload). Resolves `null` when no host is listening — a plain browser mount with no dev server — so the caller can fall back to a blob URL.
 - `BlankPlayableOptions` (interface): interface BlankPlayableOptions — Options for the blank, gameless world the standalone editor authors over.
+- `CreatorApp` (function): function CreatorApp({ gameId, config, onExit }: { gameId: string; config: CreatorConfig; onExit: () => void }): React.JSX.Element — Production creator catalog and embedded editor, reached through the game's menu.
+- `CreatorConfig` (type): type CreatorConfig = CoreCreatorConfig<PlayableGame> — Game-owned creator policy, durable storage and document-to-runtime composition.
 - `DEFAULT_PAINT_SETTINGS` (const): const DEFAULT_PAINT_SETTINGS: PaintSettings — The terrain tool's default paint controls.
 - `DEFAULT_SCULPT_SETTINGS` (const): const DEFAULT_SCULPT_SETTINGS: SculptSettings — The terrain tool's default brush controls.
 - `EDITOR_AGENT_KEY_ENV` (const): const EDITOR_AGENT_KEY_ENV: "JGENGINE_EDITOR_AGENT_KEY" — Env var name for the optional Bearer token (`JGENGINE_EDITOR_AGENT_KEY`).
 - `EDITOR_AGENT_KEY_FALLBACK_ENV` (const): const EDITOR_AGENT_KEY_FALLBACK_ENV: "ANTHROPIC_API_KEY" — Fallback API-key env when `JGENGINE_EDITOR_AGENT_KEY` is unset (`ANTHROPIC_API_KEY`).
 - `EDITOR_AGENT_URL_ENV` (const): const EDITOR_AGENT_URL_ENV: "JGENGINE_EDITOR_AGENT_URL" — Env var name for the remote agent HTTP URL (`JGENGINE_EDITOR_AGENT_URL`).
 - `EDITOR_MCP_TOOLS` (const): const EDITOR_MCP_TOOLS: readonly EditorMcpTool[] — Full set of MCP tools an agent can call to drive the live scene editor.
-- `EditorApp` (function): function EditorApp({ gameId, playable, layers, catalogs, save, modeChip, networkPresence, onExitEditor }: EditorAppProps): React.JSX.Element — Top-level scene editor: author spawns/zones/paths/notes visually over edit, walk, or play modes.
+- `EditorApp` (function): function EditorApp({ gameId, playable, layers, catalogs, save, modeChip, networkPresence, onExitEditor, createPlaytest, validateDocument, playerCreator, allowedAssets, allowedKinds, maxImportBytes, creatorPolicy }: EditorAppProps): React.JSX.Element — Top-level scene editor: author spawns/zones/paths/notes visually over edit, walk, or play modes.
 - `EditorAppProps` (interface): interface EditorAppProps — Props for mounting the scene editor over a playable game.
 - `EditorAssetEntry` (interface): interface EditorAssetEntry — A searchable, placeable asset shown in the editor's asset browser panel.
 - `EditorAssetInfo` (interface): interface EditorAssetInfo — A placeable asset entry offered in the editor's asset browser.
@@ -408,9 +463,12 @@
 - `EditorBridgeServer` (interface): interface EditorBridgeServer — A running editor bridge server: its bound port, URL, and a stop handle.
 - `EditorBridgeServerOptions` (interface): interface EditorBridgeServerOptions — Options for starting the editor's HTTP bridge server: host api, port, hostname.
 - `EditorCameraDriver` (const): const EditorCameraDriver: React.MemoExoticComponent<({ api }: { api: EditorHostApi; }) => null> — Drives the editor orbit camera from the host's focus target. When the target carries only a point, the camera pans to keep it centered (the historical behavior). When it also carries placement (`distance`/`pitch`/`yaw`/`height`), the camera is repositioned to that orbit pose — how `camera_goto`/`camera_frame` compose an aerial without the KeyF-buries-in-terrain problem.
-- `EditorChrome` (function): function EditorChrome({ gameId, session, api, assets, ui, baselineDocument, save, networkSnapshot, importAsset = importAssetToHost, onRegisterAsset, onExitEditor, }: { gameId: string; session: EditorSession; api: EditorHostApi; assets: readonly EditorAssetEntry[]; ui: EditorUiStore; /** The document… — The full editor UI shell — global app bar, contextual scene toolbar, workspace rail, resizable hierarchy/inspector docks, tabbed bottom dock (content browser, console, profiler, AI assistant), viewport overlays, and status bar — wired to the session, UI store, layout store, and host RPC. Mounted by `EditorApp`; not a game-author entry point.
+- `EditorChrome` (function): function EditorChrome({ gameId, session, api, assets, ui, baselineDocument, save, networkSnapshot, importAsset = importAssetToHost, onRegisterAsset, onExitEditor, allowedKinds, exitLabel, maxImportBytes, documentSave, draftAutosave = true, creatorPolicy, }: { gameId: string; session: EditorSession; … — The full editor UI shell — global app bar, contextual scene toolbar, workspace rail, resizable hierarchy/inspector docks, tabbed bottom dock (content browser, console, profiler, AI assistant), viewport overlays, and status bar — wired to the session, UI store, layout store, and host RPC. Mounted by `EditorApp`; not a game-author entry point.
 - `EditorHostApi` (interface): interface EditorHostApi — The live editor's global control surface — session, visibility, camera focus, assets, mode, RPC.
 - `EditorLayerOverlays` (function): function EditorLayerOverlays({ document, visibility, selection, hoverId = null, onSelect, activePathPoint, groundHeightAt, }: { document: EditorDocument; visibility: EditorKindVisibility; selection: readonly string[]; /** Pre-selection hover id from viewport pointer pick; ignored when already select… — Renders every visible marker, volume, path, and note from a document as in-scene 3D gizmos.
+- `EditorMaterialSlotInfo` (type): type EditorMaterialSlotInfo = Readonly<Omit<ModelMaterialSlotInfo, "uvSets">> & { readonly uvSets: readonly number[] } — Canonical imported slot names and mesh prerequisites reported by the loaded model.
+- `EditorMaterialSlotInventory` (type): type EditorMaterialSlotInventory = EditorMaterialSlotReport & { id: string; sourceUrl?: string } — A marker's current imported-model inventory, including an explicit availability state.
+- `EditorMaterialSlotReport` (type): type EditorMaterialSlotReport = | { status: "ready"; slots: readonly EditorMaterialSlotInfo[] } | { status: "loading" } | { status: "unavailable"; reason: string } — A live model-source observation; loading and unavailable reports never contain fabricated slots.
 - `EditorMcpTool` (interface): interface EditorMcpTool — One MCP tool descriptor — same verbs as the in-browser host RPC.
 - `EditorNetworkAdapterKind` (type): type EditorNetworkAdapterKind = MultiplayerAdapterConfig["kind"] | "unknown" — Transport kind declared by the game, or `"unknown"` when the config is unreadable.
 - `EditorNetworkPresenceActor` (interface): interface EditorNetworkPresenceActor — One online actor from a host-supplied presence feed. Fields mirror {@link PresencePoseRow} so hosts can forward backend rows without inventing shape.
@@ -469,6 +527,11 @@
 - `MATERIAL_DRAG_MIME` (const): const MATERIAL_DRAG_MIME: "application/x-jgengine-material" — Custom drag mime carrying a material id — read by hierarchy rows and the viewport drop zone.
 - `assetsFromCatalog` (function): function assetsFromCatalog(ids: readonly string[], resolve?: (id: string) => { url?: string; clips?: readonly string[] } | null): EditorAssetEntry[] — Turns a game's asset catalog ids into editor asset entries for the browser panel.
 
+## @jgengine/editor/CreatorApp
+
+- `CreatorApp` (function): function CreatorApp({ gameId, config, onExit }: { gameId: string; config: CreatorConfig; onExit: () => void }): React.JSX.Element — Production creator catalog and embedded editor, reached through the game's menu.
+- `CreatorConfig` (type): type CreatorConfig = CoreCreatorConfig<PlayableGame> — Game-owned creator policy, durable storage and document-to-runtime composition.
+
 ## @jgengine/editor/DebugDraw
 
 - `EditorLayerOverlays` (function): function EditorLayerOverlays({ document, visibility, selection, hoverId = null, onSelect, activePathPoint, groundHeightAt, }: { document: EditorDocument; visibility: EditorKindVisibility; selection: readonly string[]; /** Pre-selection hover id from viewport pointer pick; ignored when already select… — Renders every visible marker, volume, path, and note from a document as in-scene 3D gizmos.
@@ -476,7 +539,7 @@
 
 ## @jgengine/editor/EditorApp
 
-- `EditorApp` (function): function EditorApp({ gameId, playable, layers, catalogs, save, modeChip, networkPresence, onExitEditor }: EditorAppProps): React.JSX.Element — Top-level scene editor: author spawns/zones/paths/notes visually over edit, walk, or play modes.
+- `EditorApp` (function): function EditorApp({ gameId, playable, layers, catalogs, save, modeChip, networkPresence, onExitEditor, createPlaytest, validateDocument, playerCreator, allowedAssets, allowedKinds, maxImportBytes, creatorPolicy }: EditorAppProps): React.JSX.Element — Top-level scene editor: author spawns/zones/paths/notes visually over edit, walk, or play modes.
 - `EditorAppProps` (interface): interface EditorAppProps — Props for mounting the scene editor over a playable game.
 - `EditorSaveFn` (type): type EditorSaveFn = (json: string) => Promise<{ ok: boolean; path?: string; error?: string }> — Persists an exported document JSON; resolves with where it landed or why it failed.
 
@@ -486,7 +549,11 @@
 
 ## @jgengine/editor/EditorChrome
 
-- `EditorChrome` (function): function EditorChrome({ gameId, session, api, assets, ui, baselineDocument, save, networkSnapshot, importAsset = importAssetToHost, onRegisterAsset, onExitEditor, }: { gameId: string; session: EditorSession; api: EditorHostApi; assets: readonly EditorAssetEntry[]; ui: EditorUiStore; /** The document… — The full editor UI shell — global app bar, contextual scene toolbar, workspace rail, resizable hierarchy/inspector docks, tabbed bottom dock (content browser, console, profiler, AI assistant), viewport overlays, and status bar — wired to the session, UI store, layout store, and host RPC. Mounted by `EditorApp`; not a game-author entry point.
+- `EditorChrome` (function): function EditorChrome({ gameId, session, api, assets, ui, baselineDocument, save, networkSnapshot, importAsset = importAssetToHost, onRegisterAsset, onExitEditor, allowedKinds, exitLabel, maxImportBytes, documentSave, draftAutosave = true, creatorPolicy, }: { gameId: string; session: EditorSession; … — The full editor UI shell — global app bar, contextual scene toolbar, workspace rail, resizable hierarchy/inspector docks, tabbed bottom dock (content browser, console, profiler, AI assistant), viewport overlays, and status bar — wired to the session, UI store, layout store, and host RPC. Mounted by `EditorApp`; not a game-author entry point.
+
+## @jgengine/editor/MaterialAssetEditor
+
+- `MaterialAssetEditorProps` (interface): interface MaterialAssetEditorProps — A callback-driven physical material editor; the host owns persistence, undo and preview rendering.
 
 ## @jgengine/editor/PerfProbe
 
@@ -502,6 +569,10 @@
 - `SelectionGizmo` (const): const SelectionGizmo: React.MemoExoticComponent<({ session, ui, groundSnap, }: { session: EditorSession; ui: EditorUiStore; groundSnap?: ((x: number, z: number) => number) | undefined; }) => React.JSX.Element | null> — Drag-to-transform gizmo bound to the current selection, dispatching editor commands on release. Mounts the shared shell `TransformGizmo` and maps release poses onto editor commands (multi-select translate, volume scale, path vertex move).
 - `ViewportSelect` (const): const ViewportSelect: React.MemoExoticComponent<({ api, ui }: { api: EditorHostApi; ui: EditorUiStore; }) => null> — Canvas click-to-select and click-to-place. Document objects pick by screen proximity (registration always matches what you see) with click-cycling through stacked candidates and shift/ctrl additive selection; everything else picks by occlusion-ordered raycast against the tagged scene graph. When a placement tool is armed, clicks author new markers, volumes, notes, or path points at the ground hit instead of selecting.
 
+## @jgengine/editor/SimulationInspector
+
+- `SimulationInspector` (function): function SimulationInspector({ session, creatorPolicy }: { session: EditorSession; creatorPolicy?: CreatorPolicy }): React.JSX.Element — Production authoring controls share the same validated command and undo history as RPC.
+
 ## @jgengine/editor/StandaloneEditor
 
 - `AssetImporter` (type): type AssetImporter = (file: File) => Promise<StandaloneAsset | null> — Persists a dropped model file through the editor host so it survives reload as a durable catalog asset, returning the host-assigned id/url (which the manifest scan re-lists on reload). Resolves `null` when no host is listening — a plain browser mount with no dev server — so the caller can fall back to a blob URL.
@@ -620,7 +691,7 @@
 
 ## @jgengine/editor/handlers/hierarchy
 
-- `hierarchyHandlers` (const): const hierarchyHandlers: Pick< HandlerTable, | "set_parent" | "hierarchy" | "list_prefabs" | "create_prefab" | "insert_prefab" | "detach_prefab_instance" | "delete_prefab" > — Parent/child hierarchy and prefab library verbs.
+- `hierarchyHandlers` (const): const hierarchyHandlers: Pick< HandlerTable, | "set_parent" | "hierarchy" | "list_prefabs" | "create_prefab" | "insert_prefab" | "detach_prefab_instance" | "delete_prefab" | "set_prefab_static_bake" > — Parent/child hierarchy and prefab library verbs.
 
 ## @jgengine/editor/handlers/minimap
 
@@ -656,6 +727,14 @@
 - `MaterialDocumentSlice` (interface): interface MaterialDocumentSlice — Minimal document slice the materials inventory needs.
 - `MaterialObjectKind` (type): type MaterialObjectKind = "marker" | "volume" | "path" — Document-wide material assignment inventory for the Materials workspace. Reads real `meta.materialId` stamps from placeables — no thumbnails or faked previews.
 
+## @jgengine/editor/materialControls
+
+- `MaterialControl` (interface): interface MaterialControl — One physical surface field in the material workspace.
+- `MaterialControlGroup` (interface): interface MaterialControlGroup — A family-specific group of primary controls; maps and full physical fields remain available.
+- `advancedMaterialControls` (const): const advancedMaterialControls: readonly MaterialControl[] — Complete supported physical scalar/color fields, independent of the six primary groups.
+- `materialAuthoringNotes` (function): function materialAuthoringNotes(asset: MaterialAsset): readonly string[] — Reports geometry prerequisites and renderer approximations to authors.
+- `materialControlGroups` (function): function materialControlGroups(family: MaterialFamily): readonly MaterialControlGroup[] — Returns six primary groups suited to the material family without hiding the physical model.
+
 ## @jgengine/editor/mcp/bridgeServer
 
 - `EditorBridgeServer` (interface): interface EditorBridgeServer — A running editor bridge server: its bound port, URL, and a stop handle.
@@ -672,7 +751,7 @@
 
 ## @jgengine/editor/mcp/fieldSpec
 
-- `RPC_FIELD_SCHEMAS` (const): const RPC_FIELD_SCHEMAS: Record<EditorBridgeRequest["method"], readonly RpcFieldSpec[]> — Per-method field type table — the single source of truth for the RPC boundary. A field listed here is type-checked when present (see `decodeEditorBridgeRequest`); existence is left to `EditorHostApi.handle` (whose per-method guards return honest `ok:false` diagnostics for missing/unknown targets). Type-checking presented fields is what keeps a fuzzed value — a string where a number belongs, a scalar where an object belongs — from reaching a live session uncoerced. Unknown extra fields are ignored so a superset payload stays forward-compatible.
+- `RPC_FIELD_SCHEMAS` (const): const RPC_FIELD_SCHEMAS: Record<EditorBridgeRequest["method"], readonly RpcFieldSpec[]> — Per-method field type table — the single source of truth for the RPC boundary. A field listed here is type-checked when present (see `decodeEditorBridgeRequest`); existence is left to `EditorHostApi.handle` (whose per-method guards return honest `ok:false` diagnostics for missing/unknown targets). Type-checking presented fields is what keeps a fuzzed value — a string where a number belongs, a scalar where an object belongs — from reaching a live session uncoerced. Undeclared top-level fields are rejected by the decoder for every method.
 - `RpcFieldKind` (type): type RpcFieldKind = "string" | "number" | "boolean" | "string[]" | "object" | "object[]" | "vec3" | "value" — The value type a request field is expected to carry.
 - `RpcFieldSpec` (interface): interface RpcFieldSpec — One field's expected shape in a request; `oneOf`/`nullable`/`required`/`of` refine the check.
 - `buildInputSchema` (function): function buildInputSchema(method: EditorBridgeRequest["method"]): Record<string, unknown> — Generates the MCP tool `inputSchema` for a method from its {@link RPC_FIELD_SCHEMAS} entry.
@@ -696,7 +775,7 @@
 
 - `DecodeRpcRequestResult` (type): type DecodeRpcRequestResult = | { ok: true; request: EditorBridgeRequest } | { ok: false; errors: RpcRequestDiagnostic[] } — Result of {@link decodeEditorBridgeRequest}: a request whose `method` is a real one, or the diagnostic that rejected it.
 - `RpcRequestDiagnostic` (interface): interface RpcRequestDiagnostic — One field-level failure surfaced while decoding an untrusted RPC request.
-- `decodeEditorBridgeRequest` (function): function decodeEditorBridgeRequest(raw: unknown): DecodeRpcRequestResult — Validates an untrusted JSON-decoded RPC payload (from `--rpc`, the HTTP bridge, or an agent tool call) before it reaches `EditorHostApi.handle`: confirms it is a plain object carrying a known `method`, then type-checks every field the method understands against {@link RPC_FIELD_SCHEMAS}. A garbled method, or a field whose value is the wrong type (a string where a number belongs, a scalar where an object belongs), is rejected here with a path-specific diagnostic instead of flowing into a live session on a blind cast. Missing fields and unknown extra fields are left for `handle` to interpret so the boundary stays forward-compatible.
+- `decodeEditorBridgeRequest` (function): function decodeEditorBridgeRequest(raw: unknown): DecodeRpcRequestResult — Validates an untrusted JSON-decoded RPC payload (from `--rpc`, the HTTP bridge, or an agent tool call) before it reaches `EditorHostApi.handle`: confirms it is a plain object carrying a known `method`, then type-checks every field the method understands against {@link RPC_FIELD_SCHEMAS}. A garbled method, or a field whose value is the wrong type (a string where a number belongs, a scalar where an object belongs), or an undeclared field is rejected here with a path-specific diagnostic instead of flowing into a live session on a blind cast. Missing fields are left for `handle` to interpret.
 
 ## @jgengine/editor/mcp/stdioServer
 
@@ -724,11 +803,11 @@
 - `clearAnimGraph` (function): function clearAnimGraph(setting: AnimationSetting | undefined): AnimationSetting | undefined — Removes a stored graph so `states`/`oneShots` (or clip roles) drive the placement again.
 - `defaultCustomConfig` (function): function defaultCustomConfig(clips: readonly string[]): AuthoredAnimationConfig — A concrete custom config derived from a rigged asset's clip roles — the `custom` mode seed.
 - `effectiveAnimGraph` (function): function effectiveAnimGraph(setting: AnimationSetting | undefined, clips: readonly string[]): { graph: AnimGraph; source: AnimGraphSource } | null — The graph a placement plays at run time: its stored `graph`, else the locomotion graph of its custom `states`/`oneShots`, else the one clip roles derive for `"auto"` and no-override placements. `null` for `"none"`, a single-clip config, or a rig whose clips have no idle.
-- `readAnimationSetting` (function): function readAnimationSetting(meta: Record<string, unknown> | undefined): AnimationSetting | undefined — Reads and shape-validates the animation override from a marker's meta; undefined when absent/invalid.
+- `readAnimationSetting` (function): function readAnimationSetting(meta: Record<string, unknown> | undefined): AnimationSetting | undefined — Reads a whole valid override, retaining authored fields; malformed values return undefined.
 - `setAnimationMode` (function): function setAnimationMode(setting: AnimationSetting | undefined, mode: AnimationMode, clips: readonly string[] = []): AnimationSetting | undefined — Switches authoring mode. `custom` seeds from the asset's clip-role defaults (so the user starts from a working config, then overrides) when there is no existing object config; the other modes are the bare string/undefined values.
-- `setLocomotionClip` (function): function setLocomotionClip(setting: AnimationSetting | undefined, role: LocomotionRole, clipName: string | null): AuthoredAnimationConfig — Sets or clears (null) a locomotion state clip; forces the setting into `custom`.
-- `setLocomotionNumber` (function): function setLocomotionNumber(setting: AnimationSetting | undefined, key: LocomotionNumber, value: number | null): AuthoredAnimationConfig — Sets or clears (null) a numeric locomotion tuning.
-- `setOneShotClip` (function): function setOneShotClip(setting: AnimationSetting | undefined, event: string, clipName: string | null): AuthoredAnimationConfig — Binds or clears (null) a one-shot event to a clip.
+- `setLocomotionClip` (function): function setLocomotionClip(setting: AnimationSetting | undefined, role: LocomotionRole, clipName: string | null, clips: readonly string[] = []): AuthoredAnimationConfig — Sets or clears (null) a locomotion state clip; forces the setting into `custom`.
+- `setLocomotionNumber` (function): function setLocomotionNumber(setting: AnimationSetting | undefined, key: LocomotionNumber, value: number | null, clips: readonly string[] = []): AuthoredAnimationConfig — Sets or clears (null) a numeric locomotion tuning.
+- `setOneShotClip` (function): function setOneShotClip(setting: AnimationSetting | undefined, event: string, clipName: string | readonly string[] | null): AuthoredAnimationConfig — Binds or clears (null) a one-shot event's clip or variant list.
 - `setTransitionDuration` (function): function setTransitionDuration(setting: AnimationSetting | undefined, graph: AnimGraph, layerId: string, index: number, duration: number): AuthoredAnimationConfig — Sets one transition's crossfade seconds in `graph` and stores the result, so editing a derived graph turns it into an authored one.
 - `storeAnimGraph` (function): function storeAnimGraph(setting: AnimationSetting | undefined, graph: AnimGraph): AuthoredAnimationConfig — Stores `graph` on the placement, keeping its other fields; the stored graph wins at play time.
 
@@ -768,6 +847,9 @@
 - `EditorFocusTarget` (interface): interface EditorFocusTarget — Where the editor orbit camera looks, plus optional placement so a single `camera_goto`/ `camera_frame` can compose an aerial. `x/y/z` is the orbit target (pan-only when that is all that is set — the historical behavior); `distance`, `pitch` (degrees above the horizon), `yaw` (degrees), and `height` reposition the camera around that target when provided.
 - `EditorHostApi` (interface): interface EditorHostApi — The live editor's global control surface — session, visibility, camera focus, assets, mode, RPC.
 - `EditorKindVisibility` (interface): interface EditorKindVisibility — Per-kind show/hide flags for the editor's layer panel.
+- `EditorMaterialSlotInfo` (type): type EditorMaterialSlotInfo = Readonly<Omit<ModelMaterialSlotInfo, "uvSets">> & { readonly uvSets: readonly number[] } — Canonical imported slot names and mesh prerequisites reported by the loaded model.
+- `EditorMaterialSlotInventory` (type): type EditorMaterialSlotInventory = EditorMaterialSlotReport & { id: string; sourceUrl?: string } — A marker's current imported-model inventory, including an explicit availability state.
+- `EditorMaterialSlotReport` (type): type EditorMaterialSlotReport = | { status: "ready"; slots: readonly EditorMaterialSlotInfo[] } | { status: "loading" } | { status: "unavailable"; reason: string } — A live model-source observation; loading and unavailable reports never contain fabricated slots.
 - `EditorPerfSample` (interface): interface EditorPerfSample — Rolling frame-rate sample published by the in-canvas PerfProbe.
 - `EditorRunMode` (type): type EditorRunMode = "edit" | "walk" | "play" | "hud" — How the editor hosts the game: frozen placement view, roamable world, the real game, or HUD-layout authoring.
 - `EditorSession` (interface): interface EditorSession — Stateful, undoable handle for driving scene edits from UI or an MCP agent.
@@ -812,7 +894,7 @@
 
 ## @jgengine/editor/shell/TopAppBar
 
-- `TopAppBar` (function): function TopAppBar({ gameId, onExitToGame, dirty, saveState, lastSavedAt = null, saveAvailable, saveError, canUndo, canRedo, onUndo, onRedo, onSave, onPlay, onWalk, onHud, onImport, onExport, onCopyJson, onOpenPalette, onToggleHelp, onResetLayout, }: { gameId: string; /** When set (editor summoned o… — Global application bar: identity + save state on the left, command palette in the center, history / run controls / document actions on the right. Pause and Step stay disabled in edit mode; Play mode mounts {@link PlayModeBar}, which wires the same controls to the runtime pause/step RPCs so mode switches keep shell chrome.
+- `TopAppBar` (function): function TopAppBar({ gameId, onExitToGame, exitLabel = "Exit to game", dirty, saveState, lastSavedAt = null, saveAvailable, saveError, canUndo, canRedo, onUndo, onRedo, onSave, onPlay, onWalk, onHud, onImport, onExport, onCopyJson, onOpenPalette, onToggleHelp, onResetLayout, }: { gameId: string; /**… — Global application bar: identity + save state on the left, command palette in the center, history / run controls / document actions on the right. Pause and Step stay disabled in edit mode; Play mode mounts {@link PlayModeBar}, which wires the same controls to the runtime pause/step RPCs so mode switches keep shell chrome.
 - `TopBarSaveState` (type): type TopBarSaveState = "idle" | "saving" | "saved" | "error" — Document save lifecycle mirrored from `useDocumentSave`.
 
 ## @jgengine/editor/shell/ViewportOverlays
@@ -987,6 +1069,10 @@
 - `createEditorUiStore` (function): function createEditorUiStore(): EditorUiStore — Creates the shared UI store the editor chrome and viewport both drive.
 - `newPlacementId` (function): function newPlacementId(prefix: string): string — Generates a fresh scene-object id for a placement tool click.
 
+## @jgengine/editor/useDocumentSave
+
+- `EditorDocumentSave` (interface): interface EditorDocumentSave — Document save lifecycle owned by the mounted authoring session, across viewport modes.
+
 ## @jgengine/editor/useF2Chord
 
 - `useF2Chord` (function): function useF2Chord(code: string, onChord: () => void): void — Listens for the engine's F2+<key> chord family and fires on the given code (e.g. "KeyE").

package/skills/jgengine-editor/capabilities.md

@@ -4,6 +4,18 @@
 
 Reach for these before hand-rolling. Each row is *the thing you need* → *the primitive that already does it*.
 
+## authored-material-slots — read validated material assignments from editor marker metadata
+
+- `authoredMaterialAssignments` (function) · `import { authoredMaterialAssignments } from "@jgengine/core/editor/materialAuthoring"`
+
+## creator-export — export validated player scenes with approved catalogs and finite budgets
+
+- `exportCreatorDocument` (function) · `import { exportCreatorDocument } from "@jgengine/core/editor/creatorStorage"`
+
+## creator-storage — save and reopen named versioned player creations through injected durable storage
+
+- `createCreatorDocumentStorage` (function) · `import { createCreatorDocumentStorage } from "@jgengine/core/editor/creatorStorage"`
+
 ## editor-catalogs — Persist gameplay tuning rows on the scene document.
 
 - `EditorCatalogData` (interface) · `import { EditorCatalogData } from "@jgengine/core/editor"`
@@ -68,6 +80,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `createDocumentLiveSync` (function) · `import { createDocumentLiveSync } from "@jgengine/core/editor"`
 - `runtimeEntityWriteBackCommand` (function) · `import { runtimeEntityWriteBackCommand } from "@jgengine/core/editor"`
 
+## editor-material-controls — Explain geometry prerequisites and approximations for a material asset.
+
+- `materialAuthoringNotes` (function) · `import { materialAuthoringNotes } from "@jgengine/editor/materialControls"`
+- `materialControlGroups` (function) · `import { materialControlGroups } from "@jgengine/editor/materialControls"`
+
+## editor-movement — bind live character tuning while preserving distinctive game policy
+
+- `bindAuthoredMovement` (function) · `import { bindAuthoredMovement } from "@jgengine/core/editor/movementCatalog"`
+- `createAuthoredMovementReader` (function) · `import { createAuthoredMovementReader } from "@jgengine/core/editor/movementCatalog"`
+- `createMovementSchema` (function) · `import { createMovementSchema } from "@jgengine/core/editor/movementCatalog"`
+- `readAuthoredMovement` (function) · `import { readAuthoredMovement } from "@jgengine/core/editor/movementCatalog"`
+
 ## editor-runtime-inspector — gate a play-mode frame against pause/step control
 
 - `consumeRuntimePlayStep` (function) · `import { consumeRuntimePlayStep } from "@jgengine/core/editor"`
@@ -82,6 +106,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `bakeMinimapFromDocument` (function) · `import { bakeMinimapFromDocument } from "@jgengine/core/editor"`
 - `documentBakeZones` (function) · `import { documentBakeZones } from "@jgengine/core/editor"`
 
+## model-node-visibility — read authored per-placement model subtree selections
+
+- `authoredHiddenNodes` (function) · `import { authoredHiddenNodes } from "@jgengine/core/editor/modelNodeVisibility"`
+
+## player-creator — create, edit, save, playtest and reopen bounded player scenes through the production editor
+
+- `CreatorApp` (function) · `import { CreatorApp } from "@jgengine/editor"`
+
 ## scene-ownership — audit a whole ownership manifest for boundary violations
 
 - `auditManifest` (function) · `import { auditManifest } from "@jgengine/core/scene/sceneOwnership"`
@@ -90,6 +122,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `isSceneOwnershipManifest` (function) · `import { isSceneOwnershipManifest } from "@jgengine/core/scene/sceneOwnership"`
 - `ownershipKey` (function) · `import { ownershipKey } from "@jgengine/core/scene/sceneOwnership"`
 
+## simulation-inspector — author weather schedules, effects, fire, wind zones, forces and habitats with validated undoable controls
+
+- `SimulationInspector` (function) · `import { SimulationInspector } from "@jgengine/editor/SimulationInspector"`
+
+## validate-simulation — diagnose authored weather, effect, fire, force and habitat documents before publication
+
+- `decodeEditorSimulation` (function) · `import { decodeEditorSimulation } from "@jgengine/core/editor/simulation"`
+
 ## world-convergence — derive environment coordinate content from the scene document
 
 - `environmentContentFromDocument` (function) · `import { environmentContentFromDocument } from "@jgengine/core/editor"`

package/skills/jgengine-editor/reference.md

@@ -8,6 +8,38 @@ in-memory session and, when every RPC succeeds, writes the session document to
 the GUI's Ctrl+S through `devSavePlugin`). Without `--save`, `--rpc` mutations are discarded on
 exit — use it for read-only inspection only, or capture `export_document` yourself.
 
+The source-only CLI writer validates the full document before replacing any saved bytes, matching the dev save endpoint. Validation failures report document paths and leave the existing file intact.
+
+Scene and catalog modules are optional. A present module with a broken dependency, initialization error, or invalid export returns load diagnostics; the CLI and stdio host stop before opening a session or saving. Only absent optional files resolve to empty content.
+
+`dispatch` with `setEnvironment` validates only the candidate environment before changing the session, undo history, or live document revision. Supported presets are `day`, `dusk`, and `night`; custom palette, sun, intensity, and fog fields remain explicit authored values. Invalid inputs report `$.environment` paths. Validated nested fields are copied, so mutating the command afterward cannot change the document. Passing `environment: undefined` removes the bag and remains undoable. Repair unsupported authored values through an explicit editor command; preserve the author's palette and fog rather than substituting a default.
+
+## Atomic authoring batches
+
+Use `document_revision` to inspect the current revision, then send one `push_document_patch` for a complete placement operation. Commands use the `EditorCommand` shapes from `@jgengine/core/editor/commands`, rather than RPC verb shapes. Earlier commands' ids are available to later commands in the same batch:
+
+```json
+{
+  "method": "push_document_patch",
+  "patch": {
+    "type": "commands",
+    "baseRevision": 0,
+    "commands": [
+      { "type": "addMarker", "marker": { "id": "placed_a", "kind": "prop", "catalogId": "my-model", "position": { "x": 1, "y": 0, "z": 2 } } },
+      { "type": "addPath", "path": { "id": "route_a", "kind": "route", "points": [{ "x": 0, "y": 0, "z": 0 }, { "x": 1, "y": 0, "z": 2 }] } },
+      { "type": "createCollection", "id": "region_a", "name": "Region A", "memberIds": ["placed_a", "route_a"] }
+    ]
+  }
+}
+```
+
+`my-model` is a model in the game's own catalog. Send this JSON through `--rpc-file <file> --save`, the live bridge, or the embedded agent's existing tool. Human code can use `session.transaction(commands)` with the same commands and undo contract.
+
+- All commands stage before commit. A malformed command, missing/locked target, parent cycle, or cross-kind object-id collision rejects the whole batch, preserving the document, selection, undo/redo history, revision, and live subscribers. Errors include `commands[N]`; the RPC also returns `result.commandIndex` and the unchanged `result.revision`.
+- A successful edit emits one session notification, publishes one document revision, and forms one undo/redo step. Selection-only changes do not publish or consume document history. `undo`/`redo` commands cannot run inside a transaction.
+- Existing same-kind object ids upsert without automatic renaming. Repeating an already-current transform or stable-id placement succeeds without publishing another revision or consuming history. After a revision conflict, inspect the latest document before retrying against its revision. `force` skips only the revision check; validation and rollback still apply.
+- Explicit copy operations such as `duplicate`, `addFragment`, and `insertPrefab` retain their existing generated-id behavior. Use direct `addMarker`/`addVolume`/`addPath`/`addNote` commands when gameplay needs caller-owned stable ids.
+
 # Editor agent panel (embedded)
 
 Toolbar **Agent** opens a dockable chat panel in `EditorChrome`. Tool calls use the same editor RPC verbs as the MCP/CLI bridge and the GUI — one session undo stack, interleaved with human edits.
@@ -45,6 +77,7 @@ Each `toolCalls[].name` is an editor RPC method (`set_transform`, `select`, …)
 The bridge is trustworthy so agents author instead of hardcoding — every path is honest about failure:
 
 - **Rejected mutations return `ok:false` with a reason.** A locked/cyclic `set_transform`, a `set_parent` that would form a cycle, a collection/prefab verb targeting a missing id, and a batch verb that matches nothing all fail loudly — never a phantom `{ok:true}`.
+- **Command patches are atomic.** `push_document_patch` commands share `EditorSession.transaction` with core live sync: a bad command rolls back the entire batch, and an accepted batch has one undo step and document publication. See [atomic authoring batches](#atomic-authoring-batches).
 - **One decode/migrate boundary.** `decodeEditorDocument` (`@jgengine/core/editor`) validates every field with a path-specific diagnostic (`$.markers[2].position`) and migrates forward; `import_document` and a `push_document_patch` **snapshot** both clear it, so a malformed or old document fails or migrates loudly rather than corrupting a live session.
 - **Document-global id uniqueness.** Placeable ids (markers/volumes/paths/notes) are one namespace: adds re-id on collision, and a single imported document that reuses an id is rejected with its path — a duplicate-id import is impossible. Combine paths (`mergeEditorDocuments`, duplicate, overlay) re-id instead.
 - **Schema-validated input.** `decodeEditorBridgeRequest` type-checks each field a method understands against the per-method schema before it reaches `handle` — a fuzzed value (string where a number belongs, scalar where an object belongs) is rejected at the `--rpc`/HTTP/stdio/agent-tool boundary, never cast in blind. Missing/unknown fields are left to `handle`'s guards so the boundary stays forward-compatible.
@@ -97,13 +130,40 @@ export const STASH_KIND = definePlaceableMarkerKind({
 
 A placed rigged asset's animation override lives at `marker.meta.animation` and reaches the game through `markerAnimation` → `ModelConfig.animation`. It is `"auto"`, `"none"` or a config with `states`, `oneShots` and an optional stored `graph` (an `AnimGraph`, validated with `parseAnimGraph` on read).
 
-- **Inspector → Animation** picks the mode and binds idle/walk/run and one-shot clips.
+- **Inspector → Animation** picks the mode and binds idle/walk/run and one-shot clips. Custom playback exposes rate and Hold pose; choosing Single clip explicitly replaces locomotion states and a stored graph, then exposes seek time and looping. Playback edits preserve the remaining configuration. One-shot lists retain all variants; Ctrl/Cmd-click selects several clips.
+  - The first locomotion edit after single-clip playback seeds the rig's detected role clips, preserving deeper playback settings. Missing idle keeps an explicitly chosen single clip active; without one, playback stays at bind pose and reports the incomplete mapping. Missing walk keeps the idle pose while moving and displays a repair hint. A stored graph remains authoritative.
 - **Animation workspace → Graph** (rail button, or the bottom dock's Animation tab) shows the graph the selected placement plays: layers, states and transitions, with the source (stored, built from states, or derived from clip roles).
   - The scrub slider replays the graph runtime from its entry states. Parameter sliders come from the graph's blend points and conditions.
   - Trigger buttons record a press at the playhead, so scrubbing back and forth replays it. The rig at the camera focus is posed from the runtime's output through the shell's `createGraphPose`.
   - Editing a crossfade, or **Store graph**, writes the graph to `meta.animation.graph` as one undoable edit. **Use derived graph** drops it.
 - Scripted: `set_meta` with `{ "animation": { "graph": { ... } } }` on the marker; see the `jgengine-world` recipe `character-animation.md` for the graph shape.
 
+For a held single-clip pose, use `set_meta` with `{ "animation": { "clip": "Idle", "paused": true, "time": 0.75, "timeScale": 1, "loop": true } }`. Read it with `get_marker`, inspect it in play, adjust through the inspector, and save through the host's normal Save action. Reopen the document and read the same marker id to verify the saved values. `time` seeks single clips; graph playback has its own timeline. A placement without a moving entity remains at speed zero unless the game supplies animation parameters.
+
+A game-owned player spawn can use the same marker's `catalogId` to associate the rig's catalog clips with the Animation inspector. In `defineGame`, set `scenePlacement: { excludeKinds: [...ENTITY_MARKER_KINDS, "player_spawn"] }` (`ENTITY_MARKER_KINDS` comes from `@jgengine/core/world/authoredObjects`). The canonical spawn marker remains available to the game's existing entity-spawn and `markerAnimation` composition, while automatic object placement skips that kind and keeps ordinary props. This exclusion list replaces the default mob/boss list. It controls placement eligibility. Live editor synchronization removes previously authored static objects that become excluded; outside synchronization, existing store objects remain. Game-owned entities are unaffected.
+
+## Character movement tuning
+
+`createMovementSchema` (`@jgengine/core/editor/movementCatalog`) creates ordinary Data-tab controls from game-supplied defaults. Export a named `EditorCatalogDefinition` with that schema and named rows, then use `set_catalog_entry` or the GUI to adjust them. Only supplied controls appear: walk speed, signed world gravity, jump velocity, step height, acceleration, braking, air control, sprint multiplier, crouch multiplier and optional maximum climb grade. No movement style or capsule/backend is selected for the game.
+
+```ts
+const readMovement = createAuthoredMovementReader(
+  () => getDocumentLiveSync()?.getDocument() ?? editorLayers,
+  "player_motion",
+  "player",
+);
+const authored = bindAuthoredMovement(readMovement, {
+  movement: existingMovement,
+  physics: existingPhysics,
+});
+```
+
+Pass `authored.movement` to the playable configuration and `authored.physics` to the game definition's physics. These stable objects expose live numeric getters; policy callbacks, collision settings and backend remain the game's choices. The reader scans only when the immutable document changes. `authored.diagnostics` reports invalid persisted values with document paths and repair guidance; invalid values retain the explicit game fallback. Supply `readMovement().config.walkSpeed` when resolving the game's selected player catalog entry, preserving its other stats and poses. Walk speed applies when that entity spawns or reseats; this API does not overwrite existing entities every frame.
+
+Use the normal edit → play → inspect → adjust → save → reload loop. `get_catalog_entry` inspects saved controls; a fresh `import_document` or reopened scene must produce the same reader result. Runtime tuning requires this explicit binding; merely adding a Data row does not change gameplay. Capsule dimensions and terrain/controller backend configuration remain outside this catalog contract.
+
+`maxClimbGrade` limits heightfield rise per horizontal distance, including airborne travel. Expose it only when the game requires that policy; the optional `climbGradeHeight` sampler remains a game-owned callback retained by the binding. This is independent of a capsule's slope angle and does not select collision geometry.
+
 ## Pure API (`@jgengine/editor`)
 
 ```ts
@@ -182,8 +242,30 @@ save); never hardcode entity stats where the document should own them.
 
 ## Asset import
 
+A prop marker can store `meta.hiddenNodes` as an array of exact imported node names through an undoable `setMarker` metadata edit. Runtime props and the Materials model preview share `modelWithAuthoredNodeVisibility` (`@jgengine/core/editor/modelNodeVisibility`): omitted metadata preserves game model defaults, while `[]` clears that selection. JSON import and editor transactions reject malformed or blank names. Node hiding belongs to the cloned individual model; it does not make originally invisible source nodes visible. Nonempty selections bypass automatic prop batching, and generic scatter rejects them. Entity/player models use explicit `ModelConfig.hiddenNodes`; this marker adapter does not hydrate entity templates.
+
 Dropping a `.glb`/`.gltf` into the editor persists it durably, but where depends on the project shape (`editorHostPlugin`, `@jgengine/node`). A **standalone folder workspace** copies the bytes into the scanned asset folder and re-lists them under a scan-stable id (`importEditorAsset`); the id comes from the file's workspace-relative path, so a placement referencing it resolves after reload. A **promoted game** (one with a typed `src/game/assets.ts` catalog — `isPromotedProject`) instead copies the bytes into `public/<basePath>/imported/` and rewrites `assets.ts` to add a durable `extras` entry to its `buildCatalog({ extras })` call (`importPromotedAsset` → `upsertCatalogExtra`), so the **shipped** game serves and resolves the asset through its own typed catalog rather than a dev-only route. The id matches what a folder rescan would produce, the rewrite is idempotent (re-import of the same id collapses to a single entry), and an unparseable or multi-`buildCatalog` source throws so the host falls back to the folder-scan import rather than corrupt the file.
 
+## Material assets and named slots
+
+The Materials workspace authors `document.materialAssets` through `upsert_material_asset {asset,coalesce?}`. Each versioned `MaterialAsset` has a stable ID, sparse surface fields, explicit capability declarations, texture metadata and provenance (`@jgengine/core/material/materialAsset`). `materialCapabilitiesForAsset(asset)` derives the shader requirements for its fields, maps and fabric/hair adapters; artist edits union those with existing declarations, while RPC validation still rejects undeclared requirements. Empty fields inherit the imported value; resetting a field removes its override. Renaming does not change the ID. Editable wool, cotton, silk, metal, glass, plastic, stone and hair-card starting points describe response; games own textures, models and art direction.
+
+Use `assign_material_asset {ids,materialId,selector}` with a mesh name, material slot name or slot index. Every supplied selector field must match. Separate character skin, eyes, clothing and metal parts with separate assignments. Empty selectors fail rather than flatten a whole imported model. `list_material_assets` reads the library; `remove_material_asset {id}` removes unused assets; `clear_material_assets {ids}` removes selected objects' assignments and restores imported materials. Changes join the scene undo/redo and save path. The workspace exposes roughly six family-specific groups, full physical fields and per-map UV/sampler settings. Neutral and document-light previews use the runtime material renderer; the latter uses the authored environment and fixed sun, while game lighting can add other lights or motion.
+
+Before assigning, select the model and open Materials, then call `list_material_slots {id}` with its authored marker ID. It reports canonical loaded mesh/slot names, local slot indices, material types, UV sets and tangents, including for a document with no material assets yet. `ready` returns observed slots; `loading` and `unavailable` return `ok:false` with an explicit status/reason instead of pretending empty data is loaded. Headless CLI cannot load the renderer. The typed host `getMaterialSlots`/`reportMaterialSlots` seam shares the workspace observation, retains up to 64 inspected model sources and rejects stale reports after a marker or catalog URL changes. Choosing another library asset edits its controls; assign it to a slot to change the selected model.
+
+For generated building-kit models, reuse this same document library through `defineBuildingKit({ materialAssets: document.materialAssets, parts })`. Copy a selected marker's `authoredMaterialAssignments(marker.meta)` into the corresponding model variant's `materialAssignments`; do not create a second kit material catalog. The shell applies named assignments before instanced harvesting, preserving omitted native slots. This path rejects newly assigned height/displacement maps before allocation; choose an individual model renderer for them. Palette materials remain the separate broad surface path; the kit does not author scene placement or repair navigation.
+
+Texture roles define the actual shader channels: roughness G, metalness B, AO R, sheen roughness A, clearcoat roughness G, specular intensity A, transmission R and thickness G. Anisotropy RG stores direction and B strength. Color/emissive/sheen-color/specular-color maps use sRGB; normal and numeric maps use linear data. Alpha maps use G; base-color alpha remains in its color map. Supply real runtime URLs and declare UV set, transform, normal convention, sampler, compression and physical size. Compression metadata does not transcode an image; physical size documents metres while UV transforms control rendering. Repack unsupported channels instead of silently relabelling them.
+
+The installed renderer is Three r182. Its [physical material](https://threejs.org/docs/pages/MeshPhysicalMaterial.html) supports sheen, anisotropy, clearcoat, specular/IOR, transmission/volume and iridescence. Check the installed shader before adding controls: online docs can cover later releases. Transmission needs content behind the surface, adds rendering work and should use opacity 1. Alpha coverage cuts or blends the surface; it does not implement refraction. Directional response needs suitable UVs/normals or authored tangents, and must be reviewed after rotating the mesh or light.
+
+[HDRP's fabric distinction](https://docs.unity3d.com/Packages/com.unity.render-pipelines.high-definition@17.0/manual/understand-fabrics.html) separates diffuse cotton/wool fuzz from directional silk. The fuzzy adapter uses native grazing sheen; the woven adapter adds UV-oriented thread normals and roughness variation. Thread scale is cycles per UV, weave direction is radians, normal strength changes slope and variation changes roughness. Neither creates fibre silhouettes, cloth deformation or collision. Explicit surface values override appearance-adapter defaults.
+
+[Unreal shading models](https://dev.epicgames.com/documentation/en-us/unreal-engine/shading-models-in-unreal-engine) have dedicated hair and cloth responses, including hair scatter/tangent/backlit inputs. [Unreal's groom workflow](https://dev.epicgames.com/documentation/en-us/unreal-engine/hair-rendering-and-simulation-in-unreal-engine) also owns strand geometry and simulation. JGengine's hair cards/strand meshes use an explicit approximation: directional physical highlights, authored coverage and card backlighting. It provides no hair BSDF, multiple scattering, groom, collision or simulation, and its skin family does not supply subsurface scattering. Similar control names do not imply parity. Review front-lit, grazing and backlit views with the actual authored geometry.
+
+For resource review, `materialResourceMetrics` (`@jgengine/shell/render/materialAsset`) estimates loaded texture-view bytes and identifies masked, blended and transmission materials; shared uploads can make that byte estimate an upper bound. Opt in to `measureProjectedOverdraw(renderer,scene,camera,{width,height})` (`@jgengine/shell/render/projectedOverdraw`) to sample actual projected mesh fragments with native alpha discard. It requires float rendering/blending/readback, stalls the GPU, restores scene/renderer ownership and disposes its temporary resources. Depth rejection is disabled, so overlap is an upper bound rather than production early-Z cost; shadow, refraction and postprocessing passes and GPU timing are excluded. Queue and coverage flags overlap. Compare normal renderer draw counters separately, and use hardware measurements for performance claims.
+
 ## Grid / tile layers
 
 Grid-addressed content (rooms, tactics maps, farms, nav/rule layers) lives on the scene document as
@@ -229,3 +311,69 @@ undoable `setMinimapBake` command. Runtime feeds the stored `background`/`bounds
   error inline.
 - RPC/CLI verb: `bake_minimap` (optional `padding`, `resolution`, `waterLevel`). The bake path uses
   no `Date`/`Math.random`, so the same scene + sampler always bakes byte-identical output.
+
+## Terrain and viewport iteration
+
+`create_terrain` rejects invalid dimensions and more than 1,000,000 vertices before allocation; increase `cellSize` for larger maps. Brush coordinates, radius and strength must be finite, radius positive, strength nonnegative. A ramp requires both `toX` and `toZ`; blend strength is 0–1.
+
+`blend_terrain` adds a missing material layer and paints it as one authored action: one notification and one undo. A missed or invalid brush changes neither the layer stack nor undo/redo. `set_terrain_layers` and `EditableTerrain.setLayers` preserve blends by stable layer id across additions, reorder and material parameter edits. Removing a painted layer normalizes surviving weights; replacing every painted layer clears the obsolete buffer.
+
+Viewport placement honors grid snap for marker, zone, note and path points on X/Z, then resamples the authored sculpt composed over the shared base ground field. Paths select along visible segments as well as vertices. Multi-selection gizmos translate the whole group; rotate/scale remain available for individual supported objects.
+
+Terrain-only scenes work with `camera_frame` / Frame all: the authored footprint and sculpt relief contribute to document bounds without a temporary marker. Native runner captures use `drive editor --param editor=standalone` and the same editor RPCs.
+
+Grid placement resamples the authored sculpt composed over the live base ground field at snapped XZ for markers, volumes, notes and draft path points. It uses the same terrain/path policy as the ground overlays (including the ground field’s off-map behavior), and flat Y=0 when no ground sampler is mounted. Nonfinite surface heights reject placement without changing the document or clearing the tool.
+
+## Static prefab export
+
+Keep source parts in `EditorPrefab.fragment` and author export settings with `set_prefab_static_bake`
+(or the `setPrefabStaticBake` command): `prefabId` and `bake: { assetId, collisionBoxes?, clearances? }`.
+`bake: null` clears settings. Save/reopen and undo/redo retain settings alongside the editable parts;
+an invalid setting rejects the whole command without changing history. Each box uses local
+`min`/`max` XYZ triples; clearances add a unique `id`. Clearances require explicit solid boxes and
+may touch their edges but must not overlap them. These are authored constraints, not automatic
+proof that an entrance is navigable for a particular character.
+
+```json
+{"method":"set_prefab_static_bake","prefabId":"courtyard-arch","bake":{"assetId":"own:arch","collisionBoxes":[{"min":[-2,0,-1],"max":[-1,3,1]},{"min":[1,0,-1],"max":[2,3,1]}],"clearances":[{"id":"entry","min":[-1,0,-1],"max":[1,2,1]}]}}
+```
+
+Export pinned source bytes offline with `bakeStaticPrefab` from
+`@jgengine/assets/staticPrefabBake` (Node/Bun only; see `jgengine-assets`). Register the returned
+`dims`, `collisionMesh` and `anchor: "origin"` with the output URL in the game's asset catalog.
+The shared model resolver preserves that authored origin for rendering and collider consumption.
+World placements remain catalog markers in `editor.scene.json`; baking never replaces or moves
+them. Validate the game's real walker/route clearance before advertising walkable interiors.
+
+## Production creator
+
+The game owns its menu and scene rules. The shared creator owns named durable documents, editor mounting, Save and isolated playtests:
+
+```tsx
+import { createCreatorDocumentStorage, type CreatorConfig, type CreatorPolicy } from "@jgengine/core/editor/creatorStorage";
+import { GameHost } from "@jgengine/shell/GameHost";
+import type { PlayableGame } from "@jgengine/shell/registry";
+
+const policy: CreatorPolicy = {
+  maxDocuments: 8, maxBytes: 128_000, maxObjects: 48,
+  maxPathPoints: 128, maxGridCells: 0, maxTerrainVertices: 0,
+  allowedKinds: ["player_spawn", "prop", "checkpoint", "finish"],
+  allowedAssets: ["own:platform"], allowedCatalogIds: ["platform"],
+  validate(document) { validateGameRules(document); },
+};
+const creator: CreatorConfig<PlayableGame> = {
+  policy,
+  storage: createCreatorDocumentStorage({ storage: localStorage, key: "my-game:creator:v1", policy }),
+  initialDocument: () => authoredStartingDocument,
+  createPlayable: document => buildGameFromDocument(document),
+};
+
+<GameHost playable={game} editor={() => import("@jgengine/editor")}
+  creator={creator} creatorOpen={creatorOpen} onCreatorOpenChange={setCreatorOpen} />;
+```
+
+Keep `creator` and its callbacks stable across renders. `createPlayable` recomposes rendering, world and gameplay from the supplied document; do not close over the bundled starting scene. `initialDocument` supplies game-authored content, not an SDK genre preset. Creator saves are version 1 named records and reject optimistic revision conflicts. Saving at the maximum safe integer revision rejects with `Invalid scene revision` before writing; the last valid catalog stays readable. The injected storage promise must resolve only after durable success. The browser adapter writes one bounded catalog value and surfaces access/quota failures; hosted storage can implement the same list/load/save interface with transactional revisions.
+
+The approved Add kinds and asset palette are filtered in the editor. The same validator applies before commands and transactions commit, on import, and on save. External asset URLs, prefab/directive expansion and undeclared simulation budgets are rejected. `maxSimulationParticles`, `maxFireCells`, `maxForceFields` and `maxPopulation` opt into bounded authored simulation (weather reserves 5,300 precipitation particles plus 256 rain-impact slots; collision effects reserve capacity for 32 concurrent child bursts alongside standing emitters); `validate` can restrict species, triggers or required markers. Save/export contain the authored scene; gameplay mutations stay in the captured playtest runtime and are discarded on Return to editor. Returning to saved scenes reopens the last durable save. Unsaved edits stay through Play/Return, and are discarded when leaving the editor catalog entry.
+
+The repeatable snapshot → Play → Return workflow follows the iteration principle in [UEFN playtesting](https://dev.epicgames.com/documentation/en-us/fortnite/playtesting-your-island-in-unreal-editor-for-fortnite). Each Play captures a new validated snapshot; authoring stays locked during isolated play, and Save always writes the editable document.