@theoremjs/studio 0.0.0-stage → 0.3.2

package/ui/lib/boot-sequence.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The order the loader runs in: the mark draws, a project's read is mapped on the panel as it pulls
+ * in beside the rail, the map fades, and the panel pulls in to the page. What each step does on
+ * screen is the caller's; this only decides when.
+ */
+/**
+ * What the loader shows: the mark drawing, the map of a project's read on the panel as it pulls in
+ * beside the rail, the map fading out, and nothing once the page has the shell.
+ */
+export type BootPhase = 'draw' | 'map' | 'leave' | 'done';
+export interface Boot {
+    /** Whether a project is read for the page, and so mapped. Never with reduced motion. */
+    reads: boolean;
+    reduced: boolean;
+    /** How long the map takes to fade. */
+    fadeMs: number;
+    /** Settles when the page under the loader is on screen with its fonts. */
+    settled: Promise<unknown>;
+    /** Settles when the map has drawn every step of a read that has ended. */
+    mapDrawn: Promise<void>;
+    markDrawn(): Promise<void>;
+    /** Whether the pen has begun. Until it does, the panel is blank and there is nothing to wait out. */
+    penHasStarted(): boolean;
+    /** Pulls the panel in beside the rail. */
+    pullIn(): Promise<unknown>;
+    sleep(ms: number): Promise<void>;
+    show(phase: 'map' | 'leave'): void;
+    /** Pulls the panel in to the page's shape. Called once. */
+    reveal(): void;
+}
+/** Runs the loader. The function returned stops it: nothing more is shown or revealed. */
+export declare function runBoot(boot: Boot): () => void;

package/ui/lib/boot-sequence.js

@@ -0,0 +1,57 @@
+/**
+ * The order the loader runs in: the mark draws, a project's read is mapped on the panel as it pulls
+ * in beside the rail, the map fades, and the panel pulls in to the page. What each step does on
+ * screen is the caller's; this only decides when.
+ */
+/** How long the drawn mark is held before it gives way. */
+const HOLD_MS = 90;
+const REDUCED_HOLD_MS = 200;
+/** Runs the loader. The function returned stops it: nothing more is shown or revealed. */
+export function runBoot(boot) {
+    let cancelled = false;
+    let revealed = false;
+    let pulling = false;
+    const reveal = () => {
+        if (cancelled || revealed)
+            return;
+        revealed = true;
+        boot.reveal();
+    };
+    /* A project's read is drawn once the mark is, loaded or not. The mark gives way as it does for
+         any page, and the map starts on the panel as it pulls in. Settles once the panel is in. */
+    const mapped = boot.reads
+        ? boot
+            .markDrawn()
+            .then(() => boot.sleep(HOLD_MS))
+            .then(() => {
+            if (cancelled || revealed)
+                return false;
+            pulling = true;
+            boot.show('map');
+            return boot.pullIn().then(() => !cancelled);
+        })
+        : Promise.resolve(false);
+    /* If the page is ready before the pen starts, no mark was ever on screen and the panel pulls in
+         at once. Once the pen has started, it finishes, and so does a map. */
+    void boot.settled
+        .then(() => {
+        if (!boot.reduced && !pulling && !boot.penHasStarted())
+            return undefined;
+        if (!boot.reads)
+            return boot.markDrawn().then(() => boot.sleep(boot.reduced ? REDUCED_HOLD_MS : HOLD_MS));
+        return mapped.then((shown) => {
+            if (!shown || cancelled)
+                return undefined;
+            return boot.mapDrawn.then(() => {
+                if (cancelled)
+                    return undefined;
+                boot.show('leave');
+                return boot.sleep(boot.fadeMs);
+            });
+        });
+    })
+        .then(reveal);
+    return () => {
+        cancelled = true;
+    };
+}

package/ui/lib/export-agent.d.ts

@@ -0,0 +1,11 @@
+import { type CompiledStudio, type CompiledWorkspace, type ProjectCode, type SourceFile } from '../../mod.ts';
+/**
+ * The workspace as files: the README, the tools, one module per agent, and the
+ * registration, then the route and component for `agent`, the one being chatted with.
+ * On a project, `project` is what its files hold that the code names and does not write again.
+ */
+export declare function exportFiles(workspace: CompiledWorkspace, agent: CompiledStudio, project?: ProjectCode): SourceFile[];
+/** The files as one text, each under its path, to paste or to hand to a coding agent. */
+export declare function exportText(files: readonly SourceFile[]): string;
+/** The files with a brief for a coding agent: what to ask, what to install, where each file goes. */
+export declare function llmBrief(workspace: CompiledWorkspace, agent: CompiledStudio, project?: ProjectCode): string;

package/ui/lib/export-agent.js

@@ -0,0 +1,335 @@
+import { agentModulePath, importSpecifier, workspaceSource, } from "../../mod.js";
+const PACKAGES = [
+    '@theoremjs/agents',
+    '@theoremjs/react',
+    'zod',
+    'react',
+    'react-dom',
+    '@astryxdesign/core',
+    '@stylexjs/stylex',
+];
+const INSTALL = `npm install ${PACKAGES.join(' ')}`;
+/** Where the host mounts `createTheoremHandler`; `TheoremChat`'s default endpoint. */
+const ENDPOINT = '/api/theorem';
+/** Where the host mounts `createTheoremDecisionHandler`; `TheoremDecision`'s default endpoint. */
+const DECISION_ENDPOINT = '/api/decision';
+/** Where the host mounts `createTheoremHostHandler`; `TheoremHost`'s default endpoint. */
+const HOST_ENDPOINT = '/api/host';
+/** Where the host mounts `createTheoremEmbeddingHandler`; `TheoremEmbedding`'s default endpoint. */
+const EMBEDDING_ENDPOINT = '/api/embedding';
+/** Turn profiles run through `createTheoremHandler`; live profiles run through a relay. */
+const NOT_TURNS = new Set(['live', 'decision', 'host', 'embedding']);
+function servesTurns({ profile }) {
+    return !NOT_TURNS.has(profile.type);
+}
+/** The `keySlot` and `fallbackKeySlot` an object names, when they are strings. */
+function slotsOn(value) {
+    if (!value || typeof value !== 'object')
+        return [];
+    const { keySlot, fallbackKeySlot } = value;
+    return [keySlot, fallbackKeySlot].filter((slot) => typeof slot === 'string' && slot !== '');
+}
+/** Every vault slot an agent names, on the profile or on a model. */
+function keySlots({ profile }) {
+    const models = 'models' in profile ? profile.models : {};
+    const bindings = models && typeof models === 'object' ? Object.values(models) : [];
+    return [profile, ...bindings].flatMap(slotsOn);
+}
+/** The vault the route reads: each slot any agent names, from `THEOREM_VAULT_<SLOT>`. The agents it calls spend keys too. */
+function vaultSource(workspace) {
+    const slots = [...new Set(workspace.agents.flatMap(keySlots))];
+    const entries = slots.map((slot) => `${JSON.stringify(slot)}: process.env.THEOREM_VAULT_${slot.toUpperCase().replaceAll('-', '_')}`);
+    return `{ ${entries.join(', ')} }`;
+}
+/** The provider options the route needs, each key read from the server's environment. */
+function providerSource(workspace) {
+    const parts = [`vault: ${vaultSource(workspace)}`];
+    return `{\n${parts.map((part) => `    ${part},`).join('\n')}\n  }`;
+}
+/** The route file: `factory` from the server entry, built from the agent's module with `options`. */
+/** What a route imports from the agent's module: its profile, and a decision's questions and pictures. */
+function moduleNames(agent) {
+    if (agent.profile.type !== 'decision')
+        return ['profile'];
+    return ['profile', 'questions', ...(agent.images ? ['images'] : [])];
+}
+function serverFile(agent, exportName, factory, mount, options) {
+    const module = importSpecifier(agentModulePath(agent.agentId));
+    return {
+        path: 'route.ts',
+        code: `${[
+            `import { ${factory} } from '@theoremjs/react/server';`,
+            "import './theorem';",
+            `import { ${moduleNames(agent).join(', ')} } from '${module}';`,
+            '',
+            `/** ${mount} */`,
+            `export const ${exportName} = ${factory}({`,
+            ...options.map((option) => `  ${option},`),
+            '});',
+        ].join('\n')}\n`,
+    };
+}
+/** The browser file: one component that renders `component` pointed at `endpoint`. */
+function browserFile(path, name, component, endpoint, what, props = []) {
+    const element = props.length === 0
+        ? [`  return <${component} endpoint="${endpoint}" />;`]
+        : [
+            '  return (',
+            `    <${component}`,
+            `      endpoint="${endpoint}"`,
+            ...props.map((prop) => `      ${prop}`),
+            '    />',
+            '  );',
+        ];
+    return {
+        path,
+        what,
+        code: `${[
+            `import { ${component} } from '@theoremjs/react/ui';`,
+            '',
+            `export function ${name}() {`,
+            ...element,
+            '}',
+        ].join('\n')}\n`,
+    };
+}
+/** What the agent takes from its page and its server: `inputs.slots` and `inputs.context`. */
+function pageInputs({ profile }) {
+    const inputs = 'inputs' in profile ? profile.inputs : undefined;
+    const slots = inputs && 'slots' in inputs ? (inputs.slots ?? {}) : {};
+    const context = inputs && 'context' in inputs ? inputs.context : undefined;
+    return { slots: Object.entries(slots), from: context?.from ?? [] };
+}
+/** The chat's prop for the tools this page answers: a function per tool, returning its output. */
+function pageToolsProp(agent) {
+    const names = agent.customTools.flatMap((tool) => tool.type === 'function' && tool.answeredBy === 'page' ? [tool.name] : []);
+    if (names.length === 0)
+        return [];
+    return [
+        '// What this page does for each tool it answers, and the output it returns.',
+        'pageTools={{',
+        ...names.map((name) => `  ${JSON.stringify(name)}: (args) => ({ output: {} }),`),
+        '}}',
+    ];
+}
+/** The chat's props for what the page supplies: a value per slot, and its context. */
+function pageProps(agent) {
+    const { slots, from } = pageInputs(agent);
+    const picked = slots.map(([name, allowed]) => `${JSON.stringify(name)}: ${JSON.stringify(allowed.at(0) ?? '')}`);
+    return [
+        ...slots.map(([name, allowed]) => `// ${name}: ${allowed.join(' | ')}`),
+        ...(slots.length > 0 ? [`slots={{ ${picked.join(', ')} }}`] : []),
+        ...(from.includes('client')
+            ? ['// What this page tells the agent: any JSON.', 'context={{}}']
+            : []),
+        ...pageToolsProp(agent),
+    ];
+}
+/** The route's option for what the server tells the agent, when the profile takes it. */
+function serverContext(agent) {
+    return pageInputs(agent).from.includes('server')
+        ? ['// What your server tells the agent with each request: any JSON.\n  context: () => ({})']
+        : [];
+}
+/** A decision agent's route and its state-and-answers component. */
+function decisionEntry(workspace, agent) {
+    return {
+        endpoint: DECISION_ENDPOINT,
+        route: serverFile(agent, 'decision', 'createTheoremDecisionHandler', `Mount at ${DECISION_ENDPOINT} and ${DECISION_ENDPOINT}/decide. The questions stay here; the browser sends only the state.`, [...moduleNames(agent), `vault: ${vaultSource(workspace)}`]),
+        ui: browserFile('AgentDecision.tsx', 'AgentDecision', 'TheoremDecision', DECISION_ENDPOINT, 'the state field and the answers'),
+    };
+}
+/** A host agent's route and its form-per-tool component. */
+function hostEntry(agent) {
+    return {
+        endpoint: HOST_ENDPOINT,
+        route: serverFile(agent, 'host', 'createTheoremHostHandler', `Mount at ${HOST_ENDPOINT}/*: it describes the tools, and answers /call and /invoke. No model runs.`, ['profile']),
+        ui: browserFile('AgentHost.tsx', 'AgentHost', 'TheoremHost', HOST_ENDPOINT, 'a form per tool and its result'),
+    };
+}
+/** An embedding agent's route and its inputs-and-vectors component. */
+function embeddingEntry(workspace, agent) {
+    return {
+        endpoint: EMBEDDING_ENDPOINT,
+        route: serverFile(agent, 'embedding', 'createTheoremEmbeddingHandler', `Mount at ${EMBEDDING_ENDPOINT} and ${EMBEDDING_ENDPOINT}/embed.`, ['profile', `vault: ${vaultSource(workspace)}`]),
+        ui: browserFile('AgentEmbedding.tsx', 'AgentEmbedding', 'TheoremEmbedding', EMBEDDING_ENDPOINT, 'the inputs and their vectors'),
+    };
+}
+/** A turn agent's route and its chat. */
+function turnEntry(workspace, agent) {
+    return {
+        endpoint: ENDPOINT,
+        route: serverFile(agent, 'theorem', 'createTheoremHandler', `Mount at ${ENDPOINT}/*: it answers /turn, /invoke and /steer.`, ['profile', `provider: ${providerSource(workspace)}`, ...serverContext(agent)]),
+        ui: browserFile('AgentChat.tsx', 'AgentChat', 'TheoremChat', ENDPOINT, 'the chat', pageProps(agent)),
+    };
+}
+function entryFiles(workspace, agent) {
+    if (agent.profile.type === 'decision')
+        return decisionEntry(workspace, agent);
+    if (agent.profile.type === 'host')
+        return hostEntry(agent);
+    if (agent.profile.type === 'embedding')
+        return embeddingEntry(workspace, agent);
+    if (!servesTurns(agent))
+        return {};
+    return turnEntry(workspace, agent);
+}
+/** The README: what each file is, which run only on the server, and what to install. */
+function readme(files, agent, entry) {
+    const agents = files.filter((file) => file.path.startsWith('agents/'));
+    const rows = [
+        ...(files.some((file) => file.path === 'tools.ts')
+            ? ['- `tools.ts` (server only): the tools the agents share.']
+            : []),
+        ...agents.map((file) => `- \`${file.path}\` (server only): one agent's profile. It registers nothing.`),
+        '- `theorem.ts` (server only): registers every tool and agent, each after the agents it names. Import it once.',
+        ...(entry.route
+            ? [
+                `- \`route.ts\` (server only): runs \`${agent.agentId}\`, mounted at \`${entry.endpoint ?? ''}\`.`,
+            ]
+            : []),
+        ...(entry.ui
+            ? [`- \`${entry.ui.path}\` (browser): ${entry.ui.what}, pointed at that route.`]
+            : []),
+    ];
+    return `${[
+        `# ${agent.agentId}`,
+        '',
+        `Exported from the Theorem Studio: ${agents.length === 1 ? 'one agent' : `${String(agents.length)} agents`}${entry.route
+            ? `, and the route and ${entry.ui ? 'component' : 'files'} for \`${agent.agentId}\``
+            : ''}.`,
+        '',
+        ...rows,
+        '',
+        entry.route
+            ? 'The server-only files read your keys. Nothing in them may reach the browser.'
+            : `\`${agent.agentId}\` is a ${agent.profile.type} agent: register it on your server, then run it through your own relay (see @theoremjs/react/live).`,
+        '',
+        '```bash',
+        INSTALL,
+        '```',
+    ].join('\n')}\n`;
+}
+/**
+ * The workspace as files: the README, the tools, one module per agent, and the
+ * registration, then the route and component for `agent`, the one being chatted with.
+ * On a project, `project` is what its files hold that the code names and does not write again.
+ */
+export function exportFiles(workspace, agent, project) {
+    const source = workspaceSource(workspace, project).map((file) => file.path !== 'theorem.ts'
+        ? file
+        : {
+            ...file,
+            code: file.code.replace("baseUrl: 'http://localhost:11434/v1'", "baseUrl: (process.env.LOCAL_MODEL_URL ?? 'http://127.0.0.1:11434').replace(/\\/$/, '') + '/v1'"),
+        });
+    const entry = entryFiles(workspace, agent);
+    return [
+        { path: 'README.md', code: readme(source, agent, entry) },
+        ...source,
+        ...(entry.route ? [entry.route] : []),
+        ...(entry.ui ? [{ path: entry.ui.path, code: entry.ui.code }] : []),
+    ];
+}
+/** The files as one text, each under its path, to paste or to hand to a coding agent. */
+export function exportText(files) {
+    return files.map((file) => `// ─── ${file.path} ───\n\n${file.code.trimEnd()}\n`).join('\n');
+}
+/** What the brief asks before code, by the chatted agent's type. */
+function briefQuestions(agent, tools) {
+    const type = agent.profile.type;
+    if (type === 'decision') {
+        return [
+            '- Where the state comes from: typed by a person in `TheoremDecision` (`AgentDecision.tsx`), or built by my own code, which then calls `runDecision` from `@theoremjs/agents` on the server and drops `route.ts` and `AgentDecision.tsx`.',
+            `- Which framework this app uses, and where server routes live (so the handler mounts at \`${DECISION_ENDPOINT}\`, or the path you pick).`,
+            '- Where the model keys come from: environment variables or a secrets manager.',
+            '- Who may call the route, and how many decisions each caller may make: every decision spends a key.',
+        ];
+    }
+    if (type === 'host') {
+        return [
+            '- Who calls the tools: a person in `TheoremHost` (`AgentHost.tsx`), an MCP client, or my own code, which then drops `AgentHost.tsx`.',
+            `- Which framework this app uses, and where server routes live (so the handler mounts at \`${HOST_ENDPOINT}\`, or the path you pick).`,
+            "- Where each tool's keys come from, if any need them.",
+            '- Who may call the route, and how often.',
+        ];
+    }
+    if (type === 'embedding') {
+        return [
+            '- Where the inputs come from: typed by a person in `TheoremEmbedding` (`AgentEmbedding.tsx`), or sent by my own code, which then calls `runEmbedding` from `@theoremjs/agents` on the server and drops `route.ts` and `AgentEmbedding.tsx`.',
+            `- Which framework this app uses, and where server routes live (so the handler mounts at \`${EMBEDDING_ENDPOINT}\`, or the path you pick).`,
+            '- Where the model keys come from: environment variables or a secrets manager.',
+            '- Where the vectors go: the store or index that keeps them, and who may call the route: every request spends a key.',
+        ];
+    }
+    const turns = servesTurns(agent);
+    return [
+        ...(turns
+            ? [
+                '- Whether I want a UI at all, since the answer decides what you install and build:',
+                '  - The package-prepared user interface (`TheoremChat`, in `AgentChat.tsx`);',
+                '  - my own UI on `useTheoremChat` from `@theoremjs/react`, which gives the conversation state without the styling;',
+                '  - or none: my server code calls `runTurn` from `@theoremjs/agents` directly, and `route.ts` and `AgentChat.tsx` are dropped.',
+            ]
+            : []),
+        `- Which framework this app uses, and where server routes live (so the handler mounts at \`${ENDPOINT}\`, or the path you pick).`,
+        "- Where model keys come from: environment variables, a secrets manager, or each user's own key.",
+        '- Who may use the agents: anyone, or only signed-in users (the handler takes a `session` resolver).',
+        '- Whether sessions must survive restarts or span several instances (then pass a shared atomic `sessionStore` with `load` and `compareAndSwap`; a separate read followed by a write is unsafe).',
+        ...(tools.length
+            ? [
+                `- What each tool should really do: ${tools.join(', ')} return stand-in data today. Where does the real data come from, and what credentials does each need?`,
+            ]
+            : []),
+        '- If I want a UI: where it should appear, and whether it should match an existing theme.',
+    ];
+}
+/** The files with a brief for a coding agent: what to ask, what to install, where each file goes. */
+export function llmBrief(workspace, agent, project) {
+    const files = exportFiles(workspace, agent, project);
+    const stubs = [
+        ...new Set(workspace.agents.flatMap((each) => each.customTools
+            .filter((tool) => tool.type === 'function')
+            .map((tool) => `\`${tool.name}\``))),
+    ];
+    const turns = servesTurns(agent);
+    return `# Add the Theorem agents to this app
+
+The files below were exported from the Theorem Studio: ${workspace.agents.map((each) => `\`${each.agentId}\``).join(', ')}, the tools they share, the registration that wires them together${files.some((file) => file.path === 'route.ts')
+        ? `, and a server route and package-prepared user interface for \`${agent.agentId}\``
+        : ''}. The README says what each file is. Wire them into this codebase.
+
+## Before you write code, ask me
+${briefQuestions(agent, stubs).join('\n')}
+
+## Install
+${turns
+        ? `Install only what my answer about the UI needs:
+- No UI: \`npm install @theoremjs/agents zod\`
+- My own UI: \`npm install @theoremjs/agents @theoremjs/react zod react react-dom\`
+- The package-prepared user interface: \`${INSTALL}\``
+        : `\`\`\`bash
+${INSTALL}
+\`\`\``}
+
+## Organise it
+- Keep the layout: \`tools.ts\`, \`agents/\` and \`theorem.ts\` together in one server-only folder. Each agent has one module, so its profile has one source of truth.
+- Import \`theorem.ts\` once, before anything runs an agent. Keep its order: an agent is registered after the agents it calls or that summarise for it, and an agent tool after the agent it runs.
+
+## Do
+- Read model keys on the server only, from the environment or a secrets manager.
+- Keep \`registerProfile\`, \`registerTool\` and the handler in server-only modules; the browser imports only \`@theoremjs/react\`, \`/ui\` or \`/live\`.
+- Replace each function tool's stand-in handler with the real call; its input is already checked against the Zod schema given.
+- Change an agent's settings in its own module, or in the studio and export again.
+
+## Don't
+- Don't import \`tools.ts\`, \`agents/\`, \`theorem.ts\` or \`route.ts\` from browser code, or put a key in a \`VITE_\`, \`NEXT_PUBLIC_\` or other client variable.
+- Don't log request bodies or tool credentials; the handler keeps credentials per session, off the wire.
+- Don't copy a profile into several places.
+- Don't turn off an agent's guardrails to make a test pass.
+
+## The files
+\`\`\`tsx
+${exportText(files).trimEnd()}
+\`\`\`
+`;
+}

package/ui/lib/facet-icons.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Studio tree icons for PROFILE_GRAPH facets. Docs chapters reuse this
+ * map so a section does not grow a second glyph.
+ */
+export declare const FACET_ICON: {
+    identity: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+    models: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+    modelBinding: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+    tools: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+    inputs: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+    outputs: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+    turnBehaviour: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+    guardrails: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+    observability: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+    labels: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+    image: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+    speech: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+    live: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+    decision: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+};

package/ui/lib/facet-icons.js

@@ -0,0 +1,21 @@
+/**
+ * Studio tree icons for PROFILE_GRAPH facets. Docs chapters reuse this
+ * map so a section does not grow a second glyph.
+ */
+import { IconActivity, IconCpu, IconFileExport, IconFileImport, IconGavel, IconHeadset, IconId, IconPhoto, IconQuote, IconRepeat, IconShieldCheck, IconStack2, IconTool, IconVolume, } from '@tabler/icons-react';
+export const FACET_ICON = {
+    identity: IconId,
+    models: IconStack2,
+    modelBinding: IconCpu,
+    tools: IconTool,
+    inputs: IconFileImport,
+    outputs: IconFileExport,
+    turnBehaviour: IconRepeat,
+    guardrails: IconShieldCheck,
+    observability: IconActivity,
+    labels: IconQuote,
+    image: IconPhoto,
+    speech: IconVolume,
+    live: IconHeadset,
+    decision: IconGavel,
+};

package/ui/lib/panel-motion.d.ts

@@ -0,0 +1,8 @@
+/** A phone's panel already takes the frame, and reduced motion moves nothing. */
+export declare function panelCanMove(): boolean;
+/**
+ * Move the panel around `swap`, which puts the next view on screen and must have drawn it by the
+ * time it returns. `widens` is the map or Settings opening; otherwise it is closing. Without a
+ * panel to move, the swap happens at once.
+ */
+export declare function movePanel(widens: boolean, swap: () => void): Promise<void>;

package/ui/lib/panel-motion.js

@@ -0,0 +1,74 @@
+/**
+ * The panel takes the whole frame for the map or Settings, and gives it back. The preview eases
+ * out, the panel's far edge moves over the room it gave up, and the map or Settings eases in as it
+ * is uncovered. The tree and the editor stay where they are.
+ */
+import { HOLD_MS, prefersReducedMotion, sleep } from "../shell-motion.js";
+const MOVE_MS = 640;
+const FADE_MS = 280;
+const EASE = 'cubic-bezier(0.45, 0.02, 0.15, 1)';
+/** What fades out before the move and back in after it: the preview and the panel's handle. */
+const PARTS = '.studio-preview, .studio-side-handle';
+/** What eases in as the panel extends over it: the map, or Settings' list and body under its headers. */
+const INCOMING = '.studio-map-pane, .studio-settings-tree, .studio-settings-body';
+/** A phone's panel already takes the frame, and reduced motion moves nothing. */
+export function panelCanMove() {
+    return globalThis.matchMedia('(min-width: 768px)').matches && !prefersReducedMotion();
+}
+/** A tab in the background runs no animation, so each one is also given its time and no longer. */
+function ended(animations, ms) {
+    const all = Promise.all(animations.map((each) => each.finished.catch(() => undefined)));
+    return Promise.race([all, sleep(ms + 200)]);
+}
+/**
+ * Move the panel around `swap`, which puts the next view on screen and must have drawn it by the
+ * time it returns. `widens` is the map or Settings opening; otherwise it is closing. Without a
+ * panel to move, the swap happens at once.
+ */
+export async function movePanel(widens, swap) {
+    const frame = document.querySelector('.studio-frame');
+    const surface = frame?.querySelector('[data-shell-frame]');
+    if (!frame || !surface || !panelCanMove()) {
+        swap();
+        return;
+    }
+    const parts = () => [...frame.querySelectorAll(PARTS)];
+    const hidden = parts().map((part) => part.animate({ opacity: [1, 0] }, { duration: HOLD_MS, easing: 'ease', fill: 'forwards' }));
+    await ended(hidden, HOLD_MS);
+    // The panel is drawn at its full width, cut back to the width it rests at: only the cut moves.
+    // The corners are the raised surface's own, which the frame wraps.
+    const drawn = surface.firstElementChild ?? surface;
+    const round = getComputedStyle(drawn).borderTopRightRadius || '0px';
+    const cut = (width) => `inset(0 calc(100% - ${String(width)}px) 0 0 round ${round})`;
+    const whole = `inset(0 0 0 0 round ${round})`;
+    if (widens) {
+        const narrow = surface.offsetWidth;
+        surface.dataset.rests = String(narrow);
+        const move = surface.animate({ clipPath: [cut(narrow), whole] }, { duration: MOVE_MS, easing: EASE, fill: 'both' });
+        swap();
+        const incoming = frame.querySelectorAll(INCOMING);
+        const fades = [...incoming].map((each) => each.animate({ opacity: [0, 1] }, { duration: MOVE_MS, easing: EASE, fill: 'both' }));
+        await ended([move, ...fades], MOVE_MS);
+        move.cancel();
+        for (const each of fades)
+            each.cancel();
+    }
+    else {
+        const narrow = Number(surface.dataset.rests);
+        delete surface.dataset.rests;
+        if (narrow > 0) {
+            const move = surface.animate({ clipPath: [whole, cut(narrow)] }, { duration: MOVE_MS, easing: EASE, fill: 'both' });
+            await ended([move], MOVE_MS);
+            swap();
+            move.cancel();
+        }
+        else {
+            swap();
+        }
+    }
+    for (const part of parts()) {
+        part.animate({ opacity: [0, 1] }, { duration: FADE_MS, easing: EASE });
+    }
+    for (const each of hidden)
+        each.cancel();
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Where the page finds the project's local server. The studio's own page is told in its document,
+ * by the command that started both; any other page looks where the first studio on this machine
+ * listens.
+ */
+export declare const PROJECT_META = "theorem-studio-project";
+export declare const FIRST_PROJECT_ENDPOINT = "http://127.0.0.1:4983/api/studio";
+export declare function projectEndpoint(): string;
+/**
+ * Where the screen's own requests go: the guardrail probe and the key and connection tests. The
+ * studio's own page has no server of its own, so they go to the project's; any other page answers
+ * them itself, under `/api/studio`.
+ */
+export declare function screenEndpoint(): string;

package/ui/lib/project-address.js

@@ -0,0 +1,24 @@
+/**
+ * Where the page finds the project's local server. The studio's own page is told in its document,
+ * by the command that started both; any other page looks where the first studio on this machine
+ * listens.
+ */
+export const PROJECT_META = 'theorem-studio-project';
+export const FIRST_PROJECT_ENDPOINT = 'http://127.0.0.1:4983/api/studio';
+export function projectEndpoint() {
+    if (typeof document === 'undefined')
+        return FIRST_PROJECT_ENDPOINT;
+    return (document.querySelector(`meta[name="${PROJECT_META}"]`)?.content ??
+        FIRST_PROJECT_ENDPOINT);
+}
+/**
+ * Where the screen's own requests go: the guardrail probe and the key and connection tests. The
+ * studio's own page has no server of its own, so they go to the project's; any other page answers
+ * them itself, under `/api/studio`.
+ */
+export function screenEndpoint() {
+    if (typeof document === 'undefined')
+        return '/api/studio';
+    return (document.querySelector(`meta[name="${PROJECT_META}"]`)?.content ??
+        '/api/studio');
+}

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

@@ -0,0 +1,13 @@
+/**
+ * The studio's page can be opened a moment before the project's server listens: one command starts
+ * both. Nothing answering is then a server still starting, so the page asks again until one does.
+ */
+export interface Clock {
+    now(): number;
+    wait(ms: number): Promise<void>;
+}
+/**
+ * What `open` resolves to, asking again while nothing answers. Throws what `open` last threw when
+ * a server answers badly, or when none has answered by the time one would have started.
+ */
+export declare function onceAnswering<T>(open: () => Promise<T>, clock?: Clock): Promise<T>;

package/ui/lib/project-starting.js

@@ -0,0 +1,30 @@
+/**
+ * The studio's page can be opened a moment before the project's server listens: one command starts
+ * both. Nothing answering is then a server still starting, so the page asks again until one does.
+ */
+/** How long a server has to start listening, and how often the page asks. */
+const STARTING_MS = 10_000;
+const EVERY_MS = 200;
+const CLOCK = {
+    now: () => performance.now(),
+    wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+/** A fetch that reached nothing throws a TypeError; a server that answered badly throws something else. */
+const nothingAnswered = (error) => error instanceof TypeError;
+/**
+ * What `open` resolves to, asking again while nothing answers. Throws what `open` last threw when
+ * a server answers badly, or when none has answered by the time one would have started.
+ */
+export async function onceAnswering(open, clock = CLOCK) {
+    const until = clock.now() + STARTING_MS;
+    for (;;) {
+        try {
+            return await open();
+        }
+        catch (error) {
+            if (!nothingAnswered(error) || clock.now() >= until)
+                throw error;
+            await clock.wait(EVERY_MS);
+        }
+    }
+}