incanto 0.66.0 → 0.68.0

package/dist/2d.js

@@ -1,7 +1,9 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-Dd7H4bJV.js";
-import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-D0CxCveZ.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-Cji5A6sX.js";
+import { t as showBootFailure } from "./boot-failure-CKYrEcGF.js";
+import { t as isWebGLAvailable } from "./webgl-unavailable-N9nQqesw.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-IZIydDwI.js";
+import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-ibCjm-wH.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-B7Y6dPZO.js";
 //#region src/2d/library-sprite.ts
 /**
 * What a `CharacterController2D`/`3D` will ask a skin to play, and the clip in
@@ -95,4 +97,4 @@ function spriteFromLibraryMeta(meta, opts) {
 	};
 }
 //#endregion
-export { AnimatedSprite2D, Area2D, AssetStore2D, Camera2D, CharacterBody2D, CharacterController2D, ColorRect2D, Joint2D, Label, Node2D, Particles2D, Physics2D, PhysicsBody2D, Renderer2D, RigidBody2D, Sprite2D, StaticBody2D, TileMap2D, UILayer, createGame2D, enablePhysics2D, mergeSolidRects, parseCells, registerNodes2D, spriteFromLibraryMeta, syncTree2D };
+export { AnimatedSprite2D, Area2D, AssetStore2D, Camera2D, CharacterBody2D, CharacterController2D, ColorRect2D, Joint2D, Label, Node2D, Particles2D, Physics2D, PhysicsBody2D, Renderer2D, RigidBody2D, Sprite2D, StaticBody2D, TileMap2D, UILayer, createGame2D, enablePhysics2D, isWebGLAvailable, mergeSolidRects, parseCells, registerNodes2D, showBootFailure, spriteFromLibraryMeta, syncTree2D };

package/dist/3d.d.ts

@@ -1,9 +1,9 @@
-import { D as QualityCaps, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, w as GameStats } from "./behavior-BXNLfIJk.js";
-import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-DAvWQeld.js";
-import { i as SceneJson$1, s as JsonObject } from "./schema-CFeioQRE.js";
+import { c as showBootFailure, i as ParticleSim, o as ParticleView, r as SpatialPose, s as isWebGLAvailable } from "./audio-player-DOrq7sP-.js";
+import { D as QualityCaps, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, w as GameStats, x as EngineOptions } from "./behavior-DoFPYrgo.js";
+import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-CnIOiyNJ.js";
+import { i as SceneJson$1, s as JsonObject } from "./schema-B6ugCV1Q.js";
 import { a as GridCell, c as diffText, d as frameText, i as FrameStatsOptions, l as frameSignature, n as FrameSignature, o as SIGNATURE_GRID, r as FrameStats, s as diffSignatures, t as FrameDiff, u as frameStats } from "./frame-report-DCnHFmto.js";
-import { t as LoadSceneOptions } from "./loader-Cga7FVP4.js";
-import { i as ParticleSim, o as ParticleView, r as SpatialPose } from "./audio-player-_UAcHxnC.js";
+import { t as LoadSceneOptions } from "./loader-CcB533FR.js";
 import { n as PathGrid } from "./pathfinding-_fGrCFmH.js";
 import { AnimationClip, AnimationMixer, BufferGeometry, Color, DirectionalLight, Group, InstancedMesh, Mesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Scene, ShaderMaterial, Texture, Vector3, WebGLRenderer } from "three";
 import { VRM } from "@pixiv/three-vrm";
@@ -133,6 +133,31 @@ interface AnimationEntry {
 */
 declare class AssetStore3D {
   private readonly engine;
+  /**
+  * One geometry and one material per distinct SHAPE and per distinct look.
+  *
+  * `MeshInstance3D._createObject3D` used to `new BoxGeometry()` and
+  * `new MeshPhysicalMaterial()` for every node, even when byte-identical.
+  * Three identical nodes reported `geometry shared? false false / material
+  * shared? false false`, with distinct uuids. Measured at 3,200 units, all
+  * three runs at identical 3,209 draw calls / 1,741,932 triangles and an
+  * identical screenshot:
+  *
+  * ```
+  * per-node geometry + material   31.0 ms wall   (renderMs 27.3)
+  * share one geometry             27.0 ms
+  * + share two materials          15.4 ms        <- 2x the headroom
+  * ```
+  *
+  * 13.1 ms of that 26.5 ms cliff was GPU state churn from per-node objects,
+  * and none of it was visible headlessly: with no renderer `_syncObject3D`
+  * never runs, so the bench measured 55 ns/node instead of ~2,000.
+  *
+  * Renderer-scoped, deliberately — module-level state is the predecessor's
+  * fatal flaw and two games in one page must not share a cache.
+  */
+  readonly meshGeometries: Map<string, unknown>;
+  readonly meshMaterials: Map<string, unknown>;
   private readonly models;
   private readonly animations;
   private readonly modelKeys;
@@ -578,6 +603,16 @@ declare class Physics3D {
   private readonly overlaps;
   private trackOverlap;
   /**
+  * Forget every overlap whose node has left the tree.
+  *
+  * The lazy drop inside `overlapping()` only cleans the SETS of a key someone
+  * asks about, and only when they ask. This clears the KEYS, which is where the
+  * dead nodes were pinned.
+  */
+  /** Drop one node from the overlap map, both as a key and as a member. */
+  private forgetOverlaps;
+  private pruneOverlaps;
+  /**
   * The bodies currently overlapping `node` — the standing answer behind
   * `triggerEnter`/`triggerExit`.
   *
@@ -683,6 +718,18 @@ interface CreateGame3DOptions {
   */
   editor?: boolean | EditorSwitchOptions;
   seed?: number;
+  /**
+  * Namespace this game's persisted settings — volume, language, quality tier.
+  *
+  * They are keyed `incanto:<namespace>:<key>` in the browser's storage and
+  * defaulted to `settings` for everyone, so two Incanto games on one domain
+  * shared one options screen. Measured: game A's player sets `renderScale
+  * 0.25, muted, quality low`; game B, whose source never mentions settings,
+  * boots at a 480x232 drawing buffer and silent.
+  *
+  * `SaveSlots(namespace)` already takes one for exactly this reason.
+  */
+  settings?: EngineOptions["settings"];
   fixedHz?: number;
   pixelRatio?: number;
   /** Keep the frame rate by rendering fewer pixels while frames run slow
@@ -732,7 +779,22 @@ interface GameRenderer {
 }
 interface Game3D {
   engine: Engine;
-  scene: Scene$1;
+  /**
+  * The LIVE scene — a getter over `engine.scene`, not a snapshot.
+  *
+  * This used to be the scene captured at boot. `Engine.setScene` calls
+  * `this._scene?.root.free()`, so after any swap the old handle was not merely
+  * stale, it was EMPTIED — and a single-scene game reaches that through
+  * `flow.restart()`, which `incanto-hud.md` wires to a Start button. Measured:
+  *
+  *   before swap  game.scene.root.children = 2   engine.scene = 2
+  *   after  swap  game.scene.root.children = 0   engine.scene = 2
+  *   game.scene.root.getNode('Flow')  ->  No node at 'Flow'. Children here: [].
+  *
+  * `game.engine.scene` always worked and three skills use it, so there were
+  * two handles with one name and no note saying which was which.
+  */
+  get scene(): Scene$1;
   /**
   * The AUTHORED scene this game booted from — the JSON, not the live tree.
   *
@@ -1028,19 +1090,25 @@ declare class Environment3D {
 }
 //#endregion
 //#region src/3d/environment-runtime.d.ts
+declare function setEnvironment3D(engine: Engine, patch: JsonObject, opts?: {
+  rebaseTierKeys?: boolean;
+}): void;
 /**
-* Live environment editing — the renderer re-applies `scene.environment`
-* every frame (cheap when unchanged), so changing the LOOK at runtime is
-* just writing that object. This helper does it safely:
+* Apply a quality tier — the only caller that may RESET as well as patch.
 *
-*   setEnvironment3D(engine, { sky: { elevationDeg: 4 }, exposure: 0.8 });
-*   setEnvironment3D(engine, { fog: null });          // null DELETES a key
+* A tier is re-applied every time the player moves the slider, so it cannot
+* compose with what the last one left behind: `low` strips the author's bloom,
+* and `high` then has nothing to put back. This re-derives the four tier-owned
+* stages from the scene FILE first, so every tier is reversible, and so a stage
+* the author never wrote can never appear — the contract `settings.ts` states
+* and `incanto-performance.md` promises: *the tier can only take things away.*
 *
-* - one-level deep merge (patching `sky.elevationDeg` keeps the other sky keys)
-* - hard-validates the merged result NOW (in your call stack), so a bad patch
-*   throws where you wrote it — never inside the render loop
+* Measured before this, on a scene with no `bloom` and no `post` in its JSON:
+* `high` and `medium` both rendered five GL passes at 3.3 ms where `low`
+* rendered one at 1.24 ms — 62% of the frame on a chain the game never asked
+* for, and `environment.bloom` read back `{strength: 0.8, threshold: 1}`.
 */
-declare function setEnvironment3D(engine: Engine, patch: JsonObject): void;
+declare function applyQualityTier3D(engine: Engine, patch: JsonObject): void;
 //#endregion
 //#region src/3d/model-verdict.d.ts
 /**
@@ -1336,6 +1404,30 @@ declare class CharacterController3D extends Node3D {
   pitchMax: number;
   /** Spring-arm: pull the orbit camera in front of walls/ground instead of clipping. */
   cameraCollision: boolean;
+  /**
+  * Ride whatever you are standing on.
+  *
+  * `false` restores the old behaviour: the controller steers toward a target
+  * velocity in WORLD space, so standing still on a moving floor brakes you off
+  * it. Turn it off for a conveyor you want to be scenery.
+  */
+  platformCarry: boolean;
+  /** The node the ground probe hit last step, and where it was. */
+  private carriedBy;
+  private carriedFrom;
+  /**
+  * How fast the floor is moving, in world units per second.
+  *
+  * From the POSITION DELTA, not `linearVelocity`, because the documented way
+  * to author a platform is to move its `position` — a behavior, a `PathFollow`,
+  * an `Oscillate` — and that path calls `body.setTranslation`, which teleports
+  * and carries no momentum at all. The delta sees both kinds.
+  *
+  * Only while grounded on the SAME node two steps running: the first step on a
+  * new platform has nothing to compare against, and inventing a velocity there
+  * would fling the player on every step onto one.
+  */
+  private groundCarry;
   turnSpeed: number;
   /** Camera smoothing rate (1-exp(-rate·dt)); side view uses 5. */
   camLerp: number;
@@ -1792,6 +1884,10 @@ declare class MeshInstance3D extends Node3D {
   /** Loader hook: malformed materials fail at LOAD time, not at render. */
   static validateJson(node: Node): void;
   private geometryKey;
+  private materialKey;
+  /** True while this node is using a cache entry it must not dispose. */
+  private sharedGeometry;
+  private sharedMaterial;
   private textureKey;
   private loadedTextures;
   protected override _createObject3D(): Object3D;
@@ -4034,4 +4130,4 @@ declare function createNavDebugNode(nav: TerrainNav, opts?: {
   name?: string;
 }): InstancedMesh3D;
 //#endregion
-export { Area3D, AssetStore3D, type BedSampler, Billboard3D, type BillboardGroupMode, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, type DownhillTraceOptions, Environment3D, type Environment3DConfig, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, type FlowerVariety, Flowers3D, type FogEnvironment, Foliage3D, type FoliageKind, type FoliageStyle, type FrameDiff, type FrameSignature, type FrameStats, type FrameStatsOptions, type Game3D, type GridCell, type HeightSampler, type Heightmap, type HeightmapOptions, InstancedMesh3D, Joint3D, type JointType3D, LoftMesh3D, type LoftSection, MeshInstance3D, type MeshKind, type MeshMaterialProps, type ModelEntry, type ModelFacts, ModelInstance3D, type ModelVerdict, Node3D, OmniLight3D, Particles3D, Physics3D, type Physics3DOptions, PhysicsBody3D, QUARTER_PITCH, type RenderContext3D, type RenderHook3D, Renderer3D, type Renderer3DOptions, type Rig, type RigView, RigidBody3D, type Ripple, River3D, type RiverCarveOptions, type RiverCoverageGap, type RiverHit, type RiverRing, type RiverRingOptions, SIGNATURE_GRID, type SceneJson, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainNav, type TerrainNavOptions, type TerrainTheme, TextureCache3D, type TextureSpec, Trail3D, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, acquireOwnTexture, acquireTexture, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, diffSignatures, diffText, enablePhysics3D, findRiverCoverageGaps, frameSignature, frameStats, frameText, horizonColorFromSky, keyboardIntensity, modelVerdict, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath, verdictText };
+export { Area3D, AssetStore3D, type BedSampler, Billboard3D, type BillboardGroupMode, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, type DownhillTraceOptions, Environment3D, type Environment3DConfig, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, type FlowerVariety, Flowers3D, type FogEnvironment, Foliage3D, type FoliageKind, type FoliageStyle, type FrameDiff, type FrameSignature, type FrameStats, type FrameStatsOptions, type Game3D, type GridCell, type HeightSampler, type Heightmap, type HeightmapOptions, InstancedMesh3D, Joint3D, type JointType3D, LoftMesh3D, type LoftSection, MeshInstance3D, type MeshKind, type MeshMaterialProps, type ModelEntry, type ModelFacts, ModelInstance3D, type ModelVerdict, Node3D, OmniLight3D, Particles3D, Physics3D, type Physics3DOptions, PhysicsBody3D, QUARTER_PITCH, type RenderContext3D, type RenderHook3D, Renderer3D, type Renderer3DOptions, type Rig, type RigView, RigidBody3D, type Ripple, River3D, type RiverCarveOptions, type RiverCoverageGap, type RiverHit, type RiverRing, type RiverRingOptions, SIGNATURE_GRID, type SceneJson, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainNav, type TerrainNavOptions, type TerrainTheme, TextureCache3D, type TextureSpec, Trail3D, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, acquireOwnTexture, acquireTexture, applyQualityTier3D, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, diffSignatures, diffText, enablePhysics3D, findRiverCoverageGaps, frameSignature, frameStats, frameText, horizonColorFromSky, isWebGLAvailable, keyboardIntensity, modelVerdict, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, showBootFailure, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath, verdictText };

package/dist/3d.js

@@ -1,10 +1,12 @@
-import { c as parseEnvironment3D, l as sunDirectionFromElevationAzimuth, s as horizonColorFromSky, u as sunDirectionFromSky } from "./loader-lQDCwNag.js";
+import { c as parseEnvironment3D, l as sunDirectionFromElevationAzimuth, s as horizonColorFromSky, u as sunDirectionFromSky } from "./loader-BC4PNtJX.js";
+import { t as showBootFailure } from "./boot-failure-CKYrEcGF.js";
+import { t as isWebGLAvailable } from "./webgl-unavailable-N9nQqesw.js";
 import { a as frameSignature, n as diffSignatures, o as frameStats, r as diffText, s as frameText, t as SIGNATURE_GRID } from "./frame-report-BSMny7oe.js";
-import { G as StaticBody3D, H as CharacterBody3D, K as Node3D, L as Water3D, R as WATER_CUTOUT_MAX, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, Y as WATER_MAX_RIPPLES, z as WaterCutout3D } from "./gameplay-D1RADWu3.js";
-import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, G as acquireTexture, H as rigPose, I as MeshInstance3D, M as TERRAIN_THEMES, N as terrainThemeLayers, O as BoneAttachment3D, P as Joint3D, R as QUARTER_PITCH, S as Flowers3D, T as CharacterController3D, U as TextureCache3D, V as movementState, W as acquireOwnTexture, _ as LoftMesh3D, a as Tree3D, b as Foliage3D, c as buildRiverRings, d as riverCarveChannels, f as riverStepFor, g as ModelInstance3D, h as Particles3D, i as VoxelGrid3D, j as DEFAULT_TERRAIN_TEXTURE_BASE, k as Billboard3D, l as findRiverCoverageGaps, m as traceDownhillPath, n as registerNodes3D, o as Trail3D, p as smoothCourse, r as VOXEL_PALETTE, s as River3D, u as projectToRiver, v as DirectionalLight3D, w as FLOWER_VARIETIES, x as DENSITY_PRESETS, y as OmniLight3D, z as cameraRelative } from "./environment-presets-BlPsEmq6.js";
-import { a as Environment3D, i as syncTree, o as setEnvironment3D, r as Renderer3D, s as AssetStore3D, t as createGame3D } from "./create-game-DYJCIzO0.js";
+import { G as StaticBody3D, H as CharacterBody3D, K as Node3D, L as Water3D, R as WATER_CUTOUT_MAX, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, Y as WATER_MAX_RIPPLES, z as WaterCutout3D } from "./gameplay-DM1eu_cV.js";
+import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, G as acquireTexture, H as rigPose, I as MeshInstance3D, M as TERRAIN_THEMES, N as terrainThemeLayers, O as BoneAttachment3D, P as Joint3D, R as QUARTER_PITCH, S as Flowers3D, T as CharacterController3D, U as TextureCache3D, V as movementState, W as acquireOwnTexture, _ as LoftMesh3D, a as Tree3D, b as Foliage3D, c as buildRiverRings, d as riverCarveChannels, f as riverStepFor, g as ModelInstance3D, h as Particles3D, i as VoxelGrid3D, j as DEFAULT_TERRAIN_TEXTURE_BASE, k as Billboard3D, l as findRiverCoverageGaps, m as traceDownhillPath, n as registerNodes3D, o as Trail3D, p as smoothCourse, r as VOXEL_PALETTE, s as River3D, u as projectToRiver, v as DirectionalLight3D, w as FLOWER_VARIETIES, x as DENSITY_PRESETS, y as OmniLight3D, z as cameraRelative } from "./environment-presets-CybQXNqS.js";
+import { a as Environment3D, c as AssetStore3D, i as syncTree, o as applyQualityTier3D, r as Renderer3D, s as setEnvironment3D, t as createGame3D } from "./create-game-DbWtVTxD.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-BkHjwJgI.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-bG3n70Ky.js";
 //#region src/3d/model-verdict.ts
 /** Mixamo exports every bone as `mixamorigX`; the retargeter binds by that name. */
 const MIXAMO = /^mixamorig[:_]?/i;
@@ -317,4 +319,4 @@ function createNavDebugNode(nav, opts) {
 	return node;
 }
 //#endregion
-export { Area3D, AssetStore3D, Billboard3D, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, Flowers3D, Foliage3D, InstancedMesh3D, Joint3D, LoftMesh3D, MeshInstance3D, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, PhysicsBody3D, QUARTER_PITCH, Renderer3D, RigidBody3D, River3D, SIGNATURE_GRID, StaticBody3D, TERRAIN_THEMES, Terrain3D, TextureCache3D, Trail3D, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, acquireOwnTexture, acquireTexture, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, diffSignatures, diffText, enablePhysics3D, findRiverCoverageGaps, frameSignature, frameStats, frameText, horizonColorFromSky, keyboardIntensity, modelVerdict, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath, verdictText };
+export { Area3D, AssetStore3D, Billboard3D, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, Flowers3D, Foliage3D, InstancedMesh3D, Joint3D, LoftMesh3D, MeshInstance3D, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, PhysicsBody3D, QUARTER_PITCH, Renderer3D, RigidBody3D, River3D, SIGNATURE_GRID, StaticBody3D, TERRAIN_THEMES, Terrain3D, TextureCache3D, Trail3D, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, acquireOwnTexture, acquireTexture, applyQualityTier3D, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, diffSignatures, diffText, enablePhysics3D, findRiverCoverageGaps, frameSignature, frameStats, frameText, horizonColorFromSky, isWebGLAvailable, keyboardIntensity, modelVerdict, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, showBootFailure, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath, verdictText };

package/dist/{audio-player-_UAcHxnC.d.ts → audio-player-DOrq7sP-.d.ts}

@@ -1,6 +1,42 @@
-import { d as PropSchema, dt as Listener, jt as Node } from "./behavior-BXNLfIJk.js";
-import { a as Rng } from "./schema-CFeioQRE.js";
+import { d as PropSchema, dt as Listener, jt as Node } from "./behavior-DoFPYrgo.js";
+import { a as Rng } from "./schema-B6ugCV1Q.js";
 
+//#region src/core/boot-failure.d.ts
+/**
+* Put a boot failure on the SCREEN, where the player is looking.
+*
+* Every shipped starter preloads its assets behind a `#loading` overlay and
+* removes that overlay on the line after `await createGame*`. So anything that
+* rejects — no WebGL context, a scene that will not load, a 404 the preload
+* insisted on — leaves the overlay standing at "100%" forever, with the reason
+* in a console the player will never open. Measured on a pristine scaffold with
+* WebGL denied:
+*
+* ```
+* control   #loading gone      "Talk to the Elder [E] …"
+* no webgl  #loading present   "Emberwood 100%"      … and still there 8.6 s later
+* ```
+*
+* A bar that reaches 100% and stops reads as a hang, which is the one failure
+* mode a player cannot report usefully. This turns it into a sentence.
+*
+* Headless it does nothing but rethrow-safe logging, so a test that boots a
+* game without a document is unaffected.
+*/
+declare function showBootFailure(error: unknown, opts?: {
+  into?: string;
+}): void;
+//#endregion
+//#region src/core/webgl-unavailable.d.ts
+/**
+* Can this document make a WebGL context at all?
+*
+* The question a game wants BEFORE it boots, so the answer can be a screen
+* instead of an exception. Uses a throwaway canvas and never touches yours;
+* `false` outside a browser, where the question is not meaningful.
+*/
+declare function isWebGLAvailable(): boolean;
+//#endregion
 //#region src/core/particle-sim.d.ts
 /**
 * Deterministic particle pool — pure math, renderer-agnostic, headless-
@@ -197,7 +233,29 @@ declare class AudioPlayer extends Node {
   private spatialElementGain;
   /** The `spatial` option for the SFX path, or undefined when not spatial. */
   private spatialPlay;
-  play(): void;
+  /**
+  * Start the sound. `at` schedules it on the AUDIO clock instead of now.
+  *
+  * A frame is a 16.67 ms grid at 60 Hz and 33.33 ms at 30, so a sound fired
+  * from `update()` cannot land closer than one frame to where a chart wants
+  * it — measured 0 of 64 notes scheduled on the documented path. Queue it a
+  * lead ahead of `engine.sfx.now` and the same notes land at |mean| 0.000000
+  * ms:
+  *
+  * ```ts
+  * const lead = 0.08;                        // schedule this far ahead
+  * for (const note of dueSoon(engine.sfx.now + lead)) {
+  *   hit.play(engine.sfx.now + (note.atSec - songSeconds));
+  * }
+  * ```
+  *
+  * PRESETS only — a `src` clip goes through an `<audio>` element, which has no
+  * scheduling clock, and passing `at` for one is ignored rather than silently
+  * approximated. Everything else is unchanged: the bus gain applies, the sound
+  * lands in `engine.audio.recent()`, and `muted` still silences it, none of
+  * which a hand-rolled `AudioContext` scheduler keeps.
+  */
+  play(at?: number): void;
   /**
   * Procedural-SFX path: synthesize the preset and fire it through WebAudio
   * (low-latency, overlap-friendly). Headless (no AudioContext) plays nothing —
@@ -222,4 +280,4 @@ declare class AudioPlayer extends Node {
   override update(_dt: number): void;
 }
 //#endregion
-export { ParticleSimConfig as a, ParticleSim as i, AudioPlayer as n, ParticleView as o, SpatialPose as r, AudioElementLike as t };
+export { ParticleSimConfig as a, showBootFailure as c, ParticleSim as i, AudioPlayer as n, ParticleView as o, SpatialPose as r, isWebGLAvailable as s, AudioElementLike as t };

package/dist/{behavior-BXNLfIJk.d.ts → behavior-DoFPYrgo.d.ts}

@@ -1,4 +1,4 @@
-import { a as Rng, c as JsonValue, i as SceneJson, s as JsonObject } from "./schema-CFeioQRE.js";
+import { a as Rng, c as JsonValue, i as SceneJson, s as JsonObject } from "./schema-B6ugCV1Q.js";
 
 //#region src/core/signal.d.ts
 /**
@@ -16,6 +16,15 @@ declare class Signal<Args extends unknown[] = unknown[]> {
   }): () => void;
   disconnect(fn: SignalListener<Args>): void;
   disconnectAll(): void;
+  /**
+  * How many listeners are attached.
+  *
+  * A leak is a SLOPE, and a game had no way to see one: every check in this
+  * engine is a snapshot. A handler connected per frame and never disconnected,
+  * or a `once` that armed and never fired, accumulates invisibly and is
+  * perfectly healthy for the first thirty seconds of every playthrough.
+  */
+  get count(): number;
   emit(...args: Args): void;
   get connectionCount(): number;
 }
@@ -247,6 +256,14 @@ declare class Node implements NodeLifecycle {
     once?: boolean;
   }): () => void;
   off(signal: string, fn: SignalListener<unknown[]>): void;
+  /**
+  * How many listeners this node has on `signal` — 0 for one nobody watches.
+  *
+  * The engine's own leak test reads it, and so can a game: a handler connected
+  * every frame and never disconnected is invisible to every other check here,
+  * because every other check is a snapshot and a leak is a slope.
+  */
+  listenerCount(signal: string): number;
   emit(signal: string, ...args: unknown[]): void;
   /**
   * Defer destruction to the end of the current update pass (flushed by the
@@ -402,6 +419,12 @@ interface MusicTrack {
   play(): void;
   /** Stop and release the underlying element/source. */
   stop(): void;
+  /**
+  * Seconds into the track, or `null` when the backend cannot say.
+  *
+  * Optional so an existing custom backend keeps compiling.
+  */
+  playhead?(): number | null;
 }
 /** Backend that mints {@link MusicTrack}s — WebAudio-backed in the browser. */
 interface MusicBackend {
@@ -453,6 +476,22 @@ declare class MusicManager {
   constructor(buses: AudioBuses);
   /** Source of the logically-current track, or null when nothing is playing. */
   get current(): string | null;
+  /**
+  * Seconds into the current track — the playhead of the thing you can HEAR.
+  *
+  * `null` when nothing is playing, or when the backend has no clock (headless,
+  * or a custom backend that does not implement it).
+  *
+  * A game charted to a soundtrack needs this and there was no way to get it:
+  * `current` gave the src and the backend was private, so the only option was
+  * an `engine.time` counter started next to `music.play()` — a different clock
+  * from the one the audio is on, and one that keeps counting through a
+  * gesture-block, a stall or a seek. This is the audio's own answer.
+  *
+  * It is the RAW element time, so a looping track wraps to 0 at each pass:
+  * that is a loop boundary you can chart against, not a fault.
+  */
+  get playhead(): number | null;
   /** Per-manager volume (0..1), on top of the bus gain. */
   get volume(): number;
   /**
@@ -677,6 +716,23 @@ interface SfxPlayOptions {
   seed?: number;
   /** When set, the sound is spatialized through a PannerNode at this emitter. */
   spatial?: SpatialPlay;
+  /**
+  * Start at this point on the AUDIO clock (`engine.sfx.now` + lead), instead
+  * of "as soon as this call returns".
+  *
+  * Nothing in the audio API took a time, so a sound could only be fired from a
+  * frame — and a frame is a 16.67 ms grid at 60 Hz, 33.33 ms at 30. Measured
+  * on a metronome: firing from `update()` gave 0 of 64 notes a scheduled
+  * start; the same notes queued one frame ahead with `when` land at
+  * |mean| 0.000000 ms. That difference is the whole of a rhythm game, and
+  * anything charted to a soundtrack.
+  *
+  * A time already past plays immediately (Web Audio's own rule), so a late
+  * scheduler degrades instead of going silent. The bus gain and the
+  * `engine.audio.recent()` record apply either way — which is what a
+  * hand-rolled `AudioContext` scheduler loses.
+  */
+  when?: number;
 }
 /**
 * One AudioContext + a PCM cache. Instance-scoped (held by the renderer's game
@@ -724,6 +780,14 @@ declare class SfxEngine {
   /** Resume a gesture-suspended context (wired to the first user gesture). */
   unlock(): void;
   /**
+  * The AUDIO clock, in seconds — the one a sound is actually scheduled
+  * against, and the only clock that does not drift relative to what you hear.
+  *
+  * `0` headless and before the first sound, since there is no context yet.
+  * Schedule with a lead: `sfx.play(params, 1, { when: sfx.now + 0.08 })`.
+  */
+  get now(): number;
+  /**
   * Play a preset at `gain` (0..1, already bus-multiplied by the caller). Each
   * call spawns its own source so rapid repeats overlap instead of cutting off.
   * Headless → no-op.
@@ -1165,6 +1229,25 @@ interface SaveStore {
   remove(key: string): void;
   /** Wipe THIS namespace only. */
   clear(): void;
+  /**
+  * Does a write here survive the page closing?
+  *
+  * `false` means this store is a Map that lives as long as the tab does — a
+  * private window, storage disabled, quota exhausted, or headless. Everything
+  * still works IN the session, which is exactly what made it undetectable:
+  * measured in Safari-private conditions, `set('highScore', 4200)` then
+  * `get('highScore', 0)` returned 4200, zero warnings, and the interface had
+  * no way to ask. On reload the score was 0, the slot list empty, and
+  * `SavePoint` had emitted `saved(1)` for a write that went nowhere.
+  *
+  * Read it once and tell the player their progress will not be kept.
+  *
+  * Optional so a game that injects its OWN store (a cloud backend, a test
+  * double) keeps compiling; absent counts as persistent, which is what a store
+  * somebody wrote on purpose almost always is. Every store the engine makes
+  * says so explicitly.
+  */
+  readonly persistent?: boolean;
 }
 declare function createSaveStore(namespace: string): SaveStore;
 //#endregion
@@ -1220,7 +1303,8 @@ interface RestoreReport {
 declare function captureBehaviors(root: Node, source?: JsonValue): {
   state: BehaviorState; /** Paths of nodes that had state to save and no uid to save it under. */
   unaddressable: string[]; /** Behaviors in this tree that have something to save — addressable or not. */
-  saveable: number;
+  saveable: number; /** Authored nodes this run consumed that the `#freed` ledger cannot record. */
+  unrecordable: string[];
 };
 /**
 * Hand each behavior its state back.
@@ -1243,6 +1327,15 @@ declare function restoreBehaviors(root: Node, state: BehaviorState): RestoreRepo
 declare class SaveSlots {
   private readonly store;
   constructor(namespace?: string, store?: SaveStore);
+  /**
+  * Will these slots survive the page closing?
+  *
+  * `false` in a private window, with storage disabled, or headless — every
+  * write still succeeds and every read still answers, for as long as the tab
+  * lives. A load menu should say so instead of offering a slot that will not
+  * be there tomorrow.
+  */
+  get persistent(): boolean;
   /** Slot ids that have a save, newest first. */
   list(): string[];
   /** Every slot with its contents — what a load menu actually renders. */
@@ -1313,6 +1406,8 @@ declare class Scene {
   readonly orderGroups: Record<string, number> | undefined;
   /** Physics config (gravity etc. — interpreted by the physics modules). */
   readonly physics: JsonObject | undefined;
+  /** Declared piece of another scene — see `SceneJson.fragment`. */
+  readonly fragment: boolean | undefined;
   /** Multiplayer config (room etc. — interpreted by incanto/net). */
   readonly multiplayer: JsonObject | undefined;
   /** Design-resolution viewport (consumed by renderers via resolveViewport). */
@@ -1600,6 +1695,26 @@ interface EngineOptions {
   seed?: number;
   /** Frame cap in fps; 0 (default) runs at whatever the display offers. */
   maxFps?: number;
+  /**
+  * Which SETTINGS this game owns — its own, or the origin's.
+  *
+  * Persisted settings are keyed `incanto:<namespace>:<key>` in the browser's
+  * storage, and this defaulted to `settings` with no way to change it. So two
+  * Incanto games served from one domain shared one volume slider, one language
+  * and one quality tier. Measured: game A's player sets
+  * `renderScale 0.25, muted, quality low`; game B — whose source never mentions
+  * settings — boots at a 480×232 drawing buffer, silent.
+  *
+  * `SaveSlots(namespace)` and `createSaveStore(namespace)` have always taken
+  * one and document it as "keeps two games on one origin apart". This is the
+  * third sibling finally saying the same thing.
+  *
+  * Pass a `Settings` instance instead when a game wants to share deliberately
+  * (a launcher and its titles), or drive them from its own store.
+  */
+  settings?: Settings | {
+    namespace: string;
+  };
 }
 /**
 * The game loop: drives a Scene's tree with fixed-timestep `fixedUpdate`

package/dist/boot-failure-CKYrEcGF.js

@@ -0,0 +1,47 @@
+import { t as IncantoError } from "./errors-BpWbnbb_.js";
+//#region src/core/boot-failure.ts
+/**
+* Put a boot failure on the SCREEN, where the player is looking.
+*
+* Every shipped starter preloads its assets behind a `#loading` overlay and
+* removes that overlay on the line after `await createGame*`. So anything that
+* rejects — no WebGL context, a scene that will not load, a 404 the preload
+* insisted on — leaves the overlay standing at "100%" forever, with the reason
+* in a console the player will never open. Measured on a pristine scaffold with
+* WebGL denied:
+*
+* ```
+* control   #loading gone      "Talk to the Elder [E] …"
+* no webgl  #loading present   "Emberwood 100%"      … and still there 8.6 s later
+* ```
+*
+* A bar that reaches 100% and stops reads as a hang, which is the one failure
+* mode a player cannot report usefully. This turns it into a sentence.
+*
+* Headless it does nothing but rethrow-safe logging, so a test that boots a
+* game without a document is unaffected.
+*/
+function showBootFailure(error, opts = {}) {
+	const message = error instanceof IncantoError ? error.message : String(error?.message ?? error);
+	const code = error instanceof IncantoError ? error.code : null;
+	console.error(`[incanto] the game could not start${code ? ` (${code})` : ""}: ${message}`);
+	const doc = globalThis.document;
+	if (!doc?.body) return;
+	const host = opts.into ? doc.querySelector(opts.into) : doc.querySelector("#loading");
+	const panel = host ?? doc.createElement("div");
+	if (!host) {
+		panel.style.cssText = "position:fixed;inset:0;display:grid;place-content:center;gap:12px;padding:32px;background:#10131a;color:#e6e9ef;z-index:2147483647;font:14px/1.6 system-ui,sans-serif;text-align:center";
+		doc.body.appendChild(panel);
+	}
+	panel.textContent = "";
+	const title = doc.createElement("div");
+	title.textContent = "This game could not start";
+	title.style.cssText = "font-size:18px;font-weight:600;margin-bottom:8px";
+	const detail = doc.createElement("div");
+	detail.textContent = message;
+	detail.style.cssText = "opacity:.85;max-width:52ch;margin:0 auto";
+	panel.appendChild(title);
+	panel.appendChild(detail);
+}
+//#endregion
+export { showBootFailure as t };