hayao 0.2.0 → 0.3.0

package/dist/studio-plugin.js

@@ -0,0 +1,228 @@
+// src/studio/vitePlugin.ts
+import { execSync } from "node:child_process";
+import { createReadStream, existsSync, mkdirSync, readFileSync, readdirSync, statSync, watch, writeFileSync } from "node:fs";
+import { dirname, extname, join, normalize, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+function findPrebuiltStudio() {
+  for (const rel of ["../dist-studio", "../../dist-studio"]) {
+    try {
+      const dir = fileURLToPath(new URL(rel, import.meta.url));
+      if (existsSync(join(dir, "index.html"))) return dir;
+    } catch {
+    }
+  }
+  return null;
+}
+var MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript",
+  ".mjs": "text/javascript",
+  ".css": "text/css",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".json": "application/json",
+  ".woff2": "font/woff2",
+  ".wasm": "application/wasm"
+};
+function readBody(req) {
+  return new Promise((resolvePromise, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolvePromise(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+function json(res, status, body) {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json");
+  res.end(JSON.stringify(body));
+}
+var SAFE_ID = /^[a-z0-9][a-z0-9._-]*$/i;
+function hayaoStudio(opts = {}) {
+  let studioDir = "";
+  let projectRoot = "";
+  let buildRef = "unknown";
+  return {
+    name: "hayao-studio",
+    configResolved(config) {
+      projectRoot = config.root;
+      studioDir = resolve(projectRoot, opts.dir ?? ".studio");
+      mkdirSync(join(studioDir, "sessions"), { recursive: true });
+      mkdirSync(join(studioDir, "shots"), { recursive: true });
+      try {
+        buildRef = execSync("git rev-parse --short HEAD", { cwd: projectRoot, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+      } catch {
+      }
+    },
+    configureServer(server) {
+      const titleToModule = /* @__PURE__ */ new Map();
+      async function loadGameByTitle(title) {
+        const engine = await server.ssrLoadModule("@hayao");
+        const candidates = [];
+        const cached = titleToModule.get(title);
+        if (cached) candidates.push(cached);
+        for (const [parent] of [["examples"], ["sandboxes"]]) {
+          const dir = resolve(projectRoot, parent);
+          if (!existsSync(dir)) continue;
+          for (const slug of readdirSync(dir)) {
+            for (const file of [`${parent}/${slug}/game.ts`, `${parent}/${slug}/${slug}.ts`]) {
+              if (existsSync(resolve(projectRoot, file))) candidates.push(`/${file}`);
+            }
+          }
+        }
+        if (existsSync(resolve(projectRoot, "game.ts"))) candidates.push("/game.ts");
+        for (const path of candidates) {
+          try {
+            const mod = await server.ssrLoadModule(path);
+            for (const v of Object.values(mod)) {
+              if (v && typeof v === "object" && "build" in v && "title" in v && v.title === title) {
+                titleToModule.set(title, path);
+                return { def: v, engine };
+              }
+            }
+          } catch {
+          }
+        }
+        throw new Error(`no game titled "${title}" found`);
+      }
+      server.middlewares.use((req, res, next) => {
+        void (async () => {
+          const url = (req.url ?? "").split("?")[0];
+          if (req.method === "GET" && url.startsWith("/__studio/report/")) {
+            const id = decodeURIComponent(url.slice("/__studio/report/".length));
+            if (!SAFE_ID.test(id)) return json(res, 400, { error: "bad session id" });
+            const sessionPath = join(studioDir, "sessions", `${id}.json`);
+            if (!existsSync(sessionPath)) return json(res, 404, { error: "no such session" });
+            const session = JSON.parse(readFileSync(sessionPath, "utf8"));
+            const reportsDir = join(studioDir, "reports");
+            const cachePath = join(reportsDir, `${id}.json`);
+            if (existsSync(cachePath)) {
+              const cachedReport = JSON.parse(readFileSync(cachePath, "utf8"));
+              if (cachedReport.buildRef === session.buildRef) return json(res, 200, cachedReport);
+            }
+            const { def, engine } = await loadGameByTitle(session.game);
+            const report = engine.analyzePlaytest(def, session);
+            mkdirSync(reportsDir, { recursive: true });
+            writeFileSync(cachePath, JSON.stringify(report, null, 1));
+            return json(res, 200, report);
+          }
+          if (req.method === "POST" && url === "/__studio/session") {
+            const session = JSON.parse(await readBody(req));
+            if (typeof session.id !== "string" || !SAFE_ID.test(session.id)) {
+              return json(res, 400, { error: "bad session id" });
+            }
+            writeFileSync(join(studioDir, "sessions", `${session.id}.json`), JSON.stringify(session, null, 1));
+            return json(res, 200, { ok: true });
+          }
+          if (req.method === "POST" && url === "/__shot") {
+            const { path, svg } = JSON.parse(await readBody(req));
+            if (typeof svg !== "string") return json(res, 400, { error: "missing svg" });
+            const rel = normalize(path ?? `shot-${buildRef}.svg`).replace(/^([/\\])+/, "");
+            if (rel.split(/[/\\]/).includes("..")) return json(res, 400, { error: "bad path" });
+            const target = rel.startsWith("shots/") || rel.startsWith(".studio/") ? resolve(projectRoot, rel) : join(studioDir, "shots", rel);
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, svg);
+            return json(res, 200, { ok: true, path: target });
+          }
+          if (req.method === "POST" && url === "/__studio/knobs") {
+            const body = await readBody(req);
+            JSON.parse(body);
+            writeFileSync(join(studioDir, "knobs.json"), body);
+            return json(res, 200, { ok: true });
+          }
+          if (req.method === "GET" && url === "/__studio/games") {
+            const games = [];
+            for (const [parent, kind, prefix] of [
+              ["examples", "example", "/examples/"],
+              ["sandboxes", "gym", "/sandboxes/"]
+            ]) {
+              const dir = resolve(projectRoot, parent);
+              if (!existsSync(dir)) continue;
+              for (const slug of readdirSync(dir)) {
+                if (existsSync(join(dir, slug, "index.html"))) games.push({ slug, kind, url: `${prefix}${slug}/` });
+              }
+            }
+            if (games.length === 0 && existsSync(join(projectRoot, "index.html")) && existsSync(join(projectRoot, "game.ts"))) {
+              games.push({ slug: projectRoot.split("/").pop() ?? "game", kind: "project", url: "/" });
+            }
+            return json(res, 200, games);
+          }
+          if (req.method === "GET" && (url === "/studio" || url.startsWith("/studio/")) && !existsSync(join(projectRoot, "studio", "index.html"))) {
+            const prebuilt = findPrebuiltStudio();
+            if (!prebuilt) return json(res, 404, { error: "no prebuilt Studio UI in this hayao build" });
+            const rel = normalize(decodeURIComponent(url.replace(/^\/studio\/?/, "")));
+            if (rel.split(/[/\\]/).includes("..")) return json(res, 400, { error: "bad path" });
+            let file = join(prebuilt, rel);
+            if (!existsSync(file) || statSync(file).isDirectory()) file = join(prebuilt, "index.html");
+            res.statusCode = 200;
+            res.setHeader("content-type", MIME[extname(file)] ?? "text/html; charset=utf-8");
+            createReadStream(file).pipe(res);
+            return;
+          }
+          if (req.method === "GET" && url.startsWith("/__studio/variants/")) {
+            const rel = normalize(decodeURIComponent(url.slice("/__studio/variants/".length)));
+            if (rel.split(/[/\\]/).includes("..")) return json(res, 400, { error: "bad path" });
+            let file = join(studioDir, "variants", rel);
+            if (existsSync(file) && statSync(file).isDirectory()) file = join(file, "index.html");
+            if (!existsSync(file)) return json(res, 404, { error: "no such variant file" });
+            res.statusCode = 200;
+            res.setHeader("content-type", MIME[extname(file)] ?? "application/octet-stream");
+            createReadStream(file).pipe(res);
+            return;
+          }
+          if (req.method === "GET" && url.startsWith("/__studio/session/")) {
+            const id = decodeURIComponent(url.slice("/__studio/session/".length));
+            if (!SAFE_ID.test(id)) return json(res, 400, { error: "bad session id" });
+            const file = join(studioDir, "sessions", `${id}.json`);
+            if (!existsSync(file)) return json(res, 404, { error: "no such session" });
+            res.statusCode = 200;
+            res.setHeader("content-type", "application/json");
+            createReadStream(file).pipe(res);
+            return;
+          }
+          if (req.method === "GET" && url === "/__studio/state") {
+            const knobsPath = join(studioDir, "knobs.json");
+            const knobs = existsSync(knobsPath) ? JSON.parse(readFileSync(knobsPath, "utf8")) : null;
+            const variantsPath = join(studioDir, "variants.json");
+            const variants = existsSync(variantsPath) ? JSON.parse(readFileSync(variantsPath, "utf8")) : {};
+            const sessions = readdirSync(join(studioDir, "sessions")).filter((f) => f.endsWith(".json")).map((f) => {
+              try {
+                const s = JSON.parse(readFileSync(join(studioDir, "sessions", f), "utf8"));
+                return {
+                  id: s.id,
+                  game: s.game,
+                  startedAt: s.startedAt,
+                  endReason: s.endReason,
+                  frames: s.inputLog?.frames?.length ?? 0,
+                  annotations: Array.isArray(s.annotations) ? s.annotations.length : 0,
+                  variant: s.variant?.name ?? "dev"
+                };
+              } catch {
+                return null;
+              }
+            }).filter(Boolean);
+            const urls = server.resolvedUrls?.network ?? [];
+            return json(res, 200, { buildRef, knobs, variants, sessions, urls });
+          }
+          if (req.method === "GET" && url === "/__studio/events") {
+            res.statusCode = 200;
+            res.setHeader("content-type", "text/event-stream");
+            res.setHeader("cache-control", "no-cache");
+            res.write("retry: 2000\n\n");
+            const watcher = watch(studioDir, { recursive: true }, (_event, filename) => {
+              res.write(`data: ${JSON.stringify({ file: filename ?? "" })}
+
+`);
+            });
+            req.on("close", () => watcher.close());
+            return;
+          }
+          next();
+        })().catch((err) => json(res, 500, { error: String(err) }));
+      });
+    }
+  };
+}
+export {
+  hayaoStudio
+};

package/dist/ui/overlay.d.ts

@@ -20,6 +20,12 @@ export interface ScreenHandle {
 }
 /** Set the element overlays mount into (defaults to document.body). */
 export declare function setOverlayHost(el: HTMLElement): void;
+/**
+ * Observe DOM screen chrome (menus/title/game-over) opening and closing —
+ * Studio's session recorder uses this to time menu dwell, which the sim can't
+ * see. Observer only; it must never mutate.
+ */
+export declare function setScreenObserver(cb: ((kind: 'show' | 'hide', title?: string) => void) | null): void;
 /** Show a screen (replaces any current one). Returns a handle. */
 export declare function showScreen(spec: ScreenSpec): ScreenHandle;
 export declare function hideScreen(): void;

package/dist/verify/audioFilmstrip.d.ts

@@ -0,0 +1,39 @@
+import { type StereoBuffer } from '../audio/pcm';
+import { type AudioFeatures } from '../audio/analysis';
+export interface AudioFilmstripOptions {
+    /** Overall SVG width in px (default 900). */
+    width?: number;
+    /** Time columns in the spectrogram (default 220). */
+    timeBins?: number;
+    /** Frequency bands in the spectrogram (default 64). */
+    freqBands?: number;
+    /** Title shown above the strip. */
+    title?: string;
+}
+/**
+ * Render an audio filmstrip SVG for a stereo buffer: L/R waveforms, a
+ * spectrogram heatmap, and the feature readout. Deterministic and standalone
+ * (inline styles, no external refs) so it drops straight into t.artifact().
+ */
+export declare function renderAudioFilmstrip(buf: StereoBuffer, opts?: AudioFilmstripOptions): string;
+export interface AudioExpectation {
+    minDurationSec?: number;
+    maxDurationSec?: number;
+    maxPeakDb?: number;
+    minRms?: number;
+    minCentroidHz?: number;
+    maxCentroidHz?: number;
+    tempoBpm?: number;
+    tempoToleranceBpm?: number;
+}
+export interface AudioAssertion {
+    ok: boolean;
+    failures: string[];
+    features: AudioFeatures;
+}
+/**
+ * Assert a rendered buffer's measured features against an expectation. This is
+ * the numeric half of the audio channel — what a verify.ts suite calls to prove
+ * "this track is a ~120bpm piece that isn't clipping and isn't silent".
+ */
+export declare function assertAudio(buf: StereoBuffer, exp: AudioExpectation): AudioAssertion;

package/dist/verify/ethnography.d.ts

@@ -0,0 +1,67 @@
+import type { GameDefinition } from '../app/game';
+import { type PlaytestSession } from '../studio/session';
+export interface HesitationSpan {
+    startFrame: number;
+    frames: number;
+    /** Probe sampled at the span's first frame (what was on screen when input went quiet). */
+    probe: Record<string, unknown>;
+}
+export interface DeathCluster {
+    x: number;
+    y: number;
+    count: number;
+    frames: number[];
+}
+export interface FutileVerb {
+    action: string;
+    /** Rising-edge presses after which no probe field changed within the window. */
+    futilePresses: number;
+    totalPresses: number;
+    frames: number[];
+}
+export interface QuitContext {
+    frame: number;
+    probe: Record<string, unknown>;
+    /** Deaths / hesitation starts inside the final window before the quit. */
+    recentDeaths: number;
+    recentHesitations: number;
+    endReason: PlaytestSession['endReason'];
+}
+export interface AnnotationContext {
+    frame: number;
+    tag: string;
+    note?: string;
+    probe: Record<string, unknown>;
+}
+export interface PlaytestReport {
+    sessionId: string;
+    game: string;
+    buildRef: string;
+    seed: number;
+    variant: PlaytestSession['variant'];
+    frames: number;
+    /** Sim seconds (frames × dt); wall time can be longer (pauses, hidden tab). */
+    simSeconds: number;
+    reachedGoal: boolean;
+    deaths: number;
+    hesitations: HesitationSpan[];
+    deathClusters: DeathCluster[];
+    futileVerbs: FutileVerb[];
+    /** Present unless the session ended at the goal. */
+    quit?: QuitContext;
+    annotations: AnnotationContext[];
+    knobEvents: PlaytestSession['knobEvents'];
+    /** Verbs the player NEVER used (declared in the input map but absent from the log). */
+    unusedActions: string[];
+}
+export interface AnalyzeOptions {
+    /** Min quiet frames to count as a hesitation (default 45 ≈ 0.75s @ 60fps). */
+    hesitationFrames?: number;
+    /** Frames after a press in which SOMETHING must change, else it was futile (default 30). */
+    futileWindow?: number;
+    /** Final-window size for quit context, in frames (default 300 ≈ 5s). */
+    quitWindow?: number;
+    /** Death-cluster bucket size in world px (default 64). */
+    clusterPx?: number;
+}
+export declare function analyzePlaytest(def: GameDefinition, session: PlaytestSession, opts?: AnalyzeOptions): PlaytestReport;

package/dist/verify/gates.d.ts

@@ -0,0 +1,160 @@
+import type { DrawCommand } from '../render/commands';
+import type { Vec2 } from '../core/math';
+/** The forgiveness-relevant slice of any character config (PlatformerConfig satisfies it). */
+export interface ForgivenessSpec {
+    /** Seconds of coyote time after leaving the ground. */
+    coyoteTime: number;
+    /** Seconds a jump press is buffered before landing. */
+    jumpBuffer: number;
+    /** Pixels the body is nudged sideways to slip past a ceiling corner (0 = none). */
+    jumpCornerNudge?: number;
+}
+export interface ForgivenessOptions {
+    /** Minimum coyote time in seconds (default 0.05 ≈ 3 frames @60Hz). */
+    minCoyote?: number;
+    /** Minimum jump-buffer in seconds (default 0.05). */
+    minBuffer?: number;
+    /** Require a non-zero jump corner nudge (default true). */
+    requireCornerNudge?: boolean;
+}
+/**
+ * Static audit of a controller's grace windows. A platformer that ships without
+ * coyote time and input buffering feels like it drops inputs — the single most
+ * common reason an otherwise-correct platformer feels amateur.
+ */
+export declare function forgivenessIssues(spec: ForgivenessSpec, opts?: ForgivenessOptions): string[];
+/**
+ * Behavioural grace-window prover. `accepts(delayFrames)` runs the sim with the
+ * grace-triggering input applied `delayFrames` after the enabling event and
+ * returns whether the action still took. A correct window accepts every delay in
+ * `[0, windowFrames]` and refuses `windowFrames + 1` — the exact edge FUN law 5
+ * demands. Use it for coyote time, jump buffering, i-frames, mercy windows.
+ */
+export declare function graceWindowIssues(label: string, windowFrames: number, accepts: (delayFrames: number) => boolean): string[];
+export type FeedbackChannel = 'visual' | 'audio' | 'haptic';
+/** What a game promises to fire for one event kind — audited statically. */
+export interface FeedbackResponse {
+    /** Channels this event answers on (particles/flash = visual, sfx = audio, shake/rumble = haptic). */
+    channels: FeedbackChannel[];
+    /** Screen-shake trauma added (0..1), if any — bounded by the envelope. */
+    shake?: number;
+    /** Hit-stop / freeze frames injected, if any — bounded by the envelope. */
+    hitstopFrames?: number;
+}
+/** event kind → its feedback response. The game declares this next to its sim. */
+export type FeedbackContract = Record<string, FeedbackResponse>;
+export interface FeedbackOptions {
+    /** Minimum distinct channels per event (default 2). */
+    minChannels?: number;
+    /** Allowed screen-shake trauma range (default [0, 1]). */
+    shake?: [number, number];
+    /** Allowed hit-stop range in frames (default [0, 12] — beyond ~0.2s reads as a hitch). */
+    hitstop?: [number, number];
+}
+/**
+ * Audit a feedback contract: every required event exists, answers on ≥ minChannels
+ * distinct channels, and keeps its shake/hit-stop inside the envelope. This is the
+ * "does every hit/land/collect/death actually land on the senses?" gate.
+ */
+export declare function feedbackIssues(contract: FeedbackContract, requiredEvents: readonly string[], opts?: FeedbackOptions): string[];
+/** Relative luminance (WCAG) of a #rrggbb / #rgb color, in [0,1]. */
+export declare function relLuminance(hex: string): number;
+/** WCAG contrast ratio between two colors, in [1, 21]. */
+export declare function contrastRatio(a: string, b: string): number;
+export interface SalienceOptions {
+    /** Minimum contrast the avatar must hold against the background (default 3). */
+    minBackgroundContrast?: number;
+    /**
+     * The avatar's fill must out-contrast the MEDIAN non-avatar fill against the
+     * background by at least this factor (default 1.15) — i.e. it visibly pops from
+     * the scenery rather than blending into it.
+     */
+    minSalienceFactor?: number;
+}
+/**
+ * Readability gate: the player avatar must be the most salient thing on screen.
+ * The game passes the exact fill it painted the avatar with; the gate asserts that
+ * color out-contrasts both the background and the median scenery fill in the live
+ * display list. "Where's my guy?" is a fun-killer no correctness proof catches —
+ * this one does, from pure draw data.
+ */
+export declare function salienceIssues(commands: DrawCommand[], avatarFill: string, background: string, opts?: SalienceOptions): string[];
+export interface TelegraphFrame {
+    /** True on frames where a threat is warning (flash/wind-up) before it can hurt you. */
+    telegraphing: boolean;
+    /** True on frames where the threat's hitbox is live (it can deal damage). */
+    active: boolean;
+}
+/**
+ * Telegraph gate: every activation of a threat must be preceded by at least
+ * `minFrames` of contiguous telegraph. Reactive play is only possible if danger
+ * announces itself; a hitbox that goes live with no wind-up is an unfair death.
+ * Feed a per-frame timeline (one entry per sim frame) for a single threat.
+ */
+export declare function telegraphIssues(timeline: readonly TelegraphFrame[], minFrames: number, label?: string): string[];
+export interface CameraOptions {
+    /** Fixed timestep between samples in seconds (default 1/60). */
+    dt?: number;
+    /** Max camera speed in px/s before it reads as a snap (default 1800). */
+    maxSpeed?: number;
+    /** Max camera acceleration in px/s² before the motion reads as jerky (default 90000). */
+    maxAccel?: number;
+}
+/**
+ * Camera lawfulness gate over a sampled position series (one Vec2 per frame). A
+ * good follow camera never teleports and never jerks: bounded velocity (no snap)
+ * and bounded acceleration (smooth, not stuttery). You cannot systematize when a
+ * director SHOULD break these for drama — but an unbidden snap is always a bug.
+ */
+export declare function cameraIssues(samples: readonly Vec2[], opts?: CameraOptions): string[];
+/**
+ * Look-ahead gate: on the axes where the target is moving, the camera should lead
+ * in the SAME direction (bias the view toward where you're going), never trail
+ * backwards. Compares net camera drift to net target drift across the series.
+ */
+export declare function lookAheadIssues(cameraSamples: readonly Vec2[], targetSamples: readonly Vec2[], minLead?: number): string[];
+export interface FeelSpec {
+    /** The avatar's fill color — enables the salience gate. */
+    avatarFill?: string;
+    /** Background color (defaults to the game's `background`). */
+    background?: string;
+    /** Controller grace config — enables the forgiveness gate (PlatformerConfig fits). */
+    forgiveness?: ForgivenessSpec;
+    /** Declared feedback contract + the events that must be covered — enables the feedback gate. */
+    feedback?: {
+        contract: FeedbackContract;
+        events: readonly string[];
+    };
+    /** True for scrolling games — enables the camera gate (needs sampled positions). */
+    scrolls?: boolean;
+}
+/** Runtime inputs the audit/verify computes and hands to the aggregator. */
+export interface FeelContext {
+    /** A rendered display list (drive a few frames, then `world.render()`). */
+    commands?: DrawCommand[];
+    /** Sampled camera-follow positions over a run (exclude the pre-start frame). */
+    camSamples?: readonly Vec2[];
+    /** Matching target positions, for the look-ahead check. */
+    targetSamples?: readonly Vec2[];
+    /** Fixed timestep for the camera gate (default 1/60). */
+    dt?: number;
+    /** Background fallback if the spec omits one. */
+    background?: string;
+}
+export interface FeelReport {
+    ok: boolean;
+    /** One entry per gate that actually ran (given the spec + context). */
+    sections: {
+        gate: string;
+        issues: string[];
+    }[];
+    /** Gates the spec asks for but that lacked the runtime context to run. */
+    skipped: string[];
+}
+/**
+ * Run every feel gate the spec provides inputs for, returning a structured report.
+ * Static gates (forgiveness, feedback) run from the spec alone; salience needs a
+ * rendered display list; the camera gate needs sampled positions. Gates whose
+ * context is missing are reported as `skipped`, never silently dropped.
+ */
+export declare function runFeelGates(spec: FeelSpec, ctx?: FeelContext): FeelReport;

package/dist/verify/layout.d.ts

@@ -22,11 +22,38 @@ export interface LayoutOptions {
     backgroundZ?: number;
     /** Extra pixels of breathing room demanded around text (default 0 = touch is allowed, overlap is not). */
     margin?: number;
+    /**
+     * Lint transient view chrome too (floating popups, particles). Off by default:
+     * a "+10" drifting across a HUD label is motion, not a layout bug (see #26).
+     */
+    includeTransient?: boolean;
+    /**
+     * The page background these commands paint on. When given, contrast lints run
+     * (see `minContrast` / `minTextContrast`): a shape or label that barely differs
+     * from what sits under it is invisible even though the sim hashes fine (#30).
+     */
+    background?: string;
+    /**
+     * Minimum contrast ratio a solid foreground shape must hold against the
+     * background to count as visible at all (default 1.5). Only checked when
+     * `background` is set.
+     */
+    minContrast?: number;
+    /**
+     * Minimum contrast ratio text must hold against its backing (panel fill, or the
+     * background) — the WCAG AA readability bar (default 4.5). Only when `background`
+     * is set. Pass 0 to skip the text-contrast check while keeping shape contrast.
+     */
+    minTextContrast?: number;
 }
 /**
- * Lint a display list for text readability. Returns human-readable issues
- * (empty = clean). Checks: text-vs-shape partial overlaps (rule 1) and
- * text-vs-text overlaps.
+ * Lint a display list for text readability and visibility. Returns human-readable
+ * issues (empty = clean). Checks:
+ *  1. text-vs-shape partial overlaps (a label half-under a shape),
+ *  2. text fully hidden behind an opaque higher-z shape (silent invisible labels, #31),
+ *  3. text-vs-text overlaps,
+ *  4. (opt-in via `background`) low-contrast shapes and text (#30).
+ * Transient commands (popups/particles) are skipped unless `includeTransient`.
  */
 export declare function layoutIssues(commands: DrawCommand[], opts?: LayoutOptions): string[];
 /** Friendly names a hint text may use to reference a key code. */

package/dist/verify/ramp.d.ts

@@ -0,0 +1,40 @@
+export interface RampStats {
+    count: number;
+    min: number;
+    max: number;
+    mean: number;
+    /** Distinct difficulty values — a flat curve has 1. */
+    distinct: number;
+    /** Largest single step-to-step increase. */
+    maxJump: number;
+    /** Fraction of steps that rise or hold (0..1). */
+    forwardFraction: number;
+}
+/** Summarize a difficulty series — handy for logging the curve next to the gate. */
+export declare function rampStats(difficulty: readonly number[]): RampStats;
+export interface RampOptions {
+    /**
+     * Largest allowed single-step increase, as a MULTIPLE of the average forward
+     * step. A step steeper than this reads as a difficulty cliff (default 3×).
+     */
+    maxJumpFactor?: number;
+    /** Absolute floor for the jump envelope so tiny early steps don't over-constrain (default 2). */
+    minJumpAllowance?: number;
+    /** Minimum fraction of steps that must rise-or-hold — forward progress (default 0.6). */
+    minForwardFraction?: number;
+    /** Minimum distinct difficulty values — variety, not a flat line (default 3). */
+    minDistinct?: number;
+    /** Require the last level to be within this fraction of the peak (default 0.8 = finale ≥ 80% of max). */
+    finaleFraction?: number;
+}
+/**
+ * Audit a difficulty curve. `difficulty[i]` is the i-th level's difficulty proxy
+ * — typically the solver's solution depth, but any monotone measure works. Returns
+ * the specific curve sins found (empty array = a well-shaped ramp).
+ */
+export declare function rampIssues(difficulty: readonly number[], opts?: RampOptions): string[];
+/**
+ * Assert a difficulty curve is well-shaped (throws with the first issue if not).
+ * The campaign-level analogue of `assertSolvable` — one call gates the ramp.
+ */
+export declare function assertRamp(difficulty: readonly number[], opts?: RampOptions): void;

package/dist/world.d.ts

@@ -4,7 +4,7 @@ import { Rng } from './core/rng';
 import { InputState } from './input/actions';
 import { Node, type WorldContext } from './scene/node';
 import type { Camera2D } from './scene/nodes';
-import { type Transform } from './core/math';
+import { type Transform, type Vec2 } from './core/math';
 import type { DrawCommand } from './render/commands';
 export interface WorldConfig {
     seed?: number;
@@ -12,6 +12,8 @@ export interface WorldConfig {
     /** Design-space dimensions (default 1280×720). */
     width?: number;
     height?: number;
+    /** Resolved tuning values (see app/tuning.ts). Sim state: hashed + snapshotted. */
+    tuning?: Record<string, number | string>;
 }
 /** Default engine event map; games extend it with their own keys. */
 export interface CoreEvents {
@@ -37,7 +39,14 @@ export declare class World implements WorldContext {
     private seed;
     private freeQueue;
     private started;
+    private tuningValues;
     constructor(config?: WorldConfig);
+    /**
+     * Read a tuning value resolved at world creation (declared default unless
+     * overridden). Throws on an undeclared key — a typo here would otherwise
+     * silently read `undefined` into the sim.
+     */
+    tune<T extends number | string = number>(key: string): T;
     get time(): number;
     get frame(): number;
     /** Replace the scene root, entering the tree. */
@@ -49,11 +58,36 @@ export declare class World implements WorldContext {
      * This is THE deterministic transition — call it from Node or the browser loop.
      */
     step(actionsDown?: Iterable<string>): void;
-    /** Feed real elapsed ms; runs 0+ fixed steps. Returns steps run. */
+    /**
+     * Feed REAL elapsed ms; runs 0+ fixed steps. Returns steps run. This is the
+     * realtime driver entry point — it CLAMPS realMs to the clock's maxFrameMs
+     * (default 250) to avoid a spiral of death, so `advance(1200)` runs ~15 steps,
+     * not 72. For headless tests/harnesses that want to fast-forward an exact
+     * number of steps, use `runSteps(n)` or `step()` — never `advance` with a big ms.
+     */
     advance(realMs: number, actionsDown?: Iterable<string>): number;
+    /**
+     * Run exactly `n` fixed steps — the deterministic fast-forward for tests and
+     * headless drivers (unlike `advance`, no realtime clamp). Pass `actionsFor(i)`
+     * to script the input per step; omit it to hold nothing down.
+     */
+    runSteps(n: number, actionsFor?: (i: number) => Iterable<string>): void;
     private flushFree;
     /** The view transform (inverse of the active camera), mapping world → screen. */
     viewTransform(): Transform;
+    /**
+     * Map a world-space point to screen/design space (the forward view transform).
+     * With no active camera this is the identity, so world == screen.
+     */
+    worldToScreen(p: Vec2): Vec2;
+    /**
+     * Map a screen/design-space point back to world space — the inverse of the
+     * view transform. Use this to turn a pointer position (in design units) into
+     * a world coordinate under a scrolled/zoomed camera. Keep raw pointer values
+     * OUT of the sim: convert at the host edge and feed the result in as a
+     * quantized action/axis, or determinism breaks (see docs/CONVENTIONS.md).
+     */
+    screenToWorld(p: Vec2): Vec2;
     /** Project the whole scene to a display list (already camera-applied). */
     render(): DrawCommand[];
     /** Deterministic structural hash of the whole sim state. */
@@ -72,4 +106,6 @@ export interface WorldSnapshot {
     input: ReturnType<InputState['getState']>;
     state: Record<string, unknown>;
     tree: ReturnType<Node['serialize']>;
+    /** Resolved tuning values (absent in pre-tuning saves). */
+    tuning?: Record<string, number | string>;
 }