@opencraw/studio 0.0.27 → 0.0.29

package/dist/src/folder-dialog/choose-folder.client.d.ts

@@ -0,0 +1,25 @@
+import type { DialogCommand } from './folder-dialog.algorithm.js';
+/** What a dialog program did: its output, or how it ended. `missing` means the program is not installed. */
+export type DialogRun = {
+    output: string;
+} | {
+    cancelled: true;
+} | {
+    missing: true;
+};
+/** Runs one dialog program and waits for the person to answer; real by default, replaced in tests. */
+export type RunDialog = (command: DialogCommand) => Promise<DialogRun>;
+/** Runs the program with Node's own `execFile`: no shell, so a path or title is never parsed as a command. */
+export declare const runDialogProgram: RunDialog;
+/**
+ * Opens the operating system's own folder dialog on the machine the server
+ * runs on, which is where the recipe folder is: a browser tab cannot do it,
+ * the server can. Waits until the person picks a folder or closes the dialog.
+ *
+ * @param platform - `process.platform`; passed in so a test names the platform it means.
+ * @param run - How a dialog program is run.
+ * @returns The folder picked, or `undefined` when the dialog was closed without a choice.
+ * @throws Error when the platform has no dialog program installed (a server with no display, a container).
+ */
+export declare function chooseFolderWithDialog(platform?: NodeJS.Platform, run?: RunDialog): Promise<string | undefined>;
+//# sourceMappingURL=choose-folder.client.d.ts.map

package/dist/src/folder-dialog/folder-dialog.algorithm.d.ts

@@ -0,0 +1,25 @@
+/** One way to open a folder dialog: a program and its arguments. */
+export interface DialogCommand {
+    file: string;
+    args: string[];
+}
+/**
+ * The programs that can open a folder dialog on a platform, in the order to
+ * try them: the first one installed is used. Windows and macOS have one each
+ * in every install; Linux has whichever of `zenity` (GNOME and most others)
+ * and `kdialog` (KDE) the desktop ships.
+ *
+ * @param platform - `process.platform`.
+ * @returns The candidates; empty for a platform with no known dialog.
+ */
+export declare function folderDialogCommands(platform: NodeJS.Platform): DialogCommand[];
+/**
+ * The folder a dialog printed: its output without the line break and the
+ * trailing separator (`osascript` ends a folder with `/`), a root kept as it
+ * is. Nothing printed means the person cancelled.
+ *
+ * @param output - What the dialog program wrote to its standard output.
+ * @returns The folder path, or `undefined` for a cancelled dialog.
+ */
+export declare function folderFromDialogOutput(output: string): string | undefined;
+//# sourceMappingURL=folder-dialog.algorithm.d.ts.map

package/dist/src/folder-dialog/index.d.ts

@@ -0,0 +1,2 @@
+export { chooseFolderWithDialog } from './choose-folder.client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts

@@ -9,6 +9,6 @@ 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, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, missingWhyTargetSchema, rejectedWhyTargetSchema, whyTargetSchema, explainWhyCommandSchema, studioCommandSchema, importDocumentViewSchema, stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema, loadedHooksSchema, 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, LoadedHooks, 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, chooseFolderCommandSchema, openPathCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, missingWhyTargetSchema, rejectedWhyTargetSchema, whyTargetSchema, explainWhyCommandSchema, studioCommandSchema, chooseFolderViewSchema, openPathViewSchema, importDocumentViewSchema, stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema, loadedHooksSchema, 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, ChooseFolderCommand, OpenPathCommand, 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, ChooseFolderView, OpenPathView, ImportDocumentView, RegionPreviewMatchView, RegionPreviewView, StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent, LoadedHooks, 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/main.d.ts

@@ -3,6 +3,8 @@ import type { TrustedPlugins } from './trusted-plugins/index.js';
 export interface StudioMainOptions {
     /** Hooks and plugins loaded from a file the person named at launch (`opencraw studio --hooks <file>`, issue #150). `main` never loads code itself. */
     plugins?: TrustedPlugins;
+    /** A folder, recipe file or document the printed link opens straight away (`opencraw studio --open <path>`, issue #235); resolved against the current directory. */
+    open?: string;
 }
 /**
  * Runs `opencraw-studio`: starts the server, opens `folder` (if given) as

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

@@ -1,5 +1,6 @@
 export { openWorkspace } from './open-workspace.use-case.js';
 export { saveRecipe } from './save-recipe.use-case.js';
+export { openPath } from './open-path.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/recipe-workspace/open-path.use-case.d.ts

@@ -0,0 +1,18 @@
+import type { OpenPathView } from '../studio-api/index.js';
+/**
+ * Says what a path is, for a link or an IDE menu entry that only knows a
+ * path: a folder opens as the workspace; a `.json` file whose `kind` is
+ * `input` or `output` is a recipe, opened through its own folder; any other
+ * file is a document to start a recipe from.
+ *
+ * A document is read in place when it is already inside the workspace folder
+ * (`workspace`, else the file's own folder), and copied into the folder
+ * otherwise, with the same no-overwrite numbering `import-document` uses.
+ *
+ * @param path - An absolute path to a folder or a file.
+ * @param workspace - The folder a document should belong to, when the caller has one (an IDE's workspace folder).
+ * @returns What it is and where to open it.
+ * @throws Error when the path is relative or does not exist.
+ */
+export declare function openPath(path: string, workspace?: string): Promise<OpenPathView>;
+//# sourceMappingURL=open-path.use-case.d.ts.map

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

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+/** `choose-folder`'s answer: the folder the person picked in the operating system's dialog; absent when the dialog was closed without a choice. */
+export declare const chooseFolderViewSchema: z.ZodObject<{
+    folder: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ChooseFolderView = z.infer<typeof chooseFolderViewSchema>;
+//# sourceMappingURL=choose-folder-view.contract.d.ts.map

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

@@ -10,6 +10,16 @@ export declare const openWorkspaceCommandSchema: z.ZodObject<{
     type: z.ZodLiteral<"open-workspace">;
     folder: z.ZodString;
 }, z.core.$strip>;
+/** Says what a path is (folder, recipe or document) and where to open it: how a link or an IDE entry opens a path (issue #235). `workspace` is the folder a document should belong to, when the caller has one. */
+export declare const openPathCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"open-path">;
+    path: z.ZodString;
+    workspace: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Opens the operating system's folder dialog on the server's machine: the answer is the folder picked, if any. */
+export declare const chooseFolderCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"choose-folder">;
+}, z.core.$strip>;
 /** Runs one input recipe under a budget, streaming `trace-line` and `record` events, ending in `run-finished`. */
 export declare const runSampleCommandSchema: z.ZodObject<{
     type: z.ZodLiteral<"run-sample">;
@@ -360,6 +370,12 @@ export declare const importDocumentCommandSchema: z.ZodObject<{
 export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"open-workspace">;
     folder: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"choose-folder">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"open-path">;
+    path: z.ZodString;
+    workspace: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"import-document">;
     folder: z.ZodString;
@@ -500,6 +516,8 @@ 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 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 StopRunCommand = z.infer<typeof stopRunCommandSchema>;

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

@@ -56,6 +56,10 @@ export declare const deckSlideViewSchema: z.ZodObject<{
             bottom: z.ZodNumber;
             right: z.ZodNumber;
         }, z.core.$strip>>;
+        columnWidths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        rowHeights: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        defaultColumnWidth: z.ZodOptional<z.ZodNumber>;
+        defaultRowHeight: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     charts: z.ZodArray<z.ZodObject<{
         type: z.ZodString;
@@ -106,6 +110,10 @@ export declare const deckDocumentViewSchema: z.ZodObject<{
                 bottom: z.ZodNumber;
                 right: z.ZodNumber;
             }, z.core.$strip>>;
+            columnWidths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+            rowHeights: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+            defaultColumnWidth: z.ZodOptional<z.ZodNumber>;
+            defaultRowHeight: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
         charts: z.ZodArray<z.ZodObject<{
             type: z.ZodString;

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

@@ -38,6 +38,10 @@ export declare const gridSheetViewSchema: z.ZodObject<{
         bottom: z.ZodNumber;
         right: z.ZodNumber;
     }, z.core.$strip>>;
+    columnWidths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    rowHeights: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    defaultColumnWidth: z.ZodOptional<z.ZodNumber>;
+    defaultRowHeight: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 /** What `grid-view` answers with (studio plan §3.4, issue #94's 5c): every sheet's cells, typed, with hidden sheets/rows marked and merged ranges resolved, for the grid canvas to draw. */
 export declare const workbookDocumentViewSchema: z.ZodObject<{
@@ -62,6 +66,10 @@ export declare const workbookDocumentViewSchema: z.ZodObject<{
             bottom: z.ZodNumber;
             right: z.ZodNumber;
         }, z.core.$strip>>;
+        columnWidths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        rowHeights: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        defaultColumnWidth: z.ZodOptional<z.ZodNumber>;
+        defaultRowHeight: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     csv: z.ZodOptional<z.ZodObject<{
         encoding: z.ZodString;

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

@@ -1,5 +1,5 @@
-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 { sampleBudgetSchema, openWorkspaceCommandSchema, chooseFolderCommandSchema, openPathCommandSchema, 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, ChooseFolderCommand, OpenPathCommand, 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,10 @@ export { stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSch
 export type { StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, RecordingCardEvent, RecordingNoteEvent, RecordingStoppedEvent, 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';
+export type { ChooseFolderView } from './choose-folder-view.contract.js';
+export { openPathViewSchema } from './open-path-view.contract.js';
+export type { OpenPathView } from './open-path-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';

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

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+/**
+ * `open-path`'s answer: what the path turned out to be, and the folder to
+ * open as the workspace for it. A `recipe` names the input recipe to select
+ * when there is one; a `document` is where the file is read from (in place
+ * when it is already inside the folder, else the copy made there) and its
+ * `file:` URL, ready for a recipe's `start.url`.
+ */
+export declare const openPathViewSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"folder">;
+    folder: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"recipe">;
+    folder: z.ZodString;
+    recipeId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"document">;
+    folder: z.ZodString;
+    path: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type OpenPathView = z.infer<typeof openPathViewSchema>;
+//# sourceMappingURL=open-path-view.contract.d.ts.map

package/dist/src/studio-server/choose-folder.handler.d.ts

@@ -0,0 +1,13 @@
+import type { ChooseFolderView } from '../studio-api/index.js';
+import type { StudioState } from './workspace.store.js';
+/**
+ * Handles `choose-folder`: opens the folder dialog of the machine the server
+ * runs on and answers the folder picked. Only answers: the UI follows with
+ * `open-workspace`, the same as when the folder is typed. A dialog still
+ * open is not opened a second time; the second request waits for the first.
+ *
+ * @param state - The server state holding the dialog to use.
+ * @returns The folder, or none when the dialog was closed.
+ */
+export declare function handleChooseFolder(state: StudioState): Promise<ChooseFolderView>;
+//# sourceMappingURL=choose-folder.handler.d.ts.map

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

@@ -0,0 +1,11 @@
+import type { OpenPathCommand, OpenPathView } from '../studio-api/index.js';
+/**
+ * Handles `open-path`: says what the path is (folder, recipe or document) and
+ * where to open it. Opens nothing itself: the UI follows with `open-workspace`
+ * on the answer's folder, the same as when the folder is typed.
+ *
+ * @param command - The path, and the workspace it should belong to if the caller has one.
+ * @returns What the path is.
+ */
+export declare function handleOpenPath(command: OpenPathCommand): Promise<OpenPathView>;
+//# sourceMappingURL=open-path.handler.d.ts.map

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

@@ -17,6 +17,8 @@ export interface StudioServerOptions {
     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;
+    /** How `choose-folder` asks the person for a folder; default: the operating system's own folder dialog (`folder-dialog`), opened on the machine the server runs on. A host that has a dialog of its own passes it here. */
+    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;
 }
@@ -24,6 +26,11 @@ export interface StudioServerOptions {
 export interface StudioServer {
     url: string;
     token: string;
+    /** A link that opens Studio on `open` (a folder, a recipe or a document; see `open-path`), with `workspace` as the folder a document belongs to. Without a target it is `url`. */
+    link: (target?: {
+        open?: string;
+        workspace?: string;
+    }) => string;
     close: () => Promise<void>;
 }
 /**

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

@@ -19,6 +19,10 @@ export interface StudioState {
     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.chooseFolder`): how `choose-folder` asks the person for a folder. */
+    chooseFolder?: () => Promise<string | undefined>;
+    /** The dialog currently open, so a second `choose-folder` waits for it instead of opening another. */
+    openDialog?: Promise<string | undefined>;
     /** Set once at server start (`StudioServerOptions.recorderProfileDir`), else `defaultRecorderProfileDir()`. */
     recorderProfileDir: string;
 }

package/dist/studio-api/choose-folder-view.contract.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+/** `choose-folder`'s answer: the folder the person picked in the operating system's dialog; absent when the dialog was closed without a choice. */
+export declare const chooseFolderViewSchema: z.ZodObject<{
+    folder: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ChooseFolderView = z.infer<typeof chooseFolderViewSchema>;
+//# sourceMappingURL=choose-folder-view.contract.d.ts.map

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

@@ -10,6 +10,16 @@ export declare const openWorkspaceCommandSchema: z.ZodObject<{
     type: z.ZodLiteral<"open-workspace">;
     folder: z.ZodString;
 }, z.core.$strip>;
+/** Says what a path is (folder, recipe or document) and where to open it: how a link or an IDE entry opens a path (issue #235). `workspace` is the folder a document should belong to, when the caller has one. */
+export declare const openPathCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"open-path">;
+    path: z.ZodString;
+    workspace: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Opens the operating system's folder dialog on the server's machine: the answer is the folder picked, if any. */
+export declare const chooseFolderCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"choose-folder">;
+}, z.core.$strip>;
 /** Runs one input recipe under a budget, streaming `trace-line` and `record` events, ending in `run-finished`. */
 export declare const runSampleCommandSchema: z.ZodObject<{
     type: z.ZodLiteral<"run-sample">;
@@ -360,6 +370,12 @@ export declare const importDocumentCommandSchema: z.ZodObject<{
 export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"open-workspace">;
     folder: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"choose-folder">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"open-path">;
+    path: z.ZodString;
+    workspace: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"import-document">;
     folder: z.ZodString;
@@ -500,6 +516,8 @@ 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 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 StopRunCommand = z.infer<typeof stopRunCommandSchema>;

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

@@ -56,6 +56,10 @@ export declare const deckSlideViewSchema: z.ZodObject<{
             bottom: z.ZodNumber;
             right: z.ZodNumber;
         }, z.core.$strip>>;
+        columnWidths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        rowHeights: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        defaultColumnWidth: z.ZodOptional<z.ZodNumber>;
+        defaultRowHeight: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     charts: z.ZodArray<z.ZodObject<{
         type: z.ZodString;
@@ -106,6 +110,10 @@ export declare const deckDocumentViewSchema: z.ZodObject<{
                 bottom: z.ZodNumber;
                 right: z.ZodNumber;
             }, z.core.$strip>>;
+            columnWidths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+            rowHeights: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+            defaultColumnWidth: z.ZodOptional<z.ZodNumber>;
+            defaultRowHeight: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
         charts: z.ZodArray<z.ZodObject<{
             type: z.ZodString;

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

@@ -38,6 +38,10 @@ export declare const gridSheetViewSchema: z.ZodObject<{
         bottom: z.ZodNumber;
         right: z.ZodNumber;
     }, z.core.$strip>>;
+    columnWidths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    rowHeights: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    defaultColumnWidth: z.ZodOptional<z.ZodNumber>;
+    defaultRowHeight: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 /** What `grid-view` answers with (studio plan §3.4, issue #94's 5c): every sheet's cells, typed, with hidden sheets/rows marked and merged ranges resolved, for the grid canvas to draw. */
 export declare const workbookDocumentViewSchema: z.ZodObject<{
@@ -62,6 +66,10 @@ export declare const workbookDocumentViewSchema: z.ZodObject<{
             bottom: z.ZodNumber;
             right: z.ZodNumber;
         }, z.core.$strip>>;
+        columnWidths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        rowHeights: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        defaultColumnWidth: z.ZodOptional<z.ZodNumber>;
+        defaultRowHeight: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     csv: z.ZodOptional<z.ZodObject<{
         encoding: z.ZodString;

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

@@ -1,5 +1,5 @@
-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';
-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';
+export { sampleBudgetSchema, openWorkspaceCommandSchema, chooseFolderCommandSchema, openPathCommandSchema, 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';
+export type { SampleBudget, OpenWorkspaceCommand, ChooseFolderCommand, OpenPathCommand, 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';
 export { snapshotViewSchema } from './snapshot-view.contract';
 export type { SnapshotView } from './snapshot-view.contract';
 export { verifySelectorViewSchema } from './verify-selector-view.contract';
@@ -10,6 +10,10 @@ export { stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSch
 export type { StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, RecordingCardEvent, RecordingNoteEvent, RecordingStoppedEvent, 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';
+export type { ChooseFolderView } from './choose-folder-view.contract';
+export { openPathViewSchema } from './open-path-view.contract';
+export type { OpenPathView } from './open-path-view.contract';
 export { importDocumentViewSchema } from './import-document-view.contract';
 export type { ImportDocumentView } from './import-document-view.contract';
 export { sampleRunRecordSchema, sampleRunViewSchema } from './sample-run-view.contract';

package/dist/studio-api/open-path-view.contract.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+/**
+ * `open-path`'s answer: what the path turned out to be, and the folder to
+ * open as the workspace for it. A `recipe` names the input recipe to select
+ * when there is one; a `document` is where the file is read from (in place
+ * when it is already inside the folder, else the copy made there) and its
+ * `file:` URL, ready for a recipe's `start.url`.
+ */
+export declare const openPathViewSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"folder">;
+    folder: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"recipe">;
+    folder: z.ZodString;
+    recipeId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"document">;
+    folder: z.ZodString;
+    path: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type OpenPathView = z.infer<typeof openPathViewSchema>;
+//# sourceMappingURL=open-path-view.contract.d.ts.map

package/dist/studio-server/choose-folder.handler.d.ts

@@ -0,0 +1,13 @@
+import type { ChooseFolderView } from '../studio-api';
+import type { StudioState } from './workspace.store';
+/**
+ * Handles `choose-folder`: opens the folder dialog of the machine the server
+ * runs on and answers the folder picked. Only answers: the UI follows with
+ * `open-workspace`, the same as when the folder is typed. A dialog still
+ * open is not opened a second time; the second request waits for the first.
+ *
+ * @param state - The server state holding the dialog to use.
+ * @returns The folder, or none when the dialog was closed.
+ */
+export declare function handleChooseFolder(state: StudioState): Promise<ChooseFolderView>;
+//# sourceMappingURL=choose-folder.handler.d.ts.map

package/dist/studio-server/open-path.handler.d.ts

@@ -0,0 +1,11 @@
+import type { OpenPathCommand, OpenPathView } from '../studio-api';
+/**
+ * Handles `open-path`: says what the path is (folder, recipe or document) and
+ * where to open it. Opens nothing itself: the UI follows with `open-workspace`
+ * on the answer's folder, the same as when the folder is typed.
+ *
+ * @param command - The path, and the workspace it should belong to if the caller has one.
+ * @returns What the path is.
+ */
+export declare function handleOpenPath(command: OpenPathCommand): Promise<OpenPathView>;
+//# sourceMappingURL=open-path.handler.d.ts.map

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

@@ -17,6 +17,8 @@ export interface StudioServerOptions {
     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;
+    /** How `choose-folder` asks the person for a folder; default: the operating system's own folder dialog (`folder-dialog`), opened on the machine the server runs on. A host that has a dialog of its own passes it here. */
+    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;
 }
@@ -24,6 +26,11 @@ export interface StudioServerOptions {
 export interface StudioServer {
     url: string;
     token: string;
+    /** A link that opens Studio on `open` (a folder, a recipe or a document; see `open-path`), with `workspace` as the folder a document belongs to. Without a target it is `url`. */
+    link: (target?: {
+        open?: string;
+        workspace?: string;
+    }) => string;
     close: () => Promise<void>;
 }
 /**

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

@@ -19,6 +19,10 @@ export interface StudioState {
     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.chooseFolder`): how `choose-folder` asks the person for a folder. */
+    chooseFolder?: () => Promise<string | undefined>;
+    /** The dialog currently open, so a second `choose-folder` waits for it instead of opening another. */
+    openDialog?: Promise<string | undefined>;
     /** Set once at server start (`StudioServerOptions.recorderProfileDir`), else `defaultRecorderProfileDir()`. */
     recorderProfileDir: string;
 }