@opencraw/studio 0.0.33 → 0.0.36

package/dist/src/index.d.ts

@@ -2,6 +2,8 @@ export { main } from './main.js';
 export type { StudioMainOptions } from './main.js';
 export type { TrustedPlugins } from './trusted-plugins/index.js';
 export { startStudioServer } from './studio-server/index.js';
+export { defaultInstancesDirectory } from './studio-instance/index.js';
+export type { StudioInstance } from './studio-instance/index.js';
 export type { StudioServer, StudioServerOptions } from './studio-server/index.js';
 export { openWorkspace, saveRecipe, importDocument } from './recipe-workspace/index.js';
 export type { ImportedDocument } from './recipe-workspace/index.js';

package/dist/src/studio-api/command.contract.d.ts

@@ -385,6 +385,24 @@ export declare const importDocumentCommandSchema: z.ZodObject<{
     name: z.ZodString;
     bytes: z.ZodString;
 }, z.core.$strip>;
+/** Asks every open Studio page to do something (`ui-request`); the answer says how many pages were listening. How an agent opens a recipe for the person who is watching. */
+export declare const askUiCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ask-ui">;
+    request: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"open">;
+        path: z.ZodString;
+        workspace: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>;
+/** Asks what Studio is doing: its workspace, how many pages are open and the run in progress. */
+export declare const studioStatusCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"studio-status">;
+}, z.core.$strip>;
+/** Asks how a recipe's sample run is going: still running, finished (with its first records) or never run. */
+export declare const runStatusCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"run-status">;
+    recipeId: z.ZodString;
+}, z.core.$strip>;
 export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"open-workspace">;
     folder: z.ZodString;
@@ -542,6 +560,18 @@ export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     recipeId: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"stop-recording">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ask-ui">;
+    request: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"open">;
+        path: z.ZodString;
+        workspace: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"studio-status">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"run-status">;
+    recipeId: z.ZodString;
 }, z.core.$strip>], "type">;
 export type SampleBudget = z.infer<typeof sampleBudgetSchema>;
 export type OpenWorkspaceCommand = z.infer<typeof openWorkspaceCommandSchema>;
@@ -549,6 +579,9 @@ export type ChooseFolderCommand = z.infer<typeof chooseFolderCommandSchema>;
 export type OpenPathCommand = z.infer<typeof openPathCommandSchema>;
 export type ImportDocumentCommand = z.infer<typeof importDocumentCommandSchema>;
 export type RunSampleCommand = z.infer<typeof runSampleCommandSchema>;
+export type AskUiCommand = z.infer<typeof askUiCommandSchema>;
+export type StudioStatusCommand = z.infer<typeof studioStatusCommandSchema>;
+export type RunStatusCommand = z.infer<typeof runStatusCommandSchema>;
 export type StopRunCommand = z.infer<typeof stopRunCommandSchema>;
 export type SaveRecipeCommand = z.infer<typeof saveRecipeCommandSchema>;
 export type FetchStartPageCommand = z.infer<typeof fetchStartPageCommandSchema>;

package/dist/src/studio-api/event.contract.d.ts

@@ -87,6 +87,15 @@ export declare const recordingStoppedEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"recording-stopped">;
     steps: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
+/** A controller (an agent, through the MCP server) asked the open page to do something; every page does it. */
+export declare const uiRequestEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ui-request">;
+    request: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"open">;
+        path: z.ZodString;
+        workspace: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>;
 export declare const studioEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"trace-line">;
     line: z.ZodString;
@@ -139,7 +148,15 @@ export declare const studioEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"recording-stopped">;
     steps: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ui-request">;
+    request: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"open">;
+        path: z.ZodString;
+        workspace: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "kind">;
 }, z.core.$strip>], "type">;
+export type UiRequestEvent = z.infer<typeof uiRequestEventSchema>;
 export type StoppedBy = z.infer<typeof stoppedBySchema>;
 export type TraceLineEvent = z.infer<typeof traceLineEventSchema>;
 export type FieldTraceView = z.infer<typeof fieldTraceSchema>;

package/dist/src/studio-api/index.d.ts

@@ -1,13 +1,13 @@
-export { sampleBudgetSchema, openWorkspaceCommandSchema, chooseFolderCommandSchema, openPathCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, detectUrlCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, missingWhyTargetSchema, rejectedWhyTargetSchema, whyTargetSchema, explainWhyCommandSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewOptionsSchema, tablePreviewCommandSchema, regionPreviewCommandSchema, gridViewCommandSchema, gridRowsCommandSchema, gridPreviewOptionsSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewOptionsSchema, deckPreviewCommandSchema, startRecordingCommandSchema, stopRecordingCommandSchema, studioCommandSchema } from './command.contract.js';
-export type { SampleBudget, OpenWorkspaceCommand, ChooseFolderCommand, OpenPathCommand, ImportDocumentCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, DetectUrlCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, MissingWhyTarget, RejectedWhyTarget, WhyTarget, ExplainWhyCommand, InspectPageCommand, ResponsesSeenCommand, DocumentTreeCommand, PdfViewCommand, TablePreviewOptions, TablePreviewCommand, RegionPreviewCommand, GridViewCommand, GridRowsCommand, GridPreviewOptions, GridPreviewCommand, DeckViewCommand, DeckPreviewOptions, DeckPreviewCommand, StartRecordingCommand, StopRecordingCommand, StudioCommand } from './command.contract.js';
+export { sampleBudgetSchema, openWorkspaceCommandSchema, chooseFolderCommandSchema, openPathCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, detectUrlCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, missingWhyTargetSchema, rejectedWhyTargetSchema, whyTargetSchema, explainWhyCommandSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewOptionsSchema, tablePreviewCommandSchema, regionPreviewCommandSchema, gridViewCommandSchema, gridRowsCommandSchema, gridPreviewOptionsSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewOptionsSchema, deckPreviewCommandSchema, startRecordingCommandSchema, stopRecordingCommandSchema, askUiCommandSchema, studioStatusCommandSchema, runStatusCommandSchema, studioCommandSchema } from './command.contract.js';
+export type { SampleBudget, OpenWorkspaceCommand, ChooseFolderCommand, OpenPathCommand, ImportDocumentCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, DetectUrlCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, MissingWhyTarget, RejectedWhyTarget, WhyTarget, ExplainWhyCommand, InspectPageCommand, ResponsesSeenCommand, DocumentTreeCommand, PdfViewCommand, TablePreviewOptions, TablePreviewCommand, RegionPreviewCommand, GridViewCommand, GridRowsCommand, GridPreviewOptions, GridPreviewCommand, DeckViewCommand, DeckPreviewOptions, DeckPreviewCommand, StartRecordingCommand, StopRecordingCommand, AskUiCommand, StudioStatusCommand, RunStatusCommand, StudioCommand } from './command.contract.js';
 export { snapshotViewSchema } from './snapshot-view.contract.js';
 export type { SnapshotView } from './snapshot-view.contract.js';
 export { verifySelectorViewSchema } from './verify-selector-view.contract.js';
 export type { VerifySelectorView } from './verify-selector-view.contract.js';
 export { fieldPickSchema, inferSelectorViewSchema, selectorAlternativeSchema } from './infer-selector-view.contract.js';
 export type { FieldPick, InferSelectorView, SelectorAlternative } from './infer-selector-view.contract.js';
-export { stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, studioEventSchema } from './event.contract.js';
-export type { StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, RecordingCardEvent, RecordingNoteEvent, RecordingStoppedEvent, StudioEvent } from './event.contract.js';
+export { stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, uiRequestEventSchema, studioEventSchema } from './event.contract.js';
+export type { StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, RecordingCardEvent, RecordingNoteEvent, RecordingStoppedEvent, UiRequestEvent, StudioEvent } from './event.contract.js';
 export { loadedHooksSchema, recipeIssueSchema, recipeListingSchema, workspaceViewSchema } from './workspace-view.contract.js';
 export type { LoadedHooks, RecipeIssue, RecipeListing, WorkspaceView } from './workspace-view.contract.js';
 export { chooseFolderViewSchema } from './choose-folder-view.contract.js';
@@ -46,4 +46,8 @@ export { deckShapeViewSchema, deckChartSeriesViewSchema, deckChartViewSchema, de
 export type { DeckShapeView, DeckChartSeriesView, DeckChartView, DeckSlideView, DeckDocumentView } from './deck-view.contract.js';
 export { deckTablePreviewMatchSchema, deckTablePreviewViewSchema } from './deck-preview-view.contract.js';
 export type { DeckTablePreviewMatchView, DeckTablePreviewView } from './deck-preview-view.contract.js';
+export { uiRequestSchema } from './ui-request.contract.js';
+export type { UiRequest } from './ui-request.contract.js';
+export { askUiViewSchema, studioStatusViewSchema, runStatusViewSchema } from './studio-control-view.contract.js';
+export type { AskUiView, StudioStatusView, RunStatusView } from './studio-control-view.contract.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/studio-api/studio-control-view.contract.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+/** How many pages were listening when a controller asked them to do something: none means nobody has Studio open. */
+export declare const askUiViewSchema: z.ZodObject<{
+    pages: z.ZodNumber;
+}, z.core.$strip>;
+/** What Studio is doing: its workspace, how many pages are open, and the recipe whose sample run is in progress. */
+export declare const studioStatusViewSchema: z.ZodObject<{
+    folder: z.ZodOptional<z.ZodString>;
+    pages: z.ZodNumber;
+    running: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** How a recipe's sample run is going; `result` only once it finished: the counts, the first records and the first rejections (the rest are in Studio). */
+export declare const runStatusViewSchema: z.ZodObject<{
+    recipeId: z.ZodString;
+    state: z.ZodEnum<{
+        running: "running";
+        finished: "finished";
+        "never-run": "never-run";
+    }>;
+    result: z.ZodOptional<z.ZodObject<{
+        emitted: z.ZodNumber;
+        rejected: z.ZodNumber;
+        duplicates: z.ZodNumber;
+        durationMs: z.ZodNumber;
+        error: z.ZodOptional<z.ZodString>;
+        stoppedBy: z.ZodOptional<z.ZodString>;
+        records: z.ZodArray<z.ZodObject<{
+            key: z.ZodNullable<z.ZodString>;
+            data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>>;
+        rejections: z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            reason: z.ZodString;
+            url: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AskUiView = z.infer<typeof askUiViewSchema>;
+export type StudioStatusView = z.infer<typeof studioStatusViewSchema>;
+export type RunStatusView = z.infer<typeof runStatusViewSchema>;
+//# sourceMappingURL=studio-control-view.contract.d.ts.map

package/dist/src/studio-api/ui-request.contract.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+/** What an outside controller (an agent, through the MCP server) can ask the open Studio page to do. Grows one `kind` at a time. */
+export declare const uiRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"open">;
+    path: z.ZodString;
+    workspace: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "kind">;
+export type UiRequest = z.infer<typeof uiRequestSchema>;
+//# sourceMappingURL=ui-request.contract.d.ts.map

package/dist/src/studio-instance/index.d.ts

@@ -0,0 +1,3 @@
+export { announceInstance, defaultInstancesDirectory, withdrawInstance } from './instance-file.repository.js';
+export type { StudioInstance } from './studio-instance.contract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/studio-instance/instance-file.repository.d.ts

@@ -0,0 +1,14 @@
+import type { StudioInstance } from './studio-instance.contract.js';
+/** Where running Studios announce themselves, unless the caller says otherwise. */
+export declare function defaultInstancesDirectory(): string;
+/**
+ * Writes the file that tells controllers this Studio is running. Failing to write it never stops Studio: it only means no agent can find it.
+ *
+ * @param instance - What to announce.
+ * @param directory - Where announcements live.
+ * @returns Whether the file was written.
+ */
+export declare function announceInstance(instance: StudioInstance, directory: string): Promise<boolean>;
+/** Removes the announcement, when Studio stops. */
+export declare function withdrawInstance(instance: Pick<StudioInstance, 'pid' | 'url'>, directory: string): Promise<void>;
+//# sourceMappingURL=instance-file.repository.d.ts.map

package/dist/src/studio-instance/studio-instance.contract.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What a running Studio tells the machine about itself, one file per process, so a controller that did not start it (the MCP server an
+ * agent talks to) can find it: `~/.opencraw/studio/<pid>.json`. The token is in it, so the file is readable by its owner only.
+ * `@opencraw/mcp` reads the same shape (`studio-control`); change both together.
+ */
+export interface StudioInstance {
+    pid: number;
+    /** The server's address, without the token: `http://127.0.0.1:<port>`. */
+    url: string;
+    token: string;
+    /** The folder Studio was started with, if any; the live one is asked with `studio-status`. */
+    folder?: string;
+    startedAt: string;
+}
+//# sourceMappingURL=studio-instance.contract.d.ts.map

package/dist/src/studio-server/ask-ui.handler.d.ts

@@ -0,0 +1,12 @@
+import type { AskUiCommand, AskUiView } from '../studio-api/index.js';
+import type { StudioState } from './workspace.store.js';
+/**
+ * Handles `ask-ui`: tells every open page what a controller (an agent, through the MCP server) asked for, so
+ * the person watching sees it happen. Nothing is done server-side: the page does it the way a click would.
+ *
+ * @param state - The server state holding the connected pages.
+ * @param command - What to ask the pages.
+ * @returns How many pages were listening; 0 means nobody has Studio open.
+ */
+export declare function handleAskUi(state: StudioState, command: AskUiCommand): AskUiView;
+//# sourceMappingURL=ask-ui.handler.d.ts.map

package/dist/src/studio-server/run-status.handler.d.ts

@@ -0,0 +1,12 @@
+import type { RunStatusCommand, RunStatusView } from '../studio-api/index.js';
+import type { StudioState } from './workspace.store.js';
+/**
+ * Handles `run-status`: how a recipe's sample run is going, for a controller that started it and cannot watch
+ * the event stream. A run in progress is `running`; one that finished carries its counts and first records.
+ *
+ * @param state - The server state holding the run in progress and the last runs.
+ * @param command - The recipe asked about.
+ * @returns The state of the recipe's sample run.
+ */
+export declare function handleRunStatus(state: StudioState, command: RunStatusCommand): RunStatusView;
+//# sourceMappingURL=run-status.handler.d.ts.map

package/dist/src/studio-server/studio-http.use-case.d.ts

@@ -21,6 +21,8 @@ export interface StudioServerOptions {
     chooseFolder?: () => Promise<string | undefined>;
     /** Where the studio's own recorder profile lives (issue #95); default: a fixed directory under the OS temp folder, never a crawl's own profile directory, never the person's default browser. */
     recorderProfileDir?: string;
+    /** Where this Studio announces itself so an agent's MCP server can find it (`studio-instance`); default: `~/.opencraw/studio`. */
+    instancesDir?: string;
 }
 /** The running server: its URL (token included, ready to open), the token alone, and how to stop it. */
 export interface StudioServer {

package/dist/src/studio-server/studio-status.handler.d.ts

@@ -0,0 +1,10 @@
+import type { StudioStatusView } from '../studio-api/index.js';
+import type { StudioState } from './workspace.store.js';
+/**
+ * Handles `studio-status`: what Studio is doing right now.
+ *
+ * @param state - The server state.
+ * @returns The open workspace, how many pages are open and the recipe being sampled.
+ */
+export declare function handleStudioStatus(state: StudioState): StudioStatusView;
+//# sourceMappingURL=studio-status.handler.d.ts.map

package/dist/src/studio-server/workspace.store.d.ts

@@ -9,6 +9,8 @@ import type { WsConnection } from './websocket.client.js';
 export interface StudioState {
     folder?: string;
     activeRun?: SampleRunHandle;
+    /** The recipe `activeRun` is sampling. */
+    activeRunId?: string;
     activeRecording?: RecorderSessionHandle;
     /** A `start-recording` still opening its window: `stop-recording` and the server's own close wait for it, so a window is never left open behind them (issue #174). */
     openingRecording?: Promise<unknown>;

package/dist/studio-api/command.contract.d.ts

@@ -385,6 +385,24 @@ export declare const importDocumentCommandSchema: z.ZodObject<{
     name: z.ZodString;
     bytes: z.ZodString;
 }, z.core.$strip>;
+/** Asks every open Studio page to do something (`ui-request`); the answer says how many pages were listening. How an agent opens a recipe for the person who is watching. */
+export declare const askUiCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ask-ui">;
+    request: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"open">;
+        path: z.ZodString;
+        workspace: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>;
+/** Asks what Studio is doing: its workspace, how many pages are open and the run in progress. */
+export declare const studioStatusCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"studio-status">;
+}, z.core.$strip>;
+/** Asks how a recipe's sample run is going: still running, finished (with its first records) or never run. */
+export declare const runStatusCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"run-status">;
+    recipeId: z.ZodString;
+}, z.core.$strip>;
 export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"open-workspace">;
     folder: z.ZodString;
@@ -542,6 +560,18 @@ export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     recipeId: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"stop-recording">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ask-ui">;
+    request: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"open">;
+        path: z.ZodString;
+        workspace: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"studio-status">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"run-status">;
+    recipeId: z.ZodString;
 }, z.core.$strip>], "type">;
 export type SampleBudget = z.infer<typeof sampleBudgetSchema>;
 export type OpenWorkspaceCommand = z.infer<typeof openWorkspaceCommandSchema>;
@@ -549,6 +579,9 @@ export type ChooseFolderCommand = z.infer<typeof chooseFolderCommandSchema>;
 export type OpenPathCommand = z.infer<typeof openPathCommandSchema>;
 export type ImportDocumentCommand = z.infer<typeof importDocumentCommandSchema>;
 export type RunSampleCommand = z.infer<typeof runSampleCommandSchema>;
+export type AskUiCommand = z.infer<typeof askUiCommandSchema>;
+export type StudioStatusCommand = z.infer<typeof studioStatusCommandSchema>;
+export type RunStatusCommand = z.infer<typeof runStatusCommandSchema>;
 export type StopRunCommand = z.infer<typeof stopRunCommandSchema>;
 export type SaveRecipeCommand = z.infer<typeof saveRecipeCommandSchema>;
 export type FetchStartPageCommand = z.infer<typeof fetchStartPageCommandSchema>;

package/dist/studio-api/event.contract.d.ts

@@ -87,6 +87,15 @@ export declare const recordingStoppedEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"recording-stopped">;
     steps: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
+/** A controller (an agent, through the MCP server) asked the open page to do something; every page does it. */
+export declare const uiRequestEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ui-request">;
+    request: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"open">;
+        path: z.ZodString;
+        workspace: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>;
 export declare const studioEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"trace-line">;
     line: z.ZodString;
@@ -139,7 +148,15 @@ export declare const studioEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"recording-stopped">;
     steps: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ui-request">;
+    request: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"open">;
+        path: z.ZodString;
+        workspace: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "kind">;
 }, z.core.$strip>], "type">;
+export type UiRequestEvent = z.infer<typeof uiRequestEventSchema>;
 export type StoppedBy = z.infer<typeof stoppedBySchema>;
 export type TraceLineEvent = z.infer<typeof traceLineEventSchema>;
 export type FieldTraceView = z.infer<typeof fieldTraceSchema>;

package/dist/studio-api/index.d.ts

@@ -1,13 +1,13 @@
-export { sampleBudgetSchema, openWorkspaceCommandSchema, chooseFolderCommandSchema, openPathCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, detectUrlCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, missingWhyTargetSchema, rejectedWhyTargetSchema, whyTargetSchema, explainWhyCommandSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewOptionsSchema, tablePreviewCommandSchema, regionPreviewCommandSchema, gridViewCommandSchema, gridRowsCommandSchema, gridPreviewOptionsSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewOptionsSchema, deckPreviewCommandSchema, startRecordingCommandSchema, stopRecordingCommandSchema, studioCommandSchema } from './command.contract';
-export type { SampleBudget, OpenWorkspaceCommand, ChooseFolderCommand, OpenPathCommand, ImportDocumentCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, DetectUrlCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, MissingWhyTarget, RejectedWhyTarget, WhyTarget, ExplainWhyCommand, InspectPageCommand, ResponsesSeenCommand, DocumentTreeCommand, PdfViewCommand, TablePreviewOptions, TablePreviewCommand, RegionPreviewCommand, GridViewCommand, GridRowsCommand, GridPreviewOptions, GridPreviewCommand, DeckViewCommand, DeckPreviewOptions, DeckPreviewCommand, StartRecordingCommand, StopRecordingCommand, StudioCommand } from './command.contract';
+export { sampleBudgetSchema, openWorkspaceCommandSchema, chooseFolderCommandSchema, openPathCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, detectUrlCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, missingWhyTargetSchema, rejectedWhyTargetSchema, whyTargetSchema, explainWhyCommandSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewOptionsSchema, tablePreviewCommandSchema, regionPreviewCommandSchema, gridViewCommandSchema, gridRowsCommandSchema, gridPreviewOptionsSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewOptionsSchema, deckPreviewCommandSchema, startRecordingCommandSchema, stopRecordingCommandSchema, askUiCommandSchema, studioStatusCommandSchema, runStatusCommandSchema, studioCommandSchema } from './command.contract';
+export type { SampleBudget, OpenWorkspaceCommand, ChooseFolderCommand, OpenPathCommand, ImportDocumentCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, DetectUrlCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, MissingWhyTarget, RejectedWhyTarget, WhyTarget, ExplainWhyCommand, InspectPageCommand, ResponsesSeenCommand, DocumentTreeCommand, PdfViewCommand, TablePreviewOptions, TablePreviewCommand, RegionPreviewCommand, GridViewCommand, GridRowsCommand, GridPreviewOptions, GridPreviewCommand, DeckViewCommand, DeckPreviewOptions, DeckPreviewCommand, StartRecordingCommand, StopRecordingCommand, AskUiCommand, StudioStatusCommand, RunStatusCommand, StudioCommand } from './command.contract';
 export { snapshotViewSchema } from './snapshot-view.contract';
 export type { SnapshotView } from './snapshot-view.contract';
 export { verifySelectorViewSchema } from './verify-selector-view.contract';
 export type { VerifySelectorView } from './verify-selector-view.contract';
 export { fieldPickSchema, inferSelectorViewSchema, selectorAlternativeSchema } from './infer-selector-view.contract';
 export type { FieldPick, InferSelectorView, SelectorAlternative } from './infer-selector-view.contract';
-export { stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, studioEventSchema } from './event.contract';
-export type { StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, RecordingCardEvent, RecordingNoteEvent, RecordingStoppedEvent, StudioEvent } from './event.contract';
+export { stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, uiRequestEventSchema, studioEventSchema } from './event.contract';
+export type { StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, RecordingCardEvent, RecordingNoteEvent, RecordingStoppedEvent, UiRequestEvent, StudioEvent } from './event.contract';
 export { loadedHooksSchema, recipeIssueSchema, recipeListingSchema, workspaceViewSchema } from './workspace-view.contract';
 export type { LoadedHooks, RecipeIssue, RecipeListing, WorkspaceView } from './workspace-view.contract';
 export { chooseFolderViewSchema } from './choose-folder-view.contract';
@@ -46,4 +46,8 @@ export { deckShapeViewSchema, deckChartSeriesViewSchema, deckChartViewSchema, de
 export type { DeckShapeView, DeckChartSeriesView, DeckChartView, DeckSlideView, DeckDocumentView } from './deck-view.contract';
 export { deckTablePreviewMatchSchema, deckTablePreviewViewSchema } from './deck-preview-view.contract';
 export type { DeckTablePreviewMatchView, DeckTablePreviewView } from './deck-preview-view.contract';
+export { uiRequestSchema } from './ui-request.contract';
+export type { UiRequest } from './ui-request.contract';
+export { askUiViewSchema, studioStatusViewSchema, runStatusViewSchema } from './studio-control-view.contract';
+export type { AskUiView, StudioStatusView, RunStatusView } from './studio-control-view.contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/studio-api/studio-control-view.contract.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+/** How many pages were listening when a controller asked them to do something: none means nobody has Studio open. */
+export declare const askUiViewSchema: z.ZodObject<{
+    pages: z.ZodNumber;
+}, z.core.$strip>;
+/** What Studio is doing: its workspace, how many pages are open, and the recipe whose sample run is in progress. */
+export declare const studioStatusViewSchema: z.ZodObject<{
+    folder: z.ZodOptional<z.ZodString>;
+    pages: z.ZodNumber;
+    running: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** How a recipe's sample run is going; `result` only once it finished: the counts, the first records and the first rejections (the rest are in Studio). */
+export declare const runStatusViewSchema: z.ZodObject<{
+    recipeId: z.ZodString;
+    state: z.ZodEnum<{
+        finished: "finished";
+        "never-run": "never-run";
+        running: "running";
+    }>;
+    result: z.ZodOptional<z.ZodObject<{
+        emitted: z.ZodNumber;
+        rejected: z.ZodNumber;
+        duplicates: z.ZodNumber;
+        durationMs: z.ZodNumber;
+        error: z.ZodOptional<z.ZodString>;
+        stoppedBy: z.ZodOptional<z.ZodString>;
+        records: z.ZodArray<z.ZodObject<{
+            key: z.ZodNullable<z.ZodString>;
+            data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>>;
+        rejections: z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            reason: z.ZodString;
+            url: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AskUiView = z.infer<typeof askUiViewSchema>;
+export type StudioStatusView = z.infer<typeof studioStatusViewSchema>;
+export type RunStatusView = z.infer<typeof runStatusViewSchema>;
+//# sourceMappingURL=studio-control-view.contract.d.ts.map

package/dist/studio-api/ui-request.contract.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+/** What an outside controller (an agent, through the MCP server) can ask the open Studio page to do. Grows one `kind` at a time. */
+export declare const uiRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"open">;
+    path: z.ZodString;
+    workspace: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "kind">;
+export type UiRequest = z.infer<typeof uiRequestSchema>;
+//# sourceMappingURL=ui-request.contract.d.ts.map

package/dist/studio-instance/index.d.ts

@@ -0,0 +1,3 @@
+export { announceInstance, defaultInstancesDirectory, withdrawInstance } from './instance-file.repository';
+export type { StudioInstance } from './studio-instance.contract';
+//# sourceMappingURL=index.d.ts.map

package/dist/studio-instance/instance-file.repository.d.ts

@@ -0,0 +1,14 @@
+import type { StudioInstance } from './studio-instance.contract';
+/** Where running Studios announce themselves, unless the caller says otherwise. */
+export declare function defaultInstancesDirectory(): string;
+/**
+ * Writes the file that tells controllers this Studio is running. Failing to write it never stops Studio: it only means no agent can find it.
+ *
+ * @param instance - What to announce.
+ * @param directory - Where announcements live.
+ * @returns Whether the file was written.
+ */
+export declare function announceInstance(instance: StudioInstance, directory: string): Promise<boolean>;
+/** Removes the announcement, when Studio stops. */
+export declare function withdrawInstance(instance: Pick<StudioInstance, 'pid' | 'url'>, directory: string): Promise<void>;
+//# sourceMappingURL=instance-file.repository.d.ts.map

package/dist/studio-instance/studio-instance.contract.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What a running Studio tells the machine about itself, one file per process, so a controller that did not start it (the MCP server an
+ * agent talks to) can find it: `~/.opencraw/studio/<pid>.json`. The token is in it, so the file is readable by its owner only.
+ * `@opencraw/mcp` reads the same shape (`studio-control`); change both together.
+ */
+export interface StudioInstance {
+    pid: number;
+    /** The server's address, without the token: `http://127.0.0.1:<port>`. */
+    url: string;
+    token: string;
+    /** The folder Studio was started with, if any; the live one is asked with `studio-status`. */
+    folder?: string;
+    startedAt: string;
+}
+//# sourceMappingURL=studio-instance.contract.d.ts.map

package/dist/studio-server/ask-ui.handler.d.ts

@@ -0,0 +1,12 @@
+import type { AskUiCommand, AskUiView } from '../studio-api';
+import type { StudioState } from './workspace.store';
+/**
+ * Handles `ask-ui`: tells every open page what a controller (an agent, through the MCP server) asked for, so
+ * the person watching sees it happen. Nothing is done server-side: the page does it the way a click would.
+ *
+ * @param state - The server state holding the connected pages.
+ * @param command - What to ask the pages.
+ * @returns How many pages were listening; 0 means nobody has Studio open.
+ */
+export declare function handleAskUi(state: StudioState, command: AskUiCommand): AskUiView;
+//# sourceMappingURL=ask-ui.handler.d.ts.map

package/dist/studio-server/run-status.handler.d.ts

@@ -0,0 +1,12 @@
+import type { RunStatusCommand, RunStatusView } from '../studio-api';
+import type { StudioState } from './workspace.store';
+/**
+ * Handles `run-status`: how a recipe's sample run is going, for a controller that started it and cannot watch
+ * the event stream. A run in progress is `running`; one that finished carries its counts and first records.
+ *
+ * @param state - The server state holding the run in progress and the last runs.
+ * @param command - The recipe asked about.
+ * @returns The state of the recipe's sample run.
+ */
+export declare function handleRunStatus(state: StudioState, command: RunStatusCommand): RunStatusView;
+//# sourceMappingURL=run-status.handler.d.ts.map

package/dist/studio-server/studio-http.use-case.d.ts

@@ -21,6 +21,8 @@ export interface StudioServerOptions {
     chooseFolder?: () => Promise<string | undefined>;
     /** Where the studio's own recorder profile lives (issue #95); default: a fixed directory under the OS temp folder, never a crawl's own profile directory, never the person's default browser. */
     recorderProfileDir?: string;
+    /** Where this Studio announces itself so an agent's MCP server can find it (`studio-instance`); default: `~/.opencraw/studio`. */
+    instancesDir?: string;
 }
 /** The running server: its URL (token included, ready to open), the token alone, and how to stop it. */
 export interface StudioServer {

package/dist/studio-server/studio-status.handler.d.ts

@@ -0,0 +1,10 @@
+import type { StudioStatusView } from '../studio-api';
+import type { StudioState } from './workspace.store';
+/**
+ * Handles `studio-status`: what Studio is doing right now.
+ *
+ * @param state - The server state.
+ * @returns The open workspace, how many pages are open and the recipe being sampled.
+ */
+export declare function handleStudioStatus(state: StudioState): StudioStatusView;
+//# sourceMappingURL=studio-status.handler.d.ts.map

package/dist/studio-server/workspace.store.d.ts

@@ -9,6 +9,8 @@ import type { WsConnection } from './websocket.client';
 export interface StudioState {
     folder?: string;
     activeRun?: SampleRunHandle;
+    /** The recipe `activeRun` is sampling. */
+    activeRunId?: string;
     activeRecording?: RecorderSessionHandle;
     /** A `start-recording` still opening its window: `stop-recording` and the server's own close wait for it, so a window is never left open behind them (issue #174). */
     openingRecording?: Promise<unknown>;