incanto 0.67.0 → 0.68.0

package/bin/_pick-server.mjs

@@ -0,0 +1,48 @@
+/**
+ * Which of the dev servers that answered is THIS project's — the one decision
+ * `incanto-frame` and `incanto-logs` must never get wrong, in one place.
+ *
+ * They each had their own copy, and each copy had the same hatch: when exactly
+ * one server answered and it did not say whose it was, take it anyway ("an
+ * older incanto that predates the identity field"). A server that will not
+ * identify itself is the ONE kind the check cannot clear, so the hatch let
+ * through precisely what it was written to stop. Measured in an empty temp
+ * directory with one foreign page listening, on a scene with two nodes and no
+ * assets:
+ *
+ *     ✓ draws — subject fills 37.5% of the frame
+ *     ✗ says — asset …/NO-SUCH-TEXTURE.jpg never loaded: 404
+ *
+ * A ✓ measured off another game, and a ✗ naming a texture that appears nowhere
+ * in this project. It surfaced in this repo as an intermittent failure of
+ * `incanto-verify.test.ts`, which is a gate that lies in both directions.
+ *
+ * The real dev server has sent `root` since 0.41 (`frame-endpoint.test.ts`
+ * pins it), so nothing is lost; `--port` still names a server on purpose.
+ */
+
+/** Is `body.root` this directory, an ancestor of it, or inside it? */
+export function sameProject(body, cwd) {
+  if (!body?.root) return false;
+  const root = String(body.root);
+  return root === cwd || cwd.startsWith(`${root}/`) || root.startsWith(`${cwd}/`);
+}
+
+/**
+ * `{ pick }` when one of them is ours, `{ refusal }` when some answered and
+ * none is, `{}` when nothing answered at all (the caller says "no dev server").
+ */
+export function pickServer(answered, cwd, what) {
+  const mine = answered.filter((a) => sameProject(a, cwd));
+  if (mine.length > 0) return { pick: mine[0] };
+  if (answered.length === 0) return {};
+  const listed = answered
+    .map((a) => `  :${a.port}  ${a.project || '(unnamed)'}  ${a.root ?? "doesn't say"}`)
+    .join('\n');
+  return {
+    refusal:
+      `${answered.length} incanto dev server(s) are running and none of them is this ` +
+      `directory (${cwd}):\n${listed}\n\n${what}\n` +
+      "Start this project's dev server, or pass --port.",
+  };
+}

package/bin/incanto-check.mjs

@@ -155,7 +155,9 @@ if (files.length === 0) {
   process.exit(1);
 }
 
-const { auditScene, validateScene } = await import(pathToFileURL(join(DIST, 'test.js')).href);
+const { auditScene, instancedScenes, validateScene } = await import(
+  pathToFileURL(join(DIST, 'test.js')).href
+);
 
 /**
  * Every `strings` table in the corpus, unioned.
@@ -176,9 +178,16 @@ const declaredElsewhere = {};
  * part of its project it can.
  */
 const declaredAssets = {};
+/**
+ * Every scene some OTHER scene embeds — the only honest way to tell a fragment
+ * from a first draft. Without it a 3D scene with no camera and no light checked
+ * CLEAN, because "has no camera" was doing double duty as "is a fragment".
+ */
+const corpus = [];
 for (const file of files) {
   try {
     const doc = JSON.parse(readFileSync(file, 'utf-8'));
+    corpus.push({ path: resolve(file), json: doc });
     for (const [locale, entries] of Object.entries(doc?.strings ?? {})) {
       if (typeof entries !== 'object' || entries === null) continue;
       declaredElsewhere[locale] = { ...(declaredElsewhere[locale] ?? {}), ...entries };
@@ -191,6 +200,8 @@ for (const file of files) {
   }
 }
 
+const instanced = instancedScenes(corpus, (from, ref) => resolve(dirname(from), ref));
+
 const results = files.map((file) => {
   let json;
   try {
@@ -207,7 +218,10 @@ const results = files.map((file) => {
     return {
       file,
       ok: true,
-      warnings: [...auditScene(json, { declaredElsewhere }), ...missingArt(file, json)],
+      warnings: [
+        ...auditScene(json, { declaredElsewhere, instanced: instanced.has(resolve(file)) }),
+        ...missingArt(file, json),
+      ],
     };
   }
   return {

package/bin/incanto-frame.mjs

@@ -20,6 +20,7 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { pickServer } from './_pick-server.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 const { listeningPorts, parseProcNetTcp } = await import(
@@ -171,11 +172,6 @@ const answered = [];
 // is plainly on screen.
 const HOSTS = ['localhost', '127.0.0.1'];
 const CWD = process.cwd();
-const sameProject = (b) => {
-  if (!b?.root) return false;
-  const r = String(b.root);
-  return r === CWD || CWD.startsWith(`${r}/`) || r.startsWith(`${CWD}/`);
-};
 for (const port of ports) {
   for (const host of HOSTS) {
     try {
@@ -197,26 +193,15 @@ for (const port of ports) {
 if (explicit) {
   found = answered[0] ?? null;
 } else {
-  const mine = answered.filter(sameProject);
-  if (mine.length > 0) {
-    found = mine[0];
-  } else if (answered.length === 1 && answered[0].root === undefined) {
-    // An older dev server that predates the identity field. Take it, but say so.
-    found = answered[0];
-    console.error(
-      `· the dev server on :${found.port} does not report which project it is ` +
-        '(older incanto) — if this reads the wrong game, pass --port.',
-    );
-  } else if (answered.length > 0) {
-    console.error(
-      `${answered.length} incanto dev server(s) are running and NONE of them is this ` +
-        `directory (${CWD}):\n` +
-        answered
-          .map((a) => `  :${a.port}  ${a.project || '(unnamed)'}  ${a.root ?? '?'}`)
-          .join('\n') +
-        "\n\nMeasuring one project on another project's page reports a number that has\n" +
-        "nothing to do with this game. Start this project's dev server, or pass --port.",
-    );
+  const { pick, refusal } = pickServer(
+    answered,
+    CWD,
+    "Measuring one project on another project's page reports a number that has\n" +
+      'nothing to do with this game.',
+  );
+  if (pick) found = pick;
+  else if (refusal) {
+    console.error(refusal);
     process.exit(1);
   }
 }

package/bin/incanto-logs.mjs

@@ -21,6 +21,7 @@ import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { pickServer } from './_pick-server.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 const { listeningPorts } = await import(pathToFileURL(join(PKG, 'dist', 'vite.js')).href);
@@ -80,11 +81,6 @@ let found = null;
 // project's page answered both the frame and the logs request.
 const answered = [];
 const CWD = process.cwd();
-const sameProject = (b) => {
-  if (!b?.root) return false;
-  const r = String(b.root);
-  return r === CWD || CWD.startsWith(`${r}/`) || r.startsWith(`${CWD}/`);
-};
 for (const port of ports) {
   for (const host of ['localhost', '127.0.0.1']) {
     try {
@@ -105,20 +101,14 @@ for (const port of ports) {
 if (explicit) {
   found = answered[0] ? { host: answered[0].host, port: answered[0].port } : null;
 } else {
-  const mine = answered.filter(sameProject);
-  const pick =
-    mine[0] ?? (answered.length === 1 && answered[0].root === undefined ? answered[0] : null);
+  const { pick, refusal } = pickServer(
+    answered,
+    CWD,
+    "Reading another project's log buffer would report its errors as yours.",
+  );
   if (pick) found = { host: pick.host, port: pick.port };
-  else if (answered.length > 0) {
-    console.error(
-      `${answered.length} incanto dev server(s) are running and none is this directory ` +
-        `(${CWD}):\n` +
-        answered
-          .map((a) => `  :${a.port}  ${a.project || '(unnamed)'}  ${a.root ?? '?'}`)
-          .join('\n') +
-        "\n\nReading another project's log buffer would report its errors as yours.\n" +
-        "Start this project's dev server, or pass --port.",
-    );
+  else if (refusal) {
+    console.error(refusal);
     process.exit(1);
   }
 }

package/dist/2d.d.ts

@@ -1,10 +1,10 @@
-import { 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-ZnfzKDo3.js";
-import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-DAvWQeld.js";
-import { i as SceneJson, 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 { 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, s as JsonObject } from "./schema-B6ugCV1Q.js";
 import { r as FrameStats } from "./frame-report-DCnHFmto.js";
-import { t as LoadSceneOptions } from "./loader-DyT30ArB.js";
+import { t as LoadSceneOptions } from "./loader-CcB533FR.js";
 import { n as AnimationEntry } from "./sprite-animation-CMr6f1K2.js";
-import { i as ParticleSim, o as ParticleView, r as SpatialPose } from "./audio-player-BNUHo0JF.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
 import * as RapierNs from "@dimforge/rapier2d-compat";
 
@@ -1247,4 +1247,4 @@ declare function parseCells(cells: readonly (string | readonly number[])[], lege
 */
 declare function mergeSolidRects(grid: readonly (readonly number[])[], solid: Set<number>): TileRect[];
 //#endregion
-export { AnimatedSprite2D, Area2D, type AssetStatus, AssetStore2D, Camera2D, CharacterBody2D, CharacterController2D, ColorRect2D, type CreateGame2DOptions, type Game2D, Joint2D, type JointType2D, Label, Node2D, Particles2D, Physics2D, type Physics2DOptions, PhysicsBody2D, Renderer2D, type Renderer2DOptions, type ResolvedSpriteTexture, RigidBody2D, type SheetInfo, Sprite2D, type SpriteFromLibraryResult, StaticBody2D, type Sync2DResult, type TextureLoadCallbacks, TileMap2D, type TileRect, type UIAnchor, UILayer, createGame2D, enablePhysics2D, mergeSolidRects, parseCells, registerNodes2D, spriteFromLibraryMeta, syncTree2D };
+export { AnimatedSprite2D, Area2D, type AssetStatus, AssetStore2D, Camera2D, CharacterBody2D, CharacterController2D, ColorRect2D, type CreateGame2DOptions, type Game2D, Joint2D, type JointType2D, Label, Node2D, Particles2D, Physics2D, type Physics2DOptions, PhysicsBody2D, Renderer2D, type Renderer2DOptions, type ResolvedSpriteTexture, RigidBody2D, type SheetInfo, Sprite2D, type SpriteFromLibraryResult, StaticBody2D, type Sync2DResult, type TextureLoadCallbacks, TileMap2D, type TileRect, type UIAnchor, UILayer, createGame2D, enablePhysics2D, isWebGLAvailable, mergeSolidRects, parseCells, registerNodes2D, showBootFailure, spriteFromLibraryMeta, syncTree2D };

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-DMetd3vR.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-vIxU3Xbv.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-_B6zj3zU.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, x as EngineOptions } from "./behavior-ZnfzKDo3.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-DyT30ArB.js";
-import { i as ParticleSim, o as ParticleView, r as SpatialPose } from "./audio-player-BNUHo0JF.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";
@@ -1404,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;
@@ -4106,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, applyQualityTier3D, 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-KZESOZmE.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-CGSv-9XR.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-C-5g2pMh.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-FAXdHta3.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-i1IeAY0F.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, applyQualityTier3D, 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-BNUHo0JF.d.ts → audio-player-DOrq7sP-.d.ts}

@@ -1,6 +1,42 @@
-import { d as PropSchema, dt as Listener, jt as Node } from "./behavior-ZnfzKDo3.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-ZnfzKDo3.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
 /**
@@ -419,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 {
@@ -470,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;
   /**
@@ -694,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
@@ -741,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.
@@ -1182,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
@@ -1261,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. */
@@ -1331,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). */

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 };