@theoremjs/studio 0.0.0-stage → 0.3.2

package/ui/lib/studio-map-kept.js

@@ -0,0 +1,48 @@
+import { isRecord, session, WORKSPACE_KEY } from "./studio-session.js";
+const NOTHING_KEPT = { tokens: {}, detail: {}, expanded: false };
+const keptKey = (project) => project === undefined ? `${WORKSPACE_KEY}.map` : `${WORKSPACE_KEY}.map.project:${project}`;
+function places(kept) {
+    if (!isRecord(kept))
+        return {};
+    const read = {};
+    for (const [id, place] of Object.entries(kept)) {
+        if (isRecord(place) && typeof place.x === 'number' && typeof place.y === 'number') {
+            read[id] = { x: place.x, y: place.y };
+        }
+    }
+    return read;
+}
+/** What was kept; the map as it first opens when nothing was or it cannot be read. */
+export function readKeptMap(project) {
+    try {
+        const kept = JSON.parse(session()?.getItem(keptKey(project)) ?? 'null');
+        if (!isRecord(kept))
+            return NOTHING_KEPT;
+        return {
+            tokens: places(kept.tokens),
+            detail: places(kept.detail),
+            expanded: kept.expanded === true,
+            ...(typeof kept.family === 'string' ? { family: kept.family } : {}),
+        };
+    }
+    catch {
+        return NOTHING_KEPT;
+    }
+}
+/** Keeps `kept`, or forgets it when it is the map as it first opens. Storage that is full or blocked keeps nothing. */
+export function writeKeptMap(project, kept) {
+    const { tokens, detail, expanded, family } = kept;
+    const untouched = Object.keys(tokens).length === 0 &&
+        Object.keys(detail).length === 0 &&
+        !expanded &&
+        family === undefined;
+    try {
+        if (untouched)
+            session()?.removeItem(keptKey(project));
+        else
+            session()?.setItem(keptKey(project), JSON.stringify(kept));
+    }
+    catch {
+        // Nothing to do: it lasts until the page goes.
+    }
+}

package/ui/lib/studio-open.d.ts

@@ -0,0 +1,22 @@
+import { type StudioDraft } from '../../mod.ts';
+import type { ReadStep } from '../../read-steps.ts';
+import type { StudioOpened } from '../studio-host.ts';
+import { type ProjectSession } from './studio-project.ts';
+/**
+ * What the studio opens on in this tab. Draft keys are random, so this runs in the browser. The
+ * tab's kept workspace comes back unless a `seed` asks for another; then it waits behind Undo.
+ */
+export declare function openStudio(seed?: {
+    draft: StudioDraft;
+    question: string | undefined;
+}): StudioOpened;
+/**
+ * What the studio opens on when a local server holds a project: the project's workspace, with the
+ * edits this tab kept for it. The studio merges into them what the files changed since; edits
+ * that stand on no reading of the files wait behind an offer until the builder answers it.
+ * Closing the tab forgets them. `said` hears each step of the server's read of the project's
+ * files. Throws when no server answers.
+ */
+export declare function openStudioProject(said?: (step: ReadStep) => void): Promise<StudioOpened & {
+    project: ProjectSession;
+}>;

package/ui/lib/studio-open.js

@@ -0,0 +1,54 @@
+import { clearStaleStudioRuns, createExampleDraft, workspaceFromDraft, } from "../../mod.js";
+import { openProject } from "./studio-project.js";
+import { editsAside, restoreProject, restoreStudio } from "./studio-restore.js";
+import { projectKey } from "./studio-session.js";
+/**
+ * What the studio opens on in this tab. Draft keys are random, so this runs in the browser. The
+ * tab's kept workspace comes back unless a `seed` asks for another; then it waits behind Undo.
+ */
+export function openStudio(seed) {
+    clearStaleStudioRuns();
+    const kept = restoreStudio();
+    const fresh = (draft) => ({
+        workspace: workspaceFromDraft(draft),
+        revision: kept.kind === 'restored' ? kept.value.revision + 1 : 0,
+    });
+    if (seed) {
+        return {
+            start: fresh(seed.draft),
+            question: seed.question,
+            displaced: kept.kind === 'restored' ? kept.value.workspace : undefined,
+            discarded: kept.kind === 'discarded',
+        };
+    }
+    if (kept.kind === 'restored')
+        return { start: kept.value, question: undefined, displaced: undefined, discarded: false };
+    return {
+        start: fresh(createExampleDraft()),
+        question: undefined,
+        displaced: undefined,
+        discarded: kept.kind === 'discarded',
+    };
+}
+/**
+ * What the studio opens on when a local server holds a project: the project's workspace, with the
+ * edits this tab kept for it. The studio merges into them what the files changed since; edits
+ * that stand on no reading of the files wait behind an offer until the builder answers it.
+ * Closing the tab forgets them. `said` hears each step of the server's read of the project's
+ * files. Throws when no server answers.
+ */
+export async function openStudioProject(said) {
+    const { project, workspace } = await openProject(said);
+    const key = projectKey(project.name);
+    const kept = restoreProject(key, workspace, project.print);
+    return {
+        start: kept.kind === 'restored'
+            ? kept.value
+            : { workspace, revision: 0, project: { key, files: project.print } },
+        question: undefined,
+        // Edits set aside before a reload are still the builder's to answer for.
+        displaced: kept.kind === 'moved' ? kept.workspace : editsAside(key, workspace),
+        discarded: kept.kind === 'discarded',
+        project,
+    };
+}

package/ui/lib/studio-page.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What the studio's page sends an agent: a value for each of its slots and its context
+ * package. Kept in this tab beside the conversation, never in the profile.
+ */
+import { type StudioRunPayload } from '../../mod.ts';
+/** What the builder set: the value picked for each slot, and the context as typed. */
+export interface PageValues {
+    slots: Record<string, string>;
+    contextJson: string;
+}
+/** What the agent takes from a page. */
+export interface PageInputs {
+    slots: Record<string, readonly string[]>;
+    takesContext: boolean;
+    /** The tools the page answers. Only a call asks the page. */
+    pageTools: string[];
+}
+/** The context a blank preview box suggests. */
+export declare const CONTEXT_PLACEHOLDER = "{\n  \"page\": \"Checkout\"\n}";
+/** The slots a draft's JSON declares so far: each name with a list of text. Anything else is left out. */
+export declare function draftSlots(slotsJson: string): Record<string, readonly string[]>;
+/** Why typed context is not sent, when it is not JSON. */
+export declare function contextErrorOf(contextJson: string): string | undefined;
+/** What the compiled agent takes from a page, or null when it takes nothing. */
+export declare function pageInputsOf(payload: StudioRunPayload): PageInputs | null;
+/** What goes with a turn or a call. Context that is not JSON is not sent, and says why. */
+export declare function sentPageValues(inputs: PageInputs | null, values: PageValues): {
+    slots?: Record<string, string>;
+    context?: unknown;
+    contextError?: string;
+};
+/** What the studio's page sends `agentKey`, kept in this tab; the editor sets it and the preview sends it. */
+export declare function usePageValues(agentKey: string): [PageValues, (next: PageValues) => void];

package/ui/lib/studio-page.js

@@ -0,0 +1,121 @@
+/**
+ * What the studio's page sends an agent: a value for each of its slots and its context
+ * package. Kept in this tab beside the conversation, never in the profile.
+ */
+import { useCallback, useSyncExternalStore } from 'react';
+import { studioPageTools } from "../../mod.js";
+import { isRecord, session } from "./studio-session.js";
+const PAGE_PREFIX = 'theorem.studio.v2.page:';
+const NO_PAGE_VALUES = { slots: {}, contextJson: '' };
+/** The context a blank preview box suggests. */
+export const CONTEXT_PLACEHOLDER = `{
+  "page": "Checkout"
+}`;
+/** The slots a draft's JSON declares so far: each name with a list of text. Anything else is left out. */
+export function draftSlots(slotsJson) {
+    try {
+        const typed = JSON.parse(slotsJson.trim() || '{}');
+        if (!isRecord(typed))
+            return {};
+        return Object.fromEntries(Object.entries(typed).filter((entry) => Array.isArray(entry[1]) &&
+            entry[1].length > 0 &&
+            entry[1].every((value) => typeof value === 'string')));
+    }
+    catch {
+        return {};
+    }
+}
+/** Why typed context is not sent, when it is not JSON. */
+export function contextErrorOf(contextJson) {
+    const typed = contextJson.trim();
+    if (!typed)
+        return undefined;
+    try {
+        JSON.parse(typed);
+        return undefined;
+    }
+    catch {
+        return 'Context must be JSON.';
+    }
+}
+/** What the compiled agent takes from a page, or null when it takes nothing. */
+export function pageInputsOf(payload) {
+    const { profile } = payload;
+    if (profile.type === 'decision' || profile.type === 'host' || profile.type === 'embedding')
+        return null;
+    const inputs = 'inputs' in profile ? profile.inputs : undefined;
+    const slots = inputs?.slots ?? {};
+    const takesContext = inputs?.context?.from.includes('client') ?? false;
+    const pageTools = Object.keys(studioPageTools(payload));
+    if (!Object.keys(slots).length && !takesContext && !pageTools.length)
+        return null;
+    return { slots, takesContext, pageTools };
+}
+/** The value a slot sends: the one picked while the profile still lists it, else its first. */
+function slotValue(inputs, values, name) {
+    const allowed = inputs.slots[name] ?? [];
+    const picked = allowed.find((value) => value === values.slots[name]);
+    return picked ?? allowed.at(0) ?? '';
+}
+/** What goes with a turn or a call. Context that is not JSON is not sent, and says why. */
+export function sentPageValues(inputs, values) {
+    if (!inputs)
+        return {};
+    const names = Object.keys(inputs.slots);
+    const slots = names.length
+        ? Object.fromEntries(names.map((name) => [name, slotValue(inputs, values, name)]))
+        : undefined;
+    const typed = inputs.takesContext ? values.contextJson.trim() : '';
+    if (!typed)
+        return { slots };
+    const contextError = contextErrorOf(typed);
+    return contextError ? { slots, contextError } : { slots, context: JSON.parse(typed) };
+}
+function loadPageValues(agentKey) {
+    try {
+        const kept = JSON.parse(session()?.getItem(`${PAGE_PREFIX}${agentKey}`) ?? 'null');
+        if (!isRecord(kept) || !isRecord(kept.slots) || typeof kept.contextJson !== 'string') {
+            return NO_PAGE_VALUES;
+        }
+        const slots = Object.fromEntries(Object.entries(kept.slots).filter((entry) => typeof entry[1] === 'string'));
+        return { slots, contextJson: kept.contextJson };
+    }
+    catch {
+        return NO_PAGE_VALUES;
+    }
+}
+/** Never throws: a full or blocked store keeps nothing. */
+function savePageValues(agentKey, values) {
+    try {
+        session()?.setItem(`${PAGE_PREFIX}${agentKey}`, JSON.stringify(values));
+    }
+    catch {
+        // Nothing is kept.
+    }
+}
+/** Each agent's values as last read or set, so the editor and the preview show the same ones. */
+const held = new Map();
+const listeners = new Set();
+function heldValues(agentKey) {
+    let values = held.get(agentKey);
+    if (!values) {
+        values = loadPageValues(agentKey);
+        held.set(agentKey, values);
+    }
+    return values;
+}
+function listen(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+/** What the studio's page sends `agentKey`, kept in this tab; the editor sets it and the preview sends it. */
+export function usePageValues(agentKey) {
+    const values = useSyncExternalStore(listen, () => heldValues(agentKey), () => NO_PAGE_VALUES);
+    const set = useCallback((next) => {
+        held.set(agentKey, next);
+        savePageValues(agentKey, next);
+        for (const listener of listeners)
+            listener();
+    }, [agentKey]);
+    return [values, set];
+}

package/ui/lib/studio-prefs.d.ts

@@ -0,0 +1,26 @@
+export interface StudioPrefs {
+    /** The editor files open in, by its command. Empty leaves it to the studio command. */
+    editor: string;
+    /** Whether the studio takes in what the builder's editor saves, as it saves. */
+    watch: 'on' | 'off';
+    /** Whether a toast says so when the files changed a setting. */
+    filesToast: 'on' | 'off';
+    /** Whether changing a value several agents share is asked about first. */
+    askShared: 'always' | 'never';
+    /** Which tools that write ask before a run: all of them, or only the destructive ones. */
+    askWrites: 'always' | 'destructive';
+}
+export type StudioPref = keyof StudioPrefs;
+export declare const PREF_DEFAULTS: StudioPrefs;
+/** Where preferences are kept: the part of `Storage` they use. */
+export type PrefStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+/** A preference as `storage` keeps it, or its default. */
+export declare function readPref<K extends StudioPref>(storage: PrefStorage | null, name: K): StudioPrefs[K];
+/** Keeps a preference. The default is kept as nothing, so a later default reaches the builder. */
+export declare function writePref<K extends StudioPref>(storage: PrefStorage | null, name: K, value: StudioPrefs[K]): void;
+export declare function getPref<K extends StudioPref>(name: K): StudioPrefs[K];
+export declare function setPref<K extends StudioPref>(name: K, value: StudioPrefs[K]): void;
+/** A preference, and the screen drawn again when it changes. */
+export declare function usePref<K extends StudioPref>(name: K): StudioPrefs[K];
+/** Whether a run of a tool that writes asks first: a destructive one always, another unless the builder said not to. */
+export declare function writeAsks(access: string): boolean;

package/ui/lib/studio-prefs.js

@@ -0,0 +1,87 @@
+/**
+ * What the builder chose about how the studio behaves, kept in this browser and nowhere else:
+ * nothing is written to the project or sent to a server. A choice the builder never made, or one
+ * this version does not know, reads as the studio's own default.
+ */
+import { useSyncExternalStore } from 'react';
+import { isEditorChoice } from "../../editors.js";
+export const PREF_DEFAULTS = {
+    editor: '',
+    watch: 'on',
+    filesToast: 'on',
+    askShared: 'always',
+    askWrites: 'always',
+};
+const PREF_KEYS = {
+    editor: 'theorem.studio.editor',
+    watch: 'theorem.studio.watch',
+    filesToast: 'theorem.studio.files-toast',
+    askShared: 'theorem.studio.ask-shared',
+    askWrites: 'theorem.studio.ask-writes',
+};
+/** Whether a kept text is a value the preference takes. */
+const PREF_TAKES = {
+    editor: isEditorChoice,
+    watch: (kept) => kept === 'off',
+    filesToast: (kept) => kept === 'off',
+    askShared: (kept) => kept === 'never',
+    askWrites: (kept) => kept === 'destructive',
+};
+/** A preference as `storage` keeps it, or its default. */
+export function readPref(storage, name) {
+    try {
+        const kept = storage?.getItem(PREF_KEYS[name]);
+        if (typeof kept === 'string' && PREF_TAKES[name](kept))
+            return kept;
+    }
+    catch {
+        // A browser that keeps nothing has the defaults.
+    }
+    return PREF_DEFAULTS[name];
+}
+/** Keeps a preference. The default is kept as nothing, so a later default reaches the builder. */
+export function writePref(storage, name, value) {
+    try {
+        if (value === PREF_DEFAULTS[name] || !PREF_TAKES[name](value))
+            storage?.removeItem(PREF_KEYS[name]);
+        else
+            storage?.setItem(PREF_KEYS[name], value);
+    }
+    catch {
+        // A browser that keeps nothing holds the choice until the page is closed.
+    }
+}
+function local() {
+    try {
+        return typeof localStorage === 'undefined' ? null : localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+const listeners = new Set();
+export function getPref(name) {
+    return readPref(local(), name);
+}
+export function setPref(name, value) {
+    writePref(local(), name, value);
+    for (const listener of listeners)
+        listener();
+}
+/** Hears a preference change, from this tab or another one of this browser. */
+function subscribePrefs(listener) {
+    listeners.add(listener);
+    globalThis.addEventListener?.('storage', listener);
+    return () => {
+        listeners.delete(listener);
+        globalThis.removeEventListener?.('storage', listener);
+    };
+}
+/** A preference, and the screen drawn again when it changes. */
+export function usePref(name) {
+    return useSyncExternalStore(subscribePrefs, () => getPref(name), () => PREF_DEFAULTS[name]);
+}
+/** Whether a run of a tool that writes asks first: a destructive one always, another unless the builder said not to. */
+export function writeAsks(access) {
+    return access === 'destructive' || getPref('askWrites') === 'always';
+}

package/ui/lib/studio-project.d.ts

@@ -0,0 +1,106 @@
+/**
+ * A project open in the studio. A local server (`studio/server/serve.ts` in the package) hands
+ * the page the project's registered profiles and tools as a workspace, and runs each profile's
+ * own code.
+ */
+import { type ProjectCode, type StudioAsks, type StudioWorkspace } from '../../mod.ts';
+import type { StudioPeopleOffer } from '../../people.ts';
+import { type ReadStep } from '../../read-steps.ts';
+import type { EditedAnswer, OpenAnswer, OpenRequest, ProjectOrigins, ProviderPlace, SaveDone, SaveRefusal, SaveReview, SharedSetting, Unregistered } from '../../server/save-wire.ts';
+export interface ProjectSession {
+    endpoint: string;
+    /** The project's name. */
+    name: string;
+    /** The ids of the profiles the files held when the page opened them. */
+    profiles: string[];
+    /** The ids of the providers the files held when the page opened them. */
+    providers: string[];
+    /** The profiles the page could not show or run, and why. */
+    problems: {
+        profile: string;
+        message: string;
+    }[];
+    /** The models that cannot run as the files set them, and why. Their agents still run. */
+    modelProblems: {
+        profile: string;
+        model: string;
+        message: string;
+    }[];
+    /** The settings the studio holds differently from the files, by profile and provider. None is the rule. */
+    differences: {
+        kind: 'profile' | 'provider';
+        of: string;
+        settings: string[];
+    }[];
+    /** What the files hold that the studio cannot, which stops it comparing any profile. */
+    unheld: string[];
+    /** The settings several profiles share, as the project's files set them. */
+    shared: SharedSetting[];
+    /** The profiles and tools the files define that the project did not register. */
+    unregistered: Unregistered[];
+    /** The settings the project's files set in code, by profile id, tool name, and provider id. */
+    origins: ProjectOrigins;
+    /** Where the files define each provider the project registered. */
+    providerPlaces: ProviderPlace[];
+    /** The tools that write: the ones the studio makes ask, and the ones it cannot. */
+    asks: StudioAsks;
+    /** The files as the server read them, as a short text that changes when they do. */
+    print: string;
+    /** What the project printed when its files stopped loading; the page shows the last load that did. */
+    unloaded?: string;
+    /** The editor the studio command opens files in when the builder chose none, by its command. */
+    editor?: string;
+    /** The setup file the studio command was started on, from the folder it ran in. */
+    setup?: string;
+    /** The places and people the setup file offers a run to act as; none when it offers none. */
+    people: StudioPeopleOffer | undefined;
+    /** Why the people the setup file exports cannot be offered. */
+    peopleProblem: string | undefined;
+}
+/**
+ * What the project's files hold that exported code names and does not write again. A provider the
+ * builder changed is left out, so the code writes it as the studio holds it.
+ */
+export declare function projectCode(project: ProjectSession | null, workspace: StudioWorkspace): ProjectCode | undefined;
+export declare const NO_ASKS: StudioAsks;
+/** Set while the page has a project open; `null` on the website's own page. */
+export declare const ProjectContext: import("react").Context<ProjectSession | null>;
+export declare function useProject(): ProjectSession | null;
+/** The session for a project already open: the run page names it in its address. */
+export declare function projectSession(name: string): ProjectSession;
+/** Where the local server runs the profile with this id. */
+export declare function projectProfileEndpoint(project: ProjectSession, profileId: string): string;
+/** What Save would write for this workspace: each change, and the lines of each file. Writes nothing. */
+export declare function reviewSave(project: ProjectSession, workspace: StudioWorkspace): Promise<SaveReview | SaveRefusal>;
+/** Writes the changes of a review the builder read. The server checks the project and reloads it. */
+export declare function writeSave(project: ProjectSession, workspace: StudioWorkspace, stamp: string): Promise<SaveDone | SaveRefusal>;
+/** Puts the files of the last Save back. */
+export declare function undoSave(project: ProjectSession): Promise<SaveDone | SaveRefusal>;
+/**
+ * Starts the load that runs this workspace's edits over the project's files, when it is not the
+ * one running. Writes nothing.
+ */
+export declare function openEdited(project: ProjectSession, workspace: StudioWorkspace): Promise<EditedAnswer>;
+/** Where the local server runs the profile with this id as the builder's edits make it. */
+export declare function editedProfileEndpoint(project: ProjectSession, profileId: string): string;
+/** Shows a line of one of the project's files in the editor the builder chose, or the studio command's. */
+export declare function openInEditor(project: ProjectSession, place: OpenRequest): Promise<OpenAnswer>;
+/** What a project's files say, which a Save or an edit in the builder's editor changes. */
+export type ProjectFiles = Pick<ProjectSession, 'profiles' | 'providers' | 'problems' | 'modelProblems' | 'differences' | 'unheld' | 'origins' | 'providerPlaces' | 'asks' | 'print' | 'unloaded' | 'people' | 'peopleProblem'>;
+/**
+ * What the project's files say now that the page does not hold as edits: the profiles they hold
+ * and the ones the studio cannot run, the settings they set in code, whose lines a Save moves,
+ * and the tools the studio makes ask. With them, the workspace the files open as.
+ */
+export declare function readFiles(): Promise<{
+    files: ProjectFiles;
+    workspace: StudioWorkspace;
+}>;
+/**
+ * The project the local server has open. `said` hears each step of the server's read of the
+ * files. Throws when no server answers.
+ */
+export declare function openProject(said?: (step: ReadStep) => void): Promise<{
+    project: ProjectSession;
+    workspace: StudioWorkspace;
+}>;