@peripheries/renderer 0.22.0 → 0.23.1

package/dist/types/core/sources.d.ts

@@ -1,48 +1,31 @@
+import { type VersionContext } from '@peripheries/runtime';
 import type { CellSource, ResolvedCell } from './cells.js';
 import type { PageRuntime } from './load-page.js';
 import type { StateOrigin } from './types.js';
-/** Where one prop's value came from. `path` is where the value sits in its source. */
-export type PropSource = 
-/** A node's state (a declared binding, or an element of an `@each` over one): `path` is inside the state's data. */
-{
+export type PropSource = {
     kind: 'state';
     graphNodeId: string;
     reads: StateOrigin[];
     path: string[];
-}
-/** A literal in the cell's props, at its prop path. */
- | {
+} | {
     kind: 'literal';
     path: string[];
-}
-/** A literal in the page's or the cell's static data (`data.static`): `path` starts with its label. */
- | {
+} | {
     kind: 'static';
     scope: 'page' | 'cell';
     path: string[];
-}
-/** Computed, queried, walked or the host's own: not editable. */
- | {
+} | {
     kind: 'derived';
     why: 'query' | 'walk' | 'record' | 'param' | 'reserved';
 };
-/** A prop path (`['items', '0', 'title']`) and its source. */
 export type PropSourceEntry = {
     prop: string[];
     source: PropSource;
 };
-/** Told of each leaf of a cell's resolved props, with its source. */
 export type OnSource = (prop: string[], source: PropSource) => void;
-/** Keys under a state that only the agency's tools write (data.md §9.5). */
 export declare const TOOL_OWNED_KEYS: readonly ["content_index", "ref_index"];
-/** A section's fields a person edits on the structure itself (data.md §9.5, `doc_edit_structure`). */
 export declare const STRUCTURE_FIELDS: readonly ["title", "applicable", "startsPage", "directed", "status"];
-/**
- * Where an edit of a value goes: the write function and the arguments that come from the source.
- * The new value (and, for a page edit, the version seen) is the caller's. `fn: null` says why the
- * value can't be edited here; the write functions still decide everything that can.
- */
-export type EditTarget = {
+export type EditTarget = ({
     fn: 'doc_edit_content';
     graphNodeId: string;
     path: string[];
@@ -59,55 +42,19 @@ export type EditTarget = {
 } | {
     fn: 'page_edit_data';
     path: string[];
+}) & {
+    versionId?: string;
 } | {
     fn: null;
     reason: EditRefusal;
 };
-export type EditRefusal = 
-/** Computed, queried or walked: nothing holds it to edit. */
-'DERIVED'
-/** The cell's content is its node's `page_cell_config`, not the page's. */
- | 'NODE_CONFIG'
-/** A `data.static` literal of a cell whose content is its node's (NODE_CONFIG's case for static data). */
- | 'STATIC'
-/** The read didn't say which state it saw, so no version check is possible. */
- | 'NO_STATE_ID'
-/** The value merges more than one system's state, so which one to write is ambiguous. */
- | 'MERGED_READS'
-/** Not a data state (`<tier>_data`): the document write functions write data states only. */
- | 'NOT_DATA_STATE'
-/** A tool-owned index (`content_index`, `ref_index`). */
- | 'TOOL_OWNED'
-/**
- * An element of a list the write functions refused: a path whose index names no element
- * (`jsonb_set_path`). The host no longer refuses list paths itself: the functions write at a
- * path into a list (DF-SCH-9), and their dry run says whether the element exists.
- */
- | 'LIST_ELEMENT';
-/** The cell a value is in, and how its content was resolved (ResolvedCell.source). */
+export type EditRefusal = 'DERIVED' | 'NODE_CONFIG' | 'STATIC' | 'NO_STATE_ID' | 'MERGED_READS' | 'NOT_DATA_STATE' | 'TOOL_OWNED' | 'LIST_ELEMENT' | 'VERSION_IS_RELEASE';
 export type EditCell = {
     id: string;
     source?: CellSource;
 };
-/**
- * The write function an edit of this value goes to (design/data.md §9.5):
- * - a node's data state: a section's structure field or `order` to `doc_edit_structure`,
- *   anything else to `doc_edit_content`, with the state id the viewer saw;
- * - a literal in an inline cell, or its own `data.static`, to `page_edit_cell`'s path write, which
- *   writes the page artifact and the row together;
- * - the page's `data.static` to `page_edit_data`'s path write;
- * - everything else nowhere, with the reason.
- * Paths may run through list indices: the functions write at a path into a list (DF-SCH-9).
- */
-export declare function editTarget(source: PropSource, cell: EditCell): EditTarget;
-/** A value at a path, as the nested object a patch is (`['props', 'caption']` → `{ props: { caption } }`). */
+export declare function editTarget(source: PropSource, cell: EditCell, version?: VersionContext): EditTarget;
 export declare function patchAt(path: readonly string[], value: unknown): unknown;
-/**
- * One cell's props as the renderer resolves them (CellView), with each leaf's source and value,
- * without rendering: what an assistant reads to plan an edit (docs-forms M3). Null when the cell's
- * conditions hide it. The same resolution context CellView builds, from the same runtime; paged
- * labels' later pages aren't loaded, so a paged list reads its first page.
- */
 export declare function cellPropSources(runtime: Pick<PageRuntime, 'page' | 'data' | 'declared' | 'cellData'>, cell: ResolvedCell, env?: {
     params?: Record<string, unknown>;
     baseProps?: unknown;

package/dist/types/core/store/create-store.d.ts

@@ -1,11 +1,6 @@
 import { Store } from '@tanstack/store';
 import type { LiveEntry, ScopeId, SelectionsScope, StackStoreData, StackStoreState, ViewStateScope } from './types.js';
 export type StackStoreApi = ReturnType<typeof createStackStore>;
-/**
- * The shared store, on TanStack Store (design/bundles.md §5). One instance per
- * page tree. `getState()` returns the data with the actions, the shape the
- * PWA's zustand store exposed to the escape-hatch API.
- */
 export declare function createStackStore(initial?: Partial<StackStoreData>): {
     getState: () => StackStoreState;
     subscribe: (listener: (state: StackStoreState) => void) => import("@tanstack/store").Subscription;
@@ -22,6 +17,5 @@ export declare function createStackStore(initial?: Partial<StackStoreData>): {
     };
     _clearScope: (scope: ScopeId) => void;
     _reset: () => void;
-    /** The underlying TanStack store, for `useSelector`. */
     store: Store<StackStoreData, never>;
 };

package/dist/types/core/store/persistence.d.ts

@@ -7,5 +7,4 @@ export interface PersistedScope {
 export declare function loadScope(scope: ScopeId, mode: StorageMode): PersistedScope | null;
 export declare function saveScope(scope: ScopeId, slice: PersistedScope, mode: StorageMode): void;
 export declare function clearScope(scope: ScopeId, mode: StorageMode): void;
-/** Removes every persisted scope from session and local storage: a different viewer starts clean. */
 export declare function clearAllScopes(): void;

package/dist/types/core/store/projection.d.ts

@@ -2,14 +2,9 @@ import type { StackStoreApi } from './create-store.js';
 import { type ScopeContext } from './scope-keys.js';
 import type { LiveDeclarations, ProjectedBundle, ScopeId, SelectionDeclarations, StackStoreData, ViewStateDeclarations } from './types.js';
 export declare function projectSelections(decls: SelectionDeclarations | undefined, state: StackStoreData, ctx: ScopeContext): ProjectedBundle | undefined;
-/** Selections are read-only unless `writable`. */
 export declare function attachSelectionSetters(values: ProjectedBundle, decls: SelectionDeclarations, store: StackStoreApi, ctx: ScopeContext): ProjectedBundle;
 export declare function projectViewState(decls: ViewStateDeclarations | undefined, state: StackStoreData, ctx: ScopeContext): ProjectedBundle | undefined;
-/** viewState is writable unless `writable: false`. */
 export declare function attachViewStateSetters(values: ProjectedBundle, decls: ViewStateDeclarations, store: StackStoreApi, ctx: ScopeContext): ProjectedBundle;
-/** `live.<name>` is the data; `live.<name>Status` the envelope. */
 export declare function projectLive(decls: LiveDeclarations | undefined, state: StackStoreData): ProjectedBundle | undefined;
-/** Equality for a selector: re-render only when a projected channel changes. */
 export declare function shallowEqualBundle(a: ProjectedBundle | undefined, b: ProjectedBundle | undefined): boolean;
-/** Every scope a cell's declarations touch (for hydration and persistence). */
 export declare function collectScopeIds(ctx: ScopeContext, selections?: SelectionDeclarations, viewState?: ViewStateDeclarations): ScopeId[];

package/dist/types/core/store/scope-keys.d.ts

@@ -6,5 +6,4 @@ export interface ScopeContext {
     pageId?: string | null;
     projectId?: string | null;
 }
-/** `null` when the context lacks the id: no scope, so no value and no setter. */
 export declare function resolveScopeId(kind: ScopeKind, ctx: ScopeContext): ScopeId | null;

package/dist/types/core/store/types.d.ts

@@ -11,14 +11,11 @@ export interface LiveEntry<T = unknown> {
 export interface StackStoreData {
     selections: Record<ScopeId, SelectionsScope>;
     viewState: Record<ScopeId, ViewStateScope>;
-    /** Global, not scoped: a channel is one source. */
     live: Record<string, LiveEntry>;
 }
 export interface StackStoreActions {
-    /** Cell-facing, through projected setter props. */
     setSelection: (scope: ScopeId, channel: string, value: unknown) => void;
     setViewState: (scope: ScopeId, key: string, value: unknown) => void;
-    /** Host-internal. */
     _setLive: (channel: string, entry: LiveEntry) => void;
     _hydrateScope: (scope: ScopeId, slice: {
         selections?: SelectionsScope;
@@ -29,11 +26,8 @@ export interface StackStoreActions {
         viewState: ViewStateScope;
     };
     _clearScope: (scope: ScopeId) => void;
-    /** Empties selections, view state and live data: a different viewer starts clean. */
     _reset: () => void;
 }
-/** What a selector sees: the data plus the actions, as the PWA's zustand store exposed. */
 export type StackStoreState = StackStoreData & StackStoreActions;
 export type { LiveDecl, LiveDeclarations, SelectionDecl, SelectionDeclarations, ViewStateDecl, ViewStateDeclarations, } from '@peripheries/runtime';
-/** Spread onto a cell's `selections` / `viewState` / `live` props. */
 export type ProjectedBundle = Record<string, unknown>;

package/dist/types/core/structure.d.ts

@@ -5,28 +5,17 @@ export type { LayoutNode, SectionKind, SectionReference };
 export type ResolvedLayoutNode = Omit<LayoutNode, 'children'> & {
     children?: ResolvedLayoutNode[];
 };
-/** The page's own document, which almost every page is. */
 export declare const PAGE_DOCUMENT = "__page__";
-/** A string child is sugar for `{ cellId }`. */
 export declare function normalizeStructure(nodes: ReadonlyArray<LayoutNode | string> | null | undefined): ResolvedLayoutNode[];
-/** Siblings by `order` (default 0), stable. */
 export declare const sortByOrder: <T extends {
     order?: number;
 }>(nodes: readonly T[]) => T[];
 export declare const isSectionNode: (n: ResolvedLayoutNode) => boolean;
 export declare const isSectionKind: (v: unknown) => v is SectionKind;
-/** A section's anchor: its cell, else its section id (the same value `DocumentSection` and the contents use). */
 export declare const sectionAnchor: (n: Pick<ResolvedLayoutNode, "cellId" | "sectionId">) => string;
-/**
- * Hierarchical rendering when the structure wants it: `type: 'document'`, or
- * any top-level node naming a section or carrying children. A flat list of
- * `{ cellId }` is only an ordering hint for print, and renders flat.
- */
 export declare function usesStructureLayout(layout: Record<string, unknown> | null | undefined): boolean;
 export type DocumentNumbering = {
-    /** Only `kind: 'article'` sections are numbered, per document, prefixed by the parent trail. */
     numbers: Record<string, number[]>;
-    /** Structural depth of each section. */
     levels: Record<string, number>;
     authoredLevels: Record<string, number>;
     titles: Record<string, string>;
@@ -42,35 +31,19 @@ export type SectionNumbering = {
 };
 export declare const numberingFor: (numbering: SectionNumbering | undefined, documentId: string | undefined) => DocumentNumbering;
 export declare function deriveSectionNumbering(structure: ReadonlyArray<LayoutNode | string> | null | undefined): SectionNumbering;
-/** Per document: every target a cell in it may cite, by role (`residue`), `label:role`, or `role#clause`. */
 export type SectionReferences = Record<string, Record<string, SectionReference>>;
 type Documents = Record<string, {
     label?: unknown;
 }> | null | undefined;
-/** Same-page section references: a document's own roles, plus `label:role` for every uniquely labelled document. */
 export declare function deriveSectionReferences(numbering: SectionNumbering, documents: Documents): SectionReferences;
-/**
- * Clause citations (`role#clauseId`): each section's cells' resolved
- * `props.blocks`, where a `clause` block's items carry ids. The item's index
- * and the clause shape let a Reference render the clause's number.
- */
 export declare function deriveElementReferences(structure: ReadonlyArray<LayoutNode | string> | null | undefined, blocksByCellId: Readonly<Record<string, unknown>>, documents: Documents): SectionReferences;
-/** Same-page references win over data-derived ones (clauses; cross-page arrive in R5). */
 export declare function mergeSectionReferences(samePage: SectionReferences, other: SectionReferences | undefined): SectionReferences;
 export declare const referencesFor: (refs: SectionReferences | undefined, documentId: string | undefined) => Record<string, SectionReference>;
-/** What stops a structure rendering: a node naming a missing cell, or an unknown section kind (a refusal, by design). */
 export declare function structureIssues(structure: ReadonlyArray<LayoutNode | string> | null | undefined, cells: PageCell[]): string[];
-/**
- * A node's extrinsic pagination: a page break before, keep-with-previous
- * (break-before: avoid), or avoid breaking inside. `breakInside: 'auto'` is
- * dropped, so a node can't relax what a component declares; a break before
- * wins over keep-with-previous. The component's own @printPolicy joins in R5.
- */
 export declare function nodePrintStyle(node: Pick<LayoutNode, 'print'>): {
     breakBefore?: 'page' | 'avoid';
     breakInside?: 'avoid';
 } | undefined;
-/** One entry in a document's table of contents. */
 export type ContentsEntry = {
     sectionId: string;
     anchor: string;
@@ -79,10 +52,4 @@ export type ContentsEntry = {
     level: number;
     children: ContentsEntry[];
 };
-/**
- * A document's table of contents (INV-DOC-1): its sections in order, nested, with the numbers
- * articles get and the anchors the page renders (`sectionAnchor`). A section's title is its
- * structure node's, else its cell's `title` prop, else its id. `tocHidden` sections are left out,
- * their children kept in their place. Only the page's own document.
- */
 export declare function tableOfContents(structure: ReadonlyArray<LayoutNode | string> | null | undefined, cells?: ReadonlyArray<PageCell>): ContentsEntry[];

package/dist/types/core/types.d.ts

@@ -1,16 +1,10 @@
 import type { DeclaredBinding, PageCell, QueryDescriptor } from '@peripheries/runtime';
-/** One source in a DataContext: the value and its state. */
-/** A paged label's position (QueryDescriptor.paging): what loading its next page needs. */
 export type DataPage = {
     hasMore: boolean;
     endCursor: string | null;
     descriptor: QueryDescriptor;
     variables: Record<string, unknown>;
 };
-/**
- * A label's read. `unresolved` names the references that resolved to nothing, so the query never
- * ran (QUERY_UNRESOLVED): there is nothing to show yet, which is not a failed read.
- */
 export type DataEntry = {
     data: unknown;
     isLoading: boolean;
@@ -19,18 +13,13 @@ export type DataEntry = {
     unresolved?: string[];
     origin?: DataOrigin;
 };
-/** A system a label's value was read from, and the newest state seen there (null: none, or the source doesn't say). */
 export type StateOrigin = {
     systemId: string;
     name?: string;
     stateId: string | null;
+    versionId?: string | null;
+    outOfScope?: boolean;
 };
-/**
- * Where a label's value came from (INV-DOC-6), so an edit can go back to it (design/data.md §9.5).
- * `at` is the path inside the source to the label's value: inside the state's data (a binding's
- * `field`, an `@each` element's index), or the label and its path in the page's or cell's static data.
- * A label without an origin was read some other way (a query): it isn't editable.
- */
 export type DataOrigin = {
     kind: 'state';
     graphNodeId: string;

package/dist/types/core/validate.d.ts

@@ -1,7 +1,6 @@
 import { type Diagnostic } from './graph.js';
 import { type Each } from './references.js';
 import type { PageCell, ProjectPage } from './types.js';
-/** What validation knows about the components in scope. Stream 3 fills it from the catalog. */
 export type Catalog = {
     components: Record<string, {
         props_schema?: {
@@ -11,34 +10,23 @@ export type Catalog = {
         } | null;
     } | undefined>;
 };
-/**
- * The names nearest a name that isn't in scope, nearest first: a near spelling
- * (`Prse`), or each of its words starting a word of the name (`DocSection` →
- * `DocumentSection`). Full-text search can't find either.
- */
 export declare function nearestNames(name: string, names: Iterable<string>, limit?: number): string[];
 export declare const RESPONSIVE_BUCKETS: readonly ["narrow", "compact", "wide"];
 export declare const STORE_SCOPES: readonly ["page", "project"];
 export declare const WALK_DIRECTIONS: readonly ["incoming", "outgoing", "both"];
-/** Options: `template` for a page template, whose node bindings are filled when it is instantiated. */
 export type ValidateOptions = {
     template?: boolean;
 };
-/** What is wrong with a projection's form, if anything: the one judgement EACH_INVALID and validatePageProps share. */
 export declare function eachFormProblems(value: Each): string[];
-/** One cell's configuration. `ids` are the page's cell ids, for `children`. */
 export declare function validateCell(cell: PageCell, catalog?: Catalog, path?: string, ids?: ReadonlySet<string>, options?: ValidateOptions): Diagnostic[];
-/** A whole page: every cell, the page's own declarations, unique cell ids, and its document structure. */
 export declare function validatePage(page: Pick<ProjectPage, 'content' | 'layout'> & {
     is_template?: boolean | null;
 }, catalog?: Catalog): Diagnostic[];
-/** A slot a component declares in its props schema: `properties.<name>["x-slot"]` (ui-consistency.md §2.8). */
 export type SlotDeclaration = {
     name: string;
     accepts?: readonly string[];
     max?: number;
 };
-/** The slots a catalog entry declares, by name. */
 export declare function declaredSlots(schema: {
     properties?: Record<string, unknown>;
 } | null | undefined): Map<string, SlotDeclaration>;

package/dist/types/core/values.d.ts

@@ -1,12 +1,6 @@
 import type { Traversal } from '@peripheries/runtime';
 import type { PageRuntime } from './load-page.js';
 import type { ProjectPage } from './types.js';
-/**
- * `values` are labels and their resolved values, on top of the page's static
- * data. `traversal` is `@_traversal` for every walking cell: one subgraph for
- * all of them, or one per cell id; a walking cell it doesn't cover gets an
- * empty one, as the host gives a walk that found nothing.
- */
 export declare function pageRuntimeFromValues(page: ProjectPage, { values, traversal }?: {
     values?: Record<string, unknown>;
     traversal?: Traversal | Record<string, Traversal>;

package/dist/types/forms/conditions.d.ts

@@ -0,0 +1,18 @@
+export declare const CONDITION_OPS: readonly ["eq", "ne", "in", "not_in", "gt", "lt", "gte", "lte", "contains", "not_contains", "empty", "not_empty"];
+export type ConditionOp = (typeof CONDITION_OPS)[number];
+export interface ConditionClause {
+    q: string;
+    op: ConditionOp | (string & {});
+    value?: unknown;
+}
+export interface Condition {
+    all: ConditionClause[];
+    not?: boolean;
+}
+export declare function isConditionOp(op: unknown): op is ConditionOp;
+export declare function evaluateCondition(condition: Condition | null | undefined, answers: Record<string, unknown>, onProblem?: (problem: string) => void): boolean;
+export declare function normalizeOperator(op: unknown): ConditionOp | null;
+export declare function normalizeCondition(legacy: unknown): {
+    condition: Condition | null;
+    problems: string[];
+};

package/dist/types/forms/index.d.ts

@@ -0,0 +1,3 @@
+export { CONDITION_OPS, evaluateCondition, isConditionOp, normalizeCondition, normalizeOperator, type Condition, type ConditionClause, type ConditionOp } from './conditions.js';
+export { defaultMode, enterAdvances, fromPageSteps, goTo, goToQuestion, isReadOnlyStatus, linkTo, missing, move, positionFromLink, positionsOf, progress, questionsOf, settle, stepKind, visibleSteps, type DisplayMode, type FormChapter, type FormItem, type FormItemKind, type FormLink, type FormModel, type FormQuestion, type FormQuestionDefinition, type FormStep, type Position, type StepKind, type StepProgress, type SubmissionStatus, } from './model.js';
+export type { AnswerToSave, FileToUpload, FormsPort, FormsRefusal, FormsResult } from './port.js';

package/dist/types/forms/model.d.ts

@@ -0,0 +1,90 @@
+import { type Condition } from './conditions.js';
+export type FormQuestion = {
+    key: string;
+    label: string;
+    required: boolean;
+    singleLine: boolean;
+    when?: Condition | null;
+    node?: string;
+    definition?: FormQuestionDefinition;
+};
+export type FormQuestionDefinition = {
+    type: string;
+    options?: unknown[];
+    validation?: Record<string, unknown>;
+    description?: string;
+    helpText?: string;
+};
+export type FormItemKind = 'question' | 'content' | 'document' | 'review' | 'upload' | 'other';
+export type FormItem = {
+    id: string;
+    kind: FormItemKind;
+    questions: FormQuestion[];
+    when?: Condition | null;
+};
+export type FormStep = {
+    id: string;
+    title: string;
+    chapter?: string;
+    label?: string;
+    items: FormItem[];
+    when?: Condition | null;
+};
+export type FormChapter = {
+    id: string;
+    title: string;
+};
+export type FormModel = {
+    title: string;
+    chapters: FormChapter[];
+    steps: FormStep[];
+    submitRequired: 'warn' | 'block';
+    allowBack: boolean;
+    submittable?: boolean;
+};
+export type StepKind = 'answer' | 'read' | 'review' | 'upload' | 'submit';
+export type SubmissionStatus = 'in_progress' | 'submitted' | 'changes_requested' | 'completed';
+export type DisplayMode = 'step' | 'question';
+export declare function visibleSteps(model: FormModel, values: Record<string, unknown>): FormStep[];
+export declare const questionsOf: (step: FormStep) => FormQuestion[];
+export declare function stepKind(step: FormStep, isLast: boolean): StepKind;
+export type Position = {
+    step: string;
+    question?: string;
+};
+export declare function positionsOf(steps: FormStep[], mode: DisplayMode): Position[];
+export declare function settle(steps: FormStep[], mode: DisplayMode, at: Position | null): Position | null;
+export declare function move(steps: FormStep[], mode: DisplayMode, at: Position, by: 1 | -1): Position | null;
+export declare function goTo(steps: FormStep[], mode: DisplayMode, stepId: string, values: Record<string, unknown>): Position | null;
+export declare function goToQuestion(steps: FormStep[], mode: DisplayMode, key: string): Position | null;
+export declare function enterAdvances(step: FormStep, mode: DisplayMode, question?: string): boolean;
+export declare function missing(steps: FormStep[], values: Record<string, unknown>, stepId?: string): FormQuestion[];
+export type StepProgress = {
+    answered: number;
+    total: number;
+    complete: boolean;
+};
+export declare function progress(steps: FormStep[], values: Record<string, unknown>, visited: ReadonlySet<string>): {
+    answered: number;
+    required: number;
+    ratio: number;
+    total: {
+        answered: number;
+        count: number;
+    };
+    perStep: Record<string, StepProgress>;
+};
+export declare const isReadOnlyStatus: (status: SubmissionStatus | null | undefined) => status is "submitted" | "completed";
+export declare const defaultMode: (phone: boolean) => DisplayMode;
+export declare function fromPageSteps(page: {
+    name?: string | null;
+    layout?: Record<string, unknown> | null;
+}, itemOf: (cellId: string) => FormItem | null): FormModel;
+export type FormLink = {
+    mode?: 'question';
+    page?: string;
+    section?: string;
+    question?: string;
+};
+export declare function positionFromLink(steps: FormStep[], mode: DisplayMode, link: FormLink): Position | null;
+export declare function linkTo(steps: FormStep[], mode: DisplayMode, at: Position): FormLink;

package/dist/types/forms/port.d.ts

@@ -0,0 +1,47 @@
+import type { FileAnswer } from '@peripheries/runtime';
+export type FormsRefusal = 'CONFLICT' | 'ANSWER_TYPE' | 'ANSWER_OPTION' | 'ANSWER_REQUIRED' | 'ANSWER_FILE_PATH' | 'ANSWER_VALIDATION' | 'FORM_INCOMPLETE' | 'FORM_NOT_OPEN' | 'FORM_COMPLETED' | 'FORM_STEP_UNKNOWN' | 'NO_CAPABILITY' | 'NETWORK' | (string & {});
+export type FormsResult<T extends object = object> = ({
+    ok: true;
+} & T) | {
+    ok: false;
+    code: FormsRefusal;
+    message?: string;
+    detail?: unknown;
+};
+export type FileToUpload = Blob & {
+    readonly name: string;
+};
+export type AnswerToSave = {
+    key: string;
+    node?: string;
+    value: unknown;
+    expectedStateId?: string | null;
+};
+export interface FormsPort {
+    save(answer: AnswerToSave): Promise<FormsResult<{
+        stateId?: string | null;
+    }>>;
+    submit(input: {
+        missing: string[];
+    }): Promise<FormsResult<{
+        status: 'submitted';
+        missing: string[];
+    }>>;
+    reopen(): Promise<FormsResult<{
+        status: 'in_progress';
+    }>>;
+    visit(stepId: string): Promise<FormsResult>;
+    upload?(input: {
+        key: string;
+        node?: string;
+        file: FileToUpload;
+    }): Promise<FormsResult<{
+        answer: {
+            v: 1;
+            file: FileAnswer;
+        };
+    }>>;
+    openFile?(file: FileAnswer): Promise<FormsResult<{
+        url: string;
+    }>>;
+}

package/dist/types/print/document-bindings.d.ts

@@ -1,41 +1,4 @@
-/**
- * Values for the region bindings a profile names.
- *
- * ── The gap this closes ─────────────────────────────────────────────────────
- *
- * A profile says WHICH margin box holds WHAT: `instrument`'s footer is
- * `{ left: 'execution-state', right: 'page-x-of-y' }`. Only the second is
- * computable — CSS produces page numbers during pagination. The rest are facts
- * about *this document*, which the bundle cannot know and the host must supply.
- *
- * Until now it supplied none, so every `instrument` page was unprintable:
- * `execution-state` is in `requiredBindings`, and a will that does not say
- * "Not for execution" is a will that does not say it is a draft.
- *
- * ── Why the page declares them, keyed by binding name ───────────────────────
- *
- * `project_page.metadata.document.bindings` — a flat map from binding name to
- * string. Keyed by the binding name itself rather than by some host-side
- * camelCase alias, because a translation layer is one more place for
- * `document-id` and `documentId` to disagree, and because a binding a bundle adds
- * then works with no host change at all.
- *
- * ── What this deliberately does NOT do ──────────────────────────────────────
- *
- * It does not DERIVE anything. `execution-state` could plausibly be computed
- * from a document status — an org's naming system defines DRAFT / REVIEW /
- * FINAL / EXECUTED, and is emphatic that *"`FINAL` and `EXECUTED` are not the
- * same thing… never collapse these"*. Encoding that mapping here would be
- * inventing legal policy in a stylesheet helper, and getting it wrong prints a
- * document asserting the wrong status — the exact failure `requiredBindings`
- * exists to prevent, arriving through the fix for it.
- *
- * So: declared values only. A page that has not declared them stays unprintable,
- * visibly, with the reason on the button. That is the correct state for a
- * document nobody has said the status of.
- */
 import type { PageRegionValues } from './print-stylesheet.js';
-/** The `metadata.document` shape. Open — a profile may name bindings we predate. */
 export interface DocumentBindingsMetadata {
     bindings?: Record<string, unknown>;
 }
@@ -45,32 +8,8 @@ interface PageLike {
 }
 export interface ResolvedBindings {
     values: PageRegionValues;
-    /** Declared keys whose value was not a usable string. Named, never coerced. */
     malformed: string[];
 }
-/**
- * Read declared binding values off a page record.
- *
- * Non-string values are DROPPED and reported rather than stringified. `42` would
- * render as "42" in a footer and look deliberate; `null` would render as "null".
- * A footer is read as an assertion about the document, so a value that arrived
- * by accident must not reach one.
- */
 export declare function resolveRegionBindings(page: PageLike | null | undefined): ResolvedBindings;
-/**
- * The profile id the page names, plus a detector for the second copy of it.
- *
- * `layout.profile` is authoritative — a profile is geometry and belongs beside
- * `structure`. But the proof page carries `metadata.profile` as well, with
- * the same value, and **the host reads only one of them**. Today they agree; the
- * database has 1 page with each key and 0 disagreements. That is two sources for
- * one fact, in sync by luck, with no detector — the shape this pair of repos has
- * now caught four times (`PaperConfig` vs the profile, two type scales, two
- * paginators, and the carried-field lists).
- *
- * Rather than reading both and picking, or silently ignoring one: read `layout`,
- * and say so loudly the moment the copies disagree. Enforcement is cheap here
- * precisely because it is not yet a problem.
- */
 export declare function resolveProfileId(page: PageLike | null | undefined): string | undefined;
 export {};