summer-engine 3.0.0 → 3.2.0

package/dist/core/capabilities/seeing/shot-store.d.ts

@@ -0,0 +1,52 @@
+export declare const SHOTS_DIR: string;
+export declare const SAVED_SUBDIR = "saved";
+export declare const SHOT_MAX_EDGE = 1024;
+export declare const SHOTS_MAX_TOTAL_BYTES: number;
+/** Same grammar as camera bookmark names (preview_ops.cpp). */
+export declare const SHOT_NAME_PATTERN: RegExp;
+export declare class ShotStoreError extends Error {
+    readonly reason: "bad_name" | "not_jpeg" | "too_large" | "over_cap" | "unsafe_path" | "no_project";
+    constructor(reason: "bad_name" | "not_jpeg" | "too_large" | "over_cap" | "unsafe_path" | "no_project", message: string);
+}
+export interface ShotWrite {
+    path: string;
+    /** res:// form of the written file. */
+    resPath: string;
+    bytes: number;
+    width: number;
+    height: number;
+    replaced: boolean;
+    evicted: string[];
+}
+export interface ShotFile {
+    path: string;
+    bytes: number;
+    mtimeMs: number;
+}
+export interface ShotStoreOptions {
+    maxTotalBytes?: number;
+    maxEdge?: number;
+}
+export declare class ShotStore {
+    readonly root: string;
+    private readonly projectRoot;
+    private readonly maxTotalBytes;
+    private readonly maxEdge;
+    constructor(projectRoot: string, options?: ShotStoreOptions);
+    static forProject(projectRoot: string | undefined, options?: ShotStoreOptions): ShotStore;
+    slotPath(bookmark: string): string;
+    savedPath(name: string): string;
+    resPath(path: string): string;
+    readSlot(bookmark: string): Promise<ShotFile | null>;
+    writeSlot(bookmark: string, jpeg: Uint8Array): Promise<ShotWrite>;
+    saveCopy(name: string, jpeg: Uint8Array): Promise<ShotWrite>;
+    /** Every file under the folder, oldest first. */
+    list(): Promise<ShotFile[]>;
+    private write;
+    /** Throws unless `path` resolves strictly inside the shots folder. */
+    private inside;
+    /** Refuse a symlink anywhere from the project's .summer folder down to `path`. */
+    private refuseSymlinks;
+}
+/** Read a stored shot (for compare_previous). */
+export declare function readShot(path: string): Promise<Buffer>;

package/dist/core/capabilities/seeing/shot-store.js

@@ -0,0 +1,204 @@
+/**
+ * Bounded image storage for the seeing tools: res://.summer/shots/.
+ *
+ * Inline images are the product; disk is a strictly bounded side channel.
+ *   - Nothing is written unless a bookmark was rendered (its one before/after
+ *     slot) or the caller passed save_to (one named copy).
+ *   - One slot per bookmark: .summer/shots/<bookmark>.jpg, overwritten by the
+ *     next render of that bookmark. Named copies: .summer/shots/saved/<name>.jpg.
+ *   - JPEG only, longest edge <= SHOT_MAX_EDGE, and the folder never holds more
+ *     than SHOTS_MAX_TOTAL_BYTES: the oldest files are evicted first.
+ *   - Writes never leave the folder: names are validated, the resolved path is
+ *     checked against the folder, and symlinks are refused at every level.
+ * Every file here is safe to delete at any time (a dot folder: not imported,
+ * synced or exported).
+ */
+import { lstat, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { randomBytes } from "node:crypto";
+import { analyzeJpegFrame } from "../frame-quality.js";
+export const SHOTS_DIR = join(".summer", "shots");
+export const SAVED_SUBDIR = "saved";
+export const SHOT_MAX_EDGE = 1024;
+export const SHOTS_MAX_TOTAL_BYTES = 20 * 1024 * 1024;
+/** Same grammar as camera bookmark names (preview_ops.cpp). */
+export const SHOT_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+export class ShotStoreError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "ShotStoreError";
+    }
+}
+export class ShotStore {
+    root;
+    projectRoot;
+    maxTotalBytes;
+    maxEdge;
+    constructor(projectRoot, options = {}) {
+        if (!projectRoot || !isAbsolute(projectRoot)) {
+            throw new ShotStoreError("no_project", "The project root is not an absolute local path; shots are unavailable.");
+        }
+        this.projectRoot = resolve(projectRoot);
+        this.root = join(this.projectRoot, SHOTS_DIR);
+        this.maxTotalBytes = options.maxTotalBytes ?? SHOTS_MAX_TOTAL_BYTES;
+        this.maxEdge = options.maxEdge ?? SHOT_MAX_EDGE;
+    }
+    static forProject(projectRoot, options) {
+        if (!projectRoot || !existsSync(join(projectRoot, "project.godot"))) {
+            throw new ShotStoreError("no_project", "The bound project is not on this machine (no project.godot at the engine's project path), so before/after shots cannot be kept.");
+        }
+        return new ShotStore(projectRoot, options);
+    }
+    slotPath(bookmark) {
+        return this.inside(join(this.root, `${checkName(bookmark, "bookmark name")}.jpg`));
+    }
+    savedPath(name) {
+        return this.inside(join(this.root, SAVED_SUBDIR, `${checkName(name, "save_to")}.jpg`));
+    }
+    resPath(path) {
+        return `res://${relative(this.projectRoot, path).split(sep).join("/")}`;
+    }
+    async readSlot(bookmark) {
+        const path = this.slotPath(bookmark);
+        await this.refuseSymlinks(path);
+        try {
+            const info = await lstat(path);
+            if (!info.isFile())
+                return null;
+            return { path, bytes: info.size, mtimeMs: info.mtimeMs };
+        }
+        catch {
+            return null;
+        }
+    }
+    async writeSlot(bookmark, jpeg) {
+        return this.write(this.slotPath(bookmark), jpeg);
+    }
+    async saveCopy(name, jpeg) {
+        return this.write(this.savedPath(name), jpeg);
+    }
+    /** Every file under the folder, oldest first. */
+    async list() {
+        const out = [];
+        const walk = async (dir) => {
+            let names;
+            try {
+                names = await readdir(dir);
+            }
+            catch {
+                return;
+            }
+            for (const name of names) {
+                const full = join(dir, name);
+                let info;
+                try {
+                    info = await lstat(full);
+                }
+                catch {
+                    continue;
+                }
+                if (info.isSymbolicLink())
+                    continue;
+                if (info.isDirectory())
+                    await walk(full);
+                else if (info.isFile())
+                    out.push({ path: full, bytes: info.size, mtimeMs: info.mtimeMs });
+            }
+        };
+        await walk(this.root);
+        return out.sort((a, b) => a.mtimeMs - b.mtimeMs || a.path.localeCompare(b.path));
+    }
+    async write(target, jpeg) {
+        const info = analyzeJpegFrame(jpeg);
+        if (jpeg.length < 4 || jpeg[0] !== 0xff || jpeg[1] !== 0xd8 || !info.width || !info.height) {
+            throw new ShotStoreError("not_jpeg", "Only baseline JPEG images are stored under .summer/shots/.");
+        }
+        if (Math.max(info.width, info.height) > this.maxEdge) {
+            throw new ShotStoreError("too_large", `Image is ${info.width}x${info.height}; stored shots are at most ${this.maxEdge} px on the longest edge.`);
+        }
+        if (jpeg.length > this.maxTotalBytes) {
+            throw new ShotStoreError("over_cap", `Image is ${jpeg.length} bytes, more than the whole ${this.maxTotalBytes}-byte shots budget.`);
+        }
+        await this.refuseSymlinks(target);
+        await mkdir(join(target, ".."), { recursive: true });
+        await this.refuseSymlinks(target);
+        let replaced = false;
+        try {
+            replaced = (await lstat(target)).isFile();
+        }
+        catch {
+            // new file
+        }
+        // The file being replaced does not count: it is overwritten, not kept.
+        const evicted = [];
+        const files = (await this.list()).filter((f) => f.path !== target);
+        let total = files.reduce((sum, f) => sum + f.bytes, 0);
+        for (const file of files) {
+            if (total + jpeg.length <= this.maxTotalBytes)
+                break;
+            await rm(this.inside(file.path), { force: true });
+            total -= file.bytes;
+            evicted.push(this.resPath(file.path));
+        }
+        const tmp = this.inside(join(this.root, `.tmp-${randomBytes(6).toString("hex")}.jpg`));
+        await writeFile(tmp, jpeg, { mode: 0o644 });
+        try {
+            await rename(tmp, target);
+        }
+        catch (err) {
+            await rm(tmp, { force: true });
+            throw err;
+        }
+        return {
+            path: target,
+            resPath: this.resPath(target),
+            bytes: jpeg.length,
+            width: info.width,
+            height: info.height,
+            replaced,
+            evicted,
+        };
+    }
+    /** Throws unless `path` resolves strictly inside the shots folder. */
+    inside(path) {
+        const full = resolve(path);
+        const rel = relative(this.root, full);
+        if (!rel || rel.startsWith("..") || isAbsolute(rel) || rel.split(sep).includes("..")) {
+            throw new ShotStoreError("unsafe_path", `Refusing to touch ${full}: outside ${this.root}.`);
+        }
+        return full;
+    }
+    /** Refuse a symlink anywhere from the project's .summer folder down to `path`. */
+    async refuseSymlinks(path) {
+        const rel = relative(this.projectRoot, path).split(sep);
+        let cur = this.projectRoot;
+        for (const part of rel) {
+            cur = join(cur, part);
+            try {
+                const info = await lstat(cur);
+                if (info.isSymbolicLink()) {
+                    throw new ShotStoreError("unsafe_path", `Refusing to write through the symlink ${cur}.`);
+                }
+            }
+            catch (err) {
+                if (err instanceof ShotStoreError)
+                    throw err;
+                return; // the rest does not exist yet
+            }
+        }
+    }
+}
+function checkName(name, label) {
+    if (typeof name !== "string" || !SHOT_NAME_PATTERN.test(name)) {
+        throw new ShotStoreError("bad_name", `${label} must be 1-64 characters from A-Z a-z 0-9 _ - (got ${JSON.stringify(String(name)).slice(0, 80)}).`);
+    }
+    return name;
+}
+/** Read a stored shot (for compare_previous). */
+export async function readShot(path) {
+    await stat(path);
+    return readFile(path);
+}

package/dist/core/capabilities/surface-snap-mesh.d.ts

@@ -0,0 +1,88 @@
+/**
+ * surface-snap-mesh — the visible-mesh measurement behind
+ * `summer_snap_to_surface` when colliders cannot answer.
+ *
+ * The engine's SnapToSurface sweeps the subject's colliders against body
+ * colliders. When the subject or the support has no collider it falls back to
+ * visual_aabb: the subject's visible AABB swept against the AABB of every
+ * other visible geometry in the scene. One large AABB anywhere around the
+ * subject (a tree, a building block, a full-screen post quad whose mesh
+ * carries a huge custom AABB) then counts as an overlap that no back-off
+ * clears: collider-less ferns on a ground PlaneMesh all failed with
+ * overlap_recovery_exceeded, "starts in contact with or inside (unnamed)".
+ *
+ * This probe measures the same move from triangles instead. It is one
+ * read-only GDScript sent through RunSceneScript (undo "none", no
+ * checkpoint), with its arguments as base64 data, never source:
+ *
+ *   - the subject's visible mesh triangles in scene space; its vertices are
+ *     cast along the direction, each from the subject's top plane (the
+ *     subject's extreme against the direction) above it, onto the
+ *     triangles of every other visible mesh whose bounds meet the swept
+ *     column. A surface between that plane and the vertex means the subject
+ *     is sunk into it (negative travel);
+ *   - the support's vertices inside the subject's footprint are cast back
+ *     against the subject's triangles, for support peaks between subject
+ *     vertices;
+ *   - travel = the smallest of those distances; the new local position is
+ *     the current one plus (travel - gap) along the direction, mapped
+ *     through the parent's transform.
+ *
+ * Meshes whose shader writes POSITION (screen-space quads) and non-mesh
+ * geometry (CSG, MultiMesh, sprites) are skipped and counted. It reads the
+ * scene only; the mutation is an ordinary SetProp + SaveScene sent by
+ * surface-snap.ts.
+ */
+import { type CapabilityAdvertisingClient } from "../capability-skew.js";
+import { type JsonRecord } from "../util/json.js";
+export declare const SNAP_MESH_ARGS_TOKEN = "__SUMMER_SNAP_MESH_ARGS__";
+export interface SnapMeshProbeArgs {
+    scenePath: string;
+    subjectPath: string;
+    direction: [number, number, number];
+    maxDistance: number;
+    gap: number;
+}
+export interface MeshSnapMeasure {
+    ok: true;
+    /** A support was found within maxDistance. */
+    found: boolean;
+    /** Distance the subject can move along the direction before its visible
+     *  triangles touch the support's (negative: it is sunk that deep). */
+    travel?: number;
+    /** travel - gap: the move along the direction. */
+    shift?: number;
+    support?: string;
+    support_has_collider?: boolean;
+    subject_colliders?: number;
+    hit_point?: [number, number, number];
+    hit_normal?: [number, number, number];
+    /** Which cast found the contact: a subject vertex onto the support, or a support vertex onto the subject. */
+    contact_from?: "subject_vertex" | "support_vertex";
+    /** The subject's extent along the direction. */
+    extent?: number;
+    /** Godot literals of the subject's local position now and after the move. */
+    position?: string;
+    position_after?: string;
+    origin_before?: [number, number, number];
+    origin_after?: [number, number, number];
+    samples?: number;
+    subject_vertices?: number;
+    support_meshes?: number;
+    support_triangles?: number;
+    reverse_partial?: boolean;
+    skipped?: JsonRecord;
+}
+export interface MeshSnapFailure {
+    ok: false;
+    failure_reason: string;
+    error: string;
+}
+export interface SnapMeshClient extends CapabilityAdvertisingClient {
+    executeIdentityBoundOps(ops: Record<string, unknown>[], options?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+}
+/** Measure the visible-mesh snap from the subject's current pose. */
+export declare function measureMeshSnap(client: SnapMeshClient, args: SnapMeshProbeArgs): Promise<MeshSnapMeasure | MeshSnapFailure>;
+export declare function buildSnapMeshScript(args: Record<string, unknown>): string;
+/** The probe source with its placeholder, for tests. */
+export declare function snapMeshProbeTemplate(): string;