summer-engine 3.0.0 → 3.2.0

package/dist/core/capabilities/audit/args.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Argument shape for summer_scene_audit — ONE copy for both faces (the MCP
+ * registration in src/mcp/tools/audit-tools.ts and `summer tool scene-audit`
+ * in tool-dispatch.ts). The descriptions are the docs agents read.
+ *
+ * Strings that name scene content are validated again in audit.ts with the
+ * seeing tools' strict patterns before anything is sent; they reach the
+ * engine only as JSON data in config.json, never as source.
+ */
+import { z } from "zod";
+export declare const AUDIT_CHECKS: readonly ["through_hole", "floor_gap", "floating", "sunken", "interpenetration", "exposed_edge", "open_fixture_end", "orientation", "uv_stretch", "duplicate", "z_fight", "depth_step", "lights", "transform", "resource"];
+export type AuditCheck = (typeof AUDIT_CHECKS)[number];
+export declare const SEVERITIES: readonly ["error", "warn", "look"];
+export type Severity = (typeof SEVERITIES)[number];
+export declare const AUDIT_DEFAULT_LIMIT = 15;
+export declare const AUDIT_MAX_LIMIT = 50;
+/** Editor time the checks may take before the slow ones stop early (partial). */
+export declare const AUDIT_DEFAULT_BUDGET_MS = 3000;
+export declare const AUDIT_MIN_BUDGET_MS = 250;
+export declare const AUDIT_MAX_BUDGET_MS = 60000;
+export declare const AUDIT_MAX_ACCEPT = 50;
+/** An issue key: check:node path@x,y,z (world position rounded to 0.1 m;
+ *  node names never contain ":" or "@"). */
+export declare const ISSUE_KEY_PATTERN: RegExp;
+export declare const sceneAuditShape: {
+    scenePath: z.ZodOptional<z.ZodString>;
+    checks: z.ZodOptional<z.ZodArray<z.ZodEnum<["through_hole", "floor_gap", "floating", "sunken", "interpenetration", "exposed_edge", "open_fixture_end", "orientation", "uv_stretch", "duplicate", "z_fight", "depth_step", "lights", "transform", "resource"]>, "many">>;
+    root: z.ZodOptional<z.ZodString>;
+    min_severity: z.ZodOptional<z.ZodEnum<["error", "warn", "look"]>>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    budget_ms: z.ZodOptional<z.ZodNumber>;
+    accept: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        reason: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        reason: string;
+        key: string;
+    }, {
+        reason: string;
+        key: string;
+    }>, "many">>;
+    show_accepted: z.ZodOptional<z.ZodBoolean>;
+    render: z.ZodOptional<z.ZodEnum<["sheet", "none"]>>;
+};
+export declare const sceneAuditArgsSchema: z.ZodObject<{
+    scenePath: z.ZodOptional<z.ZodString>;
+    checks: z.ZodOptional<z.ZodArray<z.ZodEnum<["through_hole", "floor_gap", "floating", "sunken", "interpenetration", "exposed_edge", "open_fixture_end", "orientation", "uv_stretch", "duplicate", "z_fight", "depth_step", "lights", "transform", "resource"]>, "many">>;
+    root: z.ZodOptional<z.ZodString>;
+    min_severity: z.ZodOptional<z.ZodEnum<["error", "warn", "look"]>>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    budget_ms: z.ZodOptional<z.ZodNumber>;
+    accept: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        reason: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        reason: string;
+        key: string;
+    }, {
+        reason: string;
+        key: string;
+    }>, "many">>;
+    show_accepted: z.ZodOptional<z.ZodBoolean>;
+    render: z.ZodOptional<z.ZodEnum<["sheet", "none"]>>;
+}, "strict", z.ZodTypeAny, {
+    limit?: number | undefined;
+    root?: string | undefined;
+    scenePath?: string | undefined;
+    accept?: {
+        reason: string;
+        key: string;
+    }[] | undefined;
+    render?: "none" | "sheet" | undefined;
+    checks?: ("through_hole" | "floor_gap" | "floating" | "sunken" | "interpenetration" | "exposed_edge" | "open_fixture_end" | "orientation" | "uv_stretch" | "duplicate" | "z_fight" | "depth_step" | "lights" | "transform" | "resource")[] | undefined;
+    min_severity?: "error" | "warn" | "look" | undefined;
+    offset?: number | undefined;
+    budget_ms?: number | undefined;
+    show_accepted?: boolean | undefined;
+}, {
+    limit?: number | undefined;
+    root?: string | undefined;
+    scenePath?: string | undefined;
+    accept?: {
+        reason: string;
+        key: string;
+    }[] | undefined;
+    render?: "none" | "sheet" | undefined;
+    checks?: ("through_hole" | "floor_gap" | "floating" | "sunken" | "interpenetration" | "exposed_edge" | "open_fixture_end" | "orientation" | "uv_stretch" | "duplicate" | "z_fight" | "depth_step" | "lights" | "transform" | "resource")[] | undefined;
+    min_severity?: "error" | "warn" | "look" | undefined;
+    offset?: number | undefined;
+    budget_ms?: number | undefined;
+    show_accepted?: boolean | undefined;
+}>;
+export type SceneAuditArgs = z.output<typeof sceneAuditArgsSchema>;

package/dist/core/capabilities/audit/args.js

@@ -0,0 +1,89 @@
+/**
+ * Argument shape for summer_scene_audit — ONE copy for both faces (the MCP
+ * registration in src/mcp/tools/audit-tools.ts and `summer tool scene-audit`
+ * in tool-dispatch.ts). The descriptions are the docs agents read.
+ *
+ * Strings that name scene content are validated again in audit.ts with the
+ * seeing tools' strict patterns before anything is sent; they reach the
+ * engine only as JSON data in config.json, never as source.
+ */
+import { z } from "zod";
+export const AUDIT_CHECKS = [
+    "through_hole",
+    "floor_gap",
+    "floating",
+    "sunken",
+    "interpenetration",
+    "exposed_edge",
+    "open_fixture_end",
+    "orientation",
+    "uv_stretch",
+    "duplicate",
+    "z_fight",
+    "depth_step",
+    "lights",
+    "transform",
+    "resource",
+];
+export const SEVERITIES = ["error", "warn", "look"];
+export const AUDIT_DEFAULT_LIMIT = 15;
+export const AUDIT_MAX_LIMIT = 50;
+/** Editor time the checks may take before the slow ones stop early (partial). */
+export const AUDIT_DEFAULT_BUDGET_MS = 3000;
+export const AUDIT_MIN_BUDGET_MS = 250;
+export const AUDIT_MAX_BUDGET_MS = 60000;
+export const AUDIT_MAX_ACCEPT = 50;
+/** An issue key: check:node path@x,y,z (world position rounded to 0.1 m;
+ *  node names never contain ":" or "@"). */
+export const ISSUE_KEY_PATTERN = /^[a-z_]{3,24}:[^:@\n\r"\\]{1,300}@-?\d+(?:\.\d)?,-?\d+(?:\.\d)?,-?\d+(?:\.\d)?$/;
+export const sceneAuditShape = {
+    scenePath: z
+        .string()
+        .optional()
+        .describe('Scene to audit, e.g. "res://levels/town.tscn" (the SAVED file). Omit for the scene open in the editor.'),
+    checks: z
+        .array(z.enum(AUDIT_CHECKS))
+        .min(1)
+        .max(AUDIT_CHECKS.length)
+        .optional()
+        .describe("Only these checks (default: all 15). through_hole, floor_gap, floating, sunken, interpenetration, exposed_edge, open_fixture_end, orientation, uv_stretch, duplicate, z_fight, depth_step, lights, transform, resource. Fewer checks run faster (duplicate, lights, transform and resource need no physics); rerun a check budget_ms left partial on its own."),
+    root: z
+        .string()
+        .optional()
+        .describe('Report only issues under this node (subtree), e.g. "Block3". The whole scene is still loaded so walls and floors outside it count as surroundings.'),
+    min_severity: z
+        .enum(SEVERITIES)
+        .optional()
+        .describe('"error" (only errors), "warn" (errors and warnings) or "look" (default: everything, including look items that only ask you to look).'),
+    offset: z.number().int().min(0).max(100000).optional().describe("Skip this many issues of the sorted, filtered list (paging; the result names the next offset)."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(AUDIT_MAX_LIMIT)
+        .optional()
+        .describe(`Issues per page (default ${AUDIT_DEFAULT_LIMIT}, max ${AUDIT_MAX_LIMIT}). The result is capped at 5 KB; a page that does not fit is cut and says so.`),
+    budget_ms: z
+        .number()
+        .int()
+        .min(AUDIT_MIN_BUDGET_MS)
+        .max(AUDIT_MAX_BUDGET_MS)
+        .optional()
+        .describe(`Editor time for the whole audit (default ${AUDIT_DEFAULT_BUDGET_MS} ms, ${AUDIT_MIN_BUDGET_MS}-${AUDIT_MAX_BUDGET_MS}). Each check gets a share weighted by its usual cost (unused time passes on); a check past its share stops and counts.<check>.partial gives the share it covered. Under load, rerun the partial checks with checks:[...] or a larger budget.`),
+    accept: z
+        .array(z
+        .object({
+        key: z.string().min(8).max(360).describe("The issue's key from a previous result (issues[].key)."),
+        reason: z.string().min(3).max(200).describe("Why it is fine, e.g. \"coplanar faces hidden behind a sign\"."),
+    })
+        .strict())
+        .max(AUDIT_MAX_ACCEPT)
+        .optional()
+        .describe(`Accept look or warn items you judged fine (up to ${AUDIT_MAX_ACCEPT} per call): [{key, reason}] with keys from this scene's issues. They are written to res://.summer/audit-accept.json (the only file the audit writes), then counted (counts.<check>.accepted) but hidden on every later audit, until their evidence changes materially (severity rises, or the measured size moves by over 25%): then they show again with accept_stale. Errors cannot be accepted.`),
+    show_accepted: z.boolean().optional().describe("List accepted items too (each with its accepted reason). Default false: hidden, only counted."),
+    render: z
+        .enum(["sheet", "none"])
+        .optional()
+        .describe('"sheet": also return ONE inline image of the first 6 issues of this page framed up close from their open side, each tile labelled with its issue number. Default "none" (no image).'),
+};
+export const sceneAuditArgsSchema = z.object(sceneAuditShape).strict();

package/dist/core/capabilities/audit/audit.d.ts

@@ -0,0 +1,56 @@
+import { type CapabilityAdvertisingClient } from "../../capability-skew.js";
+import { type SeeingImage } from "../seeing/seeing.js";
+import { type ProbeClient } from "../seeing/probe.js";
+import { type AuditCheck, type SceneAuditArgs, type Severity } from "./args.js";
+import { type AuditIssue, type KernelResult } from "./judge.js";
+export declare const AUDIT_KERNEL_PATH: string;
+export declare function loadAuditKernel(): string;
+export declare const AUDIT_FALLBACK = "read the scene with summer_world_snapshot and look with summer_frame_nodes / summer_shot_sheet; cast single rays with summer_raycast";
+export interface AuditClient extends ProbeClient, CapabilityAdvertisingClient {
+    getSceneState(scenePath?: string, options?: {
+        depth?: number;
+        limit?: number;
+    }): Promise<unknown>;
+    getProjectRoot?(): string | undefined;
+}
+export interface AuditSuccess {
+    ok: true;
+    /** The page: at most 5 KB of JSON. */
+    summary: Record<string, unknown>;
+    image: SeeingImage | null;
+}
+export interface AuditFailure {
+    ok: false;
+    failure_reason: string;
+    error: string;
+    hint?: string;
+    detail?: Record<string, unknown>;
+}
+export type AuditResult = AuditSuccess | AuditFailure;
+export interface ValidatedAuditArgs {
+    scenePath?: string;
+    checks: AuditCheck[];
+    root?: string;
+    minSeverity: Severity;
+    offset: number;
+    limit: number;
+    render: "sheet" | "none";
+    budgetMs: number;
+    accept: Array<{
+        key: string;
+        reason: string;
+    }>;
+    showAccepted: boolean;
+}
+/** Strict validation; throws ToolInputError (nothing is sent). */
+export declare function validateAuditArgs(args: SceneAuditArgs): ValidatedAuditArgs;
+/** Raw kernel measurements -> sorted issues (all checks that ran). */
+export declare function judgeAll(result: KernelResult, checks: readonly AuditCheck[]): AuditIssue[];
+export interface JudgedAudit {
+    issues: AuditIssue[];
+    notes: string[];
+    /** Checks that ran but could measure nothing (never listed clean). */
+    unmeasured: AuditCheck[];
+}
+export declare function judgeAllDetailed(result: KernelResult, checks: readonly AuditCheck[]): JudgedAudit;
+export declare function sceneAudit(client: AuditClient, rawArgs: SceneAuditArgs): Promise<AuditResult>;

package/dist/core/capabilities/audit/audit.js

@@ -0,0 +1,287 @@
+/**
+ * summer_scene_audit — ONE implementation for both faces (MCP:
+ * src/mcp/tools/audit-tools.ts; CLI: `summer tool scene-audit`).
+ *
+ * One fast, read-only pass over every node of a 3D scene that reports likely
+ * visual and placement problems, so a build agent knows exactly where to look.
+ *
+ * How (no new engine op): the seeing tools' private-copy path. A throwaway
+ * wrapper scene in a private OS temp directory instances the SAVED scene and
+ * carries the audit kernel (assets/audit/scene_audit.gd) as a built-in @tool
+ * script; the existing ScenePreview op instantiates it in an offscreen
+ * SubViewport with its own World3D. The kernel works on that copy: the open
+ * tab, its unsaved state, its undo history and every project file stay
+ * untouched (RunSceneScript would mark the tab unsaved after every run).
+ *
+ * The kernel measures (capped ray grids and probes against a physics space
+ * built from the visible meshes, shapes cached per mesh resource); judge.ts
+ * decides; summary.ts pages the result under 5 KB. render:"sheet" renders the
+ * first 6 issues of the page through the seeing kernel in one more call.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PACKAGE_ROOT } from "../../package-root.js";
+import { missingEngineOpResult } from "../../capability-skew.js";
+import { ToolInputError } from "../../tool-errors.js";
+import { resolveCurrentScene } from "../project-context.js";
+import { layoutGrid, validateNodePath, validateScenePath } from "../seeing/seeing.js";
+import { runProbe } from "../seeing/probe.js";
+import { AUDIT_CHECKS, AUDIT_DEFAULT_BUDGET_MS, AUDIT_DEFAULT_LIMIT, AUDIT_MAX_ACCEPT, AUDIT_MAX_BUDGET_MS, AUDIT_MAX_LIMIT, AUDIT_MIN_BUDGET_MS, } from "./args.js";
+import { AcceptStoreError, applyAccepts, mergeAccepts, parseAcceptFile, validIssueKey, writeAcceptFile } from "./accept.js";
+import { judgeGaps } from "./gaps.js";
+import { groupRepeats, judgeDuplicates, judgeFloorGaps, judgeLights, judgeLongProps, judgeOverlaps, judgeResources, judgeSupport, judgeThroughHoles, judgeTransforms, judgeUv, judgeZFight, judgeZFightGeometry, } from "./judge.js";
+import { buildPage, countIssues, filterIssues, partialChecks, sortIssues, timingPerCheck } from "./summary.js";
+import { choosePose, SHEET_TILES } from "./frame.js";
+export const AUDIT_KERNEL_PATH = join(PACKAGE_ROOT, "assets", "audit", "scene_audit.gd");
+let kernelCache = null;
+export function loadAuditKernel() {
+    if (kernelCache === null)
+        kernelCache = readFileSync(AUDIT_KERNEL_PATH, "utf-8");
+    return kernelCache;
+}
+export const AUDIT_FALLBACK = "read the scene with summer_world_snapshot and look with summer_frame_nodes / summer_shot_sheet; cast single rays with summer_raycast";
+function fail(failure_reason, error, hint, detail) {
+    return { ok: false, failure_reason, error, ...(hint ? { hint } : {}), ...(detail ? { detail } : {}) };
+}
+/** Strict validation; throws ToolInputError (nothing is sent). */
+export function validateAuditArgs(args) {
+    const checks = args.checks?.length ? [...new Set(args.checks)] : [...AUDIT_CHECKS];
+    for (const c of checks) {
+        if (!AUDIT_CHECKS.includes(c))
+            throw new ToolInputError(`checks: unknown check ${JSON.stringify(c)}. Nothing was sent.`);
+    }
+    const offset = args.offset ?? 0;
+    const limit = args.limit ?? AUDIT_DEFAULT_LIMIT;
+    if (!Number.isInteger(offset) || offset < 0)
+        throw new ToolInputError("offset must be a non-negative integer. Nothing was sent.");
+    if (!Number.isInteger(limit) || limit < 1 || limit > AUDIT_MAX_LIMIT)
+        throw new ToolInputError(`limit must be 1-${AUDIT_MAX_LIMIT}. Nothing was sent.`);
+    const budgetMs = args.budget_ms ?? AUDIT_DEFAULT_BUDGET_MS;
+    if (!Number.isInteger(budgetMs) || budgetMs < AUDIT_MIN_BUDGET_MS || budgetMs > AUDIT_MAX_BUDGET_MS) {
+        throw new ToolInputError(`budget_ms must be an integer ${AUDIT_MIN_BUDGET_MS}-${AUDIT_MAX_BUDGET_MS}. Nothing was sent.`);
+    }
+    const root = args.root !== undefined && args.root.trim() !== "" && args.root.trim() !== "." ? validateNodePath(args.root.trim(), "root") : undefined;
+    const accept = (args.accept ?? []).map((a) => {
+        if (!a || typeof a.key !== "string" || !validIssueKey(a.key)) {
+            throw new ToolInputError(`accept: ${JSON.stringify(a?.key ?? a).slice(0, 80)} is not an issue key (check:path@x,y,z, from issues[].key). Nothing was sent.`);
+        }
+        const reason = typeof a.reason === "string" ? a.reason.trim() : "";
+        if (reason.length < 3 || reason.length > 200 || /[\r\n]/.test(reason))
+            throw new ToolInputError("accept: each reason must be one line of 3-200 characters. Nothing was sent.");
+        return { key: a.key, reason };
+    });
+    if (accept.length > AUDIT_MAX_ACCEPT)
+        throw new ToolInputError(`accept: at most ${AUDIT_MAX_ACCEPT} per call. Nothing was sent.`);
+    return {
+        ...(args.scenePath !== undefined ? { scenePath: validateScenePath(args.scenePath) } : {}),
+        checks: AUDIT_CHECKS.filter((c) => checks.includes(c)),
+        ...(root ? { root } : {}),
+        minSeverity: args.min_severity ?? "look",
+        offset,
+        limit,
+        render: args.render ?? "none",
+        budgetMs,
+        accept,
+        showAccepted: args.show_accepted === true,
+    };
+}
+/** Raw kernel measurements -> sorted issues (all checks that ran). */
+export function judgeAll(result, checks) {
+    return judgeAllDetailed(result, checks).issues;
+}
+export function judgeAllDetailed(result, checks) {
+    const inst = (Array.isArray(result.instances) ? result.instances : []);
+    const want = new Set(checks);
+    const lines = Array.isArray(result.lines) ? result.lines : [];
+    const issues = [];
+    const holes = want.has("through_hole") ? judgeThroughHoles(lines, inst) : [];
+    issues.push(...holes);
+    const gaps = judgeGaps(result, inst, want, holes);
+    issues.push(...gaps.issues);
+    if (want.has("floor_gap"))
+        issues.push(...judgeFloorGaps(result.floors, inst));
+    if (want.has("floating") || want.has("sunken")) {
+        issues.push(...judgeSupport(Array.isArray(result.support) ? result.support : [], inst).filter((i) => want.has(i.check)));
+    }
+    if (want.has("interpenetration"))
+        issues.push(...judgeOverlaps(Array.isArray(result.overlaps) ? result.overlaps : [], inst));
+    if (want.has("orientation"))
+        issues.push(...judgeLongProps(Array.isArray(result.long_props) ? result.long_props : [], inst));
+    if (want.has("uv_stretch"))
+        issues.push(...judgeUv(Array.isArray(result.uv) ? result.uv : [], inst));
+    const dup = judgeDuplicates(inst);
+    if (want.has("duplicate"))
+        issues.push(...dup.issues);
+    if (want.has("z_fight")) {
+        const geo = judgeZFightGeometry(result.zfight_geo, inst, dup.pairs);
+        issues.push(...geo.issues, ...judgeZFight(lines, result.floors, inst, dup.pairs, geo.pairs));
+    }
+    if (want.has("lights"))
+        issues.push(...judgeLights(result.lights, inst));
+    if (want.has("transform"))
+        issues.push(...judgeTransforms(inst));
+    if (want.has("resource"))
+        issues.push(...judgeResources(result.resources, inst));
+    return { issues: sortIssues(groupRepeats(issues, inst)), notes: gaps.notes, unmeasured: gaps.unmeasured };
+}
+function sceneStats(result) {
+    const s = (result.stats ?? {});
+    const pick = (k) => (typeof s[k] === "number" ? s[k] : undefined);
+    return {
+        nodes: pick("nodes"),
+        instances: pick("instances"),
+        meshes: pick("mesh_instances"),
+        unique_meshes: pick("unique_meshes"),
+        tris_unique: pick("tris_unique"),
+        rays: pick("rays"),
+    };
+}
+function lightStats(result) {
+    const l = result.lights;
+    if (!l)
+        return undefined;
+    const c = (l.counts ?? {});
+    const sh = (l.shadowed ?? {});
+    const n = (v) => (typeof v === "number" ? v : 0);
+    return { renderer: l.renderer, omni: n(c.omni), spot: n(c.spot), directional: n(c.directional), shadowed: n(sh.omni) + n(sh.spot) + n(sh.directional), per_object_limit: l.limit };
+}
+export async function sceneAudit(client, rawArgs) {
+    const args = validateAuditArgs(rawArgs);
+    let scenePath = args.scenePath;
+    if (!scenePath) {
+        const current = resolveCurrentScene(undefined, await client.getSceneState(), undefined);
+        if (!current)
+            throw new ToolInputError('No scenePath given and no scene is open in the editor. Pass scenePath ("res://...tscn"). Nothing was sent.');
+        scenePath = validateScenePath(current);
+    }
+    const missing = missingEngineOpResult(client, "ScenePreview", AUDIT_FALLBACK);
+    if (missing)
+        return fail(missing.failure_reason, missing.error, missing.hint, { op: "ScenePreview", engine_version: missing.engine_version });
+    const config = {
+        mode: "audit",
+        checks: args.checks,
+        ...(args.root ? { root: args.root } : {}),
+        poses: args.render === "sheet",
+        budget_ms: args.budgetMs,
+    };
+    const started = Date.now();
+    const run = await runProbe(client, { scenePath, config, size: [16, 16], kernel: loadAuditKernel(), timeoutMs: 120_000 });
+    const roundtrip = Date.now() - started;
+    try {
+        if (!run.ok || !run.result) {
+            if (run.failureReason === "probe_did_not_run") {
+                return fail("audit_did_not_run", "The audit kernel never wrote its result: the wrapper scene loaded but the built-in @tool script did not run (a script error, or the scene failed to load). Read summer_get_console for the engine's error.", undefined, { stage: run.result?.stage ?? null });
+            }
+            return fail(run.failureReason ?? "audit_failed", run.error ?? "The audit failed.", undefined, run.result ? { stage: run.result.stage ?? null, errors: run.result.errors ?? [] } : undefined);
+        }
+        const result = run.result;
+        const judgeStarted = Date.now();
+        const judged = judgeAllDetailed(result, args.checks);
+        const judgeMs = Date.now() - judgeStarted;
+        const partial = partialChecks(result.partial, args.checks);
+        for (const c of judged.unmeasured)
+            partial.checks[c] = 0;
+        // Accepted items: merge this call's accept list into the file, then hide
+        // what is accepted (stale entries show again).
+        let acceptEntries = parseAcceptFile(result.accept);
+        let acceptResult;
+        if (args.accept.length) {
+            const merged = mergeAccepts(acceptEntries, args.accept, judged.issues, scenePath);
+            acceptResult = { added: merged.added.length, ...(merged.refused.length ? { refused: merged.refused.slice(0, 5) } : {}) };
+            if (merged.entries) {
+                try {
+                    await writeAcceptFile(client.getProjectRoot?.(), merged.entries);
+                    acceptEntries = merged.entries;
+                }
+                catch (err) {
+                    const reason = err instanceof AcceptStoreError ? err.reason : "write_failed";
+                    return fail(`accept_${reason}`, `Accepted items were not saved: ${err instanceof Error ? err.message : String(err)}`, "Run the audit without accept, or connect to the project's editor so its folder is known.");
+                }
+            }
+        }
+        const split = applyAccepts(judged.issues, acceptEntries, scenePath);
+        for (const st of split.stale)
+            st.issue.acceptStale = st.why;
+        for (const a of split.accepted)
+            a.issue.accepted = a.entry.reason;
+        const all = args.showAccepted ? judged.issues : split.shown;
+        const accepted = split.accepted.map((a) => a.issue);
+        const { counts, clean } = countIssues(split.shown, args.checks, partial.checks, accepted);
+        const matching = filterIssues(all, args.minSeverity);
+        const notes = ["Read-only: audited the SAVED file in a private copy (open tab, undo and file untouched); save first."];
+        if (accepted.length)
+            notes.push(`${accepted.length} accepted item(s) ${args.showAccepted ? "listed (show_accepted)" : "hidden (counts.<check>.accepted; show_accepted:true lists them)"}${split.stale.length ? `; ${split.stale.length} shown again because their evidence changed (accept_stale)` : ""}.`);
+        else if (split.stale.length)
+            notes.push(`${split.stale.length} accepted item(s) shown again because their evidence changed (accept_stale).`);
+        notes.push(...judged.notes);
+        if (args.minSeverity !== "look")
+            notes.push(`min_severity ${args.minSeverity}: ${all.length - matching.length} lower-severity issue(s) hidden.`);
+        const lights = lightStats(result);
+        if (lights && args.checks.includes("lights") && lights.renderer === "forward_plus")
+            notes.push("lights: forward_plus has no per-object light limit; only spot rims were checked.");
+        const stopped = Object.entries(partial.checks).map(([c, share]) => `${c} ${Math.round(share * 100)}%`);
+        if (stopped.length)
+            notes.push(`budget_ms ${args.budgetMs}: stopped early (editor time): ${stopped.join(", ")} covered; rerun those with checks:[...] or a larger budget_ms.`);
+        if (partial.other.poses !== undefined)
+            notes.push(`framing: views measured for ${Math.round(partial.other.poses * 100)}% of the pieces (budget); the rest have no sheet tile.`);
+        for (const w of Array.isArray(result.warnings) ? result.warnings.slice(0, 3) : [])
+            notes.push(String(w).slice(0, 160));
+        const base = {
+            ok: true,
+            tool: "summer_scene_audit",
+            scenePath,
+            ...(args.root ? { root: args.root } : {}),
+            budget_ms: args.budgetMs,
+            scene: sceneStats(result),
+            counts,
+            clean,
+            ms: timingPerCheck(result.ms, { judge: judgeMs, roundtrip }),
+            ...(lights ? { lights } : {}),
+            total: all.length,
+            ...(accepted.length || split.stale.length ? { accepted: { hidden: args.showAccepted ? 0 : accepted.length, stale: split.stale.length } } : {}),
+            ...(acceptResult ? { accept_result: acceptResult } : {}),
+            notes,
+        };
+        let page = buildPage({ base, issues: matching, offset: args.offset, limit: args.limit });
+        // The sheet (one more engine call): the first issues of THIS page.
+        let image = null;
+        if (args.render === "sheet") {
+            const first = page.shown.slice(0, SHEET_TILES).map((c) => ({ n: c.n, issue: matching[c.n - 1] }));
+            const posed = first.map((f) => ({ ...f, pose: choosePose(f.issue.frame) })).filter((p) => p.pose !== null);
+            const unposed = first.filter((f) => !posed.some((p) => p.n === f.n)).map((f) => f.n);
+            let sheet;
+            if (!posed.length) {
+                sheet = { tiles: [], ...(unposed.length ? { no_clear_view: unposed } : {}) };
+            }
+            else {
+                const layout = layoutGrid(posed.length, 16 / 9, 1536);
+                const tiles = posed.map((p, k) => ({
+                    kind: "shot",
+                    rect: layout.rects[k],
+                    label: `#${p.n} ${p.issue.check}`,
+                    view: "beauty",
+                    pose: { position: [...p.pose.position], look_at: [...p.pose.look_at], fov: p.pose.fov },
+                }));
+                const renderStarted = Date.now();
+                const render = await runProbe(client, { scenePath, size: layout.canvas, config: { mode: "render", canvas: layout.canvas, tiles }, timeoutMs: 120_000 });
+                try {
+                    if (render.ok && render.image) {
+                        image = { ...render.image };
+                        sheet = { tiles: posed.map((p) => p.n), ...(unposed.length ? { no_clear_view: unposed } : {}), render_ms: Date.now() - renderStarted };
+                    }
+                    else {
+                        sheet = { error: render.failureReason ?? "render_failed", detail: (render.error ?? "").slice(0, 160) };
+                    }
+                }
+                finally {
+                    await render.dispose();
+                }
+            }
+            page = buildPage({ base: { ...base, sheet }, issues: matching, offset: args.offset, limit: args.limit });
+        }
+        return { ok: true, summary: page.body, image };
+    }
+    finally {
+        await run.dispose();
+    }
+}

package/dist/core/capabilities/audit/frame.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Framing for render:"sheet": a camera per issue, on the OPEN side of the
+ * problem. Each issue carries directions the kernel measured with two-sided
+ * rays (any surface counts, front or back face), so a camera placed within
+ * the measured clear distance is never behind a wall or inside geometry:
+ * walls render one-sided, and a camera behind one sees straight through it.
+ */
+import { type CameraPose } from "../seeing/math.js";
+import type { FrameHint } from "./judge.js";
+export declare const SHEET_FOV = 50;
+export declare const SHEET_TILES = 6;
+/** The pose from the best measured direction: preference x share of the
+ *  wanted distance that is actually clear. Null when nothing is clear. */
+export declare function choosePose(hint: FrameHint | undefined, fov?: number): CameraPose | null;

package/dist/core/capabilities/audit/frame.js

@@ -0,0 +1,35 @@
+/**
+ * Framing for render:"sheet": a camera per issue, on the OPEN side of the
+ * problem. Each issue carries directions the kernel measured with two-sided
+ * rays (any surface counts, front or back face), so a camera placed within
+ * the measured clear distance is never behind a wall or inside geometry:
+ * walls render one-sided, and a camera behind one sees straight through it.
+ */
+import { add, clamp, scale } from "../seeing/math.js";
+import { fitCameraDistance } from "./math.js";
+export const SHEET_FOV = 50;
+export const SHEET_TILES = 6;
+const MIN_DISTANCE = 0.7;
+const CLEARANCE_MARGIN = 0.3;
+/** The pose from the best measured direction: preference x share of the
+ *  wanted distance that is actually clear. Null when nothing is clear. */
+export function choosePose(hint, fov = SHEET_FOV) {
+    if (!hint)
+        return null;
+    if (hint.viewer)
+        return { position: hint.viewer, look_at: hint.focus, fov };
+    const want = clamp(fitCameraDistance(hint.size, fov), 1.5, 9);
+    let best = null;
+    for (const d of hint.dirs) {
+        const available = d.clear - CLEARANCE_MARGIN;
+        if (available < MIN_DISTANCE || d.pref <= 0)
+            continue;
+        const dist = Math.min(want, available);
+        const score = d.pref * (dist / want);
+        if (!best || score > best.score)
+            best = { dir: d.dir, dist, score };
+    }
+    if (!best)
+        return null;
+    return { position: add(hint.focus, scale(best.dir, best.dist)), look_at: hint.focus, fov };
+}