@opencraw/studio 0.0.17 → 0.0.19

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

@@ -0,0 +1,36 @@
+import type { StartRecordingCommand, StopRecordingCommand } from '../studio-api';
+import type { StudioState } from './workspace.store';
+/**
+ * Handles `start-recording`: opens the studio's own headed browser window
+ * on the named recipe's start point (issue #95, phase 6) and streams
+ * `recording-card`/`recording-note` events as the person drives it. One
+ * recording at a time, like one sample run at a time: a second
+ * `start-recording` stops whatever was already open first.
+ *
+ * @param state - The server state: `folder` must already be set, `recorderProfileDir` names the studio's own recorder profile (never a crawl's own, never the person's default browser).
+ * @param command - The command.
+ * @returns `{ started: true }` once the window is open.
+ * @throws Error when no workspace is open, or the recipe cannot be found or loaded.
+ */
+export declare function handleStartRecording(state: StudioState, command: StartRecordingCommand): Promise<{
+    started: true;
+}>;
+/**
+ * Handles `stop-recording`: closes the recording window, if one is open,
+ * and answers with every step recorded, in order — enough for the caller to
+ * build "make this the login" (`session.bootstrap`) or "keep as steps"
+ * without asking the server again. Also broadcasts `recording-stopped`, so
+ * every connected client (not only the one that asked) knows the window
+ * closed, even when nothing was open (a UI waiting on it would stay stuck).
+ * A stop that arrives while the window is still opening waits for it.
+ *
+ * @param state - The server state holding the active recording, if any.
+ * @param _command - The command (carries nothing beyond its type).
+ * @returns Every step recorded, in order; empty when nothing was recording.
+ */
+export declare function handleStopRecording(state: StudioState, _command: StopRecordingCommand): Promise<{
+    steps: Record<string, unknown>[];
+}>;
+/** Closes the recording in progress, waiting first for one still opening (issue #174). */
+export declare function settleRecording(state: StudioState): Promise<void>;
+//# sourceMappingURL=recording.handler.d.ts.map

package/dist/studio-server/region-preview.handler.d.ts

@@ -0,0 +1,17 @@
+import type { RegionPreviewCommand, RegionPreviewView } from '../studio-api';
+import type { StudioState } from './workspace.store';
+/**
+ * Handles `region-preview`: the PDF and deck canvases' live preview of a
+ * `region` extract's selector (`document-view`'s
+ * `region-preview.use-case.ts`, issues #121 and #122), off the same cached
+ * snapshot `take-snapshot` already captured — a pure computation over it,
+ * so this answers instantly on every change of the box, no re-fetch or
+ * re-parse (mirrors `table-preview.handler.ts`).
+ *
+ * @param state - The server state.
+ * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
+ * @returns The matches, or `error` when the selector does not parse or does not fit the document.
+ * @throws Error when `command.path` has no cached snapshot yet, or the snapshot is neither a PDF nor a deck.
+ */
+export declare function handleRegionPreview(state: StudioState, command: RegionPreviewCommand): RegionPreviewView;
+//# sourceMappingURL=region-preview.handler.d.ts.map

package/dist/studio-server/responses-seen.handler.d.ts

@@ -0,0 +1,16 @@
+import type { ResponsesSeenCommand, ResponsesSeenView } from '../studio-api';
+import type { StudioState } from './workspace.store';
+/**
+ * Handles `responses-seen`: the JSON responses observed while a recipe's
+ * start page rendered (`page-inspector`'s `responses-seen.use-case.ts`,
+ * issue #93), for the Inspect panel's "responses seen" list — picking one
+ * is the seam the UI uses to switch the recipe to api mode (issue #93's
+ * acceptance; the JSON tree canvas that follows is phase 5's).
+ *
+ * @param state - The server state: `folder` must already be set.
+ * @param command - The command.
+ * @returns The observed responses.
+ * @throws Error when no workspace is open, or the recipe cannot be found or loaded.
+ */
+export declare function handleResponsesSeen(state: StudioState, command: ResponsesSeenCommand): Promise<ResponsesSeenView>;
+//# sourceMappingURL=responses-seen.handler.d.ts.map

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

@@ -0,0 +1,28 @@
+import type { RunSampleCommand, StopRunCommand } from '../studio-api';
+import type { StudioState } from './workspace.store';
+/**
+ * Handles `run-sample`: stops whatever sample was still running (one run at
+ * a time), starts the new one, and returns once it has started, not once it
+ * finishes: `trace-line` and `record` stream over the WebSocket as the run
+ * proceeds, and `run-finished` closes it out.
+ *
+ * @param state - The server state: `folder` must already be set (`open-workspace` first).
+ * @param command - The command.
+ * @returns `{ started: true }` once the run has begun.
+ * @throws Error when no workspace is open, or the recipe cannot be loaded or bound.
+ */
+export declare function handleRunSample(state: StudioState, command: RunSampleCommand): Promise<{
+    started: true;
+}>;
+/**
+ * Handles `stop-run`: closes the crawler of the run in progress, if any.
+ * `run-finished` still follows once the interrupted run's promise settles.
+ *
+ * @param state - The server state holding the active run, if any.
+ * @param _command - The command (carries nothing beyond its type).
+ * @returns Whether a run was actually in progress to stop.
+ */
+export declare function handleStopRun(state: StudioState, _command: StopRunCommand): Promise<{
+    stopped: boolean;
+}>;
+//# sourceMappingURL=run-sample.handler.d.ts.map

package/dist/studio-server/save-outline.handler.d.ts

@@ -0,0 +1,18 @@
+import type { SaveOutlineCommand } from '../studio-api';
+import type { StudioState } from './workspace.store';
+/**
+ * Handles `save-outline`: the Steps tab's edits, as the outline it holds
+ * locally, converted back to the recipe's JSON (`scope-outline`'s
+ * `outlineToRecipe`, so the conversion runs here rather than in the
+ * browser) and written the same way `save-recipe` writes the JSON tab's
+ * edits. Every connected client, including the sender, is told the
+ * workspace changed, so both tabs re-fetch it and stay in sync.
+ *
+ * @param state - The server state holding the connected sockets.
+ * @param command - The command: the file path and the edited outline.
+ * @returns `{ saved: true }` once the write has completed.
+ */
+export declare function handleSaveOutline(state: StudioState, command: SaveOutlineCommand): Promise<{
+    saved: true;
+}>;
+//# sourceMappingURL=save-outline.handler.d.ts.map

package/dist/studio-server/save-recipe.handler.d.ts

@@ -0,0 +1,15 @@
+import type { SaveRecipeCommand } from '../studio-api';
+import type { StudioState } from './workspace.store';
+/**
+ * Handles `save-recipe`: writes the file (see `recipe-workspace/save-recipe.use-case.ts`
+ * for the pretty-printing and its round-trip guarantee), then tells every
+ * connected client the workspace changed, so the UI can re-fetch it.
+ *
+ * @param state - The server state holding the connected sockets.
+ * @param command - The command: the file path and the whole recipe object.
+ * @returns `{ saved: true }` once the write has completed.
+ */
+export declare function handleSaveRecipe(state: StudioState, command: SaveRecipeCommand): Promise<{
+    saved: true;
+}>;
+//# sourceMappingURL=save-recipe.handler.d.ts.map

package/dist/studio-server/static-file.handler.d.ts

@@ -0,0 +1,14 @@
+import type { ServerResponse } from 'node:http';
+/**
+ * Serves the built UI from `root` (`packages/studio/dist/ui`, `apps/studio-ui`'s
+ * build output): the requested path if it exists as a file, `index.html`
+ * otherwise, so a client-side route (or the bare `/`) always gets the SPA's
+ * shell. `root` not existing at all (the UI has not been built) answers 404
+ * with a hint rather than a stack trace.
+ *
+ * @param root - The built UI's folder.
+ * @param pathname - The request's URL path.
+ * @param response - The response to write to.
+ */
+export declare function serveStatic(root: string, pathname: string, response: ServerResponse): void;
+//# sourceMappingURL=static-file.handler.d.ts.map

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

@@ -0,0 +1,40 @@
+import type { BrowserSessionConfig } from '@opencraw/core';
+import type { TrustedPlugins } from '../trusted-plugins';
+export interface StudioServerOptions {
+    /** Where the built UI lives; default: `dist/ui` next to the running server code. */
+    uiRoot?: string;
+    /** A fixed port; default: an OS-assigned free port. */
+    port?: number;
+    /**
+     * The folder `opencraw-studio` was started with, if any: set as the
+     * server's current workspace right away, so `run-sample`, `save-recipe`
+     * and `fetch-start-page` work immediately, before the UI's own
+     * `open-workspace` call (which it still makes, to get the recipe listing;
+     * the folder reaches it through the URL's `folder` query param).
+     */
+    initialFolder?: string;
+    /** Browser launch settings every web-mode command shares (`take-snapshot`, `verify-selector`, `run-sample`, `start-recording`); an executable path override (e.g. `OPENCRAW_CHROMIUM`, read by the caller — the server itself has no opinion on env vars) for a sandbox with no full Playwright install. Default: Playwright's own bundled browser. `start-recording` always forces `headless: false` regardless of what this sets. */
+    browser?: BrowserSessionConfig;
+    /** Hooks, access plugins and captcha solvers to run recipes with, loaded by the caller from a file the person named at launch (`opencraw studio --hooks`, issue #150). The server never loads code itself and no request can set this. Default: none. */
+    plugins?: TrustedPlugins;
+    /** 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;
+}
+/** The running server: its URL (token included, ready to open), the token alone, and how to stop it. */
+export interface StudioServer {
+    url: string;
+    token: string;
+    close: () => Promise<void>;
+}
+/**
+ * Starts the studio's HTTP server: one `POST /api/command` for every
+ * command `studio-api` defines, `GET /ws` for the event stream, and the
+ * built UI for everything else. Binds `127.0.0.1` only; every request needs
+ * the token (`access-token.policy.ts`) — as a header, a query param, or the
+ * cookie the server sets once a document request proves the query param.
+ *
+ * @param options - The UI root and the port; both default sensibly.
+ * @returns The running server.
+ */
+export declare function startStudioServer(options?: StudioServerOptions): Promise<StudioServer>;
+//# sourceMappingURL=studio-http.use-case.d.ts.map

package/dist/studio-server/table-preview.handler.d.ts

@@ -0,0 +1,16 @@
+import type { TablePreviewCommand, TablePreviewView } from '../studio-api';
+import type { StudioState } from './workspace.store';
+/**
+ * Handles `table-preview`: the PDF canvas's live preview of a `table`
+ * extract's options (`document-view`'s `table-preview.use-case.ts`, studio
+ * plan §3.4, issue #94's 5b), off the same cached snapshot `take-snapshot`
+ * already captured — a pure computation over it, so this answers instantly
+ * on every option change, no re-fetch or re-parse.
+ *
+ * @param state - The server state.
+ * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
+ * @returns The matches, or `error` when an option's pattern does not compile.
+ * @throws Error when no workspace is open, or `command.path` has no cached snapshot yet.
+ */
+export declare function handleTablePreview(state: StudioState, command: TablePreviewCommand): TablePreviewView;
+//# sourceMappingURL=table-preview.handler.d.ts.map

package/dist/studio-server/take-snapshot.handler.d.ts

@@ -0,0 +1,16 @@
+import type { SnapshotView, TakeSnapshotCommand } from '../studio-api';
+import type { StudioState } from './workspace.store';
+/**
+ * Handles `take-snapshot`: loads the named input recipe, captures its
+ * snapshot at `command.path` (only `"start"` is captured for now — see
+ * `page-snapshot`'s `take-snapshot.use-case.ts`), and caches it so a later
+ * `verify-selector`/`infer-selector` against the same recipe and path, or
+ * the UI reselecting the same step, does not recapture it.
+ *
+ * @param state - The server state: `folder` must already be set.
+ * @param command - The command.
+ * @returns The rewritten snapshot.
+ * @throws Error when no workspace is open, or the recipe cannot be found or loaded.
+ */
+export declare function handleTakeSnapshot(state: StudioState, command: TakeSnapshotCommand): Promise<SnapshotView>;
+//# sourceMappingURL=take-snapshot.handler.d.ts.map

package/dist/studio-server/verify-selector.handler.d.ts

@@ -0,0 +1,18 @@
+import type { VerifySelectorCommand, VerifySelectorView } from '../studio-api';
+import type { StudioState } from './workspace.store';
+/**
+ * Handles `verify-selector`: runs a candidate through the engine's own
+ * selection (`@opencraw/core`'s `countMatches`) against the cached
+ * snapshot, and, best-effort, against the live page too — issue #91's "flag
+ * a selector that matches the snapshot but not the live page". The live
+ * page is fetched raw (`page-snapshot`'s `fetchStartPage`, the same reach
+ * `take-snapshot` has: only `"start"` today), not through the rewritten
+ * snapshot, so its match count is the site's own, not the studio's.
+ *
+ * @param state - The server state.
+ * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
+ * @returns The match counts.
+ * @throws Error when no workspace is open, the recipe cannot be found, or `command.path` has no cached snapshot yet.
+ */
+export declare function handleVerifySelector(state: StudioState, command: VerifySelectorCommand): Promise<VerifySelectorView>;
+//# sourceMappingURL=verify-selector.handler.d.ts.map

package/dist/studio-server/websocket.client.d.ts

@@ -0,0 +1,22 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+/** One accepted WebSocket connection: text frames only, no compression, no fragmentation. */
+export interface WsConnection {
+    send: (text: string) => void;
+    close: () => void;
+    onMessage: (handler: (text: string) => void) => void;
+    onClose: (handler: () => void) => void;
+}
+/**
+ * Accepts one WebSocket upgrade on the raw socket `node:http` hands an
+ * `upgrade` listener, implementing just enough of RFC 6455 for the studio's
+ * own one-directional event stream: the server sends small JSON text
+ * frames, the client sends none (commands go over `POST /api/command`). No
+ * `ws` dependency: this is deliberately small rather than general-purpose.
+ *
+ * @param request - The upgrade request (its `Sec-WebSocket-Key` header).
+ * @param socket - The raw, already-connected socket.
+ * @returns The connection: `send`, `close`, and where messages and the close go.
+ */
+export declare function acceptWebSocket(request: IncomingMessage, socket: Duplex): WsConnection;
+//# sourceMappingURL=websocket.client.d.ts.map

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

@@ -0,0 +1,36 @@
+import type { BrowserSessionConfig } from '@opencraw/core';
+import type { RecorderSessionHandle } from '../flow-recording';
+import type { SnapshotCache } from '../page-snapshot';
+import type { LastRunCache, SampleRunHandle } from '../sample-run';
+import type { StudioEvent } from '../studio-api';
+import type { TrustedPlugins } from '../trusted-plugins';
+import type { WsConnection } from './websocket.client';
+/** The server's mutable state: the opened folder, the run in progress (if any), the recording in progress (if any, issue #95), the connected event sockets, the per-recipe snapshot cache `take-snapshot`/`verify-selector`/`infer-selector` share, each recipe's last finished sample run (`explain-why`, issue #92), the browser launch settings every web-mode command (`take-snapshot`, `verify-selector`, `run-sample`, `start-recording`) shares, and where the studio's own recorder profile lives. */
+export interface StudioState {
+    folder?: string;
+    activeRun?: SampleRunHandle;
+    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>;
+    sockets: Set<WsConnection>;
+    snapshots: SnapshotCache;
+    lastRuns: LastRunCache;
+    /** Set once at server start (`StudioServerOptions.browser`); every web-mode command reads it from here rather than each accepting its own. */
+    browser?: BrowserSessionConfig;
+    /** Set once at server start (`StudioServerOptions.plugins`): the hooks and plugins the person started Studio with (issue #150). Never set by a request. */
+    plugins?: TrustedPlugins;
+    /** Set once at server start (`StudioServerOptions.recorderProfileDir`), else `defaultRecorderProfileDir()`. */
+    recorderProfileDir: string;
+}
+/** @returns Fresh state for a new server instance: no workspace open, no run, no recording, no sockets, an empty snapshot cache, no last runs, Playwright's own default browser, the default recorder profile directory. */
+export declare function createStudioState(): StudioState;
+/**
+ * Sends one event to every connected client. A socket that errors while
+ * sending (gone away without a clean close yet reaching us) is dropped
+ * rather than left to fail every later broadcast too.
+ *
+ * @param state - The server state holding the connected sockets.
+ * @param event - The event to send.
+ */
+export declare function broadcast(state: StudioState, event: StudioEvent): void;
+//# sourceMappingURL=workspace.store.d.ts.map

package/dist/trusted-plugins/index.d.ts

@@ -0,0 +1,2 @@
+export type { TrustedPlugins } from './trusted-plugins.contract';
+//# sourceMappingURL=index.d.ts.map

package/dist/trusted-plugins/trusted-plugins.contract.d.ts

@@ -0,0 +1,14 @@
+import type { AccessPlugin, CaptchaSolver, HookMap } from '@opencraw/core';
+/**
+ * Code the person who started Studio chose to run (`opencraw studio --hooks <file>`, issue #150): the
+ * hooks, access plugins and captcha solvers a recipe names. It is loaded once at launch, never at a
+ * recipe's or a browser request's say-so, so it has the trust of the command line it came from.
+ */
+export interface TrustedPlugins {
+    /** The file it was loaded from, shown to the person in the UI and in errors. */
+    source: string;
+    hooks: HookMap;
+    accessPlugins?: AccessPlugin[];
+    captchaSolvers?: CaptchaSolver[];
+}
+//# sourceMappingURL=trusted-plugins.contract.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencraw/studio",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "type": "module",
   "main": "./dist/index.esm.js",
   "module": "./dist/index.esm.js",
@@ -24,8 +24,8 @@
     "!**/*.js.map"
   ],
   "dependencies": {
-    "@opencraw/core": "^0.1.27",
-    "@opencraw/probe": "^0.0.10",
+    "@opencraw/core": "^0.1.29",
+    "@opencraw/probe": "^0.0.12",
     "cheerio": "^1.2.0",
     "playwright": "^1.63.0",
     "zod": "^4.6.5",