@pipelex/mthds-form 0.13.0 → 0.14.0

package/dist/react/index.d.ts

@@ -3,11 +3,12 @@ export { a as FieldRenderer, b as FieldRendererProps } from '../field-renderer-C
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { BooleanRunField, DateRunField, EnumRunField, FileRunField, ListRunField, NumberRunField, ObjectRunField, ProseRunField, TextRunField, UnknownRunField, RunField, ConceptCategory } from '../core/descriptor.js';
+import { PipeInputFormDescriptor, PipeIOContract } from 'mthds/protocol';
+import { Readiness } from '../core/readiness.js';
 import { SaveFiles, SaveFile, SaveResult } from '../core/save-plan.js';
 import { StuffFileKind } from '../core/stuff-files.js';
 import { HtmlContentView } from '../core/native-content.js';
 import '../core/contracts.js';
-import 'mthds/protocol';
 import '../core/file-formats.js';
 
 interface BooleanFieldProps {
@@ -164,6 +165,14 @@ interface ObjectFieldProps {
  * A structured concept: its sub-fields rendered inside one hairline-grouped
  * card so nesting stays legible. Empty optional sub-fields collapse behind a
  * "+ N optional" toggle - required and already-filled fields always show.
+ *
+ * A CLOSED optional sub-structure (absent value) folds behind that toggle and
+ * is counted like any empty optional field. The toggle also opens and closes
+ * them: expanding writes `seedObjectValue` into every closed one, collapsing
+ * writes `undefined` into every one, so they leave the payload. It reads
+ * expanded while any of them is open, so a restored value that holds one
+ * offers to close it. An open optional structure renders like any other: its
+ * label, description and card, with no badge.
  */
 declare function ObjectField({ field, value, onChange, id, error, env }: ObjectFieldProps): react.JSX.Element;
 
@@ -207,6 +216,381 @@ interface UnknownFieldProps {
  */
 declare function UnknownField({ field, value, onChange, id, error, disabled }: UnknownFieldProps): react.JSX.Element;
 
+/**
+ * How a field's LABEL chrome, and the enum values a person reads, should read.
+ * What a control stores never changes.
+ *
+ * - `studio` (default): the field's name verbatim in mono, with its concept
+ *   pill. The name IS the identifier a builder writes in the `.mthds` file, so
+ *   showing it exactly - and typed - is the point. An enum value is shown as its
+ *   code for the same reason: it has to match the bundle and the JSON the
+ *   builder reads next.
+ * - `app`: the field's name as a human question in sans, no concept pill. Inside
+ *   a method app, `full_name` and `native.Text` are implementation detail; the
+ *   person filling the form has never seen the method's source. An enum value
+ *   follows the label and reads as words.
+ *
+ * An enum value is the only value the two presentations show differently. A
+ * number, a text, a date and every other value render the same in both.
+ *
+ * Deliberately a context rather than a prop or a `FieldEnv` flag: only the
+ * components that own label chrome or an enum value's wording read it -
+ * `FieldShell`, `ObjectField`, `BooleanField`, `ListField`, `EnumField` and the
+ * result view - plus the file control, whose card hides a storage reference in
+ * `app`, and threading a prop would have meant editing every field control and
+ * both recursive containers.
+ */
+type FieldPresentation = 'studio' | 'app';
+declare function FieldPresentationProvider({ presentation, children, }: {
+    presentation: FieldPresentation;
+    children: ReactNode;
+}): react.JSX.Element;
+declare function useFieldPresentation(): FieldPresentation;
+/**
+ * `full_name` → `Full name`. Only the first word is capitalised: these are
+ * labels, not titles, and Title Case on every word reads as a form from 2009.
+ * Takes IDENTIFIERS only - snake_case or kebab-case names, where a separator
+ * is structure. An authored `title` never goes through here: it is already
+ * human-facing, and its hyphens are spelling (`E-mail address`), not structure.
+ */
+declare function humanizeFieldName(name: string): string;
+
+interface FieldStrings {
+    /** Badge on an optional field's header row. */
+    optionalBadge: string;
+    selectPlaceholder: string;
+    typeValuePlaceholder: string;
+    writeHerePlaceholder: string;
+    /** Helper under the raw-JSON escape hatch. */
+    jsonHint: string;
+    decrease: string;
+    increase: string;
+    noItemsYet: string;
+    addItem: string;
+    removeItemAria: (index: number) => string;
+    itemsCount: (count: number) => string;
+    /** The same badge for a list the method gave an exact count (`Concept[N]`). */
+    itemsCountOf: (count: number, total: number) => string;
+    /** What a record's table cell says when none of its fields can name it. */
+    fieldsCount: (count: number) => string;
+    uploading: string;
+    dropToUpload: string;
+    dropOrBrowse: string;
+    pasteUrlInstead: string;
+    /**
+     * What a file field says in place of its dropzone when its host has no way to
+     * store a file, so a link is the only way in. The field's format hint follows
+     * it, because the link still has to point at a file the runtime can read.
+     */
+    uploadUnavailable: string;
+    /**
+     * The placeholder in the URL a person may paste instead of uploading. It names
+     * the web's own scheme only: a host whose runner also takes its own storage
+     * references can say so by overriding it, and no default shows an end user a
+     * platform's storage scheme.
+     */
+    urlPlaceholder: string;
+    /**
+     * The accessible name of that URL input, given the field's label as the form
+     * shows it. The field's label is bound to the file input, so without this the
+     * placeholder was the only thing a screen reader announced here.
+     *
+     * The label is EMPTY inside a list row: the list drops each row's label, and
+     * the row number it shows instead is a bare glyph tied to no control. So every
+     * row's input currently carries the same generic name, and giving rows
+     * distinct names is a separate piece of work on the list control.
+     */
+    fileUrlAria: (label: string) => string;
+    /**
+     * The title of an attached file's card when the value carries no filename.
+     * True of a pasted link as well as of an upload, which "Uploaded file" was not.
+     */
+    uploadedFile: string;
+    /**
+     * What names a file carried INSIDE its own URL (a `data:` URL), where a
+     * reference would otherwise be printed: its format and its decoded size. The
+     * string itself is forty thousand characters of base64 and says nothing.
+     */
+    encodedFileSummary: (format: string, bytes: number) => string;
+    preview: string;
+    removeFileAria: string;
+    previewUnavailablePdf: string;
+    /**
+     * What a result slot the run resolved as an absence SHOWS — a dash, not a
+     * sentence. Beside forty values in a grid, "not provided" repeated is louder
+     * than the data; a dash reads as the blank it is.
+     */
+    resultAbsent: string;
+    /**
+     * What that dash SAYS, to a screen reader.
+     *
+     * The two are separate because a glyph and a sentence are answers to different
+     * questions. A table column of hyphens read aloud is "hyphen, hyphen, hyphen",
+     * which is noise rather than information — so the dash is `aria-hidden` and
+     * this rides beside it, visually hidden.
+     */
+    resultAbsentDescription: string;
+    /**
+     * Shown above the raw value when a result cannot be laid out because the
+     * artifacts describing it are absent. It names the CAUSE — the descriptor,
+     * not the data — because the value is right there underneath and a reader
+     * who is not told why will assume the view is broken.
+     */
+    resultUndescribed: string;
+    /** The control that opens a result table row to show the rest of the record. */
+    toggleRowDetails: (index: number) => string;
+    /** The (visually hidden) header of the column those controls sit in. */
+    rowDetailsColumn: string;
+    /** The control that puts a file's whole URL on the clipboard. */
+    copyUrl: string;
+    /** The copy control beside any text value, markdown or not. */
+    copyText: string;
+    /** The download control's label. */
+    download: string;
+    /** Announced while the files are being fetched. */
+    downloading: string;
+    /**
+     * What the whole-result download says when some files did not arrive: the
+     * ones no URL could be found for, and the ones the delivery reported. Takes
+     * the names the files would have been saved under.
+     */
+    downloadIncomplete: (names: readonly string[]) => string;
+    /**
+     * The button beside each file that saves that one file, given the name it
+     * saves under: a gallery of buttons all called "Download" would leave a
+     * screen-reader user unable to tell which file each one saves.
+     */
+    downloadFile: (name: string) => string;
+    /** What that button says when the file did not arrive. */
+    downloadFileFailed: string;
+    /** The control on an HTML page that saves it as a PDF, in one click. */
+    downloadPdf: string;
+    /** What that control says while the PDF is being made. */
+    downloadPdfBusy: string;
+    /** What that control says when the PDF could not be made or saved. */
+    downloadPdfFailed: string;
+    /**
+     * Shown in place of an HTML page for the moment the stored pictures it names
+     * are being resolved through the host.
+     */
+    pageLoading: string;
+    /**
+     * The page's own HTML download, beside "Download PDF" on a result that is
+     * one page, where a bare "Download" would not say which of the two it saves.
+     */
+    downloadHtml: string;
+    /**
+     * The dialog that asks for a download's name, when the host turns
+     * `downloads.askFileName` on: its title, which also names the field, and its
+     * two buttons.
+     */
+    fileNameTitle: string;
+    fileNameCancel: string;
+    fileNameConfirm: string;
+    /** The result panel's two views, and the control that copies the payload. */
+    viewRendered: string;
+    viewJson: string;
+    copyJson: string;
+    resultViewGroup: string;
+    yes: string;
+    no: string;
+    /**
+     * Shown when a picked file is not a format this slot accepts. Takes the
+     * slot's own formats as the hint names them (`PNG, JPG`), after any narrowing
+     * a host applied, so the message names what WOULD have worked - "not
+     * accepted" on its own leaves the user guessing at the list they just failed.
+     */
+    unsupportedFileType: (formats: string) => string;
+    /** The optional-entries disclosure ("field" inside a concept, "input" at top level). */
+    hideOptionalFields: string;
+    hideOptionalInputs: string;
+    optionalFieldsCount: (count: number) => string;
+    optionalInputsCount: (count: number) => string;
+    /**
+     * The mark `MethodForm` puts on an input the run needs and does not have,
+     * once the person has tried to run.
+     */
+    requiredField: string;
+    /**
+     * The mark on an optional input that was started but is not complete, once
+     * the person has tried to run: a started structure owes its concept every
+     * required field.
+     */
+    incompleteField: string;
+    /** What a file field says when the host's `uploadFile` rejected its file. */
+    uploadFailed: string;
+}
+/** The English strings, which every control falls back to. Kept under this name for existing hosts. */
+declare const DEFAULT_FIELD_STRINGS: FieldStrings;
+/**
+ * Set the strings every control below speaks. `locale` picks a language pack by its code (`fr`,
+ * `fr-FR`, `en-GB`…; an unknown one falls back to English), and `strings` overrides single keys
+ * on top of it. Both are optional: with neither, the controls speak English.
+ */
+declare function FieldStringsProvider({ locale, strings, children, }: {
+    locale?: string;
+    strings?: Partial<FieldStrings>;
+    children: ReactNode;
+}): react.JSX.Element;
+/** The strings the nearest provider supplies (English defaults when none does). */
+declare function useFieldStrings(): FieldStrings;
+
+/**
+ * A whole method's input form: every input of one pipe, built from its
+ * input-form descriptor and its contract, with the state a host would
+ * otherwise hand-write around `FieldRenderer` - the seed, the uploads, the
+ * top-level optional disclosure, the required marks and the run gate.
+ *
+ * It is two pieces, so the consumer keeps what is its own. `useMethodForm`
+ * holds the state and hands back the values, the run inputs and whether they
+ * are ready, wherever in the host's tree it is called - typically beside the
+ * run button. `MethodForm` renders the fields for that state and nothing else:
+ * no panel, no heading, no run button, no history, no `<form>` element. See
+ * docs/method-form.md.
+ */
+/** The form's values, keyed by input name, in the controls' own shape. */
+type MethodFormValues = Record<string, unknown>;
+/** What a host's upload resolves to: the stored file's URL, or its URL and name. */
+type UploadedFile = string | {
+    url: string;
+    filename?: string;
+};
+/** Where a dropped file goes: its field's id, which is its value path, split. */
+interface MethodFormUploadContext {
+    /** The field's id, a dotted value path (`photos.1`, `invoice.source`). */
+    id: string;
+    /** The same path, split: what `setValueAtPath` takes. */
+    path: string[];
+}
+interface UseMethodFormOptions {
+    /** The pipe's input-form descriptor (`getPipeInputForm`). */
+    descriptor: PipeInputFormDescriptor;
+    /** The pipe's entry in `pipe_io_contracts` (`getPipeIOContract`). */
+    contract: PipeIOContract;
+    /**
+     * A transform over the derived fields, applied once before anything else
+     * reads them: narrowing a file slot (`narrowFileFormats`), dropping a child
+     * the host never sends. Pass a stable function (module-level or memoized):
+     * the fields are re-derived when it changes.
+     */
+    prepareFields?: (fields: RunField[]) => RunField[];
+    /**
+     * Input names to show first, in this order. Every input not named keeps its
+     * descriptor order after them; a name no input has is ignored.
+     */
+    order?: readonly string[];
+    /**
+     * What the form holds until its first edit. Absent or `null`, the method's
+     * own seed (`seedInputs`: the authored defaults, every optional structure
+     * closed). A function receives that seed and returns the values, for a host
+     * that lays something the method cannot know over it (today's date). Read on
+     * every render until the first edit, so it may change after hydration; from
+     * the first edit the form owns its values, and `reset` goes back to it.
+     */
+    initialValues?: MethodFormValues | ((seed: MethodFormValues) => MethodFormValues) | null;
+    /**
+     * Stores a dropped or picked file and resolves to what the field holds. Its
+     * presence is the capability: without it every file field is link-only (see
+     * docs/upload-seam.md). A rejection marks the field's upload as failed with
+     * `FieldStrings.uploadFailed`; the next file dropped there clears it. When
+     * it resolves to a bare URL, or omits the name, the file's own name is kept.
+     */
+    uploadFile?: (file: File, context: MethodFormUploadContext) => Promise<UploadedFile>;
+}
+/** What the form says to its consumer: the values, the run inputs, the gate. */
+interface MethodFormState {
+    /** The fields the form renders, derived, prepared and ordered. */
+    fields: RunField[];
+    /** The current values, in the controls' shape. */
+    values: MethodFormValues;
+    /**
+     * The values as a run takes them: each input as `{ concept, content }`, an
+     * unfilled optional input left out, an empty plural input sent as `[]`
+     * (`apiInputsFromRunValues`). What a run call's `inputs` takes.
+     */
+    inputs: Record<string, unknown>;
+    /** How many of the inputs that gate a run are filled, and which are not. */
+    readiness: Readiness;
+    /** Whether a file upload is still in flight. */
+    uploading: boolean;
+    /** Whether a run may start: every gating input filled and no upload in flight. */
+    ready: boolean;
+    /** Whether `attempt` has been called since the last reset: required marks show. */
+    attempted: boolean;
+}
+/** The handle `useMethodForm` returns, and `MethodForm` renders. */
+interface MethodFormController extends MethodFormState {
+    /** Replace the values, or update them from the previous ones. */
+    setValues: (next: MethodFormValues | ((previous: MethodFormValues) => MethodFormValues)) => void;
+    /**
+     * Back to `values` (a past run's inputs, say), or to the initial values when
+     * none is given. Forgets the edits, the attempt, the failed uploads and any
+     * upload still in flight, whose result is then dropped.
+     */
+    reset: (values?: MethodFormValues | null) => void;
+    /**
+     * The run button's press: marks the attempt, so every gating input still
+     * empty shows its required mark, and answers whether the run may start.
+     */
+    attempt: () => boolean;
+    /** Ids (value paths) with an upload in flight. Read by `MethodForm`. */
+    uploadingIds: ReadonlySet<string>;
+    /** Ids whose last upload failed. Read by `MethodForm`. */
+    failedUploadIds: ReadonlySet<string>;
+    /** The upload seam `MethodForm` hands its file fields, when the host uploads. */
+    dropFile: ((id: string, file: File) => void) | undefined;
+}
+/**
+ * The state of one method's input form. See `UseMethodFormOptions` for what it
+ * takes and `MethodFormController` for what it gives back; render it with
+ * `<MethodForm form={...} />`.
+ *
+ * A different method is a different form: remount (a new `key`) when the
+ * descriptor changes, as values belong to the inputs they were typed for.
+ */
+declare function useMethodForm({ descriptor, contract, prepareFields, order, initialValues, uploadFile, }: UseMethodFormOptions): MethodFormController;
+interface MethodFormProps {
+    /** The state to render, from `useMethodForm`. */
+    form: MethodFormController;
+    /** Holds every control read-only, as a host does while a run is in flight. */
+    disabled?: boolean;
+    /** `FieldEnv.allowUrl`: `false` takes the "paste a URL instead" link away. */
+    allowUrl?: boolean;
+    /** `FieldEnv.resolveUrl`: turns a stored reference into a URL a preview can load. */
+    resolveUrl?: (uri: string) => Promise<string | null>;
+    /**
+     * Whether the empty optional inputs fold behind a "+ N optional inputs"
+     * disclosure (the default), as they do inside a structure. `false` shows
+     * every input; a closed optional structure still folds, since the
+     * disclosure is what opens it.
+     */
+    foldOptional?: boolean;
+    /**
+     * A message per input name, shown on that input over the form's own marks:
+     * a server gate's verdict, say.
+     */
+    errors?: Readonly<Record<string, string>>;
+    /** Mounts `FieldStringsProvider` with this locale (`fr`, `fr-FR`…). */
+    locale?: string;
+    /** Mounts `FieldStringsProvider` with these keys over the locale's pack. */
+    strings?: Partial<FieldStrings>;
+    /** Mounts `FieldPresentationProvider`; absent, the nearest one applies. */
+    presentation?: FieldPresentation;
+    /** Classes for the stack the fields sit in. */
+    className?: string;
+}
+/**
+ * Every input of the method `form` holds, rendered through `FieldRenderer`.
+ *
+ * Each input's id is its name, so a file's upload id is its value path. A
+ * gating input still empty after `form.attempt()` is marked `requiredField`,
+ * and an optional input started but not complete `incompleteField`; a host's
+ * `errors` entry replaces either. The top-level "+ N optional inputs"
+ * disclosure folds and opens exactly as the one inside a structure does,
+ * optional structures included.
+ */
+declare function MethodForm({ locale, strings, presentation, ...props }: MethodFormProps): react.ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
 interface ResultFieldProps {
     field: RunField;
     value: unknown;
@@ -228,6 +612,71 @@ interface ResultFieldProps {
  */
 declare function ResultField(props: ResultFieldProps): react.JSX.Element;
 
+/**
+ * The `pipelex-storage://` references inside an HTML page, exchanged for URLs a
+ * browser can load before the page is framed, rasterised or saved.
+ *
+ * A method that renders a page (a quote, an invoice) embeds the pictures it
+ * produced as `<img src="pipelex-storage://…">`. The file arms of the result
+ * view hand such a reference to the host's resolver, but a page is markup, and
+ * nothing inside it went through that seam: the frame's policy refuses the
+ * scheme, so every picture showed as a broken image, and a host had to rewrite
+ * the markup itself before handing it over. Here it is done once, for every
+ * place a page goes: the preview, the PDF and the HTML download.
+ *
+ * ## What is read, and how
+ *
+ * The markup is parsed with `DOMParser`, never searched with a pattern, because
+ * an attribute value a regex finds may be inside a comment, a `<textarea>` or
+ * another attribute, and an `<img>` it misses may be spelled with single
+ * quotes, no quotes or an uppercase tag. A `DOMParser` document is inert: no
+ * script runs and nothing is fetched while it is read. A whole document is
+ * parsed as one; a fragment is parsed as a `<template>`'s content, which keeps
+ * a leading `<style>` or `<meta>` where it was rather than moving it into a
+ * head the fragment never had.
+ *
+ * The references read are the ones a page fetches as a picture: `src` and
+ * `srcset` on `<img>` and `<source>`, a `<video>`'s `poster`, the legacy
+ * `background` attribute, an SVG `<image>`'s `href`, and every CSS `url()` in a
+ * `style` attribute or a `<style>` element (inside CSS, which is text, the
+ * `url()` tokens are found with a pattern; the HTML around them never is).
+ *
+ * ## How each reference is answered
+ *
+ * Every distinct reference is asked for once. When the host gave a bulk
+ * resolver (`resolveUrls`), all of them go in one call, which is one round trip
+ * for a page with twenty pictures; its answer is then checked by the URL gate
+ * (`viewableUrl`), as every resolver's answer is. A reference the bulk answer
+ * left out, or answered with something the gate refuses, is asked of the
+ * per-reference resolver (`resolveUrl`) next. A reference neither answers is
+ * left as it was: the picture stays broken, and the page still shows.
+ *
+ * A bulk resolver that rejects, throws or takes longer than `timeoutMs` is
+ * read as having answered nothing, so a page never waits on it for good.
+ *
+ * ## What comes back
+ *
+ * The markup with each answered reference replaced, serialised from the parsed
+ * tree. Markup holding no reference that changed comes back as the very same
+ * string, so a page with no stored pictures is never re-serialised.
+ */
+/** Answers a batch of stored references; see `ResultEnvProvider`'s `resolveUrls`. */
+type ResolveUrls = (uris: readonly string[]) => Promise<ReadonlyMap<string, string | null | undefined> | Readonly<Record<string, string | null | undefined>>>;
+interface MarkupResolvers {
+    /** One reference at a time, synchronously, as the result view's file arms ask. */
+    resolveUrl?: (url: string) => string | undefined;
+    /** Every reference of the page in one call. Asked first when present. */
+    resolveUrls?: ResolveUrls;
+}
+/**
+ * The markup with every stored reference its pictures name resolved through
+ * the host's resolvers; see the module comment for the order they are asked in.
+ * Never rejects, and never waits on a bulk resolver past `timeoutMs`.
+ */
+declare function resolveHtmlStorageUrls(markup: string, { resolveUrl, resolveUrls }: MarkupResolvers, { timeoutMs }?: {
+    timeoutMs?: number;
+}): Promise<string>;
+
 /**
  * The host's seam for turning a stored reference into something a browser can
  * fetch.
@@ -329,9 +778,47 @@ interface DownloadDisplay {
      * `'document'`, and `'markup'` for an HTML page.
      */
     files?: boolean | readonly StuffFileKind[];
+    /**
+     * The "Download PDF" control on each HTML page, which makes a PDF of the
+     * page in the browser and saves it. Drawn unless `false`.
+     */
+    pdf?: boolean;
+    /**
+     * Ask the reader for the file's name before each download, in a dialog
+     * pre-filled with the name the plan chose. Off unless `true`.
+     *
+     * It is a behaviour of every download control rather than a control of its
+     * own, which is why it sits beside the three that say which are drawn: the
+     * PDF, the page's HTML, a file's own button, and the whole-result download.
+     * A whole-result download saving one file asks for that file's name; one
+     * saving several asks for the name they share, the base name, which names
+     * the JSON copy and every file the payload did not name itself.
+     */
+    askFileName?: boolean;
 }
 interface ResultEnv {
     resolveUrl?: ResolveUrl;
+    /**
+     * Every stored reference an HTML page's pictures name, resolved in one call.
+     *
+     * A `native.Html` page embeds the pictures its method produced as
+     * `pipelex-storage://` references (`<img src>`, `srcset`, a CSS `url()`),
+     * which the frame cannot load. Before the page is shown, made into a PDF or
+     * downloaded as HTML, the view collects the distinct references it holds and
+     * hands them here, once, and writes each URL this answers into the page.
+     *
+     * Async and BULK, unlike `resolveUrl`, because a page is the one place every
+     * reference is known at once, and a host that presigns can mint them all in
+     * one round trip. Answer a `Map` or a plain record from reference to URL;
+     * leave a reference out, or answer `null`, for one this host cannot resolve.
+     * Each answer passes the URL gate like any resolver's.
+     *
+     * Optional. Unset, or for a reference it leaves out, each reference is asked
+     * of `resolveUrl`; neither answering leaves that picture broken and the page
+     * shown. A call that rejects or takes longer than ten seconds is read as no
+     * answer, so a page is never held back by it for good.
+     */
+    resolveUrls?: ResolveUrls;
     resolveShareUrl?: ResolveShareUrl;
     proseImages?: ProseImages;
     /**
@@ -370,7 +857,7 @@ interface ResultEnv {
      */
     tableColumns?: number;
 }
-declare function ResultEnvProvider({ resolveUrl, resolveShareUrl, proseImages, tableColumns, saveFiles, downloads, children, }: ResultEnv & {
+declare function ResultEnvProvider({ resolveUrl, resolveUrls, resolveShareUrl, proseImages, tableColumns, saveFiles, downloads, children, }: ResultEnv & {
     children: ReactNode;
 }): react.JSX.Element;
 /**
@@ -413,6 +900,23 @@ declare function useProseImages(): ProseImages;
  * match a host's design system. It is a renderer that cannot be improved without
  * shipping the engine. If a plain-text form is wanted, it is a COPY FORMAT and
  * belongs behind a copy control, not beside the view that reads the standard.
+ *
+ * ## Which views a reader is offered
+ *
+ * The JSON view is a builder's tool. In `studio` both views are offered; in
+ * `app` only the result is, so a person reading a method app's answer is not
+ * handed a switch to a receipt they have no use for. `views` overrides either
+ * default, and the switch is drawn only when it offers more than one view.
+ *
+ * ## A result that is one page
+ *
+ * A result whose node IS `native.Html`, or a concept refining it (read off the
+ * descriptor's `concept_ref` and `refines`, never off the value), is one page,
+ * and the panel shows it as that page: one row holding the title (none in
+ * `app`, where the page carries its own), "Download
+ * PDF" as the primary control and one HTML download, then the page edge to
+ * edge with no box around it. The page's own control row and the header's
+ * download saved the same file, so they are one control here.
  */
 type StuffViewerView = 'rendered' | 'json';
 interface StuffViewerProps {
@@ -438,7 +942,18 @@ interface StuffViewerProps {
      * is named after the thing they were reading rather than `output.json`.
      */
     name?: string;
-    /** Which view opens first. Rendered, unless a host has a reason. */
+    /**
+     * Which views the reader may switch between, in the switch's order. Unset,
+     * it follows the presentation: both in `studio`, the rendered result alone in
+     * `app`, where the JSON receipt is a builder's tool. The switch is drawn only
+     * when more than one view is offered; an empty list counts as the rendered
+     * result alone.
+     */
+    views?: readonly StuffViewerView[];
+    /**
+     * Which view opens first. Rendered, unless a host has a reason. A view not
+     * among `views` opens the first one offered instead.
+     */
     defaultView?: StuffViewerView;
     /**
      * Names the saved files, whichever control saved them: the base name names
@@ -507,17 +1022,189 @@ interface HtmlPreviewProps {
      * 480px showed three paragraphs of one with a scrollbar down the side while
      * the panel around it sat empty — the reader scrolls twice to read once. The
      * frame still sizes itself to its CONTENT, so a short snippet stays short;
-     * this only says how far it may grow before scrolling instead.
+     * this only says how far it may grow before scrolling instead. A whole
+     * document has no limit unless one is passed: it is a page, and is read whole.
      */
     maxHeight?: number;
     /**
-     * The frame's `img-src`. Defaults to `data: https:` — a method's HTML result
-     * embeds the images that method produced. Pass `"data:"` to block remote
-     * images entirely, or name an origin to allow only your own storage.
+     * The frame's `img-src`. Defaults to `'self' data: https:` — a method's HTML
+     * result embeds the images that method produced. Pass `"data:"` to block
+     * remote images entirely, or name an origin to allow only your own storage.
+     */
+    imgSrc?: string;
+    /**
+     * The frame's `font-src`. Follows `imgSrc` when unset: a page's fonts come
+     * from where its images do, the host's own origin or a font service, and a
+     * blocked one silently changes the face the page was designed in.
      */
+    fontSrc?: string;
+    /**
+     * Draw the "Download PDF" control above the page. Follows the result
+     * environment's `downloads.pdf` when unset, which draws it. The result view
+     * passes `false` and draws its own in the page's control row.
+     */
+    downloadPdf?: boolean;
+    /** The PDF's file name, without the extension. `page` when unset. */
+    pdfFileName?: string;
+    /**
+     * Draw a whole document with no border and no rounding, edge to edge with
+     * its container: for a page that IS the view (a result that is one page),
+     * where a box around it is chrome around chrome. A fragment keeps its themed
+     * box either way, since that box is its padding.
+     */
+    bare?: boolean;
+    /**
+     * Let a whole document's frame shrink to the height its container leaves it
+     * and scroll inside itself, when that container is a flex column of bounded
+     * height (a host's scrolling panel, `flex min-h-0 flex-col overflow-y-auto`).
+     * The page is then the one scroll container under the pointer, so the first
+     * wheel gesture over it scrolls it. In any other container the frame stays
+     * as tall as the page. The result view passes it for a result that is one
+     * page; a fragment ignores it.
+     */
+    fill?: boolean;
+}
+declare function HtmlPreview({ content, maxHeight, imgSrc, fontSrc, downloadPdf, pdfFileName, bare, fill, }: HtmlPreviewProps): react.JSX.Element;
+
+/**
+ * A page's print stylesheet, applied on screen: what the PDF copy needs before
+ * it is laid out and rasterised, since a browser offers no way to lay a frame
+ * out as `print` media short of printing it.
+ *
+ * ## Promoting the print rules
+ *
+ * Every media query in the copy's stylesheets is rewritten to say what it would
+ * say on paper: a query on `print` becomes one on `all`, a query on `screen` (or
+ * any other media type) becomes `not all`, and `not` flips both, so `@media
+ * print { … }` now applies and `@media screen { … }` no longer does, in the
+ * order the author wrote them. A query with no media type (`@media (min-width:
+ * 600px)`) is left alone: it is about the page's size, which the copy is laid
+ * out at. A `<style media="print">` is rewritten the same way.
+ *
+ * Rewriting the queries in place, rather than unwrapping the rules out of their
+ * blocks, keeps the cascade exactly as written: a print rule still comes after
+ * the screen rules it overrides, and nested blocks keep their nesting.
+ *
+ * ## The page box
+ *
+ * `@page` says the sheet's size and margins. A rule with no selector is read,
+ * the last one winning per property, as in the cascade; `:first`, `:left` and
+ * named pages are not. A size is a keyword (`A4`, `letter`, optionally with
+ * `landscape`) or two lengths; a margin is a length. What a page does not say is
+ * A4 portrait with 1 cm margins on every side — what Chrome's own print uses
+ * when a page names none, so a template laid out against Chrome's print lands
+ * the same way.
+ */
+/** A page's size and margins, in CSS pixels (96 to the inch). */
+interface PageBox {
+    width: number;
+    height: number;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+
+/**
+ * Make a PDF of an HTML page in the browser, with no server and no dialog: lay
+ * a script-free copy of the page out as it would print, rasterise it, cut the
+ * raster into pages at block boundaries, and wrap the pages in a PDF.
+ *
+ * ## The copy
+ *
+ * The page is laid out in a hidden frame of its own, never the preview on
+ * screen, which carries the host's theme and is sized to the panel. The frame
+ * document is the preview's (`html-frame.ts`), under the same policy: the same
+ * `img-src` and `font-src`, no scripts. It is sandboxed `allow-same-origin` and
+ * nothing else, so the host can read its layout and computed style, and the
+ * markup still runs nothing: same-origin is dangerous only together with
+ * scripts.
+ *
+ * Once loaded, every image is made eager and awaited and every face the page
+ * declares is asked for and awaited, a face used only in print included; then
+ * the page's print rules are promoted (`print-media.ts`), its `@page` box read,
+ * and the frame resized to the page's drawable width and height, so the copy is
+ * laid out as the print engine would lay it out on one sheet.
+ *
+ * ## The raster
+ *
+ * `modern-screenshot` clones the copy into an SVG `foreignObject`, inlining each
+ * element's computed style and embedding the fonts and images it uses as data
+ * URLs, which is what lets the browser paint it as an image. It is rendered
+ * once for the flow, with the elements laid out `position: fixed` left out,
+ * and once for those elements alone at one page's height, laid over every page
+ * as a print engine repeats them. Each stretch of the flow a page draws is
+ * painted from the SVG through its own `viewBox` at `scale` device pixels per
+ * CSS pixel, so only one page is ever held as pixels, and text is rasterised
+ * at print resolution rather than scaled up.
+ *
+ * ## The PDF
+ *
+ * Each page is encoded as a JPEG and placed full-bleed on a page of the size
+ * the page box says, by `jspdf`. Both libraries are loaded with `import()` on
+ * first use, so a host that never makes a PDF ships neither.
+ */
+interface HtmlPdfOptions {
+    /** The copy's `img-src`, as `HtmlPreview`'s. */
     imgSrc?: string;
+    /** The copy's `font-src`, as `HtmlPreview`'s. Follows `imgSrc` when unset. */
+    fontSrc?: string;
+    /** The typeface a fragment is laid out in, when its own CSS names none. */
+    fontFamily?: string;
+    /** The PDF's document title, in its metadata. */
+    title?: string;
+    /**
+     * Device pixels per CSS pixel of the raster. 3 (288 dpi) when unset; 2 is
+     * the least that prints crisp.
+     */
+    scale?: number;
+    /** JPEG quality of each page, from 0 to 1. 0.92 when unset. */
+    quality?: number;
 }
-declare function HtmlPreview({ content, maxHeight, imgSrc, }: HtmlPreviewProps): react.JSX.Element;
+/** What `renderHtmlPdf` produced, for a caller that wants more than the bytes. */
+interface HtmlPdf {
+    blob: Blob;
+    pageCount: number;
+    /** The page box the PDF was laid out on, in CSS pixels. */
+    page: PageBox;
+}
+/**
+ * Render `content` to a PDF. Rejects when the copy cannot be built or painted,
+ * or when the libraries that paint and assemble it cannot be loaded.
+ */
+declare function renderHtmlPdf(content: HtmlContentView, { imgSrc, fontSrc, fontFamily, title, scale, quality, }?: HtmlPdfOptions): Promise<HtmlPdf>;
+
+interface PdfDownloadButtonProps {
+    /** The page to make a PDF of. */
+    content: HtmlContentView;
+    /** The PDF's file name, without the extension. `page` when unset or empty. */
+    fileName?: string;
+    /** Where the page sits in the result, for the save plan (`path`). */
+    path?: string;
+    /** The PDF copy's `img-src`, as `HtmlPreview`'s. */
+    imgSrc?: string;
+    /** The PDF copy's `font-src`, as `HtmlPreview`'s. */
+    fontSrc?: string;
+    /** Draw it as the row's primary control: filled rather than outlined. */
+    primary?: boolean;
+    className?: string;
+}
+/**
+ * "Download PDF" for an HTML page: one click, and the browser saves
+ * `<fileName>.pdf`. The PDF is made in the browser (`renderHtmlPdf`) from a
+ * script-free copy of the page laid out with its print rules, and handed to the
+ * result environment's `saveFiles` like every other download, so a host that
+ * delivers files its own way delivers this one too. The stored pictures the
+ * page names are resolved through the environment's resolvers first, as its
+ * preview's are.
+ *
+ * Busy while the PDF is made, which takes a moment for the fonts and the
+ * raster; a PDF that could not be made or saved turns the control into a
+ * warning, described to assistive technology, until the reader tries again.
+ */
+declare function PdfDownloadButton({ content, fileName, path, imgSrc, fontSrc, primary, className, }: PdfDownloadButtonProps): react.JSX.Element;
 
 interface MarkdownProps {
     text: string;
@@ -577,155 +1264,14 @@ interface OptionalToggleProps {
  * The disclosure for empty optional entries. Optional inputs stay hidden until
  * the user asks for them - required (and already-filled) entries always show, so
  * the form opens at its simplest and grows only on demand. Used at the top level
- * and inside every structured concept, at any nesting depth.
+ * and inside every structured concept, at any nesting depth. An optional
+ * structure folds behind it too, and opens and closes with it: see
+ * `openOptionalStructures` / `closeOptionalStructures` in the core.
  */
 declare function OptionalToggle({ count, expanded, onToggle, noun }: OptionalToggleProps): react.JSX.Element;
 
 declare const fieldControlClass: string;
 
-interface FieldStrings {
-    /** Badge on an optional field's header row. */
-    optionalBadge: string;
-    selectPlaceholder: string;
-    typeValuePlaceholder: string;
-    writeHerePlaceholder: string;
-    /** Helper under the raw-JSON escape hatch. */
-    jsonHint: string;
-    decrease: string;
-    increase: string;
-    noItemsYet: string;
-    addItem: string;
-    removeItemAria: (index: number) => string;
-    itemsCount: (count: number) => string;
-    /** The same badge for a list the method gave an exact count (`Concept[N]`). */
-    itemsCountOf: (count: number, total: number) => string;
-    /** What a record's table cell says when none of its fields can name it. */
-    fieldsCount: (count: number) => string;
-    uploading: string;
-    dropToUpload: string;
-    dropOrBrowse: string;
-    pasteUrlInstead: string;
-    /**
-     * What a file field says in place of its dropzone when its host has no way to
-     * store a file, so a link is the only way in. The field's format hint follows
-     * it, because the link still has to point at a file the runtime can read.
-     */
-    uploadUnavailable: string;
-    /**
-     * The placeholder in the URL a person may paste instead of uploading. It names
-     * the web's own scheme only: a host whose runner also takes its own storage
-     * references can say so by overriding it, and no default shows an end user a
-     * platform's storage scheme.
-     */
-    urlPlaceholder: string;
-    /**
-     * The accessible name of that URL input, given the field's label as the form
-     * shows it. The field's label is bound to the file input, so without this the
-     * placeholder was the only thing a screen reader announced here.
-     *
-     * The label is EMPTY inside a list row: the list drops each row's label, and
-     * the row number it shows instead is a bare glyph tied to no control. So every
-     * row's input currently carries the same generic name, and giving rows
-     * distinct names is a separate piece of work on the list control.
-     */
-    fileUrlAria: (label: string) => string;
-    /**
-     * The title of an attached file's card when the value carries no filename.
-     * True of a pasted link as well as of an upload, which "Uploaded file" was not.
-     */
-    uploadedFile: string;
-    /**
-     * What names a file carried INSIDE its own URL (a `data:` URL), where a
-     * reference would otherwise be printed: its format and its decoded size. The
-     * string itself is forty thousand characters of base64 and says nothing.
-     */
-    encodedFileSummary: (format: string, bytes: number) => string;
-    preview: string;
-    removeFileAria: string;
-    previewUnavailablePdf: string;
-    /**
-     * What a result slot the run resolved as an absence SHOWS — a dash, not a
-     * sentence. Beside forty values in a grid, "not provided" repeated is louder
-     * than the data; a dash reads as the blank it is.
-     */
-    resultAbsent: string;
-    /**
-     * What that dash SAYS, to a screen reader.
-     *
-     * The two are separate because a glyph and a sentence are answers to different
-     * questions. A table column of hyphens read aloud is "hyphen, hyphen, hyphen",
-     * which is noise rather than information — so the dash is `aria-hidden` and
-     * this rides beside it, visually hidden.
-     */
-    resultAbsentDescription: string;
-    /**
-     * Shown above the raw value when a result cannot be laid out because the
-     * artifacts describing it are absent. It names the CAUSE — the descriptor,
-     * not the data — because the value is right there underneath and a reader
-     * who is not told why will assume the view is broken.
-     */
-    resultUndescribed: string;
-    /** The control that opens a result table row to show the rest of the record. */
-    toggleRowDetails: (index: number) => string;
-    /** The (visually hidden) header of the column those controls sit in. */
-    rowDetailsColumn: string;
-    /** The control that puts a file's whole URL on the clipboard. */
-    copyUrl: string;
-    /** The copy control beside any text value, markdown or not. */
-    copyText: string;
-    /** The download control's label. */
-    download: string;
-    /** Announced while the files are being fetched. */
-    downloading: string;
-    /**
-     * What the whole-result download says when some files did not arrive: the
-     * ones no URL could be found for, and the ones the delivery reported. Takes
-     * the names the files would have been saved under.
-     */
-    downloadIncomplete: (names: readonly string[]) => string;
-    /**
-     * The button beside each file that saves that one file, given the name it
-     * saves under: a gallery of buttons all called "Download" would leave a
-     * screen-reader user unable to tell which file each one saves.
-     */
-    downloadFile: (name: string) => string;
-    /** What that button says when the file did not arrive. */
-    downloadFileFailed: string;
-    /** The result panel's two views, and the control that copies the payload. */
-    viewRendered: string;
-    viewJson: string;
-    copyJson: string;
-    resultViewGroup: string;
-    yes: string;
-    no: string;
-    /**
-     * Shown when a picked file is not a format this slot accepts. Takes the
-     * slot's own formats as the hint names them (`PNG, JPG`), after any narrowing
-     * a host applied, so the message names what WOULD have worked - "not
-     * accepted" on its own leaves the user guessing at the list they just failed.
-     */
-    unsupportedFileType: (formats: string) => string;
-    /** The optional-entries disclosure ("field" inside a concept, "input" at top level). */
-    hideOptionalFields: string;
-    hideOptionalInputs: string;
-    optionalFieldsCount: (count: number) => string;
-    optionalInputsCount: (count: number) => string;
-}
-/** The English strings, which every control falls back to. Kept under this name for existing hosts. */
-declare const DEFAULT_FIELD_STRINGS: FieldStrings;
-/**
- * Set the strings every control below speaks. `locale` picks a language pack by its code (`fr`,
- * `fr-FR`, `en-GB`…; an unknown one falls back to English), and `strings` overrides single keys
- * on top of it. Both are optional: with neither, the controls speak English.
- */
-declare function FieldStringsProvider({ locale, strings, children, }: {
-    locale?: string;
-    strings?: Partial<FieldStrings>;
-    children: ReactNode;
-}): react.JSX.Element;
-/** The strings the nearest provider supplies (English defaults when none does). */
-declare function useFieldStrings(): FieldStrings;
-
 /**
  * The controls' strings in English: the package's defaults, and the pack every unknown or missing
  * locale falls back to (see `fieldStringsFor` in `./index.ts`).
@@ -785,43 +1331,4 @@ declare function FieldDomIdProvider({ prefix, children, }: {
  */
 declare function useFieldDomId(path: string): string;
 
-/**
- * How a field's LABEL chrome, and the enum values a person reads, should read.
- * What a control stores never changes.
- *
- * - `studio` (default): the field's name verbatim in mono, with its concept
- *   pill. The name IS the identifier a builder writes in the `.mthds` file, so
- *   showing it exactly - and typed - is the point. An enum value is shown as its
- *   code for the same reason: it has to match the bundle and the JSON the
- *   builder reads next.
- * - `app`: the field's name as a human question in sans, no concept pill. Inside
- *   a method app, `full_name` and `native.Text` are implementation detail; the
- *   person filling the form has never seen the method's source. An enum value
- *   follows the label and reads as words.
- *
- * An enum value is the only value the two presentations show differently. A
- * number, a text, a date and every other value render the same in both.
- *
- * Deliberately a context rather than a prop or a `FieldEnv` flag: only the
- * components that own label chrome or an enum value's wording read it -
- * `FieldShell`, `ObjectField`, `BooleanField`, `ListField`, `EnumField` and the
- * result view - plus the file control, whose card hides a storage reference in
- * `app`, and threading a prop would have meant editing every field control and
- * both recursive containers.
- */
-type FieldPresentation = 'studio' | 'app';
-declare function FieldPresentationProvider({ presentation, children, }: {
-    presentation: FieldPresentation;
-    children: ReactNode;
-}): react.JSX.Element;
-declare function useFieldPresentation(): FieldPresentation;
-/**
- * `full_name` → `Full name`. Only the first word is capitalised: these are
- * labels, not titles, and Title Case on every word reads as a form from 2009.
- * Takes IDENTIFIERS only - snake_case or kebab-case names, where a separator
- * is structure. An authored `title` never goes through here: it is already
- * human-facing, and its hyphens are spelling (`E-mail address`), not structure.
- */
-declare function humanizeFieldName(name: string): string;
-
-export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, DocumentField, type DownloadDisplay, EN_FIELD_STRINGS, EnumField, FIELD_STRINGS_BY_LOCALE, FR_FIELD_STRINGS, FieldDomIdProvider, FieldEnv, type FieldPresentation, FieldPresentationProvider, FieldShell, type FieldStrings, FieldStringsProvider, type FileValue, HtmlPreview, type HtmlPreviewProps, ImageField, JsonView, ListField, Markdown, type MarkdownProps, NumberField, ObjectField, OptionalToggle, ProseField, type ProseImages, type ResolveShareUrl, type ResolveUrl, ResultEnvProvider, ResultField, type ResultFieldProps, SUPPORTED_LOCALES, StuffViewer, type StuffViewerProps, type StuffViewerView, TextField, UnknownField, fieldControlClass, fieldStringsFor, humanizeFieldName, saveInBrowser, useFieldDomId, useFieldPresentation, useFieldStrings, useProseImages, useResolveShareUrl, useResolveUrl, useResolvedUrl };
+export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, DocumentField, type DownloadDisplay, EN_FIELD_STRINGS, EnumField, FIELD_STRINGS_BY_LOCALE, FR_FIELD_STRINGS, FieldDomIdProvider, FieldEnv, type FieldPresentation, FieldPresentationProvider, FieldShell, type FieldStrings, FieldStringsProvider, type FileValue, type HtmlPdf, type HtmlPdfOptions, HtmlPreview, type HtmlPreviewProps, ImageField, JsonView, ListField, Markdown, type MarkdownProps, type MarkupResolvers, MethodForm, type MethodFormController, type MethodFormProps, type MethodFormState, type MethodFormUploadContext, type MethodFormValues, NumberField, ObjectField, OptionalToggle, PdfDownloadButton, type PdfDownloadButtonProps, ProseField, type ProseImages, type ResolveShareUrl, type ResolveUrl, type ResolveUrls, ResultEnvProvider, ResultField, type ResultFieldProps, SUPPORTED_LOCALES, StuffViewer, type StuffViewerProps, type StuffViewerView, TextField, UnknownField, type UploadedFile, type UseMethodFormOptions, fieldControlClass, fieldStringsFor, humanizeFieldName, renderHtmlPdf, resolveHtmlStorageUrls, saveInBrowser, useFieldDomId, useFieldPresentation, useFieldStrings, useMethodForm, useProseImages, useResolveShareUrl, useResolveUrl, useResolvedUrl };