@opencraw/studio 0.0.8 → 0.0.10

package/dist/src/browser-provisioning/ensure-browser-launch.use-case.d.ts

@@ -0,0 +1,12 @@
+import type { BrowserSessionConfig } from '@opencraw/core';
+/**
+ * Runs a browser-launching function, and — only when it fails with Playwright's own "no browser
+ * downloaded" error, only for a default chromium launch with no explicit binary configured — installs
+ * Chromium once and retries, instead of letting Playwright's raw error reach the studio's caller.
+ *
+ * An explicit `executablePath` or `OPENCRAW_CHROMIUM` means the person (or this repo's own sandbox)
+ * already chose a specific binary; a missing-browser failure there is their setup to fix, not
+ * something to silently install over.
+ */
+export declare function ensureBrowserLaunch<T>(browser: BrowserSessionConfig | undefined, launch: () => Promise<T>, installChromium?: (run?: () => Promise<void>) => Promise<void>): Promise<T>;
+//# sourceMappingURL=ensure-browser-launch.use-case.d.ts.map

package/dist/src/browser-provisioning/index.d.ts

@@ -0,0 +1,2 @@
+export { ensureBrowserLaunch } from './ensure-browser-launch.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/browser-provisioning/install-chromium.use-case.d.ts

@@ -0,0 +1,2 @@
+export declare function installChromiumOnce(run?: () => Promise<void>): Promise<void>;
+//# sourceMappingURL=install-chromium.use-case.d.ts.map

package/dist/src/browser-provisioning/missing-browser.policy.d.ts

@@ -0,0 +1,3 @@
+/** Recognises Playwright's own "no browser downloaded" failure so a launch can be retried after installing one, instead of surfacing Playwright's raw ASCII-art error. */
+export declare function isMissingBrowserError(error: unknown): boolean;
+//# sourceMappingURL=missing-browser.policy.d.ts.map

package/dist/src/document-view/index.d.ts

@@ -6,6 +6,8 @@ export { pdfDocumentView } from './pdf-view.mapper.js';
 export type { PdfCellView, PdfDocumentView, PdfPageView, PdfRowView } from './pdf-view.mapper.js';
 export { previewDeckTable, previewGridTable, previewPdfTable } from './table-preview.use-case.js';
 export type { DeckTablePreviewMatch, DeckTablePreviewOptions, DeckTablePreviewResult, GridTablePreviewMatch, GridTablePreviewOptions, GridTablePreviewResult, TablePreviewMatch, TablePreviewOptions, TablePreviewResult } from './table-preview.use-case.js';
+export { previewRegion } from './region-preview.use-case.js';
+export type { RegionPreviewResult, RegionPreviewMatch } from './region-preview.use-case.js';
 export { workbookDocumentView } from './workbook-view.mapper.js';
 export type { GridCellType, GridCellView, GridMergeView, GridSheetView, WorkbookDocumentView } from './workbook-view.mapper.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/document-view/region-preview.use-case.d.ts

@@ -0,0 +1,30 @@
+import type { DeckDocument, DeckShape, PdfCell, PdfDocument } from '@opencraw/core';
+/** One page (or slide) a `region` extract's box reads text off: the text the step binds, and what it was read from — a PDF's cells or a deck's text boxes (what the canvas highlights). */
+export interface RegionPreviewMatch {
+    /** The page number of a PDF, or the slide number of a deck. */
+    page: number;
+    text: string;
+    cells: PdfCell[];
+    shapes: DeckShape[];
+}
+/** What a `region` extract's selector reads off the already-read document: one match per page or slide with text in the box. */
+export interface RegionPreviewResult {
+    matches: RegionPreviewMatch[];
+    /** The selector does not parse yet (the person is still typing it, or dragging a box into shape), or names a `page=` on a deck (or a `slide=` on a PDF): reported, not thrown. */
+    error?: string;
+}
+/**
+ * Runs a `region` extract's selector against an already-read PDF or deck
+ * (issues #121 and #122: the canvases' click-to-snap selection) — the
+ * engine's own `regionText` / `deckRegionText`, so what the canvas
+ * highlights and the text it shows are exactly what the step will read,
+ * and a pure function of the document, so re-running it on every change
+ * of the box costs nothing. A `slide=` on a PDF (or a `page=` on a deck)
+ * is the same mismatch the step would fail with, reported as `error`.
+ *
+ * @param document - The read PDF or deck (`take-snapshot`'s cached body).
+ * @param selector - The `region` selector, `page=1 x=72..252 y=640..664` or `slide=2 x=60..900 y=30..90`.
+ * @returns The matches, or `error` when the selector does not parse or does not fit the document.
+ */
+export declare function previewRegion(document: PdfDocument | DeckDocument, selector: string): RegionPreviewResult;
+//# sourceMappingURL=region-preview.use-case.d.ts.map

package/dist/src/index.d.ts

@@ -1,11 +1,12 @@
 export { main } from './main.js';
 export { startStudioServer } from './studio-server/index.js';
 export type { StudioServer, StudioServerOptions } from './studio-server/index.js';
-export { openWorkspace, saveRecipe } from './recipe-workspace/index.js';
+export { openWorkspace, saveRecipe, importDocument } from './recipe-workspace/index.js';
+export type { ImportedDocument } from './recipe-workspace/index.js';
 export { runSample, loadRecipePair } from './sample-run/index.js';
 export type { RecipePair, SampleRunCallbacks, SampleRunHandle, SampleRunRecord, SampleRunRejected, SampleRunResult, SampleStepSummary, SampleStoppedBy } from './sample-run/index.js';
 export { fetchStartPage } from './page-snapshot/index.js';
 export type { WhyFacts, WhyStepFact } from './explain-why/index.js';
-export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, missingWhyTargetSchema, rejectedWhyTargetSchema, whyTargetSchema, explainWhyCommandSchema, studioCommandSchema, stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema, recipeIssueSchema, recipeListingSchema, workspaceViewSchema, sampleRunRecordSchema, sampleRunViewSchema, startPageViewSchema, snapshotViewSchema, verifySelectorViewSchema, fieldPickSchema, inferSelectorViewSchema, sentencePartSchema, outlineCardSchema, outlineBracketSchema, outlineNodeSchema, outlineViewSchema, whyViewSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewOptionsSchema, tablePreviewCommandSchema, gridViewCommandSchema, gridPreviewOptionsSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewOptionsSchema, deckPreviewCommandSchema, domTreeNodeViewSchema, pageDataFindingSchema, inspectViewSchema, observedResponseSchema, responsesSeenViewSchema, documentTreeNodeViewSchema, documentTreeViewSchema, pdfCellViewSchema, pdfRowViewSchema, pdfPageViewSchema, pdfDocumentViewSchema, tablePreviewTableSchema, tablePreviewBandSchema, tablePreviewMatchSchema, tablePreviewViewSchema, gridCellViewSchema, gridMergeViewSchema, gridSheetViewSchema, workbookDocumentViewSchema, gridTablePreviewMatchSchema, gridTablePreviewViewSchema, deckShapeViewSchema, deckChartSeriesViewSchema, deckChartViewSchema, deckSlideViewSchema, deckDocumentViewSchema, deckTablePreviewMatchSchema, deckTablePreviewViewSchema, startRecordingCommandSchema, stopRecordingCommandSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, } from './studio-api/index.js';
-export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, MissingWhyTarget, RejectedWhyTarget, WhyTarget, ExplainWhyCommand, InspectPageCommand, ResponsesSeenCommand, DocumentTreeCommand, PdfViewCommand, TablePreviewOptions, TablePreviewCommand, GridViewCommand, GridPreviewOptions, GridPreviewCommand, DeckViewCommand, DeckPreviewOptions, DeckPreviewCommand, StudioCommand, StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent, RecipeIssue, RecipeListing, WorkspaceView, SampleRunView, StartPageView, SnapshotView, VerifySelectorView, FieldPick, InferSelectorView, SentencePart, OutlineCard, OutlineBracket, OutlineNode, OutlineView, WhyView, DomTreeNodeView, PageDataKind, PageDataFindingView, InspectView, ObservedResponseView, ResponsesSeenView, DocumentTreeNodeView, DocumentTreeView, PdfCellView, PdfRowView, PdfPageView, PdfDocumentView, TablePreviewTableView, TablePreviewBandView, TablePreviewMatchView, TablePreviewView, GridCellView, GridMergeView, GridSheetView, WorkbookDocumentView, GridTablePreviewMatchView, GridTablePreviewView, DeckShapeView, DeckChartSeriesView, DeckChartView, DeckSlideView, DeckDocumentView, DeckTablePreviewMatchView, DeckTablePreviewView, StartRecordingCommand, StopRecordingCommand, RecordingCardEvent, RecordingNoteEvent, RecordingStoppedEvent, } from './studio-api/index.js';
+export { sampleBudgetSchema, openWorkspaceCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, missingWhyTargetSchema, rejectedWhyTargetSchema, whyTargetSchema, explainWhyCommandSchema, studioCommandSchema, importDocumentViewSchema, stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema, recipeIssueSchema, recipeListingSchema, workspaceViewSchema, sampleRunRecordSchema, sampleRunViewSchema, startPageViewSchema, snapshotViewSchema, verifySelectorViewSchema, fieldPickSchema, inferSelectorViewSchema, sentencePartSchema, outlineCardSchema, outlineBracketSchema, outlineNodeSchema, outlineViewSchema, whyViewSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewOptionsSchema, tablePreviewCommandSchema, regionPreviewCommandSchema, regionPreviewMatchSchema, regionPreviewViewSchema, gridViewCommandSchema, gridPreviewOptionsSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewOptionsSchema, deckPreviewCommandSchema, domTreeNodeViewSchema, pageDataFindingSchema, inspectViewSchema, observedResponseSchema, responsesSeenViewSchema, documentTreeNodeViewSchema, documentTreeViewSchema, pdfCellViewSchema, pdfRowViewSchema, pdfPageViewSchema, pdfDocumentViewSchema, tablePreviewTableSchema, tablePreviewBandSchema, tablePreviewMatchSchema, tablePreviewViewSchema, gridCellViewSchema, gridMergeViewSchema, gridSheetViewSchema, workbookDocumentViewSchema, gridTablePreviewMatchSchema, gridTablePreviewViewSchema, deckShapeViewSchema, deckChartSeriesViewSchema, deckChartViewSchema, deckSlideViewSchema, deckDocumentViewSchema, deckTablePreviewMatchSchema, deckTablePreviewViewSchema, startRecordingCommandSchema, stopRecordingCommandSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, } from './studio-api/index.js';
+export type { SampleBudget, OpenWorkspaceCommand, ImportDocumentCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, MissingWhyTarget, RejectedWhyTarget, WhyTarget, ExplainWhyCommand, InspectPageCommand, ResponsesSeenCommand, DocumentTreeCommand, PdfViewCommand, TablePreviewOptions, TablePreviewCommand, RegionPreviewCommand, GridViewCommand, GridPreviewOptions, GridPreviewCommand, DeckViewCommand, DeckPreviewOptions, DeckPreviewCommand, StudioCommand, ImportDocumentView, RegionPreviewMatchView, RegionPreviewView, StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent, RecipeIssue, RecipeListing, WorkspaceView, SampleRunView, StartPageView, SnapshotView, VerifySelectorView, FieldPick, InferSelectorView, SentencePart, OutlineCard, OutlineBracket, OutlineNode, OutlineView, WhyView, DomTreeNodeView, PageDataKind, PageDataFindingView, InspectView, ObservedResponseView, ResponsesSeenView, DocumentTreeNodeView, DocumentTreeView, PdfCellView, PdfRowView, PdfPageView, PdfDocumentView, TablePreviewTableView, TablePreviewBandView, TablePreviewMatchView, TablePreviewView, GridCellView, GridMergeView, GridSheetView, WorkbookDocumentView, GridTablePreviewMatchView, GridTablePreviewView, DeckShapeView, DeckChartSeriesView, DeckChartView, DeckSlideView, DeckDocumentView, DeckTablePreviewMatchView, DeckTablePreviewView, StartRecordingCommand, StopRecordingCommand, RecordingCardEvent, RecordingNoteEvent, RecordingStoppedEvent, } from './studio-api/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/recipe-workspace/import-document.use-case.d.ts

@@ -0,0 +1,22 @@
+export interface ImportedDocument {
+    /** The copy's path on disk, inside `folder`. */
+    path: string;
+    /** The copy as a `file:` URL: what the recipe's `start.url` becomes. */
+    url: string;
+}
+/**
+ * Copies a document into a workspace folder, so a recipe can read it with a
+ * `file:` URL the same way a run would read any downloaded file (core's
+ * `HttpClient` handles `file:` itself). The folder is created when missing,
+ * so dropping a file is also a way to start a workspace. A name already in
+ * the folder is never overwritten: the copy gets the next free numbered
+ * name (`report-2.pdf`), and the returned `path`/`url` say which.
+ *
+ * @param folder - The workspace folder; created (recursively) when it does not exist.
+ * @param name - The file's own name, no directories: the copy keeps it, extension included.
+ * @param bytes - The file's content.
+ * @returns Where the copy landed.
+ * @throws Error when `name` is not a plain file name, or the folder already holds too many same-named copies.
+ */
+export declare function importDocument(folder: string, name: string, bytes: Uint8Array): Promise<ImportedDocument>;
+//# sourceMappingURL=import-document.use-case.d.ts.map

package/dist/src/recipe-workspace/index.d.ts

@@ -1,3 +1,5 @@
 export { openWorkspace } from './open-workspace.use-case.js';
 export { saveRecipe } from './save-recipe.use-case.js';
+export { importDocument } from './import-document.use-case.js';
+export type { ImportedDocument } from './import-document.use-case.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -157,6 +157,19 @@ export declare const tablePreviewCommandSchema: z.ZodObject<{
         }>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+/**
+ * The live preview of a `region` extract's selector against a cached PDF
+ * snapshot (`document-view`'s `region-preview.use-case.ts`, issue #121: the
+ * PDF canvas's click-to-snap selection): the text the step would bind and
+ * the cells to highlight, recomputed as the box changes — call
+ * `take-snapshot` first.
+ */
+export declare const regionPreviewCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"region-preview">;
+    recipeId: z.ZodString;
+    path: z.ZodString;
+    selector: z.ZodString;
+}, z.core.$strip>;
 /**
  * The grid canvas's sheets and cells (`document-view`'s `workbook-view.mapper.ts`,
  * studio plan §3.4, issue #94's 5c), off the same cached snapshot
@@ -327,9 +340,30 @@ export declare const startRecordingCommandSchema: z.ZodObject<{
 export declare const stopRecordingCommandSchema: z.ZodObject<{
     type: z.ZodLiteral<"stop-recording">;
 }, z.core.$strip>;
+/**
+ * Copies a document the person dropped on (or opened in) the studio into a
+ * workspace folder, so a recipe can point at it with a `file:` URL (issue
+ * #120). The bytes travel base64-encoded inside the JSON command envelope
+ * every other command uses: a local tool's own files are a few megabytes at
+ * most, not worth a second, multipart endpoint. `folder` is created when it
+ * does not exist yet, so a dropped file can also start a workspace; `name`
+ * is a plain file name (no directories), kept as the copy's name unless one
+ * is already there, in which case a numbered one is used.
+ */
+export declare const importDocumentCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"import-document">;
+    folder: z.ZodString;
+    name: z.ZodString;
+    bytes: z.ZodString;
+}, z.core.$strip>;
 export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"open-workspace">;
     folder: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"import-document">;
+    folder: z.ZodString;
+    name: z.ZodString;
+    bytes: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"run-sample">;
     recipeId: z.ZodString;
@@ -408,6 +442,11 @@ export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             bottom: "bottom";
         }>>;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"region-preview">;
+    recipeId: z.ZodString;
+    path: z.ZodString;
+    selector: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"grid-view">;
     recipeId: z.ZodString;
@@ -459,6 +498,7 @@ export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>], "type">;
 export type SampleBudget = z.infer<typeof sampleBudgetSchema>;
 export type OpenWorkspaceCommand = z.infer<typeof openWorkspaceCommandSchema>;
+export type ImportDocumentCommand = z.infer<typeof importDocumentCommandSchema>;
 export type RunSampleCommand = z.infer<typeof runSampleCommandSchema>;
 export type StopRunCommand = z.infer<typeof stopRunCommandSchema>;
 export type SaveRecipeCommand = z.infer<typeof saveRecipeCommandSchema>;
@@ -473,6 +513,7 @@ export type DocumentTreeCommand = z.infer<typeof documentTreeCommandSchema>;
 export type PdfViewCommand = z.infer<typeof pdfViewCommandSchema>;
 export type TablePreviewOptions = z.infer<typeof tablePreviewOptionsSchema>;
 export type TablePreviewCommand = z.infer<typeof tablePreviewCommandSchema>;
+export type RegionPreviewCommand = z.infer<typeof regionPreviewCommandSchema>;
 export type GridViewCommand = z.infer<typeof gridViewCommandSchema>;
 export type GridPreviewOptions = z.infer<typeof gridPreviewOptionsSchema>;
 export type GridPreviewCommand = z.infer<typeof gridPreviewCommandSchema>;

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

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+/** `import-document`'s answer: where the copy landed, and the `file:` URL a recipe's `start.url` points at it with. */
+export declare const importDocumentViewSchema: z.ZodObject<{
+    path: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strip>;
+export type ImportDocumentView = z.infer<typeof importDocumentViewSchema>;
+//# sourceMappingURL=import-document-view.contract.d.ts.map

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

@@ -1,5 +1,5 @@
-export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, missingWhyTargetSchema, rejectedWhyTargetSchema, whyTargetSchema, explainWhyCommandSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewOptionsSchema, tablePreviewCommandSchema, gridViewCommandSchema, gridPreviewOptionsSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewOptionsSchema, deckPreviewCommandSchema, startRecordingCommandSchema, stopRecordingCommandSchema, studioCommandSchema } from './command.contract.js';
-export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, MissingWhyTarget, RejectedWhyTarget, WhyTarget, ExplainWhyCommand, InspectPageCommand, ResponsesSeenCommand, DocumentTreeCommand, PdfViewCommand, TablePreviewOptions, TablePreviewCommand, GridViewCommand, GridPreviewOptions, GridPreviewCommand, DeckViewCommand, DeckPreviewOptions, DeckPreviewCommand, StartRecordingCommand, StopRecordingCommand, StudioCommand } from './command.contract.js';
+export { sampleBudgetSchema, openWorkspaceCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, missingWhyTargetSchema, rejectedWhyTargetSchema, whyTargetSchema, explainWhyCommandSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewOptionsSchema, tablePreviewCommandSchema, regionPreviewCommandSchema, gridViewCommandSchema, gridPreviewOptionsSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewOptionsSchema, deckPreviewCommandSchema, startRecordingCommandSchema, stopRecordingCommandSchema, studioCommandSchema } from './command.contract.js';
+export type { SampleBudget, OpenWorkspaceCommand, ImportDocumentCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, MissingWhyTarget, RejectedWhyTarget, WhyTarget, ExplainWhyCommand, InspectPageCommand, ResponsesSeenCommand, DocumentTreeCommand, PdfViewCommand, TablePreviewOptions, TablePreviewCommand, RegionPreviewCommand, GridViewCommand, GridPreviewOptions, GridPreviewCommand, DeckViewCommand, DeckPreviewOptions, DeckPreviewCommand, StartRecordingCommand, StopRecordingCommand, 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';
@@ -10,6 +10,8 @@ export { stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSch
 export type { StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, RecordingCardEvent, RecordingNoteEvent, RecordingStoppedEvent, StudioEvent } from './event.contract.js';
 export { recipeIssueSchema, recipeListingSchema, workspaceViewSchema } from './workspace-view.contract.js';
 export type { RecipeIssue, RecipeListing, WorkspaceView } from './workspace-view.contract.js';
+export { importDocumentViewSchema } from './import-document-view.contract.js';
+export type { ImportDocumentView } from './import-document-view.contract.js';
 export { sampleRunRecordSchema, sampleRunViewSchema } from './sample-run-view.contract.js';
 export type { SampleRunRecord, SampleRunView } from './sample-run-view.contract.js';
 export { startPageViewSchema } from './start-page-view.contract.js';
@@ -28,6 +30,8 @@ export { pdfCellViewSchema, pdfRowViewSchema, pdfPageViewSchema, pdfDocumentView
 export type { PdfCellView, PdfRowView, PdfPageView, PdfDocumentView } from './pdf-view.contract.js';
 export { tablePreviewTableSchema, tablePreviewBandSchema, tablePreviewMatchSchema, tablePreviewViewSchema } from './table-preview-view.contract.js';
 export type { TablePreviewTableView, TablePreviewBandView, TablePreviewMatchView, TablePreviewView } from './table-preview-view.contract.js';
+export { regionPreviewMatchSchema, regionPreviewViewSchema } from './region-preview-view.contract.js';
+export type { RegionPreviewMatchView, RegionPreviewView } from './region-preview-view.contract.js';
 export { gridCellViewSchema, gridMergeViewSchema, gridSheetViewSchema, workbookDocumentViewSchema } from './grid-view.contract.js';
 export type { GridCellView, GridMergeView, GridSheetView, WorkbookDocumentView } from './grid-view.contract.js';
 export { gridTablePreviewMatchSchema, gridTablePreviewViewSchema } from './grid-preview-view.contract.js';

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

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+/** One page of a PDF, or one slide of a deck, a `region` extract's box reads text off — mirrors `document-view/region-preview.use-case.ts`'s `RegionPreviewMatch`: `cells` for a PDF, `shapes` for a deck, the other empty. */
+export declare const regionPreviewMatchSchema: z.ZodObject<{
+    page: z.ZodNumber;
+    text: z.ZodString;
+    cells: z.ZodArray<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        text: z.ZodString;
+    }, z.core.$strip>>;
+    shapes: z.ZodArray<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        text: z.ZodString;
+        placeholder: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * What `region-preview` answers with (issues #121 and #122: the PDF and
+ * deck canvases' click-to-snap selection): the engine's own matches for
+ * the selector — the text the step would bind, and the cells or text boxes
+ * to highlight — or `error` when the selector does not parse yet, or names
+ * the other document's keyword, reported rather than thrown.
+ */
+export declare const regionPreviewViewSchema: z.ZodObject<{
+    matches: z.ZodArray<z.ZodObject<{
+        page: z.ZodNumber;
+        text: z.ZodString;
+        cells: z.ZodArray<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            text: z.ZodString;
+        }, z.core.$strip>>;
+        shapes: z.ZodArray<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            text: z.ZodString;
+            placeholder: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RegionPreviewMatchView = z.infer<typeof regionPreviewMatchSchema>;
+export type RegionPreviewView = z.infer<typeof regionPreviewViewSchema>;
+//# sourceMappingURL=region-preview-view.contract.d.ts.map

package/dist/src/studio-server/import-document.handler.d.ts

@@ -0,0 +1,14 @@
+import type { ImportDocumentCommand, ImportDocumentView } from '../studio-api/index.js';
+/**
+ * Handles `import-document` (issue #120): decodes the base64 bytes and copies
+ * the file into the folder (see `recipe-workspace/import-document.use-case.ts`
+ * for the folder creation and the no-overwrite numbering). Nothing is
+ * broadcast: the copy is not a recipe, the workspace listing does not change
+ * until the UI saves the recipe pair that points at it, which `save-recipe`
+ * announces as usual.
+ *
+ * @param command - The folder, the file's name and its base64 content.
+ * @returns Where the copy landed and its `file:` URL.
+ */
+export declare function handleImportDocument(command: ImportDocumentCommand): Promise<ImportDocumentView>;
+//# sourceMappingURL=import-document.handler.d.ts.map

package/dist/src/studio-server/open-workspace.handler.d.ts

@@ -3,7 +3,14 @@ import type { StudioState } from './workspace.store.js';
 /**
  * Handles `open-workspace`: reads the folder, remembers it as the server's
  * current workspace (every later command that names a recipe resolves it
- * against this folder), and tells every connected client the workspace changed.
+ * against this folder), and, when that is a different folder than before,
+ * tells every connected client the workspace changed.
+ *
+ * Only on an actual switch: the UI answers `workspace-changed` with another
+ * `open-workspace` of the same folder (its workspace query re-fetches), so a
+ * broadcast on every open would answer that re-fetch with another broadcast,
+ * for ever — and each round cancels the fetch in flight, so a recipe saved
+ * meanwhile never showed up in the listing (found by issue #120's drop flow).
  *
  * @param state - The server state to update.
  * @param command - The command.

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

@@ -0,0 +1,17 @@
+import type { RegionPreviewCommand, RegionPreviewView } from '../studio-api/index.js';
+import type { StudioState } from './workspace.store.js';
+/**
+ * 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