@glissade/scene 0.60.0-pre.0 → 0.60.0

package/dist/describe.d.ts

@@ -153,8 +153,16 @@ interface DescribedHelper {
 interface SurfaceEntry {
   /** The export name — also the `window.glissade.<name>` global on the IIFE. */
   name: string;
-  /** `'value'` = a runtime binding on the bundle (a class / function / object); `'type'` = a TS type-only name that erases at runtime (opaque, referenced by signatures). */
-  kind: 'value' | 'type';
+  /**
+   * `'value'` = a runtime binding on the bundle (a class / function / object);
+   * `'type'` = a TS type-only name that erases at runtime (opaque, referenced by
+   * signatures); `'diagnostic'` = a runtime AUTHORING-DIAGNOSTIC function
+   * (`critique`/`validateScene`/`resolveAt`/`instanceProps`, 0.60) — a real
+   * `window.glissade.<name>` callable that is PERCEPTION/self-check tooling, not
+   * scene-building surface. An agent BUILDING a scene filters `kind !== 'diagnostic'`;
+   * an agent CRITIQUING a rendered scene filters `kind === 'diagnostic'`.
+   */
+  kind: 'value' | 'type' | 'diagnostic';
   /** `true` when it is reachable as `window.glissade.<name>` on the single-file IIFE bundle. */
   iife: boolean;
   /** How to consume it: `'constructor'` needs `new`, `'function'` is a plain call, `'object'` is a value namespace (e.g. `easings`), `'type'` is type-only. */

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.60.0-pre.0";
+const RAW_VERSION = "0.60.0";
 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
@@ -182,6 +182,34 @@ const SURFACE_EXTRA = [
 /** Value exports that are runtime OBJECTS (not callable): the easing registry. */
 const SURFACE_VALUE_OBJECTS = ["easings"];
 /**
+* The 0.60 machine-readable AUTHORING-DIAGNOSTIC functions on `window.glissade`
+* (the `@glissade/scene/diagnostics` subpath, IIFE-re-exported off the base embed):
+* `critique` (rendered geometry), `validateScene` (static structure), `resolveAt`
+* (the truthful read primitive), `instanceProps` (instance-bound state). Marked
+* `kind: 'diagnostic'` so a consumer can PARTITION the surface — build-a-scene
+* tooling filters them OUT, render-critique/perception tooling filters them IN —
+* instead of them being invisible (previously exempt-internal, discoverable only by
+* reading the bundle). `arity` = the documented required positional-arg count.
+*/
+const SURFACE_DIAGNOSTICS = [
+	{
+		name: "critique",
+		arity: 2
+	},
+	{
+		name: "validateScene",
+		arity: 2
+	},
+	{
+		name: "resolveAt",
+		arity: 3
+	},
+	{
+		name: "instanceProps",
+		arity: 1
+	}
+];
+/**
 * The opaque, type-ONLY names the API surface references (they erase at runtime —
 * `window.glissade.Paint` is `undefined`). `gs types --global` emits a best-effort
 * alias per name; `gs describe --lint` guards they stay type-only (a type surfaced
@@ -235,6 +263,13 @@ function buildSurface() {
 		iife: true,
 		form: "object"
 	});
+	for (const d of SURFACE_DIAGNOSTICS) out.push({
+		name: d.name,
+		kind: "diagnostic",
+		iife: true,
+		form: "function",
+		arity: d.arity
+	});
 	for (const name of SURFACE_TYPE_ONLY) out.push({
 		name,
 		kind: "type",

package/dist/diagnostics.d.ts

@@ -282,6 +282,20 @@ interface CritiqueOptions {
    * override for tooling; a fixed INTEGER-frame grid is the determinism contract.
    */
   fps?: number;
+  /**
+   * Author-declared INTENTIONALLY off-stage node ids — the OFF_CANVAS opt-out.
+   * A node is exempt from OFF_CANVAS iff its id is in this list OR ANY of its
+   * ancestors' ids is (SUBTREE match): list the parked GROUP id
+   * (`'sd1-drawer'`) and its whole subtree — current children AND any it later
+   * gains — is suppressed, while sibling groups stay fully checked. This lets an
+   * author silence the true-positive-but-intentional off-stage art (wing-parked
+   * drawers, hidden placeholder cards) without muting OFF_CANVAS wholesale. A
+   * PURE emission filter — determinism-neutral (it never changes the sampled
+   * geometry, only which off-frame nodes are reported). Same param-seam shape as
+   * a future `safeAreas`; a per-node `offstage:true` marker is a planned
+   * fast-follow, not this mechanism.
+   */
+  offstage?: readonly string[];
 }
 interface CritiqueResult {
   schemaVersion: typeof DIAGNOSTIC_SCHEMA_VERSION;

package/dist/diagnostics.js

@@ -1,4 +1,4 @@
-import { I as isEstimatingMeasurer, J as collapseReplacer, P as estimatingMeasurer, W as createDisplayListBuilder, Y as IDENTITY, et as multiply, r as Group, s as Text } from "./nodes.js";
+import { I as isEstimatingMeasurer, J as collapseReplacer, P as estimatingMeasurer, R as quantize, W as createDisplayListBuilder, Y as IDENTITY, et as multiply, r as Group, s as Text } from "./nodes.js";
 import { a as evaluate, r as bindScene } from "./scene.js";
 import { emitWithIds } from "./identity.js";
 import { buildFontRegistry, compileTimeline, evaluateAt, parseCmap, parseColor, untracked, validateFonts } from "@glissade/core";
@@ -737,8 +737,10 @@ function critique(scene, timeline, opts = {}) {
 		}
 	}
 	const rendered = [];
+	const offstageSet = new Set(opts.offstage ?? []);
+	const isOffstage = (id) => offstageSet.size > 0 && (offstageSet.has(id) || hasFlaggedAncestor(scene, id, offstageSet));
 	const offCanvasIds = /* @__PURE__ */ new Set();
-	for (const [id, a] of agg) if (a.onStage > 0 && a.offCanvas === a.onStage) offCanvasIds.add(id);
+	for (const [id, a] of agg) if (a.onStage > 0 && a.offCanvas === a.onStage && !isOffstage(id)) offCanvasIds.add(id);
 	const reportedOffCanvas = /* @__PURE__ */ new Set();
 	for (const id of offCanvasIds) {
 		if (hasFlaggedAncestor(scene, id, offCanvasIds)) continue;
@@ -749,22 +751,29 @@ function critique(scene, timeline, opts = {}) {
 	for (const [id, a] of agg) {
 		if (a.lastTexts.length === 0) continue;
 		const node = scene.nodes.get(id);
-		if (!node || node.describeType !== "Text") continue;
+		if (!(node instanceof Text)) continue;
 		const width = numberAt(scene, `${id}/width`, a.lastTextFrameT);
-		if (width === void 0 || width <= 0) continue;
-		let widest = 0;
-		for (const run of a.lastTexts) {
-			let mw = 0;
-			try {
-				mw = measurer.measureText(run.text, run.font).width;
-			} catch {
-				mw = 0;
+		if (width !== void 0 && width > 0) {
+			let widest = 0;
+			for (const run of a.lastTexts) {
+				let mw = 0;
+				try {
+					mw = measurer.measureText(run.text, run.font).width;
+				} catch {
+					mw = 0;
+				}
+				if (mw > widest) widest = mw;
 			}
-			if (mw > widest) widest = mw;
+			const over = widest - width;
+			if (over > .5) rendered.push(textOverflowDiagnostic(id, "width", widest, width, over, estimating));
+		}
+		const boxH = node.box?.h;
+		if (boxH !== void 0 && boxH > 0) {
+			const fontSize = a.lastTexts[0].font.size;
+			const blockH = quantize(fontSize * node.lineHeight) * a.lastTexts.length;
+			const overH = blockH - boxH;
+			if (overH > .5) rendered.push(textOverflowDiagnostic(id, "height", blockH, boxH, overH, estimating));
 		}
-		const over = widest - width;
-		if (over <= .5) continue;
-		rendered.push(textOverflowDiagnostic(id, widest, width, over, estimating));
 	}
 	for (const [id, a] of agg) {
 		if (a.onStage === 0 || a.occluded !== a.onStage) continue;
@@ -824,8 +833,8 @@ function offCanvasDiagnostic(scene, id, a, w, h) {
 		}
 	};
 }
-function textOverflowDiagnostic(id, measured, threshold, over, estimating) {
-	const base = `text of node '${id}' overflows its box by ${round(over)}px (needs ${round(measured)}px, box width ${round(threshold)}px). Reduce fontSize, widen width, or wrap it with fitText({ maxW: ${round(threshold)} }).`;
+function textOverflowDiagnostic(id, dimension, measured, threshold, over, estimating) {
+	const base = dimension === "width" ? `text of node '${id}' overflows its box WIDTH by ${round(over)}px (needs ${round(measured)}px, box width ${round(threshold)}px). Reduce fontSize, widen width, or wrap it with fitText({ maxW: ${round(threshold)} }).` : `text of node '${id}' overflows its box HEIGHT by ${round(over)}px (wrapped block ${round(measured)}px tall, box height ${round(threshold)}px). Reduce fontSize, increase the box height, or shorten the text.`;
 	return {
 		schemaVersion: 1,
 		code: "TEXT_OVERFLOW",
@@ -834,6 +843,7 @@ function textOverflowDiagnostic(id, measured, threshold, over, estimating) {
 		node: id,
 		message: estimating ? `${base} (metrics ESTIMATED — no real text measurer injected; verify with the real backend measurer.)` : base,
 		detail: {
+			dimension,
 			measured: round(measured),
 			threshold: round(threshold),
 			overflowPx: round(over),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/scene",
-  "version": "0.60.0-pre.0",
+  "version": "0.60.0",
   "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.60.0-pre.0"
+    "@glissade/core": "0.60.0"
   },
   "repository": {
     "type": "git",