@opencraw/studio 0.0.32 → 0.0.34

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

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

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

@@ -22,7 +22,10 @@ export interface GridSheetView {
     hiddenRows: number[];
     /** The widest row's own length, ragged rows included — for the grid to size its columns. */
     columnCount: number;
+    /** The sheet's rows; only the first window of them when `rowCount` is set (the rest are fetched with `grid-rows`). */
     rows: GridCellView[][];
+    /** How many rows the sheet has, set only when `rows` holds just the first window of them. */
+    rowCount?: number;
     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>;
@@ -55,5 +58,18 @@ export interface WorkbookDocumentView {
  * @param document - The read workbook (a spreadsheet or a CSV).
  * @returns The view.
  */
-export declare function workbookDocumentView(document: WorkbookDocument): WorkbookDocumentView;
+export declare function workbookDocumentView(document: WorkbookDocument, options?: {
+    windowRows?: number;
+}): WorkbookDocumentView;
+/**
+ * A run of one sheet's rows, typed, for a grid that only holds the screens around where it is scrolled to (the rest of a big file is never
+ * sent to the browser until it is needed).
+ *
+ * @param document - The read workbook.
+ * @param sheetIndex - Which sheet, 0-based.
+ * @param from - The first row, 0-based.
+ * @param count - How many rows at most.
+ * @returns The rows (fewer at the end of the sheet, none past it).
+ */
+export declare function workbookSheetRows(document: WorkbookDocument, sheetIndex: number, from: number, count: number): GridCellView[][];
 //# sourceMappingURL=workbook-view.mapper.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, chooseFolderCommandSchema, openPathCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, detectUrlCommandSchema, 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, detectUrlViewSchema, 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, DetectUrlCommand, 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, DetectUrlView, 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, detectUrlCommandSchema, 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, detectUrlViewSchema, snapshotViewSchema, verifySelectorViewSchema, fieldPickSchema, inferSelectorViewSchema, selectorAlternativeSchema, sentencePartSchema, outlineCardSchema, outlineBracketSchema, outlineNodeSchema, outlineViewSchema, whyViewSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewOptionsSchema, tablePreviewCommandSchema, regionPreviewCommandSchema, regionPreviewMatchSchema, regionPreviewViewSchema, gridViewCommandSchema, gridRowsCommandSchema, gridPreviewOptionsSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewOptionsSchema, deckPreviewCommandSchema, domTreeNodeViewSchema, pageDataFindingSchema, inspectViewSchema, observedResponseSchema, responsesSeenViewSchema, documentTreeNodeViewSchema, documentTreeViewSchema, pdfCellViewSchema, pdfRowViewSchema, pdfPageViewSchema, pdfDocumentViewSchema, tablePreviewTableSchema, tablePreviewBandSchema, tablePreviewMatchSchema, tablePreviewViewSchema, gridCellViewSchema, gridMergeViewSchema, gridRowsViewSchema, 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, DetectUrlCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, MissingWhyTarget, RejectedWhyTarget, WhyTarget, ExplainWhyCommand, InspectPageCommand, ResponsesSeenCommand, DocumentTreeCommand, PdfViewCommand, TablePreviewOptions, TablePreviewCommand, RegionPreviewCommand, GridViewCommand, GridRowsCommand, 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, DetectUrlView, SnapshotView, VerifySelectorView, FieldPick, InferSelectorView, SelectorAlternative, SentencePart, OutlineCard, OutlineBracket, OutlineNode, OutlineView, WhyView, DomTreeNodeView, PageDataKind, PageDataFindingView, InspectView, ObservedResponseView, ResponsesSeenView, DocumentTreeNodeView, DocumentTreeView, PdfCellView, PdfRowView, PdfPageView, PdfDocumentView, TablePreviewTableView, TablePreviewBandView, TablePreviewMatchView, TablePreviewView, GridCellView, GridMergeView, GridRowsView, 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, isAbsolute, relative, resolve, normalize, sep } from 'node:path';
+import { join, dirname, extname, relative, sep, basename, isAbsolute, resolve, normalize } from 'node:path';
 import { createServer } from 'node:http';
 import { promisify, stripVTControlCharacters } from 'node:util';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -241,6 +241,18 @@ const gridViewCommandSchema = z.object({
   delimiter: z.string().min(1).optional(),
   encoding: z.string().min(1).optional()
 });
+/**
+ * `grid-rows`: a run of one sheet's rows of a big CSV/spreadsheet, for the grid canvas that holds only the screens around where it is
+ * scrolled to. The first window comes with `grid-view`; the rest are asked for as the person scrolls.
+ */
+const gridRowsCommandSchema = z.object({
+  type: z.literal('grid-rows'),
+  recipeId: z.string().min(1),
+  path: z.string().min(1),
+  sheet: z.int().min(0),
+  from: z.int().min(0),
+  count: z.int().min(1).max(1000)
+});
 /** A `table` extract's options for a workbook, as the studio's grid canvas picks build them — mirrors `document-view/table-preview.use-case.ts`'s `GridTablePreviewOptions`. */
 const gridPreviewOptionsSchema = z.object({
   sheet: z.string().min(1).optional(),
@@ -361,7 +373,7 @@ const importDocumentCommandSchema = z.object({
   name: z.string().min(1),
   bytes: z.string()
 });
-const studioCommandSchema = z.discriminatedUnion('type', [openWorkspaceCommandSchema, chooseFolderCommandSchema, openPathCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, detectUrlCommandSchema, 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, detectUrlCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, explainWhyCommandSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewCommandSchema, regionPreviewCommandSchema, gridViewCommandSchema, gridRowsCommandSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewCommandSchema, startRecordingCommandSchema, stopRecordingCommandSchema]);
 
 /**
  * What `take-snapshot` answers with: the rewritten document ready for the
@@ -398,18 +410,29 @@ const verifySelectorViewSchema = z.object({
 
 /** The candidate tiers `selector-inference`'s ranking works through, best first — see `selector-candidates.algorithm.ts`. */
 const candidateTierSchema = z.enum(['id', 'data-attr', 'class', 'structure', 'position']);
+/** Another selector that reaches the clicked node, verified against the snapshot, for the person to choose instead of the best one. */
+const selectorAlternativeSchema = z.object({
+  selector: z.string(),
+  tier: candidateTierSchema,
+  matches: z.number()
+});
 /** One clicked node's field: the best selector found for it, verified against the snapshot. */
 const fieldPickSchema = z.object({
   selector: z.string(),
   tier: candidateTierSchema,
   take: z.string(),
-  matches: z.number()
+  matches: z.number(),
+  /** Every verified selector that reaches the node, best first (the chosen one among them), for the options the person is shown. */
+  alternatives: z.array(selectorAlternativeSchema).optional(),
+  /** The node's own id when it looks generated (so it is not used in any selector above), to tell the person why. */
+  generatedId: z.string().optional()
 });
 /** A list's item shape: the best selector that matches every item, verified against the snapshot. */
 const itemPickSchema = z.object({
   selector: z.string(),
   tier: candidateTierSchema,
-  matches: z.number()
+  matches: z.number(),
+  alternatives: z.array(selectorAlternativeSchema).optional()
 });
 /**
  * What `infer-selector` answers with (issue #91, studio plan §3.2):
@@ -766,6 +789,8 @@ const gridSheetViewSchema = z.object({
   hiddenRows: z.array(z.number().int()),
   columnCount: z.number().int(),
   rows: z.array(z.array(gridCellViewSchema)),
+  /** How many rows the sheet has, set only when `rows` holds just the first window of them (a big file); the rest come from `grid-rows`. */
+  rowCount: z.number().int().optional(),
   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(),
@@ -776,6 +801,10 @@ const gridSheetViewSchema = z.object({
   /** The height of a row the file does not size, in points. */
   defaultRowHeight: z.number().optional()
 });
+/** What `grid-rows` answers with: a run of one sheet's rows. */
+const gridRowsViewSchema = z.object({
+  rows: z.array(z.array(gridCellViewSchema))
+});
 const csvFormatViewSchema = z.object({
   encoding: z.string(),
   delimiter: z.string()
@@ -1490,6 +1519,88 @@ function inlineAssets(html, pageUrl, assets) {
   return $.html();
 }
 
+const IMAGE_TYPES = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.avif': 'image/avif',
+  '.bmp': 'image/bmp'
+};
+/** The most one picture may weigh to be embedded, and the most all of a document's pictures may (bytes). */
+const MAX_IMAGE_BYTES = 1_500_000;
+const MAX_TOTAL_BYTES = 8_000_000;
+/** An image address made absolute against the document's own; one that cannot be read as an address is left as it is. */
+function absoluteAddress(source, documentUrl) {
+  try {
+    return new URL(source, documentUrl).href;
+  } catch {
+    return source;
+  }
+}
+/** A file's bytes, or `undefined` when it cannot be read. */
+async function readIfThere(path) {
+  try {
+    return await readFile(path);
+  } catch {
+    return undefined;
+  }
+}
+/** The file a `file:` image address names, when it sits in the document's own folder or below it; `undefined` for anything else (another site, another folder). */
+function localPathOf(source, documentFolder) {
+  if (!source.startsWith('file:')) return undefined;
+  let path;
+  try {
+    path = fileURLToPath(source);
+  } catch {
+    return undefined;
+  }
+  const inside = relative(documentFolder, path);
+  return inside === '' || inside.startsWith('..') || inside.split(sep).includes('..') ? undefined : path;
+}
+/**
+ * A document read from a file (a Markdown file, say) names its pictures by paths beside it, which the browser showing it cannot open. The
+ * pictures that sit in the document's own folder are embedded in the page as data addresses, so they show; ones that are not there are counted
+ * so the person is told. Nothing outside the document's folder is ever read.
+ *
+ * @param html - The document as HTML, its addresses already made absolute against `documentUrl`.
+ * @param documentUrl - The document's own `file:` address.
+ * @returns The page with the pictures embedded, and how many were embedded and how many could not be.
+ */
+async function inlineLocalImages(html, documentUrl) {
+  if (!documentUrl.startsWith('file:')) return {
+    html,
+    inlined: 0,
+    missing: 0
+  };
+  const $ = load(html);
+  const folder = dirname(fileURLToPath(documentUrl));
+  let inlined = 0;
+  let missing = 0;
+  let total = 0;
+  for (const element of $('img[src]')) {
+    const source = absoluteAddress($(element).attr('src') ?? '', documentUrl);
+    if (!source.startsWith('file:')) continue;
+    const path = localPathOf(source, folder);
+    const type = path === undefined ? undefined : IMAGE_TYPES[extname(path).toLowerCase()];
+    const bytes = path !== undefined && type !== undefined ? await readIfThere(path) : undefined;
+    if (bytes === undefined || type === undefined || bytes.length > MAX_IMAGE_BYTES || total + bytes.length > MAX_TOTAL_BYTES) {
+      missing += 1;
+      continue;
+    }
+    total += bytes.length;
+    inlined += 1;
+    $(element).attr('src', `data:${type};base64,${bytes.toString('base64')}`);
+  }
+  return {
+    html: $.html(),
+    inlined,
+    missing
+  };
+}
+
 /** Attributes that carry a URL and are rewritten to absolute; `srcset` is handled separately (it carries several). */
 const URL_ATTRIBUTES = ['href', 'src', 'action', 'poster'];
 /** Schemes left untouched: they are not a location `new URL(value, base)` should resolve, or already carry their own meaning. */
@@ -1723,13 +1834,19 @@ async function snapshotApi(url, storageState, as) {
       })
     });
     const text = textOf$1(response.body);
-    const rewritten = rewriteDocument(text, url);
+    // A document read from a file names its pictures by paths beside it, which the browser cannot open: the ones next to the file are embedded.
+    const pictures = await inlineLocalImages(text, url);
+    const rewritten = rewriteDocument(pictures.html, url);
+    const notice = pictures.missing === 0 ? undefined : `${String(pictures.missing)} picture${pictures.missing === 1 ? '' : 's'} in this document ${pictures.missing === 1 ? 'is' : 'are'} not shown: only pictures kept in the same folder as the file can be.`;
     return {
       ...rewritten,
       baseUrl: url,
       rawHtml: text,
       format: response.format,
-      body: response.body
+      body: response.body,
+      ...(notice !== undefined && {
+        notice
+      })
     };
   } finally {
     await client.dispose();
@@ -1878,21 +1995,26 @@ const ISO_DATE_OR_TIME = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2})?$|^\d{2}:\d{2
  * @param document - The read workbook (a spreadsheet or a CSV).
  * @returns The view.
  */
-function workbookDocumentView(document) {
+function workbookDocumentView(document, options = {}) {
   return {
-    sheets: document.sheets.map(sheet => sheetView(sheet)),
+    sheets: document.sheets.map(sheet => sheetView(sheet, options.windowRows)),
     ...(document.csv !== undefined && {
       csv: document.csv
     })
   };
 }
-function sheetView(sheet) {
+function sheetView(sheet, windowRows) {
+  const windowed = windowRows !== undefined && sheet.rows.length > windowRows;
   return {
     name: sheet.name,
     hidden: sheet.hidden === true,
     hiddenRows: sheet.hiddenRows === undefined ? [] : [...sheet.hiddenRows],
-    columnCount: Math.max(0, ...sheet.rows.map(row => row.length)),
-    rows: sheet.rows.map(row => row.map(cell => cellView(cell))),
+    // Not `Math.max(...lengths)`: a spread of a few hundred thousand rows overflows the call stack.
+    columnCount: sheet.rows.reduce((widest, row) => Math.max(widest, row.length), 0),
+    rows: (windowed ? sheet.rows.slice(0, windowRows) : sheet.rows).map(row => row.map(cell => cellView(cell))),
+    ...(windowed && {
+      rowCount: sheet.rows.length
+    }),
     merges: (sheet.merges ?? []).flatMap(reference => {
       const range = rangeOf(reference);
       return range === undefined ? [] : [{
@@ -1918,6 +2040,21 @@ function sheetView(sheet) {
     })
   };
 }
+/**
+ * A run of one sheet's rows, typed, for a grid that only holds the screens around where it is scrolled to (the rest of a big file is never
+ * sent to the browser until it is needed).
+ *
+ * @param document - The read workbook.
+ * @param sheetIndex - Which sheet, 0-based.
+ * @param from - The first row, 0-based.
+ * @param count - How many rows at most.
+ * @returns The rows (fewer at the end of the sheet, none past it).
+ */
+function workbookSheetRows(document, sheetIndex, from, count) {
+  const sheet = document.sheets[sheetIndex];
+  if (sheet === undefined) return [];
+  return sheet.rows.slice(from, from + count).map(row => row.map(cell => cellView(cell)));
+}
 function cellView(cell) {
   return {
     value: cell,
@@ -3082,6 +3219,8 @@ function handleGridPreview(state, command) {
   return previewGridTable(snapshot.body, command.options);
 }
 
+/** How many rows of a sheet the first `grid-view` answer carries; a bigger sheet's other rows come from `grid-rows` as the grid is scrolled. */
+const GRID_WINDOW_ROWS = 200;
 /**
  * Handles `grid-view`: 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
@@ -3104,7 +3243,9 @@ async function handleGridView(state, command) {
   const overriding = command.delimiter !== undefined || command.encoding !== undefined;
   if (!overriding) {
     if (!isWorkbookDocument(snapshot.body)) throw new Error(`"${command.recipeId}" at "${command.path}" is not a workbook snapshot: the grid canvas only reads a read CSV/spreadsheet document`);
-    return workbookDocumentView(snapshot.body);
+    return workbookDocumentView(snapshot.body, {
+      windowRows: GRID_WINDOW_ROWS
+    });
   }
   if (snapshot.format !== 'csv') throw new Error(`"${command.recipeId}" at "${command.path}" is not a CSV snapshot: "delimiter"/"encoding" only override a CSV reading`);
   const body = await rereadCsv(snapshot.baseUrl, {
@@ -3115,7 +3256,25 @@ async function handleGridView(state, command) {
     ...snapshot,
     body
   });
-  return workbookDocumentView(body);
+  return workbookDocumentView(body, {
+    windowRows: GRID_WINDOW_ROWS
+  });
+}
+/**
+ * Handles `grid-rows`: a run of one sheet's rows from the cached snapshot, for the grid that holds only a few screens of a big file at a time.
+ *
+ * @param state - The server state.
+ * @param command - The command; `command.path` must already have a cached snapshot.
+ * @returns The rows (none past the end of the sheet).
+ * @throws Error when there is no cached snapshot or it is not a workbook.
+ */
+function handleGridRows(state, command) {
+  const snapshot = cachedSnapshot(state.snapshots, command.recipeId, command.path);
+  if (snapshot === undefined) throw new Error(`no cached snapshot for "${command.recipeId}" at "${command.path}": call take-snapshot first`);
+  if (!isWorkbookDocument(snapshot.body)) throw new Error(`"${command.recipeId}" at "${command.path}" is not a workbook snapshot: grid-rows only reads a CSV/spreadsheet document`);
+  return {
+    rows: workbookSheetRows(snapshot.body, command.sheet, command.from, command.count)
+  };
 }
 
 /**
@@ -3970,6 +4129,12 @@ function structureCandidates(path) {
       tier: 'structure'
     });
   }
+  // The whole tree down to the node, each level named by its stable id or classes (an id or class that looks generated is left out of it).
+  const levels = path.slice(-5);
+  if (levels.length > 2) candidates.push({
+    selector: levels.map(level => simpleSelector(level)).join(' > '),
+    tier: 'structure'
+  });
   return candidates;
 }
 /** `parent > tag:nth-of-type(n)`, the position-only fallback; never `nth-child`, which counts every sibling tag, not just this element's own. */
@@ -4021,7 +4186,7 @@ const TIER_ORDER = {
  * Ordering: candidates that do not match `targetNodeId` (when given) sort
  * last; among the rest, best tier first, and within a tier the fewest
  * matches first (the most specific selector that still hits the target).
- * A candidate matching nothing is dropped entirely: it is not a real option.
+ * Equal on all that, the selector naming more ids and classes comes first. A candidate matching nothing is dropped entirely: it is not a real option.
  *
  * @param html - The document to verify against (the snapshot, or the live page for the second, cross-check pass).
  * @param candidates - Unranked candidates, e.g. from `candidatesFor`.
@@ -4038,7 +4203,11 @@ function rankCandidates(html, candidates, targetNodeId) {
       hitsTarget
     };
   });
-  return ranked.filter(candidate => candidate.matches > 0).sort((a, b) => Number(b.hitsTarget) - Number(a.hitsTarget) || TIER_ORDER[a.tier] - TIER_ORDER[b.tier] || a.matches - b.matches);
+  return ranked.filter(candidate => candidate.matches > 0).sort((a, b) => Number(b.hitsTarget) - Number(a.hitsTarget) || TIER_ORDER[a.tier] - TIER_ORDER[b.tier] || a.matches - b.matches || namedParts(b.selector) - namedParts(a.selector));
+}
+/** How many ids and classes a selector names: of two that tie, the one built on names keeps working better than one made only of tags. */
+function namedParts(selector) {
+  return (selector.match(/[#.]/g) ?? []).length;
 }
 /** The single best candidate, or `undefined` when none of them matched anything. */
 function bestCandidate(html, candidates, targetNodeId) {
@@ -4165,7 +4334,7 @@ function handleInferSelector(state, command) {
   const [pathA, pathB] = paths;
   if (pathB === undefined) return itemField(html, command, pathA) ?? {
     kind: 'field',
-    field: fieldPick(html, pathA)
+    field: fieldPick(html, pathA, pathA, command.nodeIds[0])
   };
   try {
     const result = inferList(pathA, pathB);
@@ -4173,7 +4342,8 @@ function handleInferSelector(state, command) {
       kind: 'unsupported',
       reason: 'these two picks do not belong to the same list: pick the same field on two similar items'
     };
-    const item = bestCandidate(html, candidatesFor(result.itemPath, false));
+    const itemOptions = rankCandidates(html, candidatesFor(result.itemPath, false));
+    const item = itemOptions[0];
     if (item === undefined) return {
       kind: 'unsupported',
       reason: 'no selector matches every item of this list; try picking two items closer to each other in the markup'
@@ -4184,7 +4354,8 @@ function handleInferSelector(state, command) {
       item: {
         selector: item.selector,
         tier: item.tier,
-        matches: item.matches
+        matches: item.matches,
+        alternatives: alternativesOf(itemOptions)
       },
       field
     };
@@ -4217,18 +4388,42 @@ function itemField(html, command, clicked) {
   };
 }
 /** The best selector for one clicked node, `take` decided from the concrete clicked element; `rankSource` (a generalised path) is used for candidate generation when given, so a per-item-unique attribute of the one node picked cannot end up in the selector. */
-function fieldPick(html, clicked, rankSource = clicked) {
+function fieldPick(html, clicked, rankSource = clicked, targetNodeId) {
   const leaf = clicked.at(-1);
   const take = leaf === undefined ? 'text' : takeKindFor(leaf);
-  const best = bestCandidate(html, candidatesFor(rankSource));
+  const options = rankCandidates(html, candidatesFor(rankSource), targetNodeId);
+  const best = options[0];
   if (best === undefined) throw new Error('no selector matches the picked node — this should not happen, since the node came from this same document');
+  const generatedId = leaf?.id !== undefined && !isStableId(leaf.id) ? leaf.id : undefined;
   return {
     selector: best.selector,
     tier: best.tier,
     take,
-    matches: best.matches
+    matches: best.matches,
+    alternatives: alternativesOf(options),
+    ...(generatedId !== undefined && {
+      generatedId
+    })
   };
 }
+/** How many other selectors a person is offered at most. */
+const MAX_ALTERNATIVES = 6;
+/** The verified candidates as the options shown to the person: the ones that reach the clicked node, each selector once. */
+function alternativesOf(options) {
+  const seen = new Set();
+  const alternatives = [];
+  for (const option of options) {
+    if (!option.hitsTarget || seen.has(option.selector)) continue;
+    seen.add(option.selector);
+    alternatives.push({
+      selector: option.selector,
+      tier: option.tier,
+      matches: option.matches
+    });
+    if (alternatives.length === MAX_ALTERNATIVES) break;
+  }
+  return alternatives;
+}
 
 /** A leaf element's own text longer than this is cut, with an ellipsis. */
 const TEXT_LIMIT = 80;
@@ -6102,6 +6297,10 @@ function dispatch(command, state) {
       {
         return handleGridView(state, command);
       }
+    case 'grid-rows':
+      {
+        return Promise.resolve(handleGridRows(state, command));
+      }
     case 'grid-preview':
       {
         return Promise.resolve(handleGridPreview(state, command));
@@ -6189,5 +6388,5 @@ async function main(argv, options = {}) {
   process.on('SIGTERM', shutdown);
 }
 
-export { chooseFolderCommandSchema, chooseFolderViewSchema, deckChartSeriesViewSchema, deckChartViewSchema, deckDocumentViewSchema, deckPreviewCommandSchema, deckPreviewOptionsSchema, deckShapeViewSchema, deckSlideViewSchema, deckTablePreviewMatchSchema, deckTablePreviewViewSchema, deckViewCommandSchema, detectUrlCommandSchema, detectUrlViewSchema, 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 };
+export { chooseFolderCommandSchema, chooseFolderViewSchema, deckChartSeriesViewSchema, deckChartViewSchema, deckDocumentViewSchema, deckPreviewCommandSchema, deckPreviewOptionsSchema, deckShapeViewSchema, deckSlideViewSchema, deckTablePreviewMatchSchema, deckTablePreviewViewSchema, deckViewCommandSchema, detectUrlCommandSchema, detectUrlViewSchema, documentTreeCommandSchema, documentTreeNodeViewSchema, documentTreeViewSchema, domTreeNodeViewSchema, explainWhyCommandSchema, fetchStartPage, fetchStartPageCommandSchema, fieldPickSchema, fieldTraceSchema, gridCellViewSchema, gridMergeViewSchema, gridPreviewCommandSchema, gridPreviewOptionsSchema, gridRowsCommandSchema, gridRowsViewSchema, 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, selectorAlternativeSchema, 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/page-snapshot/index.d.ts

@@ -3,6 +3,8 @@ export type { UrlKind } from './detect-url.use-case';
 export { fetchStartPage } from './fetch-start-page.use-case';
 export { takeSnapshot } from './take-snapshot.use-case';
 export type { SnapshotResult } from './take-snapshot.use-case';
+export { inlineLocalImages } from './inline-local-images.use-case';
+export type { InlinedImages } from './inline-local-images.use-case';
 export { rewriteDocument } from './rewrite-document.mapper';
 export type { RewrittenDocument } from './rewrite-document.mapper';
 export { hiddenMarksScript, HIDDEN_ATTRIBUTE } from './hidden-marks.algorithm';

package/dist/page-snapshot/inline-local-images.use-case.d.ts

@@ -0,0 +1,19 @@
+/** What `inlineLocalImages` made of a document. */
+export interface InlinedImages {
+    html: string;
+    /** How many images were embedded. */
+    inlined: number;
+    /** How many pictures could not be found next to the file (or were too big), so they stay as they were. */
+    missing: number;
+}
+/**
+ * A document read from a file (a Markdown file, say) names its pictures by paths beside it, which the browser showing it cannot open. The
+ * pictures that sit in the document's own folder are embedded in the page as data addresses, so they show; ones that are not there are counted
+ * so the person is told. Nothing outside the document's folder is ever read.
+ *
+ * @param html - The document as HTML, its addresses already made absolute against `documentUrl`.
+ * @param documentUrl - The document's own `file:` address.
+ * @returns The page with the pictures embedded, and how many were embedded and how many could not be.
+ */
+export declare function inlineLocalImages(html: string, documentUrl: string): Promise<InlinedImages>;
+//# sourceMappingURL=inline-local-images.use-case.d.ts.map

package/dist/selector-inference/selector-ranking.policy.d.ts

@@ -14,7 +14,7 @@ export interface RankedCandidate extends SelectorCandidate {
  * Ordering: candidates that do not match `targetNodeId` (when given) sort
  * last; among the rest, best tier first, and within a tier the fewest
  * matches first (the most specific selector that still hits the target).
- * A candidate matching nothing is dropped entirely: it is not a real option.
+ * Equal on all that, the selector naming more ids and classes comes first. A candidate matching nothing is dropped entirely: it is not a real option.
  *
  * @param html - The document to verify against (the snapshot, or the live page for the second, cross-check pass).
  * @param candidates - Unranked candidates, e.g. from `candidatesFor`.

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

@@ -8,6 +8,6 @@ export { previewDeckTable, previewGridTable, previewPdfTable } from './table-pre
 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 { workbookDocumentView, workbookSheetRows } 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/workbook-view.mapper.d.ts

@@ -22,7 +22,10 @@ export interface GridSheetView {
     hiddenRows: number[];
     /** The widest row's own length, ragged rows included — for the grid to size its columns. */
     columnCount: number;
+    /** The sheet's rows; only the first window of them when `rowCount` is set (the rest are fetched with `grid-rows`). */
     rows: GridCellView[][];
+    /** How many rows the sheet has, set only when `rows` holds just the first window of them. */
+    rowCount?: number;
     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>;
@@ -55,5 +58,18 @@ export interface WorkbookDocumentView {
  * @param document - The read workbook (a spreadsheet or a CSV).
  * @returns The view.
  */
-export declare function workbookDocumentView(document: WorkbookDocument): WorkbookDocumentView;
+export declare function workbookDocumentView(document: WorkbookDocument, options?: {
+    windowRows?: number;
+}): WorkbookDocumentView;
+/**
+ * A run of one sheet's rows, typed, for a grid that only holds the screens around where it is scrolled to (the rest of a big file is never
+ * sent to the browser until it is needed).
+ *
+ * @param document - The read workbook.
+ * @param sheetIndex - Which sheet, 0-based.
+ * @param from - The first row, 0-based.
+ * @param count - How many rows at most.
+ * @returns The rows (fewer at the end of the sheet, none past it).
+ */
+export declare function workbookSheetRows(document: WorkbookDocument, sheetIndex: number, from: number, count: number): GridCellView[][];
 //# sourceMappingURL=workbook-view.mapper.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, chooseFolderCommandSchema, openPathCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, detectUrlCommandSchema, 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, detectUrlViewSchema, 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, DetectUrlCommand, 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, DetectUrlView, 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, detectUrlCommandSchema, 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, detectUrlViewSchema, snapshotViewSchema, verifySelectorViewSchema, fieldPickSchema, inferSelectorViewSchema, selectorAlternativeSchema, sentencePartSchema, outlineCardSchema, outlineBracketSchema, outlineNodeSchema, outlineViewSchema, whyViewSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewOptionsSchema, tablePreviewCommandSchema, regionPreviewCommandSchema, regionPreviewMatchSchema, regionPreviewViewSchema, gridViewCommandSchema, gridRowsCommandSchema, gridPreviewOptionsSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewOptionsSchema, deckPreviewCommandSchema, domTreeNodeViewSchema, pageDataFindingSchema, inspectViewSchema, observedResponseSchema, responsesSeenViewSchema, documentTreeNodeViewSchema, documentTreeViewSchema, pdfCellViewSchema, pdfRowViewSchema, pdfPageViewSchema, pdfDocumentViewSchema, tablePreviewTableSchema, tablePreviewBandSchema, tablePreviewMatchSchema, tablePreviewViewSchema, gridCellViewSchema, gridMergeViewSchema, gridRowsViewSchema, 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, DetectUrlCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, MissingWhyTarget, RejectedWhyTarget, WhyTarget, ExplainWhyCommand, InspectPageCommand, ResponsesSeenCommand, DocumentTreeCommand, PdfViewCommand, TablePreviewOptions, TablePreviewCommand, RegionPreviewCommand, GridViewCommand, GridRowsCommand, 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, DetectUrlView, SnapshotView, VerifySelectorView, FieldPick, InferSelectorView, SelectorAlternative, SentencePart, OutlineCard, OutlineBracket, OutlineNode, OutlineView, WhyView, DomTreeNodeView, PageDataKind, PageDataFindingView, InspectView, ObservedResponseView, ResponsesSeenView, DocumentTreeNodeView, DocumentTreeView, PdfCellView, PdfRowView, PdfPageView, PdfDocumentView, TablePreviewTableView, TablePreviewBandView, TablePreviewMatchView, TablePreviewView, GridCellView, GridMergeView, GridRowsView, 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/page-snapshot/index.d.ts

@@ -3,6 +3,8 @@ export type { UrlKind } from './detect-url.use-case.js';
 export { fetchStartPage } from './fetch-start-page.use-case.js';
 export { takeSnapshot } from './take-snapshot.use-case.js';
 export type { SnapshotResult } from './take-snapshot.use-case.js';
+export { inlineLocalImages } from './inline-local-images.use-case.js';
+export type { InlinedImages } from './inline-local-images.use-case.js';
 export { rewriteDocument } from './rewrite-document.mapper.js';
 export type { RewrittenDocument } from './rewrite-document.mapper.js';
 export { hiddenMarksScript, HIDDEN_ATTRIBUTE } from './hidden-marks.algorithm.js';

package/dist/src/page-snapshot/inline-local-images.use-case.d.ts

@@ -0,0 +1,19 @@
+/** What `inlineLocalImages` made of a document. */
+export interface InlinedImages {
+    html: string;
+    /** How many images were embedded. */
+    inlined: number;
+    /** How many pictures could not be found next to the file (or were too big), so they stay as they were. */
+    missing: number;
+}
+/**
+ * A document read from a file (a Markdown file, say) names its pictures by paths beside it, which the browser showing it cannot open. The
+ * pictures that sit in the document's own folder are embedded in the page as data addresses, so they show; ones that are not there are counted
+ * so the person is told. Nothing outside the document's folder is ever read.
+ *
+ * @param html - The document as HTML, its addresses already made absolute against `documentUrl`.
+ * @param documentUrl - The document's own `file:` address.
+ * @returns The page with the pictures embedded, and how many were embedded and how many could not be.
+ */
+export declare function inlineLocalImages(html: string, documentUrl: string): Promise<InlinedImages>;
+//# sourceMappingURL=inline-local-images.use-case.d.ts.map

package/dist/src/selector-inference/selector-ranking.policy.d.ts

@@ -14,7 +14,7 @@ export interface RankedCandidate extends SelectorCandidate {
  * Ordering: candidates that do not match `targetNodeId` (when given) sort
  * last; among the rest, best tier first, and within a tier the fewest
  * matches first (the most specific selector that still hits the target).
- * A candidate matching nothing is dropped entirely: it is not a real option.
+ * Equal on all that, the selector naming more ids and classes comes first. A candidate matching nothing is dropped entirely: it is not a real option.
  *
  * @param html - The document to verify against (the snapshot, or the live page for the second, cross-check pass).
  * @param candidates - Unranked candidates, e.g. from `candidatesFor`.