@opencraw/studio 0.0.26 → 0.0.28

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

@@ -1,2 +1,15 @@
+/**
+ * How the install is run: the current executable as a Node, on Playwright's own CLI. Inside the desktop app
+ * the executable is Electron, which runs as plain Node only with `ELECTRON_RUN_AS_NODE` (otherwise it would
+ * start a second copy of the app); under Node the variable does nothing.
+ *
+ * @param cliPath - Playwright's `cli.js`.
+ * @returns What to hand to `execFile`.
+ */
+export declare function installInvocation(cliPath: string): {
+    file: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+};
 export declare function installChromiumOnce(run?: () => Promise<void>): Promise<void>;
 //# sourceMappingURL=install-chromium.use-case.d.ts.map

package/dist/document-view/workbook-view.mapper.d.ts

@@ -24,6 +24,14 @@ export interface GridSheetView {
     columnCount: number;
     rows: GridCellView[][];
     merges: GridMergeView[];
+    /** Column widths in characters by 0-based column, as the spreadsheet stores them; absent keys are columns the file does not size. */
+    columnWidths?: Record<string, number>;
+    /** Row heights in points by 0-based row, as the spreadsheet stores them. */
+    rowHeights?: Record<string, number>;
+    /** The width of a column the file does not size, in characters. */
+    defaultColumnWidth?: number;
+    /** The height of a row the file does not size, in points. */
+    defaultRowHeight?: number;
 }
 /** 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 — the CSV/workbook grid's own view of the document, structurally the same idea as `pdf-view.mapper.ts`'s `PdfDocumentView`. */
 export interface WorkbookDocumentView {

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

@@ -0,0 +1,25 @@
+import type { DialogCommand } from './folder-dialog.algorithm';
+/** 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/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/folder-dialog/index.d.ts

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

package/dist/index.d.ts

@@ -9,6 +9,6 @@ export { runSample, loadRecipePair } from './sample-run';
 export type { RecipePair, SampleRunCallbacks, SampleRunHandle, SampleRunRecord, SampleRunRejected, SampleRunResult, SampleStepSummary, SampleStoppedBy } from './sample-run';
 export { fetchStartPage } from './page-snapshot';
 export type { WhyFacts, WhyStepFact } from './explain-why';
-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';
-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';
+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';
+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';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.esm.js

@@ -1,4 +1,4 @@
-import { join, dirname, basename, extname, normalize, sep, resolve } from 'node:path';
+import { join, dirname, basename, extname, isAbsolute, relative, resolve, normalize, sep } from 'node:path';
 import { createServer } from 'node:http';
 import { promisify, stripVTControlCharacters } from 'node:util';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -8,7 +8,7 @@ import { randomBytes, createHash } from 'node:crypto';
 import { execFile } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { load } from 'cheerio';
-import { readFile, writeFile, rm, rename, mkdir } from 'node:fs/promises';
+import { readFile, writeFile, rm, rename, mkdir, stat } from 'node:fs/promises';
 import { describeJson } from '@opencraw/probe';
 import { tmpdir } from 'node:os';
 import { existsSync, createReadStream } from 'node:fs';
@@ -52,6 +52,16 @@ const openWorkspaceCommandSchema = z.object({
   type: z.literal('open-workspace'),
   folder: z.string().min(1)
 });
+/** 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. */
+const openPathCommandSchema = z.object({
+  type: z.literal('open-path'),
+  path: z.string().min(1),
+  workspace: z.string().min(1).optional()
+});
+/** Opens the operating system's folder dialog on the server's machine: the answer is the folder picked, if any. */
+const chooseFolderCommandSchema = z.object({
+  type: z.literal('choose-folder')
+});
 /** Runs one input recipe under a budget, streaming `trace-line` and `record` events, ending in `run-finished`. */
 const runSampleCommandSchema = z.object({
   type: z.literal('run-sample'),
@@ -344,7 +354,7 @@ const importDocumentCommandSchema = z.object({
   name: z.string().min(1),
   bytes: z.string()
 });
-const studioCommandSchema = z.discriminatedUnion('type', [openWorkspaceCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, explainWhyCommandSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewCommandSchema, regionPreviewCommandSchema, gridViewCommandSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewCommandSchema, startRecordingCommandSchema, stopRecordingCommandSchema]);
+const studioCommandSchema = z.discriminatedUnion('type', [openWorkspaceCommandSchema, chooseFolderCommandSchema, openPathCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, explainWhyCommandSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewCommandSchema, regionPreviewCommandSchema, gridViewCommandSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewCommandSchema, startRecordingCommandSchema, stopRecordingCommandSchema]);
 
 /**
  * What `take-snapshot` answers with: the rewritten document ready for the
@@ -525,6 +535,32 @@ const workspaceViewSchema = z.object({
   hooks: loadedHooksSchema.optional()
 });
 
+/** `choose-folder`'s answer: the folder the person picked in the operating system's dialog; absent when the dialog was closed without a choice. */
+const chooseFolderViewSchema = z.object({
+  folder: z.string().min(1).optional()
+});
+
+/**
+ * `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`.
+ */
+const openPathViewSchema = z.discriminatedUnion('kind', [z.object({
+  kind: z.literal('folder'),
+  folder: z.string().min(1)
+}), z.object({
+  kind: z.literal('recipe'),
+  folder: z.string().min(1),
+  recipeId: z.string().min(1).optional()
+}), z.object({
+  kind: z.literal('document'),
+  folder: z.string().min(1),
+  path: z.string().min(1),
+  url: z.string().startsWith('file:')
+})]);
+
 /** `import-document`'s answer: where the copy landed, and the `file:` URL a recipe's `start.url` points at it with. */
 const importDocumentViewSchema = z.object({
   path: z.string().min(1),
@@ -708,7 +744,15 @@ const gridSheetViewSchema = z.object({
   hiddenRows: z.array(z.number().int()),
   columnCount: z.number().int(),
   rows: z.array(z.array(gridCellViewSchema)),
-  merges: z.array(gridMergeViewSchema)
+  merges: z.array(gridMergeViewSchema),
+  /** Column widths in characters by 0-based column, as the spreadsheet stores them (absent for a CSV, and for a column the file does not size). */
+  columnWidths: z.record(z.string(), z.number()).optional(),
+  /** Row heights in points by 0-based row, as the spreadsheet stores them. */
+  rowHeights: z.record(z.string(), z.number()).optional(),
+  /** The width of a column the file does not size, in characters. */
+  defaultColumnWidth: z.number().optional(),
+  /** The height of a row the file does not size, in points. */
+  defaultRowHeight: z.number().optional()
 });
 const csvFormatViewSchema = z.object({
   encoding: z.string(),
@@ -860,14 +904,174 @@ function cookieToken(header) {
   return undefined;
 }
 
+const TITLE = 'Choose the recipe folder';
+/** PowerShell's own Windows Forms dialog: the only folder picker every Windows install has. UTF-8 out, so a path with accents survives the pipe. */
+const WINDOWS_SCRIPT = ['[Console]::OutputEncoding = [System.Text.Encoding]::UTF8', 'Add-Type -AssemblyName System.Windows.Forms', '$dialog = New-Object System.Windows.Forms.FolderBrowserDialog', `$dialog.Description = '${TITLE}'`, '$dialog.ShowNewFolderButton = $true', "if ($dialog.ShowDialog() -eq 'OK') { [Console]::Out.Write($dialog.SelectedPath) }"].join('; ');
+/**
+ * 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.
+ */
+function folderDialogCommands(platform) {
+  switch (platform) {
+    case 'win32':
+      {
+        return [{
+          file: 'powershell.exe',
+          args: ['-NoProfile', '-STA', '-NonInteractive', '-Command', WINDOWS_SCRIPT]
+        }];
+      }
+    case 'darwin':
+      {
+        return [{
+          file: 'osascript',
+          args: ['-e', `POSIX path of (choose folder with prompt "${TITLE}")`]
+        }];
+      }
+    case 'linux':
+    case 'freebsd':
+    case 'openbsd':
+      {
+        return [{
+          file: 'zenity',
+          args: ['--file-selection', '--directory', `--title=${TITLE}`]
+        }, {
+          file: 'kdialog',
+          args: ['--getexistingdirectory', '.', '--title', TITLE]
+        }];
+      }
+    default:
+      {
+        return [];
+      }
+  }
+}
+/**
+ * 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.
+ */
+function folderFromDialogOutput(output) {
+  const line = output.trim();
+  if (line === '') return undefined;
+  const withoutSeparator = line.replace(/[/\\]+$/u, '');
+  return withoutSeparator === '' || /^[A-Za-z]:$/u.test(withoutSeparator) ? line : withoutSeparator;
+}
+
+/** Runs the program with Node's own `execFile`: no shell, so a path or title is never parsed as a command. */
+const runDialogProgram = async command => await new Promise(resolve => {
+  execFile(command.file, command.args, {
+    windowsHide: false,
+    encoding: 'utf8'
+  }, (error, stdout) => {
+    if (error === null) {
+      resolve({
+        output: stdout
+      });
+      return;
+    }
+    if ('code' in error && error.code === 'ENOENT') {
+      resolve({
+        missing: true
+      });
+      return;
+    }
+    // `zenity` and `osascript` exit non-zero when the dialog is closed without a choice.
+    resolve(stdout.trim() === '' ? {
+      cancelled: true
+    } : {
+      output: stdout
+    });
+  });
+});
+/**
+ * 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).
+ */
+async function chooseFolderWithDialog(platform = process.platform, run = runDialogProgram) {
+  const candidates = folderDialogCommands(platform);
+  for (const command of candidates) {
+    const result = await run(command);
+    if ('missing' in result) continue;
+    if ('cancelled' in result) return undefined;
+    return folderFromDialogOutput(result.output);
+  }
+  const tried = candidates.map(command => command.file).join(' or ');
+  throw new Error(`there is no folder dialog on this machine${tried === '' ? '' : ` (${tried} is not installed)`}: type the folder instead`);
+}
+
+/** Asks the dialog, and clears `openDialog` once it has answered or failed, so the next request opens a new one. */
+async function askOnce(state, ask) {
+  try {
+    return await ask();
+  } finally {
+    state.openDialog = undefined;
+  }
+}
+/**
+ * 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.
+ */
+async function handleChooseFolder(state) {
+  if (state.chooseFolder === undefined) throw new Error('this server has no folder dialog: type the folder instead');
+  state.openDialog ??= askOnce(state, state.chooseFolder);
+  const folder = await state.openDialog;
+  return folder === undefined ? {} : {
+    folder
+  };
+}
+
 const execFileAsync = promisify(execFile);
 /** `playwright`'s own `exports` map doesn't whitelist a `./cli` subpath, so its CLI is resolved off `playwright/package.json`'s real location — the same technique `@opencraw/captcha-tesseract`'s `bundledLangPath()` uses for a bundled data path. */
 function playwrightCliPath() {
   const require = createRequire(import.meta.url);
   return join(dirname(require.resolve('playwright/package.json')), 'cli.js');
 }
+/**
+ * How the install is run: the current executable as a Node, on Playwright's own CLI. Inside the desktop app
+ * the executable is Electron, which runs as plain Node only with `ELECTRON_RUN_AS_NODE` (otherwise it would
+ * start a second copy of the app); under Node the variable does nothing.
+ *
+ * @param cliPath - Playwright's `cli.js`.
+ * @returns What to hand to `execFile`.
+ */
+function installInvocation(cliPath) {
+  return {
+    file: process.execPath,
+    args: [cliPath, 'install', 'chromium'],
+    env: {
+      ...process.env,
+      ELECTRON_RUN_AS_NODE: '1'
+    }
+  };
+}
 async function runPlaywrightInstall() {
-  await execFileAsync(process.execPath, [playwrightCliPath(), 'install', 'chromium']);
+  const {
+    file,
+    args,
+    env
+  } = installInvocation(playwrightCliPath());
+  await execFileAsync(file, args, {
+    env
+  });
 }
 let installing;
 /**
@@ -1364,6 +1568,22 @@ function sheetView(sheet) {
         ref: reference,
         ...range
       }];
+    }),
+    ...(sheet.columnWidths !== undefined && {
+      columnWidths: {
+        ...sheet.columnWidths
+      }
+    }),
+    ...(sheet.rowHeights !== undefined && {
+      rowHeights: {
+        ...sheet.rowHeights
+      }
+    }),
+    ...(sheet.defaultColumnWidth !== undefined && {
+      defaultColumnWidth: sheet.defaultColumnWidth
+    }),
+    ...(sheet.defaultRowHeight !== undefined && {
+      defaultRowHeight: sheet.defaultRowHeight
     })
   };
 }
@@ -3026,6 +3246,102 @@ function isAlreadyThere(error) {
   return typeof error === 'object' && error !== null && 'code' in error && error.code === 'EEXIST';
 }
 
+/** A recipe is a small JSON file; anything larger is a document that happens to be JSON. */
+const MAX_RECIPE_BYTES = 5 * 1024 * 1024;
+/**
+ * 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.
+ */
+async function openPath(path, workspace) {
+  if (!isAbsolute(path)) throw new Error(`"${path}" is not an absolute path`);
+  const info = await statOrNothing(path);
+  if (info === undefined) throw new Error(`"${path}" does not exist`);
+  if (info.isDirectory()) return {
+    kind: 'folder',
+    folder: path
+  };
+  const recipe = info.size <= MAX_RECIPE_BYTES ? await recipeAt(path) : undefined;
+  if (recipe !== undefined) return {
+    kind: 'recipe',
+    folder: dirname(path),
+    recipeId: recipe.id
+  };
+  const folder = workspace ?? dirname(path);
+  if (isInside(folder, path)) return {
+    kind: 'document',
+    folder,
+    path,
+    url: pathToFileURL(path).href
+  };
+  const copy = await importDocument(folder, basename(path), new Uint8Array(await readFile(path)));
+  return {
+    kind: 'document',
+    folder,
+    path: copy.path,
+    url: copy.url
+  };
+}
+/** The recipe a `.json` file holds, with the id of the input recipe to select (an output recipe selects the first input naming it); `undefined` when the file is not a recipe. */
+async function recipeAt(path) {
+  if (extname(path).toLowerCase() !== '.json') return undefined;
+  let content;
+  try {
+    content = JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    return undefined;
+  }
+  const {
+    kind,
+    id
+  } = typeof content === 'object' && content !== null ? content : {};
+  if (kind === 'input') return {
+    id: typeof id === 'string' ? id : undefined
+  };
+  if (kind !== 'output') return undefined;
+  const listing = await openWorkspace(dirname(path));
+  for (const candidate of listing.recipes) {
+    const named = candidate.kind === 'input' ? inputNaming(candidate.text, id) : undefined;
+    if (named !== undefined) return {
+      id: named
+    };
+  }
+  return {};
+}
+/** The id of the input recipe whose text names `outputId` as its output, read from the JSON itself so an input that does not validate still counts. */
+function inputNaming(text, outputId) {
+  try {
+    const {
+      id,
+      output
+    } = JSON.parse(text);
+    return output === outputId && typeof id === 'string' ? id : undefined;
+  } catch {
+    return undefined;
+  }
+}
+async function statOrNothing(path) {
+  try {
+    return await stat(path);
+  } catch {
+    return undefined;
+  }
+}
+function isInside(folder, path) {
+  const from = relative(resolve(folder), resolve(path));
+  return from !== '' && !from.startsWith('..') && !isAbsolute(from);
+}
+
 /**
  * Handles `import-document` (issue #120): decodes the base64 bytes and copies
  * the file into the folder (see `recipe-workspace/import-document.use-case.ts`
@@ -3860,6 +4176,18 @@ function handleInspectPage(state, command) {
   };
 }
 
+/**
+ * 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.
+ */
+async function handleOpenPath(command) {
+  return await openPath(command.path, command.workspace);
+}
+
 /**
  * Which of what Studio was started with calls outside the process, for the bar that warns the person and
  * for the stubs a sample run may use.
@@ -5163,6 +5491,7 @@ async function startStudioServer(options = {}) {
   if (options.initialFolder !== undefined) state.folder = options.initialFolder;
   state.browser = options.browser;
   state.plugins = options.plugins;
+  state.chooseFolder = options.chooseFolder ?? (() => chooseFolderWithDialog());
   if (options.recorderProfileDir !== undefined) state.recorderProfileDir = options.recorderProfileDir;
   const server = createServer((request, response) => {
     void handleRequest(request, response, token, state, uiRoot);
@@ -5177,9 +5506,15 @@ async function startStudioServer(options = {}) {
   const address = server.address();
   const port = typeof address === 'object' && address !== null ? address.port : 0;
   const folderParam = options.initialFolder === undefined ? '' : `&folder=${encodeURIComponent(options.initialFolder)}`;
+  const base = `http://127.0.0.1:${port}/?token=${token}`;
   return {
-    url: `http://127.0.0.1:${port}/?token=${token}${folderParam}`,
+    url: `${base}${folderParam}`,
     token,
+    link: target => {
+      const workspace = target?.workspace ?? options.initialFolder;
+      const open = target?.open === undefined ? '' : `&open=${encodeURIComponent(target.open)}`;
+      return `${base}${workspace === undefined ? '' : `&folder=${encodeURIComponent(workspace)}`}${open}`;
+    },
     close: () => stop(server, state)
   };
 }
@@ -5275,6 +5610,14 @@ function dispatch(command, state) {
       {
         return handleOpenWorkspace(state, command);
       }
+    case 'choose-folder':
+      {
+        return handleChooseFolder(state);
+      }
+    case 'open-path':
+      {
+        return handleOpenPath(command);
+      }
     case 'import-document':
       {
         return handleImportDocument(command);
@@ -5416,7 +5759,11 @@ async function main(argv, options = {}) {
     initialFolder: folder,
     plugins: options.plugins
   });
-  process.stdout.write(`OpenCraw Studio: ${server.url}\n`);
+  const address = options.open === undefined ? server.url : server.link({
+    open: resolve(options.open),
+    workspace: folder
+  });
+  process.stdout.write(`OpenCraw Studio: ${address}\n`);
   process.stdout.write(`Workspace: ${folder}\n`);
   if (options.plugins !== undefined) process.stdout.write(`Hooks: ${options.plugins.source} (runs as your code)\n`);
   const shutdown = () => {
@@ -5426,5 +5773,5 @@ async function main(argv, options = {}) {
   process.on('SIGTERM', shutdown);
 }
 
-export { deckChartSeriesViewSchema, deckChartViewSchema, deckDocumentViewSchema, deckPreviewCommandSchema, deckPreviewOptionsSchema, deckShapeViewSchema, deckSlideViewSchema, deckTablePreviewMatchSchema, deckTablePreviewViewSchema, deckViewCommandSchema, documentTreeCommandSchema, documentTreeNodeViewSchema, documentTreeViewSchema, domTreeNodeViewSchema, explainWhyCommandSchema, fetchStartPage, fetchStartPageCommandSchema, fieldPickSchema, fieldTraceSchema, gridCellViewSchema, gridMergeViewSchema, gridPreviewCommandSchema, gridPreviewOptionsSchema, gridSheetViewSchema, gridTablePreviewMatchSchema, gridTablePreviewViewSchema, gridViewCommandSchema, importDocument, importDocumentCommandSchema, importDocumentViewSchema, inferSelectorCommandSchema, inferSelectorViewSchema, inspectPageCommandSchema, inspectViewSchema, loadRecipePair, loadedHooksSchema, main, missingWhyTargetSchema, observedResponseSchema, openWorkspace, openWorkspaceCommandSchema, outlineBracketSchema, outlineCardSchema, outlineNodeSchema, outlineViewSchema, pageDataFindingSchema, pdfCellViewSchema, pdfDocumentViewSchema, pdfPageViewSchema, pdfRowViewSchema, pdfViewCommandSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, recordRejectedEventSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, regionPreviewCommandSchema, regionPreviewMatchSchema, regionPreviewViewSchema, rejectedWhyTargetSchema, responsesSeenCommandSchema, responsesSeenViewSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveOutlineCommandSchema, saveRecipe, saveRecipeCommandSchema, sentencePartSchema, snapshotViewSchema, startPageViewSchema, startRecordingCommandSchema, startStudioServer, stopRecordingCommandSchema, stopRunCommandSchema, stoppedBySchema, studioCommandSchema, studioEventSchema, tablePreviewBandSchema, tablePreviewCommandSchema, tablePreviewMatchSchema, tablePreviewOptionsSchema, tablePreviewTableSchema, tablePreviewViewSchema, takeSnapshotCommandSchema, traceLineEventSchema, verifySelectorCommandSchema, verifySelectorViewSchema, whyTargetSchema, whyViewSchema, workbookDocumentViewSchema, workspaceChangedEventSchema, workspaceViewSchema };
+export { chooseFolderCommandSchema, chooseFolderViewSchema, deckChartSeriesViewSchema, deckChartViewSchema, deckDocumentViewSchema, deckPreviewCommandSchema, deckPreviewOptionsSchema, deckShapeViewSchema, deckSlideViewSchema, deckTablePreviewMatchSchema, deckTablePreviewViewSchema, deckViewCommandSchema, documentTreeCommandSchema, documentTreeNodeViewSchema, documentTreeViewSchema, domTreeNodeViewSchema, explainWhyCommandSchema, fetchStartPage, fetchStartPageCommandSchema, fieldPickSchema, fieldTraceSchema, gridCellViewSchema, gridMergeViewSchema, gridPreviewCommandSchema, gridPreviewOptionsSchema, gridSheetViewSchema, gridTablePreviewMatchSchema, gridTablePreviewViewSchema, gridViewCommandSchema, importDocument, importDocumentCommandSchema, importDocumentViewSchema, inferSelectorCommandSchema, inferSelectorViewSchema, inspectPageCommandSchema, inspectViewSchema, loadRecipePair, loadedHooksSchema, main, missingWhyTargetSchema, observedResponseSchema, openPathCommandSchema, openPathViewSchema, openWorkspace, openWorkspaceCommandSchema, outlineBracketSchema, outlineCardSchema, outlineNodeSchema, outlineViewSchema, pageDataFindingSchema, pdfCellViewSchema, pdfDocumentViewSchema, pdfPageViewSchema, pdfRowViewSchema, pdfViewCommandSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, recordRejectedEventSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, regionPreviewCommandSchema, regionPreviewMatchSchema, regionPreviewViewSchema, rejectedWhyTargetSchema, responsesSeenCommandSchema, responsesSeenViewSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveOutlineCommandSchema, saveRecipe, saveRecipeCommandSchema, sentencePartSchema, snapshotViewSchema, startPageViewSchema, startRecordingCommandSchema, startStudioServer, stopRecordingCommandSchema, stopRunCommandSchema, stoppedBySchema, studioCommandSchema, studioEventSchema, tablePreviewBandSchema, tablePreviewCommandSchema, tablePreviewMatchSchema, tablePreviewOptionsSchema, tablePreviewTableSchema, tablePreviewViewSchema, takeSnapshotCommandSchema, traceLineEventSchema, verifySelectorCommandSchema, verifySelectorViewSchema, whyTargetSchema, whyViewSchema, workbookDocumentViewSchema, workspaceChangedEventSchema, workspaceViewSchema };
 //# sourceMappingURL=index.esm.js.map

package/dist/main.d.ts

@@ -3,6 +3,8 @@ import type { TrustedPlugins } from './trusted-plugins';
 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/recipe-workspace/index.d.ts

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

package/dist/recipe-workspace/open-path.use-case.d.ts

@@ -0,0 +1,18 @@
+import type { OpenPathView } from '../studio-api';
+/**
+ * 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/browser-provisioning/install-chromium.use-case.d.ts

@@ -1,2 +1,15 @@
+/**
+ * How the install is run: the current executable as a Node, on Playwright's own CLI. Inside the desktop app
+ * the executable is Electron, which runs as plain Node only with `ELECTRON_RUN_AS_NODE` (otherwise it would
+ * start a second copy of the app); under Node the variable does nothing.
+ *
+ * @param cliPath - Playwright's `cli.js`.
+ * @returns What to hand to `execFile`.
+ */
+export declare function installInvocation(cliPath: string): {
+    file: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+};
 export declare function installChromiumOnce(run?: () => Promise<void>): Promise<void>;
 //# sourceMappingURL=install-chromium.use-case.d.ts.map

package/dist/src/document-view/workbook-view.mapper.d.ts

@@ -24,6 +24,14 @@ export interface GridSheetView {
     columnCount: number;
     rows: GridCellView[][];
     merges: GridMergeView[];
+    /** Column widths in characters by 0-based column, as the spreadsheet stores them; absent keys are columns the file does not size. */
+    columnWidths?: Record<string, number>;
+    /** Row heights in points by 0-based row, as the spreadsheet stores them. */
+    rowHeights?: Record<string, number>;
+    /** The width of a column the file does not size, in characters. */
+    defaultColumnWidth?: number;
+    /** The height of a row the file does not size, in points. */
+    defaultRowHeight?: number;
 }
 /** 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 — the CSV/workbook grid's own view of the document, structurally the same idea as `pdf-view.mapper.ts`'s `PdfDocumentView`. */
 export interface WorkbookDocumentView {