summer-engine 3.1.0 → 3.2.0

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

@@ -0,0 +1,62 @@
+export declare const KERNEL_PATH: string;
+export declare function loadKernelSource(): string;
+/** Engine paths always use forward slashes (Windows accepts them too). */
+export declare function enginePath(path: string): string;
+/** Escape a string for a quoted value in a text scene (.tscn): the engine's
+ *  variant parser unescapes \\ and \" ; newlines may stay literal. */
+export declare function escapeTscnString(value: string): string;
+/**
+ * The wrapper scene. The ONLY caller-derived value in it is the target scene
+ * path, which must already have passed validateScenePath (res://, no quotes,
+ * backslashes, newlines or `$`); it is escaped again here as defence in depth.
+ * Every other argument travels as data in config.json, which the kernel finds
+ * through its own script path and parses as JSON — nothing is spliced into
+ * GDScript source.
+ */
+export declare function buildWrapperScene(targetScenePath: string, kernelSource: string): string;
+/** The engine reads ScenePreview through the shared ops path. */
+export interface ProbeClient {
+    executeOps(ops: Record<string, unknown>[], options?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+}
+export interface ProbeImage {
+    base64: string;
+    mime: string;
+    width?: number;
+    height?: number;
+}
+export interface ProbeRun {
+    ok: boolean;
+    /** The kernel's result.json, when it got far enough to write one. */
+    result: Record<string, unknown> | null;
+    /** The composed frame ScenePreview read back (render mode). */
+    image?: ProbeImage;
+    /** The temp directory: captures live here until dispose(). */
+    dir: string;
+    failureReason?: string;
+    error?: string;
+    dispose(): Promise<void>;
+}
+export interface RunProbeOptions {
+    scenePath: string;
+    config: Record<string, unknown>;
+    /** Another kernel to run the same private-copy way (default: the seeing
+     *  kernel). summer_scene_audit passes assets/audit/scene_audit.gd. */
+    kernel?: string;
+    /** ScenePreview output size; the canvas for render mode, tiny for analyze. */
+    size: [number, number];
+    timeoutMs?: number;
+}
+export declare const PROBE_DIR_PREFIX = "summer-seeing-";
+/**
+ * Per-call run directory for the wrapper scene, its config and captures:
+ * mkdtemp DIRECTLY in the OS temp directory (random name, mode 0700). There is
+ * deliberately no shared fixed parent such as <tmp>/summer-engine/seeing: on
+ * a multi-user machine (Linux /tmp) another user could pre-create or symlink
+ * that parent and swap the wrapper scene the engine then loads and runs as
+ * code. The directory is re-checked before anything is written into it.
+ */
+export declare function makeProbeDir(): Promise<string>;
+/** Refuse a run directory that is not a real directory owned by this user
+ *  with no group/other permissions (symlink, shared, or foreign). */
+export declare function assertPrivateDir(dir: string): Promise<void>;
+export declare function runProbe(client: ProbeClient, options: RunProbeOptions, dirOverride?: string): Promise<ProbeRun>;

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

@@ -0,0 +1,188 @@
+/**
+ * Run the seeing kernel (assets/seeing/seeing_probe.gd) inside the engine.
+ *
+ * How: write a throwaway wrapper scene to a fresh OS temp directory — it
+ * instances the target scene as "Subject" and carries the kernel as a
+ * built-in @tool script — then render that wrapper with the existing
+ * ScenePreview op (absolute scene_path). ScenePreview instantiates it in an
+ * offscreen SubViewport with its own World3D, so the kernel works on a private
+ * copy: the edited scene, its undo history and every project file stay
+ * untouched (ScenePreview is read-only, and the op executor discards the empty
+ * undo action it opens). The kernel writes result.json (and tile captures,
+ * when asked) into the same temp directory; the caller reads them and the
+ * directory is removed afterwards. No engine change, no child process.
+ *
+ * Why not RunSceneScript / RunEditorScript: RunSceneScript marks the open scene
+ * unsaved after every run, even a read-only one; RunEditorScript boots a
+ * headless child editor that has no renderer at all.
+ */
+import { lstat, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PACKAGE_ROOT } from "../../package-root.js";
+import { getFailureReason } from "../engine-receipt.js";
+export const KERNEL_PATH = join(PACKAGE_ROOT, "assets", "seeing", "seeing_probe.gd");
+let kernelCache = null;
+export function loadKernelSource() {
+    if (kernelCache === null)
+        kernelCache = readFileSync(KERNEL_PATH, "utf-8");
+    return kernelCache;
+}
+/** Engine paths always use forward slashes (Windows accepts them too). */
+export function enginePath(path) {
+    return path.replace(/\\/g, "/");
+}
+/** Escape a string for a quoted value in a text scene (.tscn): the engine's
+ *  variant parser unescapes \\ and \" ; newlines may stay literal. */
+export function escapeTscnString(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+/**
+ * The wrapper scene. The ONLY caller-derived value in it is the target scene
+ * path, which must already have passed validateScenePath (res://, no quotes,
+ * backslashes, newlines or `$`); it is escaped again here as defence in depth.
+ * Every other argument travels as data in config.json, which the kernel finds
+ * through its own script path and parses as JSON — nothing is spliced into
+ * GDScript source.
+ */
+export function buildWrapperScene(targetScenePath, kernelSource) {
+    const script = kernelSource;
+    return [
+        "[gd_scene format=3]",
+        "",
+        `[ext_resource type="PackedScene" path="${escapeTscnString(targetScenePath)}" id="1_subject"]`,
+        "",
+        '[sub_resource type="GDScript" id="GDScript_seeing"]',
+        `script/source = "${escapeTscnString(script)}"`,
+        "",
+        '[node name="SummerSeeing" type="Node3D"]',
+        "",
+        '[node name="Subject" parent="." instance=ExtResource("1_subject")]',
+        "",
+        '[node name="SeeingProbe" type="Node" parent="."]',
+        'script = SubResource("GDScript_seeing")',
+        "",
+    ].join("\n");
+}
+function firstResult(response) {
+    if (!response || typeof response !== "object")
+        return {};
+    const envelope = response;
+    const first = Array.isArray(envelope.results) ? envelope.results[0] : undefined;
+    if (first && typeof first === "object")
+        return first;
+    return envelope;
+}
+export const PROBE_DIR_PREFIX = "summer-seeing-";
+/**
+ * Per-call run directory for the wrapper scene, its config and captures:
+ * mkdtemp DIRECTLY in the OS temp directory (random name, mode 0700). There is
+ * deliberately no shared fixed parent such as <tmp>/summer-engine/seeing: on
+ * a multi-user machine (Linux /tmp) another user could pre-create or symlink
+ * that parent and swap the wrapper scene the engine then loads and runs as
+ * code. The directory is re-checked before anything is written into it.
+ */
+export async function makeProbeDir() {
+    const dir = await mkdtemp(join(tmpdir(), PROBE_DIR_PREFIX));
+    await assertPrivateDir(dir);
+    return dir;
+}
+/** Refuse a run directory that is not a real directory owned by this user
+ *  with no group/other permissions (symlink, shared, or foreign). */
+export async function assertPrivateDir(dir) {
+    const info = await lstat(dir);
+    if (info.isSymbolicLink() || !info.isDirectory()) {
+        throw new Error(`Refusing seeing run directory ${dir}: not a real directory.`);
+    }
+    if (process.platform === "win32")
+        return;
+    if (typeof process.getuid === "function" && info.uid !== process.getuid()) {
+        throw new Error(`Refusing seeing run directory ${dir}: owned by another user.`);
+    }
+    if ((info.mode & 0o077) !== 0) {
+        throw new Error(`Refusing seeing run directory ${dir}: group/other can access it (mode ${(info.mode & 0o777).toString(8)}).`);
+    }
+}
+export async function runProbe(client, options, dirOverride) {
+    const dir = dirOverride ?? (await makeProbeDir());
+    await assertPrivateDir(dir);
+    const dispose = async () => {
+        await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+    };
+    const configPath = join(dir, "config.json");
+    const wrapperPath = join(dir, "wrapper.tscn");
+    const config = { ...options.config, scene_path: options.scenePath };
+    await writeFile(configPath, JSON.stringify(config));
+    await writeFile(wrapperPath, buildWrapperScene(options.scenePath, options.kernel ?? loadKernelSource()));
+    let response;
+    try {
+        response = await client.executeOps([
+            {
+                op: "ScenePreview",
+                scene_path: enginePath(wrapperPath),
+                // A fixed pose keeps ScenePreview from injecting its flat preview
+                // environment or an auxiliary light into the shared world; the
+                // kernel turns this camera's own 3D pass off.
+                framing: "free",
+                camera_position: "Vector3(0, 10, 10)",
+                camera_look_at: "Vector3(0, 0, 0)",
+                size: options.size,
+            },
+        ], undefined, options.timeoutMs ?? 120_000);
+    }
+    catch (err) {
+        return { ok: false, result: null, dir, failureReason: "transport", error: err instanceof Error ? err.message : String(err), dispose };
+    }
+    const op = firstResult(response);
+    let result = null;
+    try {
+        result = JSON.parse(await readFile(join(dir, "result.json"), "utf-8"));
+    }
+    catch {
+        result = null;
+    }
+    if (op.ok === false || response?.ok === false) {
+        return {
+            ok: false,
+            result,
+            dir,
+            failureReason: getFailureReason(op) ?? getFailureReason(response) ?? "preview_failed",
+            error: typeof op.error === "string" ? op.error : JSON.stringify(op).slice(0, 400),
+            dispose,
+        };
+    }
+    const base64 = typeof op.image_base64 === "string" ? op.image_base64 : typeof op.base64 === "string" ? op.base64 : undefined;
+    const image = base64
+        ? {
+            base64,
+            mime: typeof op.mime === "string" ? op.mime : "image/jpeg",
+            ...(typeof op.width === "number" ? { width: op.width } : {}),
+            ...(typeof op.height === "number" ? { height: op.height } : {}),
+        }
+        : undefined;
+    if (!result) {
+        return {
+            ok: false,
+            result: null,
+            image,
+            dir,
+            failureReason: "probe_did_not_run",
+            error: "The seeing kernel never wrote its result: the wrapper scene loaded but the built-in @tool script did not run (a script compile error, or the target scene failed to load). Read summer_get_console for the engine's error.",
+            dispose,
+        };
+    }
+    if (result.ok !== true) {
+        const errors = Array.isArray(result.errors) ? result.errors.map(String).join("; ") : "";
+        return {
+            ok: false,
+            result,
+            image,
+            dir,
+            failureReason: typeof result.failure_reason === "string" ? result.failure_reason : "probe_failed",
+            error: errors || `The seeing kernel stopped at stage "${String(result.stage)}".`,
+            dispose,
+        };
+    }
+    return { ok: true, result, image, dir, dispose };
+}

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

@@ -0,0 +1,235 @@
+/**
+ * Smart framing, part 2: score what each candidate pose would see. Pure and
+ * engine-free; the inputs are the engine's measurements (thick-sweep
+ * visibility codes, near-lens/low-angle adjustments, and a ray grid through
+ * the frame with a class and a distance per cell).
+ *
+ * Terms (each 0..1): visibility, fill, thirds, horizon, sky, void, depth,
+ * foreground, clear, balance, detail, contrast, entry, solid (no surfaces
+ * seen from behind), light (key-light direction) and edge (no world edge
+ * below the horizon). Weights depend on the shot type. Hard rejections
+ * (blocked by walls/terrain, camera behind or inside a surface, camera in
+ * geometry, subject out of frame, too much clutter, an eye-level or corridor
+ * camera off eye height) never rank, but are counted by reason. Establishing
+ * shots rank in tiers: a pose that shows more than EMPTY_LIMIT empty ground or
+ * world edge ranks below every pose that shows less, whatever the weights.
+ */
+import { type Candidate, type ShotType } from "./candidates.js";
+import { type Aabb, type CameraPose, type Vec3 } from "./math.js";
+export declare const SCORE_TERMS: readonly ["visibility", "fill", "thirds", "horizon", "sky", "void", "depth", "foreground", "clear", "balance", "detail", "contrast", "entry", "solid", "light", "edge"];
+export type ScoreTerm = (typeof SCORE_TERMS)[number];
+export interface ShotProfile {
+    fillTarget: number;
+    fillTolerance: number;
+    sky: [number, number];
+    foregroundTarget: number;
+    foregroundMax: number;
+    weights: Record<ScoreTerm, number>;
+    /** Tier rule: a pose whose empty share (world edge + empty ground) is over
+     *  this ranks below every pose at or under it. */
+    emptyLimit?: number;
+}
+/** Establishing: "about 15%" empty ground or world edge is decisive. */
+export declare const EMPTY_LIMIT = 0.15;
+export declare const SHOT_PROFILES: Record<ShotType, ShotProfile>;
+/** What the engine measured for one candidate (seeing_probe.gd _measure_one). */
+export interface Measurement {
+    i: number;
+    position: Vec3;
+    look_at: Vec3;
+    fov: number;
+    rejected?: string;
+    near_lens_hit?: string;
+    adjustments?: Array<Record<string, unknown>>;
+    /** One code per sample: V visible, T seen through transparent surfaces
+     *  (partial weight), F soft-occluded, H hard-blocked, B behind a surface
+     *  (the line crosses a hard or subject surface from its BACK side: culled,
+     *  so the image would look through it). */
+    vis?: string;
+    blockers_hard?: string[];
+    blockers_soft?: string[];
+    /** Surfaces the sight lines crossed from behind ("B" samples). */
+    blockers_back?: string[];
+    /** Transparent surfaces the sight lines passed through ("T" samples). */
+    seen_through?: string[];
+    /** Row-major ray grid codes: "." nothing (sky/void), S subject, H hard,
+     *  F soft, T transparent (seen through), B a hard/subject surface met from
+     *  behind (not drawn). */
+    grid?: string;
+    /** Distance per grid cell, -1 for no hit. */
+    dist?: number[];
+    /** Image check (a small beauty render of the final pose), per grid cell:
+     *  luminance decile and texture spread, "0" = featureless. */
+    lum?: string;
+    tex?: string;
+    /** Height of the first solid surface straight below the final camera
+     *  position; null = nothing below it (the world edge). */
+    ground_y?: number | null;
+}
+export interface ScoringOptions {
+    shot: ShotType;
+    aspect: number;
+    gridCols: number;
+    gridRows: number;
+    /** Subject bounds for fill/thirds/in-frame/depth; absent = no subject. */
+    subject?: Aabb;
+    maxHardFraction: number;
+    maxSoftFraction: number;
+    /** Direction the key light TRAVELS (a DirectionalLight3D's -Z); absent =
+     *  no light term. */
+    keyLight?: Vec3;
+}
+/** A frame showing more than this share of surfaces from behind is a camera
+ *  behind (or inside) a wall: the image would look through it. */
+export declare const MAX_BACK_SHARE = 0.25;
+export interface FrameStats {
+    sky: number;
+    void: number;
+    subject: number;
+    hard: number;
+    soft: number;
+    foreground: number;
+    /** Fraction of non-subject, non-foreground cells hitting hard geometry no
+     *  more than 40% beyond the subject: a flat wall right behind it. */
+    wallBehind: number;
+    /** Cells whose first surface is a hard/subject surface seen from behind
+     *  (not drawn: the image looks through it). */
+    back: number;
+    /** Cells whose first surface is transparent (seen through). */
+    translucent: number;
+    /** Fraction of the frame covered by hard geometry right at the lens
+     *  (closer than max(2.5 m, 15% of the subject distance)). */
+    nearHard: number;
+    /** Near-wall share in the left vs right half of the frame. */
+    nearLeft: number;
+    nearRight: number;
+    /** Image check: share of the frame that renders featureless (sky excluded),
+     *  and mean luminance decile of near vs far cells. */
+    flat?: number;
+    nearLum?: number;
+    farLum?: number;
+    /** Image check: share of the frame that is featureless ground or
+     *  surroundings outside the subject's footprint, below the horizon (a bare
+     *  plain, a fogged backing plane). */
+    emptyGround?: number;
+    /** World edge + empty ground: what the establishing tier rule reads. */
+    empty?: number;
+}
+export interface ScoredCandidate {
+    id: string;
+    index: number;
+    pose: CameraPose;
+    total: number;
+    terms: Partial<Record<ScoreTerm, number>>;
+    rejected?: string;
+    stats?: FrameStats;
+    hardFraction?: number;
+    softFraction?: number;
+    fill?: number;
+    inFrame?: number;
+    adjustments?: Array<Record<string, unknown>>;
+    blockers?: {
+        hard?: string[];
+        soft?: string[];
+        back?: string[];
+        through?: string[];
+        lens?: string;
+    };
+    note?: string;
+    /** The first solid surface straight below the camera (null: none). */
+    groundY?: number | null;
+    /** 0 = clean; 1 = over the shot's empty limit (ranks below every tier 0). */
+    tier?: number;
+}
+export declare function foregroundScore(share: number, target: number, max: number): number;
+export declare function thirdsScore(pose: CameraPose, aspect: number, box: Aabb): number;
+/**
+ * Poses are built with a level up vector, so roll is always zero (a level
+ * horizon by construction); what is left to judge is where the horizon cuts
+ * the frame. Eye-level and corridor shots are one-point perspective views
+ * where a centered horizon is natural; elsewhere a horizon through the dead
+ * center splits the frame in two and is marked down.
+ */
+export declare function horizonScore(pose: CameraPose, shot?: ShotType): number;
+/**
+ * One featureless grid cell (image check tex "0") is empty ground when its ray
+ * points below the horizon and meets non-subject geometry outside the
+ * subject's footprint (+ 0.5 m) and below its middle: the bare ground or
+ * fogged backing plane around the subject, not the subject's own floor.
+ */
+export declare function isEmptyGround(code: string | undefined, d: number, ray: Vec3, pose: CameraPose, subject: Aabb | undefined): boolean;
+export declare function frameStats(m: Measurement, pose: CameraPose, opts: ScoringOptions): {
+    stats: FrameStats;
+    depth: number;
+};
+/** Ratio (0..1) of the median wall distance in the frame's left and right
+ *  quarters; 0 when one side shows no wall at all. */
+export declare function edgeSymmetry(m: Measurement, opts: ScoringOptions): number;
+export interface ViewProblem {
+    /** behind_surface | hard_blocked | inside_volume | near_lens_blocked | below_ground */
+    reason: string;
+    /** One line for a caption. */
+    detail: string;
+    blockers?: string[];
+}
+/**
+ * Is this pose a view a player could have of the subject? The one rule both
+ * smart framing (rejection) and frame_nodes (a warning for an explicit pose)
+ * use. A sight line that crosses a hard or subject surface from BEHIND is as
+ * blocked as one that hits a wall's front: back faces are not drawn, so the
+ * image would look through the wall the camera stands behind. A frame that
+ * shows more than MAX_BACK_SHARE of surfaces from behind is the same failure
+ * seen through the lens; the engine's own lens checks (inside a closed shell,
+ * just behind a surface, touching geometry) come through as rejections.
+ */
+export declare function viewProblem(m: Measurement, maxHardFraction?: number): ViewProblem | null;
+/**
+ * Eye mode guard (eye_level, corridor): the camera must stand min..max above
+ * the solid surface straight below it, and must never have been raised. The
+ * engine places eye poses that way; this refuses anything else, so a raised
+ * eye can never win. Null when the pose is at eye height.
+ */
+export declare function eyeProblem(m: Measurement, candidate: Candidate): string | null;
+/** Camera height above the solid surface straight below it, or undefined. */
+export declare function heightAboveGround(position: Vec3, groundY: number | null | undefined): number | undefined;
+/**
+ * Key-light direction relative to the view (0..1). `light` is the direction
+ * the light travels. Best: side or front-side light (the faces the camera
+ * sees get form and shadow); worst: light from straight behind the camera
+ * (a flat-lit face); backlight is in between. A sun near the zenith lights
+ * every side alike, so the term flattens toward neutral.
+ */
+export declare function lightScore(pose: CameraPose, light: Vec3): number;
+/** Share of the frame below the horizon that shows sky or void: the world's
+ *  edge (the ground ends in view). The grid's "." cells with a downward ray. */
+export declare const WORLD_EDGE_LIMIT = 0.04;
+export declare function scoreMeasurement(m: Measurement, candidate: Candidate, opts: ScoringOptions): ScoredCandidate;
+/** Rank order: tier first (a pose over the empty limit loses to every pose
+ *  under it), then score. */
+export declare function rankOrder(a: ScoredCandidate, b: ScoredCandidate): number;
+export interface PickDiversity {
+    /** Ring shots: the yaw of each pick is the camera's azimuth around this
+     *  point; without it, the yaw of the view direction. */
+    around?: Vec3;
+    /** Minimum yaw between any two picks, degrees (default 25). */
+    minYaw?: number;
+    /** Prefer picks from distinct sides (front +Z, right +X, back -Z, left -X)
+     *  while they score within `sideMargin` of the best (default 0.15). */
+    sides?: boolean;
+    sideMargin?: number;
+}
+/** Yaw (degrees, 0 = +Z, 90 = +X) of a pose: around `around`, else of its view. */
+export declare function poseYaw(pose: CameraPose, around?: Vec3): number;
+/** Side quadrant of a yaw: 0 front (+Z), 1 right (+X), 2 back (-Z), 3 left (-X). */
+export declare function sideOf(yaw: number): number;
+/**
+ * Top `count` non-rejected candidates in score order, skipping near-duplicates
+ * (camera within `minSeparation` m AND looking within 12 degrees of a better
+ * pick). With `diversity`, the picks also spread out: first one per side
+ * (within the score margin), then any pose at least `minYaw` from every pick,
+ * and only then the plain near-duplicate rule fills what is left — so the top
+ * 3 of an establishing shot are three different views, not one front view
+ * three times.
+ */
+export declare function pickTop(scored: readonly ScoredCandidate[], count: number, minSeparation: number, diversity?: PickDiversity): ScoredCandidate[];
+export declare function rejectionCounts(scored: readonly ScoredCandidate[]): Record<string, number>;