@glissade/scene 0.59.0-pre.0 → 0.59.0-pre.1

package/dist/describe.js

@@ -23,7 +23,7 @@ import { easings, listValueTypes } from "@glissade/core";
 * never pulled onto the base embed path — a scene that never calls `describe()`
 * pays zero bytes for it.
 */
-const RAW_VERSION = "0.59.0-pre.0";
+const RAW_VERSION = "0.59.0-pre.1";
 const PACKAGE_VERSION = RAW_VERSION.includes("GLISSADE_".concat("VERSION")) ? "0.0.0-dev" : RAW_VERSION;
 /**
 * Parse the documented positional-arg count from a helper `usage` string — the
@@ -568,7 +568,7 @@ const HELPERS = [
 		name: "createPlayer",
 		summary: "Build the transport object (play / pause / seek / rate / loop / marker + cue callbacks) directly — what mount() returns as mounted.player.",
 		import: "@glissade/player",
-		usage: "createPlayer({ playhead: createPlayhead(), duration: 2 }, { loop?: boolean }): Player  —  player.play() → { finished }, player.pause(), player.seek(u), player.rate = 2, player.onMarker(name, cb), player.onCue(kind, cb)"
+		usage: "createPlayer({ playhead: createPlayhead(), duration: 2 }, { loop?: boolean }): Player  —  player.play() → { finished }, player.pause(), player.seek(t: seconds), player.rate = 2, player.onMarker(name, cb), player.onCue(kind, cb)"
 	},
 	{
 		name: "mount",

package/dist/diagnostics.d.ts

@@ -152,21 +152,31 @@ declare function validateSceneFonts(scene: Scene, doc: Timeline, loadBytes: Font
 declare const DIAGNOSTIC_SCHEMA_VERSION: 1;
 /** Closed severity ladder. `error` = a build error (unbound target); `warning`
  *  = a probable-mistake (position of a flow child); `info` = a valid-but-notable
- *  observation (off-canvas, estimating measurer). */
+ *  observation (estimating measurer). */
 type DiagnosticSeverity = 'error' | 'warning' | 'info';
 /**
  * Stable, ADDITIVE-ONLY diagnostic codes (never renamed/removed — the wire
  * contract). Chosen with BOTH `validateScene` and the future
  * `gs parity --semantic` surface in mind.
- * - `UNKNOWN_TARGET` — a track targets an id/prop that resolves to no signal.
- * - `ID_COLLISION` — reserved: a duplicate node id (a built Scene rejects these
- *   at assembly, so it is unreachable here today; kept for the shared contract).
- * - `OFF_CANVAS` — a node's static position places its box fully outside the
- *   viewport (valid, but usually a mistake).
- * - `YOGA_CHILD_POSITION` — a track drives `position`/`position.*` of a FLOWABLE
- *   child of a Layout, whose flex slot overrides/confounds that position.
- * - `MEASURER_FALLBACK` — the scene carries Text but no real measurer is
- *   injected, so layout uses the rough per-character estimate.
+ *
+ * This enum is the shared diagnostic VOCABULARY — NOT "everything validateScene
+ * emits." Each code maps to a distinct ENFORCEMENT POINT:
+ * - `UNKNOWN_TARGET` — EMITTED by validateScene: a track targets an id/prop that
+ *   resolves to no signal.
+ * - `MEASURER_FALLBACK` — EMITTED by validateScene: the scene carries Text but no
+ *   real measurer is injected, so layout uses the rough per-character estimate.
+ * - `YOGA_CHILD_POSITION` — EMITTED by validateScene: a track drives
+ *   `position`/`position.*` of a FLOWABLE child of a Layout, whose flex slot
+ *   overrides/confounds that position.
+ * - `OFF_CANVAS` — RESERVED for `critique()` (0.60): a node's RENDERED box lands
+ *   fully outside the viewport. It is a composed-geometry check (needs ancestor
+ *   Group world transforms from the DisplayList), so validateScene — which reads
+ *   only static LOCAL positions — does NOT emit it (a nested child would
+ *   false-positive). Kept in the enum as the additive-only wire contract so 0.60
+ *   critique() can emit it without a schema bump.
+ * - `ID_COLLISION` — ENFORCED at `createScene()` (throws `DuplicateNodeIdError`):
+ *   a built Scene structurally cannot contain a duplicate id, so validateScene
+ *   never reaches this case. Kept for the shared contract / `gs parity` surface.
  */
 type DiagnosticCode = 'UNKNOWN_TARGET' | 'ID_COLLISION' | 'OFF_CANVAS' | 'YOGA_CHILD_POSITION' | 'MEASURER_FALLBACK';
 /** One diagnostic. The `{schemaVersion, code, severity, message, node?, track?}`
@@ -209,8 +219,10 @@ declare function nearestId(name: string, candidates: Iterable<string>): string |
  * `scene.resolveTarget`; an unresolved one becomes an `UNKNOWN_TARGET` error
  * with a Levenshtein nearest-id / nearest-prop suggestion, and a
  * `position`/`position.*` track on a flowable Layout child becomes a
- * `YOGA_CHILD_POSITION` warning. Scene-only checks (off-canvas, measurer
- * fallback) run regardless.
+ * `YOGA_CHILD_POSITION` warning. The scene-only MEASURER_FALLBACK check runs
+ * regardless. validateScene emits exactly three codes — UNKNOWN_TARGET,
+ * MEASURER_FALLBACK, YOGA_CHILD_POSITION; OFF_CANVAS/ID_COLLISION are reserved
+ * (see the DiagnosticCode doc for their enforcement points).
  */
 declare function validateScene(scene: Scene, doc?: Timeline): ValidateSceneResult;
 /**

package/dist/diagnostics.js

@@ -284,7 +284,7 @@ async function validateSceneFonts(scene, doc, loadBytes, options = {}) {
 * THE THREE INVARIANTS THIS MODULE UPHOLDS:
 *  - `validateScene(scene, doc)` is a PURE READ: it walks track targets through
 *    the EXISTING `scene.resolveTarget` (no new resolution machinery), reads node
-*    bounds/flow-flags, and reports. It NEVER draws RNG, warms a signal memo,
+*    flow-flags, and reports. It NEVER draws RNG, warms a signal memo,
 *    populates a measurer/font cache, or mutates a node — so `render(scene)` is
 *    byte-identical whether or not `validateScene` ran first. (Flowable-ness is
 *    probed with the STATELESS estimating measurer, not the scene's injected one,
@@ -370,8 +370,10 @@ function isFlowableLayoutChild(node) {
 * `scene.resolveTarget`; an unresolved one becomes an `UNKNOWN_TARGET` error
 * with a Levenshtein nearest-id / nearest-prop suggestion, and a
 * `position`/`position.*` track on a flowable Layout child becomes a
-* `YOGA_CHILD_POSITION` warning. Scene-only checks (off-canvas, measurer
-* fallback) run regardless.
+* `YOGA_CHILD_POSITION` warning. The scene-only MEASURER_FALLBACK check runs
+* regardless. validateScene emits exactly three codes — UNKNOWN_TARGET,
+* MEASURER_FALLBACK, YOGA_CHILD_POSITION; OFF_CANVAS/ID_COLLISION are reserved
+* (see the DiagnosticCode doc for their enforcement points).
 */
 function validateScene(scene, doc) {
 	const diagnostics = [];
@@ -401,20 +403,9 @@ function validateScene(scene, doc) {
 				...owner.node.id !== void 0 ? { node: owner.node.id } : {}
 			});
 		}
-		const animatedPos = /* @__PURE__ */ new Set();
-		if (doc) for (const tr of doc.tracks) {
-			const m = /^(.+)\/position(?:\.[xy])?$/.exec(tr.target);
-			if (m) animatedPos.add(m[1]);
-		}
-		const { w, h } = scene.size;
 		let sawText = false;
 		const visit = (node) => {
 			if (isTextNode(node)) sawText = true;
-			const pos = node.position;
-			if (node.id !== void 0 && !animatedPos.has(node.id) && typeof pos === "function") {
-				const [px, py] = pos();
-				if (Number.isFinite(px) && Number.isFinite(py) && (px < 0 || py < 0 || px > w || py > h)) push("OFF_CANVAS", "info", `node '${node.id}' has a static position [${px}, ${py}] outside the ${w}×${h} viewport — it may not be visible (fine if intentional, e.g. an off-screen start).`, { node: node.id });
-			}
 			const children = node.children;
 			if (Array.isArray(children)) for (const c of children) visit(c);
 		};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/scene",
-  "version": "0.59.0-pre.0",
+  "version": "0.59.0-pre.1",
   "description": "glissade scene graph: nodes, transforms, DisplayList emission. Renderer-agnostic; zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "engines": {
@@ -81,7 +81,7 @@
   ],
   "dependencies": {
     "yoga-layout": "^3.2.1",
-    "@glissade/core": "0.59.0-pre.0"
+    "@glissade/core": "0.59.0-pre.1"
   },
   "repository": {
     "type": "git",