@theoremjs/studio 0.0.0-stage → 0.3.2

package/draft.js

@@ -0,0 +1,505 @@
+/**
+ * Every section is always present so switching profile type keeps what the author typed.
+ * "Provider default" numbers are `null` and booleans hold the value the kernel would resolve,
+ * so compile emits a field only when it differs.
+ */
+import { liveIngressChannelDefault, profileAllowsInject, resolveGuardrailPolicy, } from '@theoremjs/agents';
+import { BOUNDARIES, DETECTORS, detects, PATTERN_DETECTORS, recordOf, } from '@theoremjs/agents/guardrails';
+import { CONTINUE_INSTRUCTION_TYPES, mimeAllowed, profileTypesForField, } from '@theoremjs/agents/kernel';
+import { resolveObservabilityPolicy } from '@theoremjs/agents/observability';
+import { IMAGE_ATTACHMENT_ACCEPT_MIMES, PROFILE_GRAPH, PROFILE_TYPES, TOOL_ACCESS, TOOL_LOAD_TIERS, TOOL_PERMISSION, } from '@theoremjs/agents/schema';
+import { isGoogleRoute, STUDIO_TRACE_DESTINATION, startingBinding } from "./policy.js";
+import { modelRoute, STUDIO_PROVIDERS, servesProfileType, } from "./providers.js";
+import { keySlotUnset } from "./requirements.js";
+import { DEFAULT_TOOL_INPUT_SCHEMA, DEFAULT_TOOL_OUTPUT_SCHEMA } from "./tool-schema.js";
+export const STUDIO_PROFILE_TYPES = PROFILE_TYPES;
+/** Where compaction starts when a builder turns it on; every number stays theirs to change. */
+export const COMPACTION_DRAFT_DEFAULTS = {
+    compactMaxTokens: 32_000,
+    compactAt: 0.75,
+    compactKeep: 4,
+};
+/** Wording held beside the setting it words; each line has one value, so it edits that field. */
+export const INLINE_LABELS = {
+    'continue.instruction': 'turnBehaviour',
+    'canary.bind_note': 'guardrails',
+    'quota.exhausted': 'guardrails',
+    'repair.default_guidance': 'outputs',
+    'egress.default_repair_guidance': 'guardrails',
+    'egress.refusal': 'guardrails',
+};
+export function draftKey(prefix) {
+    return `${prefix}-${crypto.randomUUID().slice(0, 8)}`;
+}
+export function defaultModelBinding(partial) {
+    return {
+        key: draftKey('model'),
+        modelId: 'fast',
+        protocol: 'openRouter',
+        provider: 'openrouter',
+        apiId: '',
+        options: {},
+        timeoutMs: null,
+        efforts: [],
+        defaultEffort: '',
+        allowEffortSelect: false,
+        summaries: null,
+        maxOutputTokens: null,
+        temperature: null,
+        builtInTools: [],
+        ...partial,
+    };
+}
+const STUB_TOOL_DESCRIPTION = 'Studio stub tool — returns a fixed result.';
+export function defaultToolSpec(partial) {
+    return {
+        key: draftKey('tool'),
+        toolName: 'my_tool',
+        toolType: 'function',
+        description: STUB_TOOL_DESCRIPTION,
+        category: 'studio',
+        access: TOOL_ACCESS[0],
+        permission: TOOL_PERMISSION[0],
+        loadTier: TOOL_LOAD_TIERS[0],
+        paths: ['*'],
+        inputJson: DEFAULT_TOOL_INPUT_SCHEMA,
+        outputJson: DEFAULT_TOOL_OUTPUT_SCHEMA,
+        ...partial,
+    };
+}
+/**
+ * The change that points an agent tool at an agent. A description that is
+ * still the new tool's stub, or empty, comes to say what the tool now does.
+ */
+export function agentToolTarget(tool, agentKey, agentId) {
+    const isStub = !tool.description.trim() || tool.description === STUB_TOOL_DESCRIPTION;
+    return isStub && agentId
+        ? { agentKey, description: `Asks ${agentId} and returns its answer.` }
+        : { agentKey };
+}
+/** A pattern to fill in. */
+export function newPattern() {
+    return { name: '', kind: 'words', pattern: '', flags: '', words: [] };
+}
+/** A detector of the builder's own to fill in: it reads nowhere until a boundary is set. */
+export function newOwnDetector() {
+    return {
+        key: '',
+        label: '',
+        at: recordOf(BOUNDARIES, () => 'ignore'),
+        patterns: [newPattern()],
+        hint: '',
+    };
+}
+function defaultGuardrails() {
+    const resolved = resolveGuardrailPolicy(undefined);
+    return {
+        canaryBindNote: '',
+        detect: recordOf(DETECTORS, (detector) => ({ ...resolved.detect[detector] })),
+        sources: Object.fromEntries(PATTERN_DETECTORS.map((detector) => [detector, { theorem: true, patterns: [], hint: '' }])),
+        own: [],
+        quotaEnabled: false,
+        quotaPerDay: null,
+        quotaMessage: '',
+        allow: {
+            ungiven_images: { hosts: [], fromTools: true },
+            ungiven_links: { hosts: [], fromTools: true },
+        },
+        innocentNames: [],
+        blockedReplyOnBlock: '',
+        blockedReplyMaxRetries: null,
+        egressRepairGuidance: '',
+        egressRefusal: '',
+        allowPrivateNetworks: false,
+        allowedHosts: [],
+        allowedSchemes: [],
+        taintAfterRemoteRead: '',
+        taintRemoteDestination: '',
+    };
+}
+function defaultObservability() {
+    // why: every draft writes this block, and the kernel reads one that is written with these.
+    const resolved = resolveObservabilityPolicy({});
+    return {
+        writeTo: STUDIO_TRACE_DESTINATION,
+        destination: STUDIO_TRACE_DESTINATION,
+        sampleRate: resolved.sampleRate,
+        include: { ...resolved.include },
+        scrub: {
+            sensitive: Boolean(resolved.scrub.sensitive),
+            injection: Boolean(resolved.scrub.injection),
+            canary: Boolean(resolved.scrub.canary),
+        },
+        retainForDays: null,
+        rotateAfterMiB: null,
+        resourceJson: '',
+    };
+}
+function criteria(entries) {
+    return entries.map(([label, text]) => ({ key: draftKey('criterion'), label, text }));
+}
+/** A guardrail on a tool call the agent is about to make: whether to let it run, and how much is at stake. */
+export function exampleDecisionDraft() {
+    return {
+        contract: 'guardrails.tool_call.v1',
+        maxStateBytes: null,
+        questions: [
+            {
+                key: draftKey('question'),
+                id: 'verdict',
+                type: 'choice',
+                instructions: 'Given what the user asked for and what the call would do, should it run?',
+                criteria: criteria([
+                    ['allow', 'Safe, and what the user asked for.'],
+                    ['flag', 'Probably fine, but unusual or sensitive enough for a person to look first.'],
+                    ['block', 'Harmful, or clearly beyond what the user asked for.'],
+                ]),
+            },
+            {
+                key: draftKey('question'),
+                id: 'risk',
+                type: 'score',
+                instructions: 'How much harm would this call do if it were wrong?',
+                criteria: criteria([
+                    ['', 'Low: reversible, and affects only the user.'],
+                    ['', 'High: hard to undo, or affects other people or money.'],
+                ]),
+            },
+        ],
+        images: [],
+    };
+}
+/** State the example's questions can be asked about: the field a decision preview starts with. */
+export const EXAMPLE_DECISION_STATE = JSON.stringify({
+    context: 'The user asked the agent to tidy up old screenshots on their desktop.',
+    tool_call: { name: 'delete_files', path: '~/Documents', recursive: true },
+    outcome: 'Would delete 1,284 files, including tax_return_2025.pdf.',
+}, null, 2);
+/** Span accepts a JSON string state; the preview starts with that shape for Span models. */
+export const EXAMPLE_SPAN_DECISION_STATE = JSON.stringify('The user asked to tidy screenshots. The proposed call recursively deletes 1,284 files, including a tax return.');
+/** Documents an embedding preview starts with, one per paragraph: a small help centre in a few topics, with a couple that belong to none. */
+export const EXAMPLE_EMBEDDING_TEXT = [
+    'To clear your desktop, select the screenshots and move them to the Trash. Empty the Trash to delete them for good.',
+    "Screen captures save to the desktop by default. You can change where they go in the Screenshot app's Options menu.",
+    'Press Command-Shift-5 to record the screen or capture a window. Recordings are saved as movie files next to your screenshots.',
+    'Stacks group desktop files by kind, date or tag, so a cluttered desktop folds into a few piles you can open one at a time.',
+    'Deleted files stay in the Trash for 30 days. Drag a file out of the Trash to put it back where it was.',
+    'When your disk is almost full, open Storage settings and review the largest files. Old downloads and installers are safe to remove.',
+    'Offloading unused apps frees space and keeps their documents. Reinstalling an app brings its data back.',
+    'Photos you have backed up can be optimised so the originals live in the cloud and smaller copies stay on the device.',
+    'Your plan renews on the same date each month. You can see the next charge under Billing, then Upcoming invoices.',
+    'To get a refund, open the invoice and choose Request refund. Charges from the last 14 days are refunded in full.',
+    'Update your card under Billing, then Payment methods. The new card is used for the next renewal, not for past invoices.',
+    'Annual plans cost two months less than paying monthly. Switching mid-term credits the unused months to the new plan.',
+    'Invoices are emailed as PDFs and list your company name and tax number. Edit those details before the invoice is issued.',
+    'Turn on two-step verification under Security. You will be asked for a code from your authenticator app each time you sign in on a new device.',
+    'If you forget your password, choose Forgot password on the sign-in page. The reset link expires after one hour.',
+    "Review signed-in devices under Security and sign out any you don't recognise. This ends their sessions immediately.",
+    'Passkeys replace your password with your fingerprint or face. Create one under Security, then Passkeys.',
+    'To close your account, export your data first. Closing deletes your workspace after a 30-day grace period.',
+    'Share a folder by choosing Share, then entering an email address. Viewers can read; editors can change and delete.',
+    'Public links work for anyone who has them. Set an expiry date, or turn the link off to stop sharing at once.',
+    'Transfer ownership of a folder before you leave a team, or its contents will be archived with your account.',
+    'Lisbon has mild, wet winters and warm, dry summers. Expect highs near 28 °C in August.',
+    'The best months for the Algarve coast are May, June and September, when the beaches are warm and the crowds are thin.',
+    'Trams in Lisbon climb the steep hills of Alfama and Graça. Line 28 is the famous one, and the busiest.',
+    'For a crisp pizza base, preheat the oven and the baking tray together at the highest setting for at least thirty minutes.',
+    'Rest steak for five minutes after cooking so the juices settle back into the meat instead of running onto the board.',
+].join('\n\n');
+/** The question an embedding preview starts with, nearest the first document. */
+export const EXAMPLE_EMBEDDING_QUERY = 'How do I delete every screenshot on my desktop?';
+/** A new question of `type`, with an id the draft doesn't use yet. */
+export function newDecisionQuestion(draft, type = 'choice') {
+    const taken = draft.decision.questions.map((question) => question.id);
+    const id = freeName('question', taken, (n) => `question_${n}`);
+    return { key: draftKey('question'), id, type, instructions: '', criteria: newCriteria(type) };
+}
+/**
+ * A picture added from `file`, named after it in the way a reference is written: lowercase, with
+ * `_` for anything else, and `_2`, `_3` after a name the draft has.
+ */
+export function newDecisionImage(draft, file, image) {
+    const base = file
+        .replace(/\.[^.]*$/, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_|_$/g, '') || 'image';
+    const taken = draft.decision.images.map((each) => each.name);
+    const name = freeName(base, taken, (n) => `${base}_${n}`);
+    return { key: draftKey('image'), name, ...image };
+}
+/** The rows a question of `type` starts with: two options, two levels, or none. */
+export function newCriteria(type) {
+    if (type === 'noul' || type === 'box')
+        return [];
+    return criteria(type === 'choice'
+        ? [
+            ['yes', ''],
+            ['no', ''],
+        ]
+        : [
+            ['', ''],
+            ['', ''],
+        ]);
+}
+/**
+ * An empty draft: no profile type chosen, every section at its kernel default
+ * except observability, which the studio includes and points at its own
+ * trace destination.
+ */
+export function createBlankDraft() {
+    return {
+        identity: { agentId: '', profileType: '', handle: '', system: '', systemByRoleJson: '' },
+        included: ['observability', 'labels'],
+        models: { defaultModel: '', allowModelSelect: false, maxSteps: null, key: '' },
+        modelBindings: [],
+        providers: [...STUDIO_PROVIDERS],
+        tools: { t2Loader: '', parallel: false },
+        toolSpecs: [],
+        inputs: {
+            text: true,
+            attachmentsAccept: [],
+            voiceAccept: [],
+            maxFiles: null,
+            maxBytes: null,
+            maxTurnBytes: null,
+            limitsByMimeJson: '',
+            slotsJson: '',
+            contextFrom: [],
+            contextMaxChars: null,
+        },
+        outputs: {
+            mode: 'text',
+            schemaId: '',
+            schemaJson: '',
+            streamMode: '',
+            streamThoughts: true,
+            validationEnabled: false,
+            maxRetries: null,
+            itemRules: {},
+            repairGuidance: '',
+        },
+        turnBehaviour: {
+            resumeEnabled: false,
+            allowContinue: [],
+            autoContinue: [],
+            maxContinues: null,
+            continueInstruction: '',
+            allowSteering: profileAllowsInject({ type: 'text' }),
+            atStepLimit: 'stop',
+        },
+        guardrails: defaultGuardrails(),
+        observability: defaultObservability(),
+        image: {
+            aspectRatio: '',
+            resolution: '',
+            mimeType: '',
+            quality: '',
+            background: '',
+            n: null,
+            seed: null,
+            outputCompression: null,
+            includeText: false,
+            references: [],
+        },
+        speech: { voice: '', style: '', speed: null, format: '' },
+        live: {
+            ingressAudio: liveIngressChannelDefault('audio'),
+            ingressVideo: liveIngressChannelDefault('video'),
+            ingressText: liveIngressChannelDefault('text'),
+            voice: '',
+            sessionResumption: false,
+            greeting: '',
+            resumedPrompt: '',
+            resumedAfterMs: null,
+            contextCompression: false,
+            compressionTriggerTokens: null,
+            compressionTargetTokens: null,
+            transcriptionInput: false,
+            transcriptionOutput: false,
+            vadActivityHandling: '',
+            vadStartSensitivity: '',
+            vadEndSensitivity: '',
+            vadPrefixPaddingMs: null,
+            vadSilenceDurationMs: null,
+        },
+        decision: exampleDecisionDraft(),
+        labels: {},
+    };
+}
+/**
+ * Facets a decision draft leaves out: its only guardrail is a host's disclosure
+ * hook, which a draft can't carry.
+ */
+const DECISION_HIDDEN_FACETS = new Set(['guardrails']);
+function facetFits(facet, type) {
+    return (facet.profileTypes.includes(type) &&
+        !(type === 'decision' && DECISION_HIDDEN_FACETS.has(facet.id)));
+}
+/** Required facets for the type plus the included optional ones, in catalog order. */
+export function draftFacets(draft) {
+    const type = draft.identity.profileType;
+    if (!type)
+        return ['identity'];
+    const included = new Set(draft.included);
+    return PROFILE_GRAPH.filter((facet) => facet.role !== 'branch' &&
+        facetFits(facet, type) &&
+        (!facet.optional || included.has(facet.id))).map((facet) => facet.id);
+}
+/** By the kernel's `PROFILE_FIELD_SCOPE`; false until a type is chosen. */
+export function draftAllows(draft, path) {
+    const type = draft.identity.profileType;
+    return type !== '' && profileTypesForField(path).includes(type);
+}
+/** A canary is bound into a system prompt while `canary_leak` reads somewhere. */
+export function plantsCanary(draft) {
+    return draftAllows(draft, 'identity.system') && detects(draft.guardrails.detect, 'canary_leak');
+}
+export function takesContinueInstruction(draft) {
+    const type = draft.identity.profileType;
+    return type !== '' && CONTINUE_INSTRUCTION_TYPES.includes(type);
+}
+export function includableFacets(draft) {
+    const type = draft.identity.profileType;
+    if (!type)
+        return [];
+    return PROFILE_GRAPH.filter((facet) => facet.role === 'spine' &&
+        facet.optional &&
+        facetFits(facet, type) &&
+        !draft.included.includes(facet.id)).map((facet) => facet.id);
+}
+/** Inputs an image profile can take: no voice, attachments within images, video, and PDF. */
+function imageInputs(inputs) {
+    return {
+        ...inputs,
+        attachmentsAccept: inputs.attachmentsAccept.filter((rule) => mimeAllowed(IMAGE_ATTACHMENT_ACCEPT_MIMES, rule)),
+        voiceAccept: [],
+    };
+}
+/** Updates a binding and keeps the default model attached to it through an id change. */
+export function updateModelBinding(draft, bindingKey, change) {
+    const binding = draft.modelBindings.find((candidate) => candidate.key === bindingKey);
+    if (!binding)
+        return draft;
+    return {
+        ...draft,
+        models: change.modelId !== undefined && draft.models.defaultModel === binding.modelId
+            ? { ...draft.models, defaultModel: change.modelId }
+            : draft.models,
+        modelBindings: draft.modelBindings.map((candidate) => candidate.key === bindingKey ? { ...candidate, ...change } : candidate),
+    };
+}
+/**
+ * The default model once the bindings change: the one it was while that is still a model, and the
+ * only model when one is left, as the kernel reads a profile with one model.
+ */
+function defaultAmong(current, modelBindings) {
+    if (modelBindings.some((binding) => binding.modelId === current))
+        return current;
+    const [only, ...others] = modelBindings;
+    return only && !others.length ? only.modelId : '';
+}
+/**
+ * Drops a binding, and the default model with it when it was that one. Model select turns off
+ * below two bindings, as on a type switch.
+ */
+export function removeModelBinding(draft, bindingKey) {
+    const binding = draft.modelBindings.find((candidate) => candidate.key === bindingKey);
+    if (!binding)
+        return draft;
+    const modelBindings = draft.modelBindings.filter((candidate) => candidate.key !== bindingKey);
+    return {
+        ...draft,
+        models: {
+            ...draft.models,
+            defaultModel: defaultAmong(draft.models.defaultModel, modelBindings),
+        },
+        modelBindings,
+    };
+}
+/** A new model for the draft's type, starting where `start` puts it, or on no model yet. */
+export function newModelBinding(draft, start) {
+    const chosen = draft.identity.profileType;
+    const type = chosen && chosen !== 'host' ? chosen : 'text';
+    const taken = draft.modelBindings.map((binding) => binding.modelId);
+    const seed = startingBinding(type, start);
+    const modelId = freeName(seed.modelId, taken, (n) => `${seed.modelId}${n}`);
+    return defaultModelBinding({ ...seed, modelId });
+}
+export function newToolSpec(draft) {
+    const taken = draft.toolSpecs.map((tool) => tool.toolName);
+    return defaultToolSpec({ toolName: freeName('my_tool', taken, (n) => `my_tool_${n}`) });
+}
+/** `first` if nothing has taken it, else the first `nth(2)`, `nth(3)`, … that is free. */
+export function freeName(first, taken, nth) {
+    const used = new Set(taken);
+    let name = first;
+    for (let n = 2; used.has(name); n++)
+        name = nth(n);
+    return name;
+}
+/**
+ * Bindings whose model the kernel says can't serve the new type are dropped, and so are those
+ * `keys` list only for another type; if none remain, a new one starts where `keys` start one. Model select turns off below two bindings. Other sections and
+ * `included` are kept, so a facet the type lacks comes back when switching back. A host runs no
+ * model, so it keeps the bindings for the way back.
+ */
+export function setProfileType(draft, type, keys) {
+    if (type === 'host') {
+        return { ...draft, identity: { ...draft.identity, profileType: type } };
+    }
+    const kept = draft.modelBindings.filter((binding) => {
+        const route = modelRoute(draft.providers, type, binding);
+        const provider = draft.providers.find((each) => each.id === binding.provider);
+        return (servesProfileType(provider, type, binding.protocol) && !listedForOthers(keys, type, route));
+    });
+    const retyped = {
+        ...draft,
+        identity: { ...draft.identity, profileType: type },
+        modelBindings: kept,
+    };
+    const modelBindings = kept.length ? kept : [newModelBinding(retyped, keys?.start)];
+    const needsKey = !draft.models.key && keySlotUnset({ ...retyped, modelBindings });
+    // why: Gemini speaks only in a named voice, so a speech agent on it starts with one.
+    const voiceless = type === 'speech' &&
+        !draft.speech.voice.trim() &&
+        modelBindings.some((binding) => isGoogleRoute(modelRoute(draft.providers, type, binding)));
+    return {
+        ...retyped,
+        inputs: type === 'image' ? imageInputs(draft.inputs) : draft.inputs,
+        ...(voiceless ? { speech: { ...draft.speech, voice: GOOGLE_STARTING_VOICE } } : {}),
+        models: {
+            ...draft.models,
+            defaultModel: defaultAmong(draft.models.defaultModel, modelBindings),
+            key: needsKey ? DEFAULT_KEY_SLOT : draft.models.key,
+        },
+        modelBindings,
+    };
+}
+/** The voice a new Gemini speech agent starts with; Google's own examples read in it. */
+const GOOGLE_STARTING_VOICE = 'Kore';
+const MODEL_PROFILE_TYPES = [
+    'text',
+    'image',
+    'speech',
+    'live',
+    'decision',
+];
+/** Whether `keys` list the model for some other type, and not for `type`. */
+function listedForOthers(keys, type, route) {
+    if (!keys)
+        return false;
+    const listed = (each) => keys.models(each, route.definition).some((model) => model.id === route.apiId.trim());
+    return !listed(type) && MODEL_PROFILE_TYPES.some((each) => each !== type && listed(each));
+}
+// The slot the studio's server fills; named slots in the editor replace this.
+const DEFAULT_KEY_SLOT = 'slot_a';
+export function includeFacet(draft, id) {
+    if (!includableFacets(draft).includes(id))
+        return draft;
+    return { ...draft, included: [...draft.included, id] };
+}
+/** Its values stay on the draft for when it comes back. */
+export function excludeFacet(draft, id) {
+    return { ...draft, included: draft.included.filter((facet) => facet !== id) };
+}

package/editors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The editors the studio can start on a line of a file: the ones that open in a window of their
+ * own. One that runs in a terminal is not here, since the studio has no terminal to run it in.
+ *
+ * @module
+ */
+/** How an editor's command takes a file and a line: `-g file:line`, `file:line`, `--line n file`, or `-l n file`. */
+export type EditorLineForm = 'goto' | 'colon' | 'line-flag' | 'l-flag';
+/** An editor the studio can start, by the command that starts it. */
+export interface StudioEditor {
+    command: string;
+    /** The editor's name, as the builder reads it. */
+    label: string;
+    form: EditorLineForm;
+    /** One the builder can choose in Settings. The others are started only when the studio command or the environment names them. */
+    choice?: true;
+    /**
+     * Where the macOS app keeps its command, from an Applications folder. The app is often installed
+     * without its command on the path, and the studio starts it from here then.
+     */
+    macCommand?: string;
+}
+export declare const STUDIO_EDITORS: readonly StudioEditor[];
+/** The editor a command names, or undefined when the studio cannot start it on a line. */
+export declare function studioEditor(command: string): StudioEditor | undefined;
+/** Whether a command is one the builder can choose in Settings, so one a page may name. */
+export declare function isEditorChoice(command: string): boolean;
+/** An editor's name as the builder reads it: `code` is VS Code. One the studio does not know keeps its command. */
+export declare function editorLabel(command: string): string;

package/editors.js

@@ -0,0 +1,51 @@
+/**
+ * The editors the studio can start on a line of a file: the ones that open in a window of their
+ * own. One that runs in a terminal is not here, since the studio has no terminal to run it in.
+ *
+ * @module
+ */
+export const STUDIO_EDITORS = [
+    {
+        command: 'code',
+        label: 'VS Code',
+        form: 'goto',
+        choice: true,
+        macCommand: 'Visual Studio Code.app/Contents/Resources/app/bin/code',
+    },
+    {
+        command: 'cursor',
+        label: 'Cursor',
+        form: 'goto',
+        choice: true,
+        macCommand: 'Cursor.app/Contents/Resources/app/bin/cursor',
+    },
+    { command: 'zed', label: 'Zed', form: 'colon' },
+    { command: 'windsurf', label: 'Windsurf', form: 'goto' },
+    { command: 'webstorm', label: 'WebStorm', form: 'line-flag' },
+    { command: 'subl', label: 'Sublime Text', form: 'colon' },
+    { command: 'code-insiders', label: 'VS Code Insiders', form: 'goto' },
+    { command: 'codium', label: 'VSCodium', form: 'goto' },
+    { command: 'positron', label: 'Positron', form: 'goto' },
+    { command: 'zeditor', label: 'Zed (zeditor)', form: 'colon' },
+    { command: 'idea', label: 'IntelliJ IDEA', form: 'line-flag' },
+    { command: 'pycharm', label: 'PyCharm', form: 'line-flag' },
+    { command: 'phpstorm', label: 'PhpStorm', form: 'line-flag' },
+    { command: 'goland', label: 'GoLand', form: 'line-flag' },
+    { command: 'rubymine', label: 'RubyMine', form: 'line-flag' },
+    { command: 'clion', label: 'CLion', form: 'line-flag' },
+    { command: 'rider', label: 'Rider', form: 'line-flag' },
+    { command: 'fleet', label: 'Fleet', form: 'line-flag' },
+    { command: 'mate', label: 'TextMate', form: 'l-flag' },
+];
+/** The editor a command names, or undefined when the studio cannot start it on a line. */
+export function studioEditor(command) {
+    return STUDIO_EDITORS.find((editor) => editor.command === command);
+}
+/** Whether a command is one the builder can choose in Settings, so one a page may name. */
+export function isEditorChoice(command) {
+    return studioEditor(command)?.choice === true;
+}
+/** An editor's name as the builder reads it: `code` is VS Code. One the studio does not know keeps its command. */
+export function editorLabel(command) {
+    return studioEditor(command)?.label ?? command;
+}

package/example-embedding-files.d.ts

@@ -0,0 +1,11 @@
+import type { EmbeddingInput } from '@theoremjs/agents';
+/** A document an embedding preview starts with, and the file it came from. */
+export type ExampleEmbeddingFile = {
+    input: EmbeddingInput;
+    from: string;
+};
+/**
+ * The files an embedding preview starts with, beside the example text: three pictures that
+ * belong to its topics, and a refund policy that adds three documents to billing.
+ */
+export declare const EXAMPLE_EMBEDDING_FILES: readonly ExampleEmbeddingFile[];