@opencraw/studio 0.0.4 → 0.0.6

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

@@ -1,5 +1,11 @@
-export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, studioCommandSchema } from './command.contract.js';
-export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, StudioCommand } from './command.contract.js';
+export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, studioCommandSchema } from './command.contract.js';
+export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, 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 } from './infer-selector-view.contract.js';
+export type { FieldPick, InferSelectorView } from './infer-selector-view.contract.js';
 export { stoppedBySchema, traceLineEventSchema, recordEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema } from './event.contract.js';
 export type { StoppedBy, TraceLineEvent, RecordEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent } from './event.contract.js';
 export { recipeIssueSchema, recipeListingSchema, workspaceViewSchema } from './workspace-view.contract.js';
@@ -8,4 +14,6 @@ export { sampleRunRecordSchema, sampleRunViewSchema } from './sample-run-view.co
 export type { SampleRunRecord, SampleRunView } from './sample-run-view.contract.js';
 export { startPageViewSchema } from './start-page-view.contract.js';
 export type { StartPageView } from './start-page-view.contract.js';
+export { sentencePartSchema, outlineCardSchema, outlineBracketSchema, outlineNodeSchema, outlineViewSchema } from './outline-view.contract.js';
+export type { SentencePart, OutlineCard, OutlineBracket, OutlineNode, OutlineView } from './outline-view.contract.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+/** One clicked node's field: the best selector found for it, verified against the snapshot. */
+export declare const fieldPickSchema: z.ZodObject<{
+    selector: z.ZodString;
+    tier: z.ZodEnum<{
+        id: "id";
+        "data-attr": "data-attr";
+        class: "class";
+        structure: "structure";
+        position: "position";
+    }>;
+    take: z.ZodString;
+    matches: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * What `infer-selector` answers with (issue #91, studio plan §3.2):
+ * `"field"` for one clicked node — a `Read` card's shape; `"list"` for two
+ * similar nodes — the safe `extract`(items)+`forEach`(field) shape, item and
+ * field each verified separately; `"unsupported"` when the two picks are not
+ * a coherent list (different branches, the same node twice, or shadow DOM),
+ * with a message the card can show as-is.
+ */
+export declare const inferSelectorViewSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"field">;
+    field: z.ZodObject<{
+        selector: z.ZodString;
+        tier: z.ZodEnum<{
+            id: "id";
+            "data-attr": "data-attr";
+            class: "class";
+            structure: "structure";
+            position: "position";
+        }>;
+        take: z.ZodString;
+        matches: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"list">;
+    item: z.ZodObject<{
+        selector: z.ZodString;
+        tier: z.ZodEnum<{
+            id: "id";
+            "data-attr": "data-attr";
+            class: "class";
+            structure: "structure";
+            position: "position";
+        }>;
+        matches: z.ZodNumber;
+    }, z.core.$strip>;
+    field: z.ZodObject<{
+        selector: z.ZodString;
+        tier: z.ZodEnum<{
+            id: "id";
+            "data-attr": "data-attr";
+            class: "class";
+            structure: "structure";
+            position: "position";
+        }>;
+        take: z.ZodString;
+        matches: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"unsupported">;
+    reason: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type FieldPick = z.infer<typeof fieldPickSchema>;
+export type InferSelectorView = z.infer<typeof inferSelectorViewSchema>;
+//# sourceMappingURL=infer-selector-view.contract.d.ts.map

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

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+/** One piece of a card's sentence: plain wording, a bound id (a "pill"), or a literal shown as code. Mirrors `scope-outline/outline.model.ts`'s `SentencePart`: the wire shape for the UI. */
+export interface SentencePart {
+    kind: 'word' | 'pill' | 'code';
+    text: string;
+}
+interface OutlineNodeBase {
+    path: string;
+    stepType: string;
+    sentence: SentencePart[];
+    step: Record<string, unknown>;
+}
+/** A leaf step, read as a sentence (or, when `custom`, not read as one: the UI shows `step`'s raw JSON instead). */
+export interface OutlineCard extends OutlineNodeBase {
+    kind: 'card';
+    custom: boolean;
+}
+/** A container step (`forEach`, `paginate`, `if`), its body nested one level in. */
+export interface OutlineBracket extends OutlineNodeBase {
+    kind: 'bracket';
+    stepType: 'forEach' | 'paginate' | 'if';
+    children: OutlineNode[];
+    elseChildren?: OutlineNode[];
+}
+export type OutlineNode = OutlineCard | OutlineBracket;
+/** The outline the UI renders and edits: the recipe's other keys untouched, plus its steps as a tree. */
+export interface OutlineView {
+    recipe: Record<string, unknown>;
+    steps: OutlineNode[];
+}
+export declare const sentencePartSchema: z.ZodType<SentencePart>;
+export declare const outlineCardSchema: z.ZodType<OutlineCard>;
+export declare const outlineBracketSchema: z.ZodType<OutlineBracket>;
+export declare const outlineNodeSchema: z.ZodType<OutlineNode>;
+export declare const outlineViewSchema: z.ZodType<OutlineView>;
+export {};
+//# sourceMappingURL=outline-view.contract.d.ts.map

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

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+/** What `take-snapshot` answers with: the rewritten document ready for the content pane's sandboxed iframe (studio plan §3.1, issue #91). */
+export declare const snapshotViewSchema: z.ZodObject<{
+    html: z.ZodString;
+    nodeCount: z.ZodNumber;
+    baseUrl: z.ZodString;
+}, z.core.$strip>;
+export type SnapshotView = z.infer<typeof snapshotViewSchema>;
+//# sourceMappingURL=snapshot-view.contract.d.ts.map

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

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+/**
+ * What `verify-selector` answers with: the match count against the snapshot
+ * and, when the live page could be reached, against it too (issue #91's
+ * "flag a selector that matches the snapshot but not the live page").
+ * `liveChecked` is `false` when the live page could not be fetched (offline,
+ * blocked by `allowedHosts`, a transient error) — the card shows the
+ * snapshot count alone rather than a misleading "0 on the live page".
+ */
+export declare const verifySelectorViewSchema: z.ZodObject<{
+    selector: z.ZodString;
+    snapshotMatches: z.ZodNumber;
+    liveChecked: z.ZodBoolean;
+    liveMatches: z.ZodOptional<z.ZodNumber>;
+    liveError: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type VerifySelectorView = z.infer<typeof verifySelectorViewSchema>;
+//# sourceMappingURL=verify-selector-view.contract.d.ts.map

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

@@ -12,9 +12,9 @@ export declare const recipeIssueSchema: z.ZodObject<{
 export declare const recipeListingSchema: z.ZodObject<{
     file: z.ZodString;
     kind: z.ZodEnum<{
-        unknown: "unknown";
         input: "input";
         output: "output";
+        unknown: "unknown";
     }>;
     id: z.ZodOptional<z.ZodString>;
     issues: z.ZodArray<z.ZodObject<{
@@ -26,6 +26,7 @@ export declare const recipeListingSchema: z.ZodObject<{
         }>;
     }, z.core.$strip>>;
     text: z.ZodString;
+    outline: z.ZodOptional<z.ZodType<import("./outline-view.contract").OutlineView, unknown, z.core.$ZodTypeInternals<import("./outline-view.contract").OutlineView, unknown>>>;
 }, z.core.$strip>;
 /** What `open-workspace` answers with: every recipe file directly inside the folder. */
 export declare const workspaceViewSchema: z.ZodObject<{
@@ -33,9 +34,9 @@ export declare const workspaceViewSchema: z.ZodObject<{
     recipes: z.ZodArray<z.ZodObject<{
         file: z.ZodString;
         kind: z.ZodEnum<{
-            unknown: "unknown";
             input: "input";
             output: "output";
+            unknown: "unknown";
         }>;
         id: z.ZodOptional<z.ZodString>;
         issues: z.ZodArray<z.ZodObject<{
@@ -47,6 +48,7 @@ export declare const workspaceViewSchema: z.ZodObject<{
             }>;
         }, z.core.$strip>>;
         text: z.ZodString;
+        outline: z.ZodOptional<z.ZodType<import("./outline-view.contract").OutlineView, unknown, z.core.$ZodTypeInternals<import("./outline-view.contract").OutlineView, unknown>>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type RecipeIssue = z.infer<typeof recipeIssueSchema>;

package/dist/src/studio-server/infer-selector.handler.d.ts

@@ -0,0 +1,18 @@
+import type { InferSelectorCommand, InferSelectorView } from '../studio-api/index.js';
+import type { StudioState } from './workspace.store.js';
+/**
+ * Handles `infer-selector`: turns one or two picked nodes (their
+ * `data-oc-node` ids, off the cached snapshot) into a verified selector —
+ * one id for a `Read` card's field, two for the safe item+field list shape
+ * `selector-inference`'s `inferList` builds by construction (issue #91,
+ * studio plan §3.2). All the actual candidate/ranking/list-inference work
+ * is `selector-inference`'s (pure); this handler only locates the clicked
+ * nodes in the cached document and calls into it.
+ *
+ * @param state - The server state.
+ * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
+ * @returns A field pick, a list pick, or `"unsupported"` with why.
+ * @throws Error when no workspace is open, or `command.path` has no cached snapshot yet.
+ */
+export declare function handleInferSelector(state: StudioState, command: InferSelectorCommand): InferSelectorView;
+//# sourceMappingURL=infer-selector.handler.d.ts.map

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

@@ -0,0 +1,18 @@
+import type { SaveOutlineCommand } from '../studio-api/index.js';
+import type { StudioState } from './workspace.store.js';
+/**
+ * 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/src/studio-server/studio-http.use-case.d.ts

@@ -1,3 +1,4 @@
+import type { BrowserSessionConfig } from '@opencraw/core';
 export interface StudioServerOptions {
     /** Where the built UI lives; default: `dist/ui` next to the running server code. */
     uiRoot?: string;
@@ -11,6 +12,8 @@ export interface StudioServerOptions {
      * 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`); 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. */
+    browser?: BrowserSessionConfig;
 }
 /** 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/take-snapshot.handler.d.ts

@@ -0,0 +1,16 @@
+import type { SnapshotView, TakeSnapshotCommand } from '../studio-api/index.js';
+import type { StudioState } from './workspace.store.js';
+/**
+ * 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/src/studio-server/verify-selector.handler.d.ts

@@ -0,0 +1,18 @@
+import type { VerifySelectorCommand, VerifySelectorView } from '../studio-api/index.js';
+import type { StudioState } from './workspace.store.js';
+/**
+ * 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/src/studio-server/workspace.store.d.ts

@@ -1,13 +1,18 @@
+import type { BrowserSessionConfig } from '@opencraw/core';
+import type { SnapshotCache } from '../page-snapshot/index.js';
 import type { SampleRunHandle } from '../sample-run/index.js';
 import type { StudioEvent } from '../studio-api/index.js';
 import type { WsConnection } from './websocket.client.js';
-/** The server's mutable state: the opened folder, the run in progress (if any), and the connected event sockets. */
+/** The server's mutable state: the opened folder, the run in progress (if any), the connected event sockets, the per-recipe snapshot cache `take-snapshot`/`verify-selector`/`infer-selector` share, and the browser launch settings every web-mode command (`take-snapshot`, `verify-selector`, `run-sample`) shares. */
 export interface StudioState {
     folder?: string;
     activeRun?: SampleRunHandle;
     sockets: Set<WsConnection>;
+    snapshots: SnapshotCache;
+    /** Set once at server start (`StudioServerOptions.browser`); every web-mode command reads it from here rather than each accepting its own. */
+    browser?: BrowserSessionConfig;
 }
-/** @returns Fresh state for a new server instance: no workspace open, no run, no sockets. */
+/** @returns Fresh state for a new server instance: no workspace open, no run, no sockets, an empty snapshot cache, Playwright's own default browser. */
 export declare function createStudioState(): StudioState;
 /**
  * Sends one event to every connected client. A socket that errors while