@theoremjs/studio 0.0.0-stage → 0.3.2

package/server/save-session.js

@@ -0,0 +1,418 @@
+/**
+ * Save for one open project: the review of what would change, the write with
+ * its three proofs, and the undo. It reaches the disk and the project's process
+ * only through the host it is given, so the rules can be run without either.
+ *
+ * @module
+ */
+import { relative, resolve } from 'node:path';
+import { sourceOrigins } from "./origins.js";
+import { projectOf, providerNamed, readProjectSource, sharedSettings, walkProject, writtenType, } from "./project-source.js";
+import { projectDiffers, projectNames, saveSubjects } from "./save.js";
+import { planNew } from "./save-new.js";
+import { applyEdits, diffHunks, planSave } from "./save-plan.js";
+import { planRemoved } from "./save-remove.js";
+const other = (side) => (side === 'before' ? 'after' : 'before');
+/** Why nothing was done, with what to show for it. */
+export const refusal = (reason, detail = []) => ({
+    ok: false,
+    reason,
+    detail,
+});
+/** What a thrown value says. */
+export const message = (error) => (error instanceof Error ? error.message : String(error));
+/** A name for a value that changes when the value does. */
+export async function stampOf(value) {
+    const bytes = new TextEncoder().encode(JSON.stringify(value));
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes));
+    return [...digest].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/** Whether a body is a Save request, or one for the edited load: a workspace with its starts. */
+export function isSaveRequest(body) {
+    const workspace = body?.workspace;
+    return (Array.isArray(workspace?.agents) &&
+        Array.isArray(workspace.toolSpecs) &&
+        typeof workspace.starts?.agents === 'object' &&
+        typeof workspace.starts.tools === 'object');
+}
+/**
+ * What Save answers a request with, as a status and a body: the review or the write at `base`, and
+ * the undo at `base/undo`. Undefined when the request is not Save's.
+ */
+export async function answerSave(session, base, request) {
+    if (request.method !== 'POST')
+        return undefined;
+    const path = new URL(request.url).pathname;
+    if (path === `${base}/undo`)
+        return { status: 200, body: await session.undo() };
+    if (path !== base)
+        return undefined;
+    const body = await request.json().catch(() => null);
+    return isSaveRequest(body)
+        ? { status: 200, body: await session.save(body) }
+        : { status: 400, body: {} };
+}
+/** Each profile and tool the files define that the project did not register, in the files' order. */
+function unregisteredIn(source, names, inRoot) {
+    const idle = (kind, defined, registered) => [...defined].flatMap(([name, [at]]) => {
+        if (!at || registered.includes(name))
+            return [];
+        const { line } = at.source.getLineAndCharacterOfPosition(at.options.getStart(at.source));
+        return [{ kind, name, file: inRoot(at.file), line: line + 1 }];
+    });
+    return [
+        ...idle('profile', source.profiles, names.profiles),
+        ...idle('tool', source.tools, names.tools),
+    ];
+}
+/** Where the files define each provider the project registered: one written once, in the files' order. */
+function providerPlaces(source, names, inRoot) {
+    return [...source.providers].flatMap(([id, targets]) => {
+        const [at] = targets;
+        if (!at || targets.length > 1 || !names.providers.includes(id))
+            return [];
+        const named = providerNamed(source, id);
+        const { line } = at.source.getLineAndCharacterOfPosition(at.options.getStart(at.source));
+        return [
+            {
+                id,
+                ...(named ? { name: named.name } : {}),
+                ...(named?.exported ? { exported: true } : {}),
+                file: inRoot(at.file),
+                line: line + 1,
+            },
+        ];
+    });
+}
+/**
+ * A project's origins as the page reads them: each file from the project's folder, and each
+ * profile and tool the project registers that no file defines marked as one the studio cannot find.
+ */
+export function pageOrigins(found, names, source, inRoot) {
+    const read = (origins, registered, defined) => {
+        const placed = Object.entries(origins).map(([name, held]) => [
+            name,
+            held.map((origin) => (origin.file ? { ...origin, file: inRoot(origin.file) } : origin)),
+        ]);
+        const unfound = registered
+            .filter((name) => !defined.has(name))
+            .map((name) => [name, [{ path: [], kind: 'unfound' }]]);
+        return Object.fromEntries([...placed, ...unfound]);
+    };
+    const placed = (sites) => Object.fromEntries(Object.entries(sites).map(([name, held]) => [
+        name,
+        held.map((site) => ({
+            ...site,
+            file: inRoot(site.file),
+            ...(site.readBy
+                ? { readBy: site.readBy.map((each) => ({ ...each, file: inRoot(each.file) })) }
+                : {}),
+        })),
+    ]));
+    return {
+        profiles: read(found.profiles, names.profiles, source.profiles),
+        tools: read(found.tools, names.tools, source.tools),
+        providers: read(found.providers, names.providers, source.providers),
+        ...(found.sites
+            ? { sites: { profiles: placed(found.sites.profiles), tools: placed(found.sites.tools) } }
+            : {}),
+    };
+}
+/** How long the walk runs before it pauses to let what it said go out. */
+const PAUSE_EVERY_MS = 12;
+/** Starts Save for a project that `first` loaded. */
+export function createSaveSession(host, first) {
+    const { root } = host;
+    const inRoot = (file) => relative(root, file);
+    let project = first;
+    /** The last Save's files, until another Save or an undo. */
+    let lastSave;
+    const source = () => readProjectSource(host.setupFile, root, host.read);
+    /** The text of every file the setup reads, which changes when the builder's editor writes one. */
+    const heldIn = (read) => JSON.stringify([...read.files].map(([file, each]) => [file, each.text]));
+    const held = () => heldIn(source());
+    /** What the files held when the load that answers started. */
+    let loadedFrom = held();
+    /** The files that did not load, and what the project printed. */
+    let unloaded;
+    /** What the builder changed, or why it cannot be read. */
+    const subjectsOf = (workspace) => {
+        try {
+            return saveSubjects(workspace, projectNames(host.opened(project)));
+        }
+        catch (error) {
+            return { ok: false, issues: [message(error)] };
+        }
+    };
+    /** The review of a workspace's changes, with the files they would write. */
+    const review = async (workspace) => {
+        const subjects = subjectsOf(workspace);
+        if (!subjects.ok)
+            return refusal('issues', subjects.issues);
+        const source = readProjectSource(host.setupFile, root, host.read);
+        const plan = planSave(source, subjects.subjects);
+        const added = planNew(source, subjects.added, (path) => host.read(path) !== undefined);
+        const files = new Map();
+        const view = [];
+        const taken = planRemoved(source, subjects.removed);
+        const whole = taken.gone.map((file) => ({
+            file,
+            start: 0,
+            end: source.files.get(file)?.text.length ?? 0,
+            text: '',
+        }));
+        const edits = [...plan.edits, ...added.edits, ...taken.edits].filter((edit) => !taken.gone.includes(edit.file));
+        for (const [file, held] of Map.groupBy([...edits, ...whole], (edit) => edit.file)) {
+            const opened = source.files.get(file);
+            const before = opened?.text ?? '';
+            const removed = taken.gone.includes(file);
+            let after;
+            try {
+                after = applyEdits(before, held);
+            }
+            catch (error) {
+                return refusal('unwritable', [`${inRoot(file)}: ${message(error)}`]);
+            }
+            files.set(file, { before, after, created: !opened, removed });
+            const marked = removed
+                ? { removed: true }
+                : opened
+                    ? {}
+                    : { created: true };
+            view.push({ file: inRoot(file), hunks: diffHunks(before, held), ...marked });
+        }
+        const changes = [...subjects.changes, ...plan.changes, ...added.changes, ...taken.changes].map((change) => (change.file ? { ...change, file: inRoot(change.file) } : change));
+        const writable = files.size > 0 && changes.every((change) => change.status === 'written');
+        return {
+            files,
+            view: { ok: true, changes, files: view, stamp: await stampOf([...files]), writable },
+        };
+    };
+    /** What a file holds on `side`: undefined where it is not there. */
+    const textOn = (change, side) => side === 'before'
+        ? change.created
+            ? undefined
+            : change.before
+        : change.removed
+            ? undefined
+            : change.after;
+    /** Writes a file as it was or as Save makes it. A file that is not there on that side is taken away, not emptied. */
+    const putFile = (file, change, side) => {
+        const text = textOn(change, side);
+        if (text === undefined)
+            host.remove(file);
+        else
+            host.write(file, text);
+    };
+    /**
+     * Writes each file to `side`. When one can't be written, the files already written, and that one,
+     * are put back to the other side, and the refusal says which file and why.
+     */
+    const put = (files, side) => {
+        const done = new Map();
+        for (const [file, change] of files) {
+            try {
+                putFile(file, change, side);
+            }
+            catch (error) {
+                const back = other(side);
+                const kept = putBack(done, back);
+                if (host.read(file) !== textOn(change, back)) {
+                    try {
+                        putFile(file, change, back);
+                    }
+                    catch {
+                        kept.push(inRoot(file));
+                    }
+                }
+                const refused = refusal('write', [`${inRoot(file)}: ${message(error)}`]);
+                return kept.length ? { ...refused, kept } : refused;
+            }
+            done.set(file, change);
+        }
+        return undefined;
+    };
+    /**
+     * Puts `files` back to `side`, but for a file that no longer holds what the other side wrote:
+     * someone changed it meanwhile, so it is left as it is now. One that can't be written is left too.
+     * Answers with those it left.
+     */
+    const putBack = (files, side) => {
+        const left = [];
+        for (const [file, change] of files) {
+            if (host.read(file) !== textOn(change, other(side))) {
+                left.push(inRoot(file));
+                continue;
+            }
+            try {
+                putFile(file, change, side);
+            }
+            catch {
+                left.push(inRoot(file));
+            }
+        }
+        return left;
+    };
+    /** A write taken back, with the files it left as they are now. */
+    const takenBack = (refused, files, side) => {
+        const kept = putBack(files, side);
+        return kept.length ? { ...refused, kept } : refused;
+    };
+    /** Loads the project from disk and answers with it from now on. */
+    const reload = async (keep, from = held()) => {
+        let next;
+        try {
+            next = await host.load();
+        }
+        catch (error) {
+            return refusal('load', [message(error)]);
+        }
+        const differs = keep(next);
+        if (differs.length) {
+            await host.stop(next);
+            return refusal('differs', differs);
+        }
+        const old = project;
+        project = next;
+        loadedFrom = from;
+        unloaded = undefined;
+        await host.stop(old);
+        return undefined;
+    };
+    /** Loads the project again when `files` are not the ones the load that answers was read from. Whether it did. */
+    const refresh = async (files, said) => {
+        const now = heldIn(files);
+        if (now === loadedFrom)
+            unloaded = undefined;
+        // Files that did not load are not tried again until they change.
+        else if (unloaded?.from !== now) {
+            said?.({ again: true });
+            const refused = await reload(() => [], now);
+            if (refused)
+                unloaded = { from: now, printed: refused.detail.join('\n') };
+            return true;
+        }
+        return false;
+    };
+    /** The same walk as `source`, pausing so each step said reaches the page while the walk goes on. */
+    const sourceSaying = async (said) => {
+        const walk = walkProject(host.setupFile, root, host.read);
+        let paused = performance.now();
+        let step = walk.next();
+        while (!step.done) {
+            const { file, from } = step.value;
+            said({ file: inRoot(file), ...(from === undefined ? {} : { from: inRoot(from) }) });
+            if (performance.now() - paused > PAUSE_EVERY_MS) {
+                await new Promise((resume) => setTimeout(resume, 0));
+                paused = performance.now();
+            }
+            step = walk.next();
+        }
+        const files = projectOf(step.value, host.setupFile, root);
+        for (const [found, made] of [
+            ['profile', files.profiles],
+            ['tool', files.tools],
+        ]) {
+            for (const [name, targets] of made) {
+                const at = targets[0];
+                if (!at)
+                    continue;
+                const type = writtenType(files, at);
+                said({ found, name, file: inRoot(at.file), ...(type === undefined ? {} : { type }) });
+            }
+        }
+        return files;
+    };
+    const read = async (said) => {
+        const first = said ? await sourceSaying(said) : source();
+        // A load takes time, so the files are read again after one: the answer is what they say now.
+        const loaded = await refresh(first, said);
+        const files = loaded ? source() : first;
+        const opened = host.opened(project);
+        const decisions = opened.agents
+            .filter((agent) => agent.identity.profileType === 'decision')
+            .map((agent) => agent.identity.agentId);
+        return {
+            shared: sharedSettings(files).map((setting) => ({ ...setting, file: inRoot(setting.file) })),
+            origins: pageOrigins(sourceOrigins(files, decisions), projectNames(opened), files, inRoot),
+            unregistered: unregisteredIn(files, projectNames(opened), inRoot),
+            providerPlaces: providerPlaces(files, projectNames(opened), inRoot),
+            ...(unloaded === undefined ? {} : { unloaded: unloaded.printed }),
+        };
+    };
+    /** Proves the files as written: the project type-checks, loads, and is what was tested. */
+    const proven = async (tested) => {
+        const check = await host.typeChecks().catch((error) => ({ ok: false, output: message(error) }));
+        if (!check.ok)
+            return refusal('check', [check.output]);
+        return reload((next) => projectDiffers(host.opened(next), tested));
+    };
+    const write = async (files, view, request) => {
+        if (view.stamp !== request.stamp)
+            return refusal('stale');
+        if (!view.writable)
+            return refusal('unwritable');
+        const astray = [...files.keys()].filter((file) => !host.landsInside(file));
+        if (astray.length)
+            return refusal('unwritable', astray.map(inRoot));
+        const failed = put(files, 'after');
+        if (failed)
+            return failed;
+        const refused = await proven(request.workspace);
+        if (refused)
+            return takenBack(refused, files, 'before');
+        lastSave = files;
+        return { ok: true, written: [...files.keys()].map(inRoot) };
+    };
+    const save = async (request) => {
+        const reviewed = await review(request.workspace);
+        if ('reason' in reviewed)
+            return reviewed;
+        return request.stamp === undefined
+            ? reviewed.view
+            : write(reviewed.files, reviewed.view, request);
+    };
+    const undo = async () => {
+        if (!lastSave)
+            return refusal('nothing');
+        const files = lastSave;
+        const moved = [...files].filter(([file, change]) => host.read(file) !== (change.removed ? undefined : change.after));
+        if (moved.length)
+            return refusal('stale', moved.map(([file]) => inRoot(file)));
+        const failed = put(files, 'before');
+        if (failed)
+            return failed;
+        const refused = await reload(() => []);
+        if (refused)
+            return takenBack(refused, files, 'after');
+        lastSave = undefined;
+        return { ok: true, written: [...files.keys()].map(inRoot) };
+    };
+    /** One write at a time: a second waits for the first. */
+    let writing = Promise.resolve();
+    const inTurn = (work) => {
+        const next = writing.then(work, work);
+        writing = next.catch(() => { });
+        return next;
+    };
+    return {
+        project: () => project,
+        place: (file) => {
+            const path = resolve(root, file);
+            return source().files.has(path) ? path : undefined;
+        },
+        save: (request) => inTurn(() => save(request)),
+        undo: () => inTurn(undo),
+        read: (said) => inTurn(() => read(said)),
+        watched: () => [...source().files.keys()],
+        // In turn, so a Save that is still proving its files is not taken for the builder's editor.
+        changed: () => inTurn(() => {
+            const now = held();
+            if (now === loadedFrom)
+                return Promise.resolve([]);
+            const [was, is] = [loadedFrom, now].map((text) => new Map(JSON.parse(text)));
+            const files = [...new Set([...(was?.keys() ?? []), ...(is?.keys() ?? [])])];
+            return Promise.resolve(files.filter((file) => was?.get(file) !== is?.get(file)).map(inRoot));
+        }),
+    };
+}

package/server/save-wire.d.ts

@@ -0,0 +1,235 @@
+/**
+ * What the page and the studio's server say to each other about the project's
+ * files: its shared settings, and Save. Types only: the page imports this
+ * without the server's code.
+ *
+ * @module
+ */
+import type { StudioWorkspace } from '../workspace.ts';
+/** A constant that more than one profile or tool reads: one value, set in one place. */
+export interface SharedSetting {
+    /** The constant's name where it is declared. */
+    name: string;
+    /** The name as words: `STANDARD_GUARDRAILS` is "Standard guardrails". */
+    label: string;
+    /** Where it is declared: the path and the one-based line. */
+    file: string;
+    line: number;
+    /**
+     * The profile key it fills, when every profile reads it as the whole of that key and no tool
+     * reads it. The studio opens these at that key; any other is edited where a profile or tool shows it.
+     */
+    key?: string;
+    /** The profiles it reaches, by id, and the tools, by name. */
+    profiles: string[];
+    tools: string[];
+    /** Code that is not a profile or a tool reads it too. */
+    readByCode: boolean;
+}
+/**
+ * A profile or tool the project's files define that the project did not register when it loaded:
+ * one it registers only on a condition that did not hold. The studio shows what is registered, so
+ * it names these and does not open them.
+ */
+export interface Unregistered {
+    kind: 'profile' | 'tool';
+    /** The profile's id, or the tool's name. */
+    name: string;
+    /** Where the files define it: the path and the one-based line. */
+    file: string;
+    line: number;
+}
+/**
+ * A setting the project's files do not write out as a plain value, so the studio shows it and
+ * does not change it.
+ * - `code`: code computes it: a call, a name the studio cannot follow, a method.
+ * - `constant`: a named constant holds an id (the profile's, a provider's), and code that is not a profile or a tool reads the constant too.
+ * - `spread`: the object spreads another into itself, so the studio writes only the keys in `written`.
+ * - `twice`: the files define the profile or tool more than once.
+ * - `unfound`: no place in the project's files defines the profile or tool.
+ */
+export interface SettingOrigin {
+    /** The keys that lead to the setting: `['models', 'fast', 'apiId']`. Empty for the whole profile or tool. */
+    path: string[];
+    kind: 'code' | 'constant' | 'spread' | 'twice' | 'unfound';
+    /** What the file says there, on one line: `bonsaiInputs()`. */
+    text?: string;
+    /** Where it says it: the path and the one-based line. */
+    file?: string;
+    line?: number;
+    /** For a `spread`: the keys written after it, which the studio still writes. */
+    written?: string[];
+}
+/**
+ * Where the files write one setting's value. Two settings with the same `site` are one value in
+ * the files: a constant several profiles read, what a function they all call returns, the call a
+ * function makes for each of them.
+ */
+export interface SettingSite {
+    /** The keys that lead to the setting. Empty for the whole profile or tool. */
+    path: string[];
+    /** The place, as a number the project gives it for this read. */
+    site: number;
+    /** Another setting has the same site. False for a value a profile sets apart inside a shared one. */
+    shared: boolean;
+    /** The constant or function that holds the place. */
+    name?: string;
+    /** Where it is: the path and the one-based line. */
+    file: string;
+    line: number;
+    /** Set when code that is not a profile or a tool reads the place too: each line that reads it. */
+    readBy?: SourcePlace[];
+}
+/** A line of one of the project's files. */
+export interface SourcePlace {
+    file: string;
+    line: number;
+}
+/** Each profile's, tool's and provider's settings that are set in code, by profile id, tool name, and provider id. */
+export interface ProjectOrigins {
+    profiles: Record<string, SettingOrigin[]>;
+    tools: Record<string, SettingOrigin[]>;
+    providers: Record<string, SettingOrigin[]>;
+    /** Where each value others read too is written, by profile id and tool name. Only those that hold one are listed. */
+    sites?: {
+        profiles: Record<string, SettingSite[]>;
+        tools: Record<string, SettingSite[]>;
+    };
+}
+/**
+ * Where the project's files define a provider. `name` is the constant it is defined under, when
+ * it has one; `exported` says another file can import that name.
+ */
+export interface ProviderPlace {
+    id: string;
+    name?: string;
+    exported?: true;
+    /** The path and the one-based line. */
+    file: string;
+    line: number;
+}
+/** What the page asks to see in the builder's editor: a project file, from the project's folder. */
+export interface OpenRequest {
+    file: string;
+    line?: number;
+    /** The editor to open it in, by a command the studio lists. Without one, the editor the studio started with. */
+    editor?: string;
+}
+/**
+ * Whether the builder's editor was started on the line. `byDefault` is the machine's own default
+ * editor, started on the file when the named one did not start; it opens at the top.
+ * - `file`: the project's setup does not read that file.
+ * - `editor`: the studio does not know how to start the editor on a line.
+ * - `failed`: the editor did not start.
+ */
+export type OpenAnswer = {
+    ok: true;
+    editor: string;
+    byDefault?: true;
+} | {
+    ok: false;
+    reason: 'file' | 'editor' | 'failed';
+    editor?: string;
+    place?: string;
+};
+/**
+ * What happens to one changed value.
+ * - `written`: Save rewrites it in the file.
+ * - `constant`: a named constant holds it, and something else that reads the constant does not make this change.
+ * - `code`: code computes it, or the file sets it in a way the studio cannot follow.
+ * - `changed`: the file no longer holds the value the studio opened.
+ * - `unfound`: no place in the project's files sets it.
+ * - `unused`: a tool the studio added that no agent allows, so it was never run.
+ * - `taken`: the file a new profile or tool would be written to is already there.
+ * - `setup`: the studio cannot tell how the project's setup registers things, so it cannot add one.
+ * - `owed`: a new profile holds a rule whose check is code, which the studio does not have to write.
+ * - `removed`: a profile or tool the studio took away, registered in a way the studio cannot follow.
+ */
+export type SaveStatus = 'written' | 'constant' | 'code' | 'changed' | 'unfound' | 'unused' | 'taken' | 'setup' | 'owed' | 'removed';
+export interface SaveChange {
+    kind: 'profile' | 'tool' | 'provider';
+    /** The profile's id, the tool's name or the provider's id, as the project has it. */
+    of: string;
+    /** The setting, as a path: `tools.allow`. Empty for the whole profile or tool. */
+    setting: string;
+    status: SaveStatus;
+    /** Where the value is set: the absolute path and the one-based line. */
+    file?: string;
+    line?: number;
+    /** The constant that holds it. */
+    name?: string;
+    /** The other profiles and tools that read the constant, by id and name. Save writes it when each makes the same change. */
+    sharedWith?: string[];
+    /** Code that is not a profile or a tool reads the constant too. */
+    readByCode?: boolean;
+}
+/** A run of changed lines in one file, with the lines around it. */
+export interface DiffHunk {
+    /** The one-based line the removed lines start on. */
+    line: number;
+    lead: string[];
+    removed: string[];
+    added: string[];
+    trail: string[];
+}
+/** The page's workspace, and for a write the stamp of the review the builder read. */
+export interface SaveRequest {
+    workspace: StudioWorkspace;
+    /** Present to write. It must match the review's, so what is written is what was read. */
+    stamp?: string;
+}
+/** One file Save changes, with its path from the project's folder. */
+export interface SaveFile {
+    file: string;
+    hunks: DiffHunk[];
+    /** Save creates the file: its one hunk is the whole of it. */
+    created?: true;
+    /** Save takes the file away: nothing of its own is left in it. Its one hunk is the whole of it. */
+    removed?: true;
+}
+/** The review before a write: every change, where it lands, and whether Save can write them all. */
+export interface SaveReview {
+    ok: true;
+    /** Each change, with `file` from the project's folder. */
+    changes: SaveChange[];
+    files: SaveFile[];
+    stamp: string;
+    /** True when there is something to write and every change can be written. */
+    writable: boolean;
+}
+/** Files written, or put back by an undo. */
+export interface SaveDone {
+    ok: true;
+    written: string[];
+}
+/**
+ * The load that runs the builder's unsaved edits is up, and which edits it holds: `stamp` changes
+ * when they do. A refusal says why there is none: the edits have `issues`, the project did not
+ * `load` with them, or it loaded as something that `differs` from them. Either way, `saved` is the
+ * ids of the profiles the files hold: the ones the files' own load can run beside it.
+ */
+export type EditedAnswer = ({
+    ok: true;
+    stamp: string;
+} | SaveRefusal) & {
+    saved: string[];
+};
+/**
+ * Why nothing was written, or why a write was taken back.
+ * - `issues`: the workspace does not compile.
+ * - `stale`: the files changed after the review was read.
+ * - `unwritable`: a change cannot be written.
+ * - `write`: a file could not be written or taken away, so those already written were put back.
+ * - `check`: the project did not type-check with the change.
+ * - `load`: the project did not load with the change.
+ * - `differs`: the project loaded, but not as the builder tested it.
+ * - `nothing`: there is no Save to undo.
+ * - `unanswered`: the page's own: the studio's server did not answer, so what the files hold is not known.
+ */
+export interface SaveRefusal {
+    ok: false;
+    reason: 'issues' | 'stale' | 'unwritable' | 'write' | 'check' | 'load' | 'differs' | 'nothing' | 'unanswered';
+    detail: string[];
+    /** Files a write taken back left as they are now: they changed while Save checked them. */
+    kept?: string[];
+}

package/server/save-wire.js

@@ -0,0 +1,8 @@
+/**
+ * What the page and the studio's server say to each other about the project's
+ * files: its shared settings, and Save. Types only: the page imports this
+ * without the server's code.
+ *
+ * @module
+ */
+export {};