summer-engine 3.0.0 → 3.2.0

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

@@ -0,0 +1,348 @@
+/**
+ * Argument shapes for the seeing tools — ONE copy for both faces (the MCP
+ * registration in src/mcp/tools/seeing-tools.ts and `summer tool <slug>` in
+ * tool-dispatch.ts). The descriptions are the tool docs agents read.
+ */
+import { z } from "zod";
+export declare const frameNodesShape: {
+    scenePath: z.ZodOptional<z.ZodString>;
+    nodes: z.ZodArray<z.ZodString, "many">;
+    direction: z.ZodOptional<z.ZodEnum<["front", "back", "left", "right", "top", "iso"]>>;
+    from: z.ZodOptional<z.ZodString>;
+    fill: z.ZodOptional<z.ZodNumber>;
+    fov: z.ZodOptional<z.ZodNumber>;
+    max_size: z.ZodOptional<z.ZodNumber>;
+    aspect: z.ZodOptional<z.ZodNumber>;
+    marks: z.ZodOptional<z.ZodBoolean>;
+    max_marks: z.ZodOptional<z.ZodNumber>;
+    bookmark_name: z.ZodOptional<z.ZodString>;
+};
+export declare const shotSheetShape: {
+    scenePath: z.ZodOptional<z.ZodString>;
+    shots: z.ZodArray<z.ZodObject<{
+        bookmark_name: z.ZodOptional<z.ZodString>;
+        camera_position: z.ZodOptional<z.ZodString>;
+        camera_look_at: z.ZodOptional<z.ZodString>;
+        fov: z.ZodOptional<z.ZodNumber>;
+        label: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        camera_position?: string | undefined;
+        camera_look_at?: string | undefined;
+        fov?: number | undefined;
+        label?: string | undefined;
+        bookmark_name?: string | undefined;
+    }, {
+        camera_position?: string | undefined;
+        camera_look_at?: string | undefined;
+        fov?: number | undefined;
+        label?: string | undefined;
+        bookmark_name?: string | undefined;
+    }>, "many">;
+    view: z.ZodOptional<z.ZodEnum<["beauty", "lighting", "unshaded", "normals", "overdraw", "wireframe"]>>;
+    compare_previous: z.ZodOptional<z.ZodBoolean>;
+    update_previous: z.ZodOptional<z.ZodBoolean>;
+    max_size: z.ZodOptional<z.ZodNumber>;
+    aspect: z.ZodOptional<z.ZodNumber>;
+    save_to: z.ZodOptional<z.ZodString>;
+};
+export declare const debugViewsShape: {
+    scenePath: z.ZodOptional<z.ZodString>;
+    bookmark_name: z.ZodOptional<z.ZodString>;
+    camera_position: z.ZodOptional<z.ZodString>;
+    camera_look_at: z.ZodOptional<z.ZodString>;
+    fov: z.ZodOptional<z.ZodNumber>;
+    views: z.ZodOptional<z.ZodArray<z.ZodEnum<["beauty", "lighting", "unshaded", "normals", "overdraw", "wireframe"]>, "many">>;
+    update_previous: z.ZodOptional<z.ZodBoolean>;
+    max_size: z.ZodOptional<z.ZodNumber>;
+    aspect: z.ZodOptional<z.ZodNumber>;
+    save_to: z.ZodOptional<z.ZodString>;
+};
+export declare const zoomShape: {
+    scenePath: z.ZodOptional<z.ZodString>;
+    bookmark_name: z.ZodOptional<z.ZodString>;
+    camera_position: z.ZodOptional<z.ZodString>;
+    camera_look_at: z.ZodOptional<z.ZodString>;
+    fov: z.ZodOptional<z.ZodNumber>;
+    region: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    mark: z.ZodOptional<z.ZodNumber>;
+    reference_size: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    pad: z.ZodOptional<z.ZodNumber>;
+    view: z.ZodOptional<z.ZodEnum<["beauty", "lighting", "unshaded", "normals", "overdraw", "wireframe"]>>;
+    max_size: z.ZodOptional<z.ZodNumber>;
+    save_to: z.ZodOptional<z.ZodString>;
+};
+export declare const frameShotShape: {
+    scenePath: z.ZodOptional<z.ZodString>;
+    shot: z.ZodEnum<["establishing", "eye_level", "low_angle", "detail", "corridor"]>;
+    subject: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    spawn: z.ZodOptional<z.ZodString>;
+    eye_height: z.ZodOptional<z.ZodNumber>;
+    fov: z.ZodOptional<z.ZodNumber>;
+    aspect: z.ZodOptional<z.ZodNumber>;
+    occluders: z.ZodOptional<z.ZodObject<{
+        hard: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        soft: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        hard_layers: z.ZodOptional<z.ZodNumber>;
+        soft_layers: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        ignore?: string[] | undefined;
+        hard?: string[] | undefined;
+        soft?: string[] | undefined;
+        hard_layers?: number | undefined;
+        soft_layers?: number | undefined;
+    }, {
+        ignore?: string[] | undefined;
+        hard?: string[] | undefined;
+        soft?: string[] | undefined;
+        hard_layers?: number | undefined;
+        soft_layers?: number | undefined;
+    }>>;
+    max_soft_fraction: z.ZodOptional<z.ZodNumber>;
+    bookmark_name: z.ZodOptional<z.ZodString>;
+    save_bookmark: z.ZodOptional<z.ZodBoolean>;
+    render: z.ZodOptional<z.ZodEnum<["sheet", "best", "none"]>>;
+    max_size: z.ZodOptional<z.ZodNumber>;
+};
+export declare const frameNodesArgsSchema: z.ZodObject<{
+    scenePath: z.ZodOptional<z.ZodString>;
+    nodes: z.ZodArray<z.ZodString, "many">;
+    direction: z.ZodOptional<z.ZodEnum<["front", "back", "left", "right", "top", "iso"]>>;
+    from: z.ZodOptional<z.ZodString>;
+    fill: z.ZodOptional<z.ZodNumber>;
+    fov: z.ZodOptional<z.ZodNumber>;
+    max_size: z.ZodOptional<z.ZodNumber>;
+    aspect: z.ZodOptional<z.ZodNumber>;
+    marks: z.ZodOptional<z.ZodBoolean>;
+    max_marks: z.ZodOptional<z.ZodNumber>;
+    bookmark_name: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    nodes: string[];
+    fill?: number | undefined;
+    scenePath?: string | undefined;
+    fov?: number | undefined;
+    marks?: boolean | undefined;
+    max_marks?: number | undefined;
+    from?: string | undefined;
+    max_size?: number | undefined;
+    bookmark_name?: string | undefined;
+    aspect?: number | undefined;
+    direction?: "top" | "iso" | "front" | "back" | "left" | "right" | undefined;
+}, {
+    nodes: string[];
+    fill?: number | undefined;
+    scenePath?: string | undefined;
+    fov?: number | undefined;
+    marks?: boolean | undefined;
+    max_marks?: number | undefined;
+    from?: string | undefined;
+    max_size?: number | undefined;
+    bookmark_name?: string | undefined;
+    aspect?: number | undefined;
+    direction?: "top" | "iso" | "front" | "back" | "left" | "right" | undefined;
+}>;
+export declare const shotSheetArgsSchema: z.ZodObject<{
+    scenePath: z.ZodOptional<z.ZodString>;
+    shots: z.ZodArray<z.ZodObject<{
+        bookmark_name: z.ZodOptional<z.ZodString>;
+        camera_position: z.ZodOptional<z.ZodString>;
+        camera_look_at: z.ZodOptional<z.ZodString>;
+        fov: z.ZodOptional<z.ZodNumber>;
+        label: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        camera_position?: string | undefined;
+        camera_look_at?: string | undefined;
+        fov?: number | undefined;
+        label?: string | undefined;
+        bookmark_name?: string | undefined;
+    }, {
+        camera_position?: string | undefined;
+        camera_look_at?: string | undefined;
+        fov?: number | undefined;
+        label?: string | undefined;
+        bookmark_name?: string | undefined;
+    }>, "many">;
+    view: z.ZodOptional<z.ZodEnum<["beauty", "lighting", "unshaded", "normals", "overdraw", "wireframe"]>>;
+    compare_previous: z.ZodOptional<z.ZodBoolean>;
+    update_previous: z.ZodOptional<z.ZodBoolean>;
+    max_size: z.ZodOptional<z.ZodNumber>;
+    aspect: z.ZodOptional<z.ZodNumber>;
+    save_to: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    shots: {
+        camera_position?: string | undefined;
+        camera_look_at?: string | undefined;
+        fov?: number | undefined;
+        label?: string | undefined;
+        bookmark_name?: string | undefined;
+    }[];
+    scenePath?: string | undefined;
+    max_size?: number | undefined;
+    save_to?: string | undefined;
+    view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
+    update_previous?: boolean | undefined;
+    aspect?: number | undefined;
+    compare_previous?: boolean | undefined;
+}, {
+    shots: {
+        camera_position?: string | undefined;
+        camera_look_at?: string | undefined;
+        fov?: number | undefined;
+        label?: string | undefined;
+        bookmark_name?: string | undefined;
+    }[];
+    scenePath?: string | undefined;
+    max_size?: number | undefined;
+    save_to?: string | undefined;
+    view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
+    update_previous?: boolean | undefined;
+    aspect?: number | undefined;
+    compare_previous?: boolean | undefined;
+}>;
+export declare const debugViewsArgsSchema: z.ZodObject<{
+    scenePath: z.ZodOptional<z.ZodString>;
+    bookmark_name: z.ZodOptional<z.ZodString>;
+    camera_position: z.ZodOptional<z.ZodString>;
+    camera_look_at: z.ZodOptional<z.ZodString>;
+    fov: z.ZodOptional<z.ZodNumber>;
+    views: z.ZodOptional<z.ZodArray<z.ZodEnum<["beauty", "lighting", "unshaded", "normals", "overdraw", "wireframe"]>, "many">>;
+    update_previous: z.ZodOptional<z.ZodBoolean>;
+    max_size: z.ZodOptional<z.ZodNumber>;
+    aspect: z.ZodOptional<z.ZodNumber>;
+    save_to: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    scenePath?: string | undefined;
+    camera_position?: string | undefined;
+    camera_look_at?: string | undefined;
+    fov?: number | undefined;
+    max_size?: number | undefined;
+    save_to?: string | undefined;
+    bookmark_name?: string | undefined;
+    views?: ("lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe")[] | undefined;
+    update_previous?: boolean | undefined;
+    aspect?: number | undefined;
+}, {
+    scenePath?: string | undefined;
+    camera_position?: string | undefined;
+    camera_look_at?: string | undefined;
+    fov?: number | undefined;
+    max_size?: number | undefined;
+    save_to?: string | undefined;
+    bookmark_name?: string | undefined;
+    views?: ("lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe")[] | undefined;
+    update_previous?: boolean | undefined;
+    aspect?: number | undefined;
+}>;
+export declare const zoomArgsSchema: z.ZodObject<{
+    scenePath: z.ZodOptional<z.ZodString>;
+    bookmark_name: z.ZodOptional<z.ZodString>;
+    camera_position: z.ZodOptional<z.ZodString>;
+    camera_look_at: z.ZodOptional<z.ZodString>;
+    fov: z.ZodOptional<z.ZodNumber>;
+    region: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    mark: z.ZodOptional<z.ZodNumber>;
+    reference_size: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    pad: z.ZodOptional<z.ZodNumber>;
+    view: z.ZodOptional<z.ZodEnum<["beauty", "lighting", "unshaded", "normals", "overdraw", "wireframe"]>>;
+    max_size: z.ZodOptional<z.ZodNumber>;
+    save_to: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    scenePath?: string | undefined;
+    camera_position?: string | undefined;
+    camera_look_at?: string | undefined;
+    fov?: number | undefined;
+    max_size?: number | undefined;
+    save_to?: string | undefined;
+    bookmark_name?: string | undefined;
+    view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
+    region?: number[] | undefined;
+    mark?: number | undefined;
+    reference_size?: number[] | undefined;
+    pad?: number | undefined;
+}, {
+    scenePath?: string | undefined;
+    camera_position?: string | undefined;
+    camera_look_at?: string | undefined;
+    fov?: number | undefined;
+    max_size?: number | undefined;
+    save_to?: string | undefined;
+    bookmark_name?: string | undefined;
+    view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
+    region?: number[] | undefined;
+    mark?: number | undefined;
+    reference_size?: number[] | undefined;
+    pad?: number | undefined;
+}>;
+export declare const frameShotArgsSchema: z.ZodObject<{
+    scenePath: z.ZodOptional<z.ZodString>;
+    shot: z.ZodEnum<["establishing", "eye_level", "low_angle", "detail", "corridor"]>;
+    subject: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    spawn: z.ZodOptional<z.ZodString>;
+    eye_height: z.ZodOptional<z.ZodNumber>;
+    fov: z.ZodOptional<z.ZodNumber>;
+    aspect: z.ZodOptional<z.ZodNumber>;
+    occluders: z.ZodOptional<z.ZodObject<{
+        hard: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        soft: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        hard_layers: z.ZodOptional<z.ZodNumber>;
+        soft_layers: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        ignore?: string[] | undefined;
+        hard?: string[] | undefined;
+        soft?: string[] | undefined;
+        hard_layers?: number | undefined;
+        soft_layers?: number | undefined;
+    }, {
+        ignore?: string[] | undefined;
+        hard?: string[] | undefined;
+        soft?: string[] | undefined;
+        hard_layers?: number | undefined;
+        soft_layers?: number | undefined;
+    }>>;
+    max_soft_fraction: z.ZodOptional<z.ZodNumber>;
+    bookmark_name: z.ZodOptional<z.ZodString>;
+    save_bookmark: z.ZodOptional<z.ZodBoolean>;
+    render: z.ZodOptional<z.ZodEnum<["sheet", "best", "none"]>>;
+    max_size: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    shot: "detail" | "establishing" | "eye_level" | "low_angle" | "corridor";
+    spawn?: string | undefined;
+    scenePath?: string | undefined;
+    fov?: number | undefined;
+    max_size?: number | undefined;
+    bookmark_name?: string | undefined;
+    render?: "none" | "sheet" | "best" | undefined;
+    aspect?: number | undefined;
+    occluders?: {
+        ignore?: string[] | undefined;
+        hard?: string[] | undefined;
+        soft?: string[] | undefined;
+        hard_layers?: number | undefined;
+        soft_layers?: number | undefined;
+    } | undefined;
+    subject?: string[] | undefined;
+    eye_height?: number | undefined;
+    max_soft_fraction?: number | undefined;
+    save_bookmark?: boolean | undefined;
+}, {
+    shot: "detail" | "establishing" | "eye_level" | "low_angle" | "corridor";
+    spawn?: string | undefined;
+    scenePath?: string | undefined;
+    fov?: number | undefined;
+    max_size?: number | undefined;
+    bookmark_name?: string | undefined;
+    render?: "none" | "sheet" | "best" | undefined;
+    aspect?: number | undefined;
+    occluders?: {
+        ignore?: string[] | undefined;
+        hard?: string[] | undefined;
+        soft?: string[] | undefined;
+        hard_layers?: number | undefined;
+        soft_layers?: number | undefined;
+    } | undefined;
+    subject?: string[] | undefined;
+    eye_height?: number | undefined;
+    max_soft_fraction?: number | undefined;
+    save_bookmark?: boolean | undefined;
+}>;

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

@@ -0,0 +1,178 @@
+/**
+ * Argument shapes for the seeing tools — ONE copy for both faces (the MCP
+ * registration in src/mcp/tools/seeing-tools.ts and `summer tool <slug>` in
+ * tool-dispatch.ts). The descriptions are the tool docs agents read.
+ */
+import { z } from "zod";
+import { DIRECTION_PRESET_NAMES } from "./math.js";
+import { SHOT_TYPES } from "./candidates.js";
+import { MAX_IMAGE_EDGE, VIEW_MODES } from "./seeing.js";
+const scenePath = z
+    .string()
+    .optional()
+    .describe('Scene to look at, e.g. "res://levels/town.tscn" (the SAVED file). Omit for the scene open in the editor.');
+const bookmarkName = z
+    .string()
+    .optional()
+    .describe('Pose from a camera bookmark (summer_camera_bookmark). Use INSTEAD of camera_position/camera_look_at.');
+const cameraPosition = z.string().optional().describe('Explicit pose: camera position, "Vector3(x, y, z)". Goes with camera_look_at.');
+const cameraLookAt = z.string().optional().describe('Explicit pose: point the camera looks at, "Vector3(x, y, z)".');
+const fov = z.number().optional().describe("Vertical field of view in degrees (1..179). Default: the bookmark's own, or 60.");
+const maxSize = (fallback) => z
+    .number()
+    .int()
+    .min(64)
+    .max(MAX_IMAGE_EDGE)
+    .optional()
+    .describe(`Longest edge of the returned JPEG in pixels (default ${fallback}). Bigger costs more context; up to ${MAX_IMAGE_EDGE} for detail work on a PC.`);
+const aspect = z.number().optional().describe("Frame width/height (default 1.7778 = 16:9). Every tile uses it.");
+const saveTo = z
+    .string()
+    .optional()
+    .describe('Also write the returned image to res://.summer/shots/saved/<name>.jpg (1-64 of A-Z a-z 0-9 _ -; needs max_size <= 1024). Nothing is written without it, except one previous-image slot per rendered bookmark.');
+const view = z
+    .enum(VIEW_MODES)
+    .optional()
+    .describe('"beauty" (default: real environment, lights, fog, tonemap), "lighting" (light only), "unshaded" (albedo/texture only), "normals" (world normals, x red y green z blue), "overdraw", "wireframe".');
+export const frameNodesShape = {
+    scenePath,
+    nodes: z
+        .array(z.string())
+        .min(1)
+        .max(16)
+        .describe('Node paths relative to the scene root ("House1", "Props/Crate_02"). The camera fits their combined WORLD bounds (visible meshes, children included).'),
+    direction: z
+        .enum(DIRECTION_PRESET_NAMES)
+        .optional()
+        .describe('Side the camera sits on: "front" (+Z), "back" (-Z), "left" (-X), "right" (+X), "top", "iso" (default, 3/4 from -X,+Y,-Z like summer_screenshot). Use from for anything else.'),
+    from: z
+        .string()
+        .optional()
+        .describe('Explicit direction FROM the nodes TOWARD the camera, "Vector3(1, 0.4, 2)". Replaces direction. The fitted pose is checked in-engine: when walls block it, or it puts the camera behind or inside a one-sided surface (whose back is not drawn, so the image would look THROUGH it), the caption opens with a WARNING and offers the nearest valid from (+ fov); the requested view is still rendered.'),
+    fill: z.number().optional().describe("Share of the frame the nodes span along their limiting dimension (0.1..1.5, default 0.8)."),
+    fov: z.number().optional().describe("Vertical field of view in degrees (default 50)."),
+    max_size: maxSize(1024),
+    aspect,
+    marks: z
+        .boolean()
+        .optional()
+        .describe("Numbered Set-of-Mark labels over the largest visible nodes; the caption maps label -> node path (feed a label to summer_zoom mark). Each labelled node gets an occlusion test (centre + 4 bounds points); a node hidden behind other geometry is noted \"(hidden behind <path>)\" — ignore its label."),
+    max_marks: z.number().int().min(1).max(128).optional().describe("marks only: cap on labels (engine default 32)."),
+    bookmark_name: z
+        .string()
+        .optional()
+        .describe("Also save the fitted pose as this camera bookmark (1-64 of A-Z a-z 0-9 _ -), so later renders line up with it."),
+};
+const shotShape = z.object({
+    bookmark_name: bookmarkName,
+    camera_position: cameraPosition,
+    camera_look_at: cameraLookAt,
+    fov,
+    label: z.string().optional().describe("Tile label (1-64 printable characters, no quotes, backslashes or $). Default: the bookmark name or 'shot N'."),
+});
+export const shotSheetShape = {
+    scenePath,
+    shots: z
+        .array(shotShape)
+        .min(1)
+        .max(12)
+        .describe("1-12 shots, each a bookmark_name OR camera_position + camera_look_at (+ fov), with an optional label. Rendered in this order, left to right, top to bottom."),
+    view,
+    compare_previous: z
+        .boolean()
+        .optional()
+        .describe("For bookmark shots: one row per bookmark of [previous render | now | difference map], with the share of changed pixels in the caption. The previous render is the bookmark's slot in res://.summer/shots/; this render replaces it (it is the next baseline)."),
+    update_previous: z
+        .boolean()
+        .optional()
+        .describe("Replace each bookmark's previous image (its compare baseline) with this render without comparing. Default false: a sheet without compare_previous only creates a missing slot and never overwrites an existing baseline."),
+    max_size: maxSize(1536),
+    aspect,
+    save_to: saveTo,
+};
+export const debugViewsShape = {
+    scenePath,
+    bookmark_name: bookmarkName,
+    camera_position: cameraPosition,
+    camera_look_at: cameraLookAt,
+    fov,
+    views: z
+        .array(z.enum(VIEW_MODES))
+        .max(8)
+        .optional()
+        .describe("Which views, in grid order (default all six: beauty, lighting, unshaded, normals, overdraw, wireframe)."),
+    update_previous: z
+        .boolean()
+        .optional()
+        .describe("bookmark_name only: replace the bookmark's previous image (compare baseline) with this beauty tile. Default false: only a missing slot is created."),
+    max_size: maxSize(1536),
+    aspect,
+    save_to: saveTo,
+};
+export const zoomShape = {
+    scenePath,
+    bookmark_name: bookmarkName,
+    camera_position: cameraPosition,
+    camera_look_at: cameraLookAt,
+    fov,
+    region: z
+        .array(z.number())
+        .length(4)
+        .optional()
+        .describe("[x, y, w, h] as fractions (0..1) of the frame from the same pose, x/y from the TOP-LEFT. Use this OR mark. Rendered EXACTLY (no padding by default, never widened to an aspect ratio): the image takes the region's own aspect, with dark bars only for extreme shapes."),
+    mark: z
+        .number()
+        .int()
+        .optional()
+        .describe("A label number from a marks:true render of the SAME pose and reference_size (summer_frame_nodes, or summer_screenshot framing free/bookmark at that size). The caption warns when that node is hidden behind other geometry at this pose."),
+    reference_size: z
+        .array(z.number().int())
+        .length(2)
+        .optional()
+        .describe("[width, height] of the frame region/mark refer to (default [1024, 576]). Sets the zoom's aspect."),
+    pad: z
+        .number()
+        .optional()
+        .describe("Margin added around the region on each side, as a fraction of its size (0..1; default 0 for region, 0.15 for mark). The caption's widened_because says when the rendered window is larger than asked."),
+    view,
+    max_size: maxSize(1024),
+    save_to: saveTo,
+};
+export const frameShotShape = {
+    scenePath,
+    shot: z
+        .enum(SHOT_TYPES)
+        .describe('"establishing" (wide, whole subject, 12-40 deg up; a pose showing more than 15% empty ground or world edge ranks below every pose showing less), "eye_level" (player eye at spawn: its Camera3D kept inside 1.5-1.8 m, or eye_height, above the walkable surface under the camera), "low_angle" (hero, camera near the ground looking up), "detail" (close-up), "corridor" (down a lane/corridor inside the subject, found by a free-space scan, at eye height; prefers looking in from its open end). Eye-level and corridor cameras are never raised: a pose that cannot stand at eye height moves horizontally or is rejected. Every top pose states its camera height above the surface below it and its absolute y.'),
+    subject: z
+        .array(z.string())
+        .max(8)
+        .optional()
+        .describe("Node paths to frame (required except for eye_level, where it is what the player looks at)."),
+    spawn: z.string().optional().describe("eye_level only: node the player stands at, e.g. the player or a spawn marker. Its own geometry never counts as an occluder."),
+    eye_height: z.number().optional().describe("eye_level/corridor: exact camera height in metres above the walkable surface under the camera (default: 1.6; an eye_level spawn's own Camera3D keeps its height clamped into 1.5-1.8)."),
+    fov: z.number().optional().describe("Override the shot type's field of view (establishing 55, eye_level 60/75, low_angle 60 then widened, detail 40, corridor 60/75)."),
+    aspect,
+    occluders: z
+        .object({
+        hard: z.array(z.string()).optional().describe("Path prefixes that must never block the view (walls, terrain): a pose they block is rejected."),
+        soft: z.array(z.string()).optional().describe("Path prefixes that may sit in front as framing (foliage, fences, props)."),
+        ignore: z.array(z.string()).optional().describe("Path prefixes left out of the visibility pass entirely."),
+        hard_layers: z.number().int().optional().describe("Physics layer mask: geometry whose nearest CollisionObject3D is on these layers is hard."),
+        soft_layers: z.number().int().optional().describe("Physics layer mask for soft geometry."),
+    })
+        .optional()
+        .describe("Override the occluder classification. Default: path names (wall/house/terrain... = hard; tree/fence/lamp/prop/pipe... = soft), MultiMesh = soft, else size (<= 2.5 m = soft). The caption reports the counts by rule."),
+    max_soft_fraction: z.number().optional().describe("Most of the subject that soft geometry may cover before a pose is rejected (0..1, default 0.67)."),
+    bookmark_name: z.string().optional().describe("Name for the saved best pose (default <shot>_<subject leaf>)."),
+    save_bookmark: z.boolean().optional().describe("Save the best pose as a camera bookmark (default true)."),
+    render: z
+        .enum(["sheet", "best", "none"])
+        .optional()
+        .describe('"sheet" (default): the top 3 in one labelled grid with real lighting; "best": the winner only; "none": scores only.'),
+    max_size: maxSize(1536),
+};
+export const frameNodesArgsSchema = z.object(frameNodesShape).strict();
+export const shotSheetArgsSchema = z.object(shotSheetShape).strict();
+export const debugViewsArgsSchema = z.object(debugViewsShape).strict();
+export const zoomArgsSchema = z.object(zoomShape).strict();
+export const frameShotArgsSchema = z.object(frameShotShape).strict();

package/dist/core/capabilities/seeing/candidates.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Smart framing, part 1: candidate camera poses per shot type. Pure and
+ * engine-free — the engine only measures what these poses would see
+ * (assets/seeing/seeing_probe.gd "measure"); scoring.ts ranks the result.
+ *
+ * Every candidate sits at the distance where the subject fills the shot
+ * type's target share of the frame (fitDistance), on a ring or hemisphere
+ * around the subject, or along a corridor's free line. Low angles follow the
+ * low-angle rule (closer + wider instead of buried in the ground).
+ */
+import { type Aabb, type Vec3 } from "./math.js";
+export declare const SHOT_TYPES: readonly ["establishing", "eye_level", "low_angle", "detail", "corridor"];
+export type ShotType = (typeof SHOT_TYPES)[number];
+/**
+ * Eye mode (eye_level and corridor): the camera stands at eye height above the
+ * walkable surface under it and is never raised. The engine finds that
+ * surface straight below the lens (overhead structure never counts), checks
+ * it is within a step of the floor under `stand`, and puts the camera
+ * `target` above it (without a target: its current height, clamped into
+ * min..max). A pose that cannot stand there moves horizontally or is rejected.
+ */
+export interface EyeSpec {
+    /** Lowest and highest allowed camera height above the walkable surface (m). */
+    min: number;
+    max: number;
+    /** Height above the walkable surface to stand the camera at; absent = keep
+     *  its own height inside min..max (a spawn's Camera3D). */
+    target?: number;
+    /** Where the player stands (spawn origin, corridor seed): the floor under it
+     *  is the walkable reference. */
+    stand: Vec3;
+}
+export interface Candidate {
+    id: string;
+    position: Vec3;
+    look_at: Vec3;
+    fov: number;
+    /** World points the thick sweep must reach (subject bounds or corridor line). */
+    samples: Vec3[];
+    /** Below this height above the ground under the camera the engine applies
+     *  the low-angle rule (or raises the camera when it is not looking up).
+     *  Ignored in eye mode. */
+    min_clearance: number;
+    low_angle_rule: boolean;
+    /** Eye mode: eye_level and corridor poses. */
+    eye?: EyeSpec;
+    note?: string;
+    /** Corridor only: 1 = from an open end looking in, 0 = looking out of a
+     *  dead end, 0.5 = a through passage (both ends alike). */
+    into?: number;
+}
+export interface SpawnInfo {
+    path: string;
+    origin: Vec3;
+    forward: Vec3;
+    camera?: {
+        path: string;
+        position: Vec3;
+        forward: Vec3;
+        fov: number;
+    };
+}
+export interface CorridorRun {
+    seed: Vec3;
+    dir: Vec3;
+    fwd: number;
+    back: number;
+    left: number;
+    right: number;
+}
+export interface CorridorAxis extends CorridorRun {
+    /** Free length inside the subject bounds (+ a small margin) along dir. */
+    usableFwd: number;
+    usableBack: number;
+    width: number;
+    score: number;
+    /** The free run continues past the subject bounds on that end: an
+     *  entrance. A closed end is a dead end (or the far wall). */
+    openFwd: boolean;
+    openBack: boolean;
+}
+export interface CandidateContext {
+    shot: ShotType;
+    /** Merged bounds of the subject nodes (absent for a subject-less eye-level look). */
+    subject?: Aabb;
+    spawn?: SpawnInfo;
+    corridor?: CorridorAxis;
+    aspect: number;
+    /** Overrides the shot type's default fov. */
+    fov?: number;
+    eyeHeight?: number;
+    /** Ground height under the subject; defaults to the subject's lowest point. */
+    groundY?: number;
+}
+export interface ShotDefaults {
+    fov: number;
+    /** Target share of the frame along the subject's limiting dimension. */
+    fill: number;
+}
+export declare const SHOT_DEFAULTS: Record<ShotType, ShotDefaults>;
+export declare const LOW_ANGLE_CLEARANCE = 0.35;
+export declare const DEFAULT_CLEARANCE = 0.3;
+export declare const MAX_FOV = 100;
+export declare const DEFAULT_EYE_HEIGHT = 1.6;
+/** A standing eye without an explicit eye_height: 1.5-1.8 m above the walkable
+ *  surface under the camera. */
+export declare const EYE_BAND: readonly [number, number];
+/** The eye band: exactly eye_height when given, else EYE_BAND. */
+export declare function eyeBand(eyeHeight: number | undefined): [number, number];
+/** Nine points the thick sweep aims at: the center plus the eight corners
+ *  pulled 40% toward it, so a subject standing on the ground still offers
+ *  points above the ground plane. */
+export declare function subjectSamples(box: Aabb): Vec3[];
+/** Where a ray from `origin` along `dir` leaves `box` (slab test), or Infinity. */
+export declare function exitDistance(box: Aabb, origin: Vec3, dir: Vec3): number;
+/**
+ * Pick the corridor axis from the engine's free-run scan: the longest free
+ * line (clipped to the subject bounds + 2 m on each end) that is also narrow
+ * enough to read as a corridor and wide enough to walk.
+ */
+export declare function chooseCorridorAxis(runs: readonly CorridorRun[], box: Aabb): CorridorAxis[];
+/** The walkable floor along a corridor axis: the scan put its seed at eye
+ *  height above the floor it found there. */
+export declare function corridorFloorY(axis: CorridorRun, eyeHeight: number | undefined): number;
+export declare function generateCandidates(ctx: CandidateContext): Candidate[];
+/** Corridor "subject" box used for frame metrics: the free line it looks down. */
+export declare function corridorBox(axis: CorridorAxis, floorY: number): Aabb;