@pipelex/mthds-form 0.8.0 → 0.10.0

package/dist/chunk-ZB4RYUKV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/derive.ts"],"names":[],"mappings":"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","file":"chunk-ZB4RYUKV.js","sourcesContent":["/**\n * The ONE derivation function: wire input-form descriptor → `RunField[]`.\n *\n * `buildRunFields` maps the standard's per-pipe descriptor STRUCTURALLY onto\n * the kernel's `RunField` shape. It decides nothing: what a field IS - its\n * kind, its constraints, its refinement chain, whether Run gates on it - is\n * stated by the wire, derived by the engine from the resolved library. The\n * heuristics that used to live here (native-concept sets, the url-bearing\n * object test, the depth-based prose/label rule) are deleted, not bypassed;\n * docs/derivation-swap.md is the record of that swap and of every behaviour\n * that moved with it.\n *\n * The contract is still consulted, for exactly two facts the wire deliberately\n * does not carry:\n *\n * - **`contentKey`** - the single property a native scalar's value sits inside\n *   on the wire (`TextContent {text}`, `NumberContent {number}`). A renderer\n *   holds the bare scalar; the value bridge wraps by this name. It is read off\n *   the contract's `json_schema` because it is a fact about the PAYLOAD shape,\n *   which is the schema's job - the descriptor describes the form, never the\n *   payload.\n * - **Nested list bounds** - the wire puts `item_count` only on a top-level\n *   fixed `[N]` slot, but the model behind a structured concept may state\n *   `minItems`/`maxItems` on an array property of its own, and ajv enforces\n *   them. Reading them off the schema is what keeps readiness from being more\n *   permissive than the gate.\n *\n * Both are structural reads (a property count, two keywords ajv itself\n * enforces), not judgements - the mapper stays honest about owning no taxonomy.\n */\n\nimport type { PipeInputFormDescriptor } from 'mthds/protocol';\nimport type { InputForm, InputFormField, InputFormItem } from 'mthds/protocol';\n\nimport { buildPipeRef, type PipeInputContract } from './contracts';\nimport { formatsForKind } from './file-formats';\nimport type { RunField, RunFieldCommon } from './descriptor';\nimport { ownProp } from './own-property';\nimport { collectSchemaDefs, resolveSchemaNode, type JsonSchema } from './schema-utils';\n\n/**\n * Look up a pipe's input-form descriptor by pipe code, tolerant of both key\n * conventions - the exact mirror of `getPipeIOContract`, because the standard\n * keys `input_form` by the same `pipe_ref` set as `pipe_io_contracts` and a\n * host tracks the same bare codes either way.\n */\nexport function getPipeInputForm(\n  inputForm: InputForm | null | undefined,\n  domain: string | null | undefined,\n  pipeCode: string | null | undefined,\n): PipeInputFormDescriptor | undefined {\n  if (!inputForm || !pipeCode) return undefined;\n  if (domain) {\n    const byRef = ownProp(inputForm, buildPipeRef(domain, pipeCode));\n    if (byRef) return byRef;\n  }\n  return ownProp(inputForm, pipeCode);\n}\n\n/**\n * The single property a scalar content model holds its value in - `TextContent\n * {text}`, `NumberContent {number}`, `YesNoContent {yes_no}`.\n *\n * A wrapper is a schema declaring EXACTLY ONE property. A multi-property\n * content model (`DateContent {date, time}`, `HtmlContent {inner_html,\n * css_class}`) is not one and deliberately answers `undefined` - those travel\n * as the structures they are, which the wire now also says by giving them\n * `kind: \"object\"`. Reading the declared shape rather than keeping a list of\n * wrapping concepts is what covers a concept nobody remembered to add.\n */\nfunction scalarWrapperKey(schema: JsonSchema | undefined): string | undefined {\n  const props = schema?.properties as Record<string, JsonSchema> | undefined;\n  const keys = props ? Object.keys(props) : [];\n  return keys.length === 1 ? keys[0] : undefined;\n}\n\nfunction numOrUndef(v: unknown): number | undefined {\n  return typeof v === 'number' ? v : undefined;\n}\n\n/** The inclusive bound a control can express for a wire-stated exclusive one.\n *  On an integer the open interval has a nearest neighbour and the conversion\n *  is exact (`> 0` IS `>= 1`), so `toNearest` steps off the endpoint onto it.\n *  It rounds rather than adding one, because the endpoint need not be integral\n *  - JSON Schema allows `> 0.5` on an integer node, whose nearest neighbour is\n *  `1`, not `1.5`. On a float the interval has no nearest neighbour, and the\n *  answer is to publish no bound at all: a control that only clamps cannot\n *  express an open interval, and naming the excluded endpoint would advertise\n *  the one value the gate is about to refuse. */\nfunction inclusiveFrom(\n  bound: number | undefined,\n  integer: boolean | undefined,\n  toNearest: (endpoint: number) => number,\n): number | undefined {\n  return typeof bound === 'number' && integer === true ? toNearest(bound) : undefined;\n}\n\n/** Resolve one schema node the same way the gate's validator will see it -\n *  to the FIXPOINT, so a nullable `$ref` (pydantic's Optional concept-typed\n *  field) yields its definition rather than an unresolved reference. */\nfunction resolveSchema(\n  schema: JsonSchema | undefined,\n  defs: Record<string, JsonSchema>,\n): JsonSchema | undefined {\n  return schema ? resolveSchemaNode(schema, defs) : undefined;\n}\n\n/** The slots every wire node carries, mapped onto the descriptor's names. */\nfunction commonOf(node: InputFormItem, name: string): RunFieldCommon {\n  return {\n    name,\n    title: node.title,\n    conceptRef: node.concept_ref,\n    refines: node.refines,\n    description: node.description,\n    required: node.required,\n    defaultValue: node.default_value,\n    examples: node.examples,\n    hints: node.hints,\n  };\n}\n\n/**\n * Map one wire node onto a `RunField`, walking the aligned `json_schema` node\n * beside it. The schema walk supplies only `contentKey` and list bounds (see\n * the module header); a missing or misaligned schema degrades to their absence,\n * never to a different field.\n */\nfunction mapNode(\n  node: InputFormItem,\n  name: string,\n  rawSchema: JsonSchema | undefined,\n  defs: Record<string, JsonSchema>,\n): RunField {\n  const schema = resolveSchema(rawSchema, defs);\n  const common = commonOf(node, name);\n\n  switch (node.kind) {\n    case 'text':\n    case 'prose':\n      return {\n        ...common,\n        contentKey: scalarWrapperKey(schema),\n        kind: node.kind,\n        minLength: node.min_length,\n        maxLength: node.max_length,\n        pattern: node.pattern,\n        format: node.format,\n      };\n    case 'date':\n      return { ...common, kind: 'date', datetime: node.datetime };\n    case 'number':\n      return {\n        ...common,\n        contentKey: scalarWrapperKey(schema),\n        kind: 'number',\n        integer: node.integer,\n        // A number control clamps; it does not express open intervals. So an\n        // exclusive bound becomes the nearest inclusive one where that is\n        // exact (integers) and is dropped where it is not (floats) - never\n        // the excluded endpoint itself, which the control would clamp onto\n        // and the gate would then refuse. ajv enforces the exact keyword off\n        // the schema either way, so the bound is a hint, never the rule.\n        min:\n          node.minimum ??\n          inclusiveFrom(\n            node.exclusive_minimum,\n            node.integer,\n            (endpoint) => Math.floor(endpoint) + 1,\n          ),\n        max:\n          node.maximum ??\n          inclusiveFrom(\n            node.exclusive_maximum,\n            node.integer,\n            (endpoint) => Math.ceil(endpoint) - 1,\n          ),\n      };\n    case 'boolean':\n      return { ...common, contentKey: scalarWrapperKey(schema), kind: 'boolean' };\n    case 'enum':\n      // The wire carries the authored `choices` verbatim (`unknown[]`); the\n      // control set renders and stores strings, as it always has.\n      return { ...common, kind: 'enum', options: node.choices.map(String) };\n    case 'document':\n    case 'image':\n      // `formats` is a renderer-side affordance the wire deliberately does not\n      // state - which bytes a runtime can decode is a property of the runtime,\n      // not of the method. The list is therefore ours, and it is one table\n      // (`./file-formats`) rather than a literal here. The field carries the\n      // LIST, not a label made from it, so the hint a user reads, the filter the\n      // dropzone applies and the check it enforces all read one value and cannot\n      // disagree - and a host narrowing it (`narrowFileFormats`) moves all three.\n      // They used to disagree: this line advertised `TXT`, which no format\n      // covered, and later the hint was a label while the filter and the check\n      // went back to the kind's table, so rewriting the label moved nothing else.\n      return { ...common, kind: node.kind, formats: formatsForKind(node.kind) };\n    case 'object': {\n      const props = schema?.properties as Record<string, JsonSchema> | undefined;\n      return {\n        ...common,\n        kind: 'object',\n        fields: node.fields.map((child: InputFormField) =>\n          mapNode(child, child.name, props ? ownProp(props, child.name) : undefined, defs),\n        ),\n      };\n    }\n    case 'list': {\n      // The item keeps the parent's name (unused for labels - the index labels\n      // items), exactly as the wire's `item` carries no `name` of its own.\n      const item = mapNode(node.item, name, schema?.items as JsonSchema | undefined, defs);\n      const itemCount = node.item_count ?? numOrUndef(schema?.minItems);\n      const maxItemCount = numOrUndef(schema?.maxItems) ?? node.item_count;\n      return {\n        ...common,\n        kind: 'list',\n        item,\n        ...(itemCount === undefined ? {} : { itemCount }),\n        ...(maxItemCount === undefined ? {} : { maxItemCount }),\n      };\n    }\n    case 'unknown':\n      return { ...common, kind: 'unknown' };\n  }\n  // Version drift: the wire states a kind this build's pinned `mthds` does not\n  // define. The switch above is exhaustive over `InputFormItem`, so\n  // `satisfies never` keeps the build LOUD when the PIN grows a kind - and\n  // this return keeps the mapper TOTAL when a SERVER is ahead of that pin,\n  // which no type can rule out. The standard's own escape hatch is the honest\n  // answer (`unknown` exists so a derivation can be total truthfully): the\n  // field keeps its name and falls back to raw entry against the contract's\n  // `json_schema`. Returning nothing produced a field with no `name` at all -\n  // unaddressable by the value bridge and unnameable by readiness.\n  node satisfies never;\n  return { ...common, kind: 'unknown' };\n}\n\n/**\n * Map a pipe's wire input-form descriptor onto the kernel's field descriptors,\n * with the pipe's input contracts beside it for the two schema-derived facts.\n *\n * The order is the DESCRIPTOR's - authored input order, the fact the contract's\n * `inputs` map deliberately does not carry. `required`, `presence` and `gating`\n * are taken from the wire verbatim: the standard's top-level type ties\n * `required` to the presence marker, and `gating` is the producer-derived\n * answer `mustBeFilled` reads - the kernel re-derives none of them.\n */\n/**\n * The same mapping, for a single node that belongs to no slot — a pipe's OUTPUT.\n *\n * `buildRunFields` maps a descriptor's fields and then stamps each with the slot\n * facts (`presence`, `gating`) the wire states per input. An output has no slot,\n * so this stamps nothing: the node arrives without them and leaves without them,\n * which is exactly what the standard's optional members are for.\n *\n * Everything else is shared, deliberately. An output is a concept ref like an\n * input is, so its kinds, its nesting, its list bounds and its `contentKey` are\n * the same questions with the same answers — and a second mapper would be a\n * second place for them to drift.\n *\n * ## `schema` is REQUIRED, and that is the whole point\n *\n * It was optional once, and the renderer paid for it: with no schema it could\n * not know that `native.Text`'s payload sits under `text`, so it worked the\n * unwrapping out by COUNTING the value's properties, and worked a plural payload\n * out by looking for an `items` key. Both are shape sniffing — the exact pattern\n * [../../docs/derivation-swap.md] records deleting from the input side, where\n * `contentKey` is read off a schema and handed to a control as a property NAME.\n *\n * So the parameter is required, the two heuristics are gone, and what the\n * argument must be is stated precisely: **the schema of the PAYLOAD**, which for\n * every kind but `object` is the content model that wraps it —\n * `TextContent {text}` for a `native.Text` output, `ListContent {items}` for a\n * plural one. That is a change the standard has to make on the output contract\n * (see `./output-form`); until it does, a producer supplies it beside the\n * descriptor.\n */\nexport function buildResultField(\n  descriptor: { field: InputFormField },\n  schema: Record<string, unknown>,\n): RunField {\n  const node = descriptor.field;\n  const defs: Record<string, JsonSchema> = {};\n  collectSchemaDefs(schema as JsonSchema, defs, { traverseArrays: true });\n\n  // Unwrap the content model, ONCE, at the top.\n  //\n  // A result's payload is its concept's content model, and for every kind but\n  // `object` that model is a wrapper: the value sits under a single property the\n  // schema names. Reading it here rather than in `mapNode` is what keeps the\n  // schema walk ALIGNED with the descriptor beneath it — a plural output's node\n  // is a `list`, so the schema it must be walked against is the `items` array,\n  // not the `ListContent` object around it.\n  //\n  // Gated on the node's stated KIND, never on the value: an `object` output IS\n  // its content model, and a structured concept that happens to declare exactly\n  // one field would otherwise be mistaken for a wrapper. The kind comes from the\n  // descriptor, so this is a read of what the field is, not a guess at it.\n  const wrapperKey = node.kind === 'object' ? undefined : scalarWrapperKey(schema as JsonSchema);\n  const inner =\n    wrapperKey === undefined\n      ? (schema as JsonSchema)\n      : ((schema as JsonSchema).properties as Record<string, JsonSchema>)[wrapperKey];\n\n  const field = mapNode(node, node.name, inner, defs);\n  return wrapperKey === undefined ? field : { ...field, contentKey: wrapperKey };\n}\n\nexport function buildRunFields(\n  descriptor: PipeInputFormDescriptor,\n  inputs: Record<string, PipeInputContract>,\n): RunField[] {\n  return descriptor.fields.map((node) => {\n    const input = ownProp(inputs, node.name);\n    const defs: Record<string, JsonSchema> = {};\n    if (input) collectSchemaDefs(input.json_schema, defs, { traverseArrays: true });\n    const field = mapNode(node, node.name, input?.json_schema as JsonSchema | undefined, defs);\n    return { ...field, presence: node.presence, gating: node.gating };\n  });\n}\n"]}

package/dist/core/contracts.d.ts

@@ -12,7 +12,7 @@ export { IOMultiplicity, PipeIOContract, PipeIOContracts, PipeInputContract, Pip
  * predicates that turn a declared slot into a gating answer, and the lookup
  * that tolerates both key conventions a real payload arrives with.
  *
- * `mthds` is a TYPES-ONLY peer dependency: every import here is `import type`,
+ * `mthds` is a TYPES-ONLY dependency: every import here is `import type`,
  * so nothing survives into `dist/` and no consumer ships the standard's CLI.
  * `scripts/assert-bundle.mjs` holds that on the built graph and lint holds it
  * on the source. See docs/dependency-budget.md.
@@ -34,9 +34,9 @@ export { IOMultiplicity, PipeIOContract, PipeIOContracts, PipeInputContract, Pip
  *   which lint and graph surfaces read and a form does not.
  *
  * Kept as an alias rather than renamed because a consumer imports it by this
- * name; a host that would rather read the standard's spelling has `mthds`
- * installed through this package's peer and can import `PresenceMarker`
- * straight from `mthds/protocol`.
+ * name; a host that would rather read the standard's spelling gets `mthds`
+ * installed alongside this package and can import `PresenceMarker` straight
+ * from `mthds/protocol`.
  */
 type InputPresence = PresenceMarker;
 /** Namespaced pipe ref (`<domain>.<pipe_code>`) - the identity convention the

package/dist/core/contracts.js

@@ -1,4 +1,4 @@
-export { buildPipeRef, getPipeIOContract, inputMustBeFilled, isFixedCountInput, isOptionalInput, isPluralInput } from '../chunk-XYQ7NXQZ.js';
+export { buildPipeRef, getPipeIOContract, inputMustBeFilled, isFixedCountInput, isOptionalInput, isPluralInput } from '../chunk-WYH56SOZ.js';
 import '../chunk-V3OV2XQT.js';
 //# sourceMappingURL=contracts.js.map
 //# sourceMappingURL=contracts.js.map

package/dist/core/derive.d.ts

@@ -1,6 +1,7 @@
 import { InputFormField, PipeInputFormDescriptor, PipeInputContract, InputForm } from 'mthds/protocol';
 import { RunField } from './descriptor.js';
 import './contracts.js';
+import './file-formats.js';
 
 /**
  * The ONE derivation function: wire input-form descriptor → `RunField[]`.

package/dist/core/derive.js

@@ -1,7 +1,7 @@
-export { buildResultField, buildRunFields, getPipeInputForm } from '../chunk-J4L32LD6.js';
-import '../chunk-2JWRG53S.js';
+export { buildResultField, buildRunFields, getPipeInputForm } from '../chunk-ZB4RYUKV.js';
+import '../chunk-XCO6GTEC.js';
 import '../chunk-OD3VYXUY.js';
-import '../chunk-XYQ7NXQZ.js';
+import '../chunk-WYH56SOZ.js';
 import '../chunk-V3OV2XQT.js';
 //# sourceMappingURL=derive.js.map
 //# sourceMappingURL=derive.js.map

package/dist/core/descriptor.d.ts

@@ -1,4 +1,5 @@
 import { InputPresence } from './contracts.js';
+import { FileFormat } from './file-formats.js';
 import 'mthds/protocol';
 
 /**
@@ -123,8 +124,18 @@ interface EnumRunField extends RunFieldCommon {
 }
 interface FileRunField extends RunFieldCommon {
     kind: 'document' | 'image';
-    /** Accept hint shown to the user, e.g. "PDF, PNG, JPG". */
-    accept?: string;
+    /**
+     * The formats this slot accepts, in the order the hint names them. The ONE
+     * list the file control reads for all three of its answers - the hint under
+     * the dropzone, the OS picker's filter and the check a picked or dropped file
+     * must pass - so none of them can promise what another refuses.
+     *
+     * Not a wire fact: which bytes a runtime can decode is a property of the
+     * runtime, so `buildRunFields` stamps the kind's whole table here
+     * (`formatsForKind`), and a host whose own upload path takes less narrows the
+     * tree with `narrowFileFormats`.
+     */
+    formats: readonly FileFormat[];
 }
 interface ObjectRunField extends RunFieldCommon {
     kind: 'object';

package/dist/core/descriptor.js

@@ -1,3 +1,3 @@
-export { conceptCategory } from '../chunk-25I6JDIK.js';
+export { conceptCategory } from '../chunk-FABY3DEY.js';
 //# sourceMappingURL=descriptor.js.map
 //# sourceMappingURL=descriptor.js.map

package/dist/core/file-formats.d.ts

@@ -50,7 +50,14 @@
  * A stale entry here is worse than no list at all, because it refuses a file the
  * runtime would have taken. If the deck grows a format, this table moves with it.
  *
- * Pure data. No React, no ajv, nothing imported.
+ * **The table is the source; a field's `formats` is what gets read.** The
+ * helpers below take a format LIST rather than a kind, because what a given
+ * slot accepts can be narrower than its kind: a host whose server takes only
+ * some of these types narrows the field tree once (`narrowFileFormats`), and
+ * the dropzone's hint, its picker filter and its check all read the narrowed
+ * list, so the three cannot disagree with each other or with that server.
+ *
+ * Pure data and pure functions over it. No React, no ajv, nothing imported.
  */
 /** One accepted format: its MIME type and the extensions that carry it. */
 interface FileFormat {
@@ -74,19 +81,39 @@ declare const DOCUMENT_FORMATS: readonly FileFormat[];
  * must not be refused over its spelling.
  */
 declare const IMAGE_FORMATS: readonly FileFormat[];
+/**
+ * The source table: every format a slot of this kind can take, before a host
+ * narrows it. `buildRunFields` stamps this onto each `document` and `image`
+ * field as its `formats`, and everything downstream reads the field's list
+ * rather than coming back here - which is what lets a host narrow one list and
+ * have the hint, the picker and the check all follow it.
+ */
 declare function formatsForKind(kind: 'document' | 'image'): readonly FileFormat[];
-/** `"PDF, DOCX, PPTX"` — the hint shown under a dropzone. */
-declare function acceptLabelForKind(kind: 'document' | 'image'): string;
 /**
- * Whether a picked file is one this kind accepts.
+ * A MIME type as the table spells it: no parameters, no surrounding space,
+ * lowercase. `APPLICATION/PDF; version=1.7` is `application/pdf`.
+ */
+declare function normalizeMimeType(type: string): string;
+/** `"PDF, JPG, PNG"` - the hint shown under a dropzone. */
+declare function acceptLabel(formats: readonly FileFormat[]): string;
+/**
+ * The format a filename's extension names, among these formats, or `undefined`
+ * when it names none of them. Case-insensitive, because `PHOTO.PNG` is a PNG.
+ */
+declare function formatOfFilename(formats: readonly FileFormat[], filename: string): FileFormat | undefined;
+/**
+ * Whether a picked file is one of these formats.
  *
  * Checks the MIME type first and falls back to the extension, because a
  * browser's `File.type` is empty often enough to matter: an OS with no handler
  * registered for `.docx` reports `''`, and refusing that file would be refusing
  * a valid one over a fact about the user's machine. A wrong-but-present MIME
  * type is still a rejection — that is the case this exists for.
+ *
+ * It takes the field's own list, never the kind's, so a slot a host narrowed
+ * refuses exactly what its hint no longer names.
  */
-declare function isAcceptedFile(kind: 'document' | 'image', file: {
+declare function isAcceptedFile(formats: readonly FileFormat[], file: {
     name: string;
     type: string;
 }): boolean;
@@ -97,6 +124,6 @@ declare function isAcceptedFile(kind: 'document' | 'image', file: {
  * `accept` attribute is built from. Listing extensions BESIDE the MIME type is
  * what makes the empty-`File.type` case above work in the OS picker too.
  */
-declare function acceptMapForKind(kind: 'document' | 'image'): Record<string, string[]>;
+declare function acceptMap(formats: readonly FileFormat[]): Record<string, string[]>;
 
-export { DOCUMENT_FORMATS, type FileFormat, IMAGE_FORMATS, acceptLabelForKind, acceptMapForKind, formatsForKind, isAcceptedFile };
+export { DOCUMENT_FORMATS, type FileFormat, IMAGE_FORMATS, acceptLabel, acceptMap, formatOfFilename, formatsForKind, isAcceptedFile, normalizeMimeType };

package/dist/core/file-formats.js

@@ -1,3 +1,3 @@
-export { DOCUMENT_FORMATS, IMAGE_FORMATS, acceptLabelForKind, acceptMapForKind, formatsForKind, isAcceptedFile } from '../chunk-2JWRG53S.js';
+export { DOCUMENT_FORMATS, IMAGE_FORMATS, acceptLabel, acceptMap, formatOfFilename, formatsForKind, isAcceptedFile, normalizeMimeType } from '../chunk-XCO6GTEC.js';
 //# sourceMappingURL=file-formats.js.map
 //# sourceMappingURL=file-formats.js.map

package/dist/core/gate.js

@@ -1,12 +1,12 @@
-export { apiInputsFromSchemaData, buildRunInputsSchema, gateRunInputs, prepareRunInputs, validateRunInputs } from '../chunk-R7B7ID25.js';
+export { apiInputsFromSchemaData, buildRunInputsSchema, gateRunInputs, prepareRunInputs, validateRunInputs } from '../chunk-IUWLOSAM.js';
 import '../chunk-GCXV76WU.js';
 import '../chunk-LBFZXYCY.js';
 import '../chunk-PM55AHRO.js';
 import '../chunk-VTPUDBSJ.js';
 import '../chunk-GKV77RAS.js';
-import '../chunk-YEVVR6FE.js';
+import '../chunk-Y2ND6W4W.js';
 import '../chunk-OD3VYXUY.js';
-import '../chunk-XYQ7NXQZ.js';
+import '../chunk-WYH56SOZ.js';
 import '../chunk-V3OV2XQT.js';
 //# sourceMappingURL=gate.js.map
 //# sourceMappingURL=gate.js.map

package/dist/core/gating-fields.d.ts

@@ -1,6 +1,7 @@
 import { PipeInputContract } from 'mthds/protocol';
 import { RunField } from './descriptor.js';
 import './contracts.js';
+import './file-formats.js';
 
 /**
  * The gate's own field tree - structural, schema-derived, and private.

package/dist/core/gating-fields.js

@@ -1,6 +1,6 @@
-export { gatingFieldsFromInputs } from '../chunk-YEVVR6FE.js';
+export { gatingFieldsFromInputs } from '../chunk-Y2ND6W4W.js';
 import '../chunk-OD3VYXUY.js';
-import '../chunk-XYQ7NXQZ.js';
+import '../chunk-WYH56SOZ.js';
 import '../chunk-V3OV2XQT.js';
 //# sourceMappingURL=gating-fields.js.map
 //# sourceMappingURL=gating-fields.js.map

package/dist/core/index.d.ts

@@ -3,8 +3,9 @@ export { IOMultiplicity, InputForm, InputFormTopLevelField, OutputForm, PipeIOCo
 export { buildResultField, buildRunFields, getPipeInputForm } from './derive.js';
 export { getPipeOutputForm } from './output-form.js';
 export { StuffFile, collectStuffFiles } from './stuff-files.js';
-export { DOCUMENT_FORMATS, FileFormat, IMAGE_FORMATS, acceptLabelForKind, acceptMapForKind, formatsForKind, isAcceptedFile } from './file-formats.js';
-export { CompositeMember, DateContentView, DocumentContentView, HtmlContentView, ImageContentView, NATIVE_COMPOSITE_CONCEPT_REF, NATIVE_DATE_CONCEPT_REF, NATIVE_HTML_CONCEPT_REF, TYPED_SCALAR_MARKERS, formatDateContent, hasTypedScalarMarkers, isNativeCompositeNode, isNativeDateNode, isNativeHtmlNode, isViewableUrl, readCompositeContent, readDateContent, readDocumentContent, readHtmlContent, readImageContent } from './native-content.js';
+export { DOCUMENT_FORMATS, FileFormat, IMAGE_FORMATS, acceptLabel, acceptMap, formatsForKind, isAcceptedFile } from './file-formats.js';
+export { narrowFileFormats } from './narrow-file-formats.js';
+export { CompositeMember, DataUrlView, DateContentView, DocumentContentView, HtmlContentView, ImageContentView, NATIVE_COMPOSITE_CONCEPT_REF, NATIVE_DATE_CONCEPT_REF, NATIVE_HTML_CONCEPT_REF, TYPED_SCALAR_MARKERS, formatDateContent, hasTypedScalarMarkers, isNativeCompositeNode, isNativeDateNode, isNativeHtmlNode, isViewableUrl, readCompositeContent, readDataUrl, readDateContent, readDocumentContent, readHtmlContent, readImageContent, viewableUrl } from './native-content.js';
 export { Readiness, computeReadiness, fieldFilled, isFilled, mustBeFilled } from './readiness.js';
 export { InputPresence, buildPipeRef, getPipeIOContract, inputMustBeFilled, isFixedCountInput, isOptionalInput, isPluralInput } from './contracts.js';
 export { RunInputsGateResult, RunInputsVerdict, apiInputsFromSchemaData, buildRunInputsSchema, gateRunInputs, prepareRunInputs, validateRunInputs } from './gate.js';

package/dist/core/index.js

@@ -1,20 +1,21 @@
 export { describeValidationError, displayValue, valueAtProperty } from '../chunk-RPA7DNSK.js';
-export { apiInputsFromRunValues, fieldsForContract, inputDataFromWorkingMemory, outputsFromPipeOutput, rjsfDataFromRunValues, runValuesFromStore, setValueAtPath, storeInputDataFromRunValues } from '../chunk-T4NSAGOS.js';
-export { getPipeOutputForm } from '../chunk-IIU3YK4O.js';
-export { collectStuffFiles } from '../chunk-4BSBBG2T.js';
-export { NATIVE_COMPOSITE_CONCEPT_REF, NATIVE_DATE_CONCEPT_REF, NATIVE_HTML_CONCEPT_REF, TYPED_SCALAR_MARKERS, formatDateContent, hasTypedScalarMarkers, isNativeCompositeNode, isNativeDateNode, isNativeHtmlNode, isViewableUrl, readCompositeContent, readDateContent, readDocumentContent, readHtmlContent, readImageContent } from '../chunk-45C2MKK6.js';
-export { buildResultField, buildRunFields, getPipeInputForm } from '../chunk-J4L32LD6.js';
-export { conceptCategory } from '../chunk-25I6JDIK.js';
-export { DOCUMENT_FORMATS, IMAGE_FORMATS, acceptLabelForKind, acceptMapForKind, formatsForKind, isAcceptedFile } from '../chunk-2JWRG53S.js';
-export { apiInputsFromSchemaData, buildRunInputsSchema, gateRunInputs, prepareRunInputs, validateRunInputs } from '../chunk-R7B7ID25.js';
+export { apiInputsFromRunValues, fieldsForContract, inputDataFromWorkingMemory, outputsFromPipeOutput, rjsfDataFromRunValues, runValuesFromStore, setValueAtPath, storeInputDataFromRunValues } from '../chunk-4KGQ65TQ.js';
+export { collectStuffFiles } from '../chunk-4JQAJT7C.js';
+export { narrowFileFormats } from '../chunk-CAKQ5VFT.js';
+export { NATIVE_COMPOSITE_CONCEPT_REF, NATIVE_DATE_CONCEPT_REF, NATIVE_HTML_CONCEPT_REF, TYPED_SCALAR_MARKERS, formatDateContent, hasTypedScalarMarkers, isNativeCompositeNode, isNativeDateNode, isNativeHtmlNode, isViewableUrl, readCompositeContent, readDataUrl, readDateContent, readDocumentContent, readHtmlContent, readImageContent, viewableUrl } from '../chunk-TID7ZN63.js';
+export { getPipeOutputForm } from '../chunk-DARLDVJM.js';
+export { buildResultField, buildRunFields, getPipeInputForm } from '../chunk-ZB4RYUKV.js';
+export { conceptCategory } from '../chunk-FABY3DEY.js';
+export { DOCUMENT_FORMATS, IMAGE_FORMATS, acceptLabel, acceptMap, formatsForKind, isAcceptedFile } from '../chunk-XCO6GTEC.js';
+export { apiInputsFromSchemaData, buildRunInputsSchema, gateRunInputs, prepareRunInputs, validateRunInputs } from '../chunk-IUWLOSAM.js';
 export { deflateAllInputs, deflateInput, healStringWrappers, inflateAllInputs, inflateInput, pruneEmptyOptionals, resolveConceptCode } from '../chunk-GCXV76WU.js';
 export { normalizeSchemaForRjsf, prepareSchemaForRjsf } from '../chunk-LBFZXYCY.js';
 export { computeReadiness, fieldFilled, isFilled, mustBeFilled } from '../chunk-PM55AHRO.js';
 export { validateRunInputsSchema } from '../chunk-VTPUDBSJ.js';
 export { asCalendarDate, dayWithinDateTime, isAcceptableDate, isAcceptableDateTime, toDateInputValue, toStoredDateValue } from '../chunk-GKV77RAS.js';
-import '../chunk-YEVVR6FE.js';
+import '../chunk-Y2ND6W4W.js';
 export { collapseNullable, collectSchemaDefs, derefSchema, flattenAnyOf, hoistDefsToRoot, resolveSchemaIndirection, schemaTypeOf } from '../chunk-OD3VYXUY.js';
-export { buildPipeRef, getPipeIOContract, inputMustBeFilled, isFixedCountInput, isOptionalInput, isPluralInput } from '../chunk-XYQ7NXQZ.js';
+export { buildPipeRef, getPipeIOContract, inputMustBeFilled, isFixedCountInput, isOptionalInput, isPluralInput } from '../chunk-WYH56SOZ.js';
 import '../chunk-V3OV2XQT.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/core/narrow-file-formats.d.ts

@@ -0,0 +1,50 @@
+import { RunField } from './descriptor.js';
+import './contracts.js';
+import 'mthds/protocol';
+import './file-formats.js';
+
+/**
+ * Narrowing what a form's file slots accept to what a host will take.
+ *
+ * `buildRunFields` gives every `document` and `image` field the whole of its
+ * kind's table (`./file-formats`): everything the runtime can decode. A host's
+ * own upload path can be narrower - a method that only ever reads photographs,
+ * a server that stores only some types - and a dropzone that advertises more
+ * than the server takes refuses the file only after the upload has been asked
+ * for. So a host narrows the tree once, with the same list its server checks
+ * uploads against, and the control reads the narrowed list for its hint, its
+ * picker filter and its check.
+ *
+ * It reads `RunField`, the kernel's own output, and never a JSON Schema: which
+ * bytes a runtime can decode is not a wire fact, so there is nothing in the
+ * schema to read, and the two schema walks the kernel allows stay the only two.
+ *
+ * It lives in the core rather than on `FieldEnv` so that a host's server, which
+ * renders no control, can hold the very list its form was narrowed with.
+ *
+ * Pure: no React, no ajv, and the input tree is never mutated.
+ */
+
+/**
+ * The field tree with every `document` and `image` field narrowed to the
+ * formats whose MIME type is in `mimeTypes`, walking nested structures and
+ * list items.
+ *
+ * One list serves every slot: it is intersected with each slot's own formats,
+ * so a list of PDF, PNG and JPEG leaves a document slot with all three and an
+ * image slot with PNG and JPEG. Narrowing never widens a slot - a MIME type the
+ * slot's kind cannot take is simply not in the intersection - and each slot
+ * keeps its own table's order, whatever order the list is in. MIME types are
+ * compared the way `isAcceptedFile` compares them: without parameters, and
+ * case-insensitively.
+ *
+ * **Throws when a slot would be left accepting nothing**, naming the field. A
+ * dropzone that refuses every file is a host's configuration error, and a form
+ * that renders one has already failed the person holding the file.
+ *
+ * The input tree is never mutated: a file slot, a structure or a list comes
+ * back as a copy, and every other field as the same object it was.
+ */
+declare function narrowFileFormats(fields: readonly RunField[], mimeTypes: readonly string[]): RunField[];
+
+export { narrowFileFormats };

package/dist/core/narrow-file-formats.js

@@ -0,0 +1,4 @@
+export { narrowFileFormats } from '../chunk-CAKQ5VFT.js';
+import '../chunk-XCO6GTEC.js';
+//# sourceMappingURL=narrow-file-formats.js.map
+//# sourceMappingURL=narrow-file-formats.js.map

package/dist/core/narrow-file-formats.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"narrow-file-formats.js"}

package/dist/core/native-content.d.ts

@@ -132,10 +132,7 @@ declare function readCompositeContent(value: unknown): CompositeMember[] | undef
  * wants the markup rendered just the same. `refines` is on the wire for exactly
  * this question.
  */
-declare function isNativeHtmlNode(node: {
-    conceptRef?: string;
-    refines?: readonly string[];
-}): boolean;
+declare function isNativeHtmlNode(node: NativeNode): boolean;
 /**
  * Whether a node IS a `native.Date` — the other content model the kind
  * vocabulary cannot name.
@@ -150,10 +147,7 @@ declare function isNativeHtmlNode(node: {
  * A `date` FIELD inside a structure is a different thing and needs none of this:
  * it carries `kind: "date"` already.
  */
-declare function isNativeDateNode(node: {
-    conceptRef?: string;
-    refines?: readonly string[];
-}): boolean;
+declare function isNativeDateNode(node: NativeNode): boolean;
 /**
  * Whether a node is a `native.Composite` — a named bag of contents.
  *
@@ -168,10 +162,25 @@ declare function isNativeDateNode(node: {
  * of ordinary `StuffContent`s. Keyed by concept, a renderer can at least show
  * the members as the named things they are. See `CompositeValue`.
  */
-declare function isNativeCompositeNode(node: {
+declare function isNativeCompositeNode(node: NativeNode): boolean;
+/**
+ * Whether a node is one of the three natives the kind vocabulary cannot name —
+ * a date, a page, a composite — which a renderer reads by CONCEPT before it
+ * reads the kind. A list of one answers no (the predicates refuse a `list`
+ * node), and its item answers yes.
+ *
+ * One answer, read twice: the result view renders a list whose item answers yes
+ * one value per line rather than as a table, and the generative layer delegates
+ * that list to the kernel, because no catalog component reads a native value.
+ * Not re-exported: a host asks the three predicates it needs.
+ */
+declare function isNativeValueNode(node: NativeNode): boolean;
+/** What the native predicates read off a node: its stated kind and its concept. */
+interface NativeNode {
+    kind?: string;
     conceptRef?: string;
     refines?: readonly string[];
-}): boolean;
+}
 /**
  * Read a `date`-kind value, in any of the three shapes a run produces.
  *
@@ -184,14 +193,50 @@ declare function isNativeCompositeNode(node: {
 declare function readDateContent(value: unknown): DateContentView | undefined;
 /** `{date}` / `{date, time}` as one line, which is how both are read aloud. */
 declare function formatDateContent(content: DateContentView): string;
+/** What a `data:` URL says about the bytes it carries. */
+interface DataUrlView {
+    /** Lowercased, without its parameters; `text/plain` when the URL declares none. */
+    mediaType: string;
+    /** The size of the DECODED payload, in bytes. */
+    bytes: number;
+}
 /**
- * Whether a browser can paint this URL as-is.
+ * A `data:` URL's media type and decoded size, or `undefined` for any other URL.
  *
- * A `pipelex-storage://` reference cannot be resolved client-side — that is the
- * upload seam's job (see [../../docs/upload-seam.md]) — so a renderer with no
- * resolver must show the reference rather than a broken `<img>`. `file:` is
- * deliberately NOT viewable: a run on a developer's machine writes one, and a
- * browser refuses to load it from a page served over http.
+ * A host that encodes a picked file in the browser writes the file itself into
+ * the value's `url`, so a thirty-kilobyte PDF is a forty-thousand-character
+ * string, and printed where a reference would be it tells a person nothing. Its
+ * type and its size are what they can read.
+ *
+ * The size is COUNTED rather than decoded. A base64 payload's size follows from
+ * how many symbols it holds, and decoding a megabyte to measure it would be the
+ * frozen main thread {@link stripUrlWhitespace} is written to avoid. This is a
+ * reading for display, not a gate: whether the URL may be painted is still
+ * {@link viewableUrl}'s answer alone.
+ */
+declare function readDataUrl(candidate: string): DataUrlView | undefined;
+/**
+ * The URL a browser can paint, normalised — or `undefined` when there is none.
+ *
+ * **The string this returns is the string a sink must use.** That is the whole
+ * point of returning one rather than answering yes or no: the gate judges a
+ * normalised URL, so handing the caller back the raw member would let the two
+ * diverge again on exactly the whitespace the parser strips.
+ *
+ * The gate parses rather than prefix-matches, and branches on the protocol the
+ * parser reports:
+ *
+ * - `http:` and `https:` are viewable.
+ * - `blob:` is viewable. A blob URL is bound to the origin that minted it, so a
+ *   payload cannot forge one that points anywhere else.
+ * - `data:` is viewable only for a media type in {@link VIEWABLE_DATA_MEDIA_TYPES}.
+ *   `data:text/html` is a document at the EMBEDDING page's own origin, which is
+ *   what made an unsandboxed frame over a payload URL a real hole.
+ * - Everything else is not: `javascript:`, `file:` (a run on a developer's
+ *   machine writes one, and a browser refuses to load it from an http page) and
+ *   `pipelex-storage://`, which cannot be resolved client-side at all — that is
+ *   the upload seam's job (see [../../docs/upload-seam.md]), and a renderer with
+ *   no resolver must show the reference rather than a broken `<img>`.
  *
  * **A root-relative path counts**, and leaving it out was a real bug rather
  * than an omission. A host's URL resolver naturally hands back a path on its
@@ -201,8 +246,19 @@ declare function formatDateContent(content: DateContentView): string;
  * away and the arms fell back to the payload's `public_url`: a presigned URL
  * that had already expired. The image stayed broken with the fix in place.
  *
- * `//host/path` is deliberately excluded. It is protocol-relative, so it points
- * at another origin while looking like a path.
+ * A path is rejected when it is protocol-relative — `//host/x`, and the two
+ * backslash spellings the parser reads the same way (`\\host\x`, `/\host/x`) —
+ * and then checked against the sentinel as well. An accepted path is returned
+ * relative, because making it absolute against a sentinel would point it at
+ * nowhere.
+ */
+declare function viewableUrl(candidate: string | undefined): string | undefined;
+/**
+ * Whether a browser can paint this URL as-is — {@link viewableUrl} as a guard.
+ *
+ * Prefer `viewableUrl` wherever the URL is then USED: this answers the question
+ * without handing back the normalised string, so a caller that acts on the raw
+ * candidate acts on a string the gate did not judge.
  */
 declare function isViewableUrl(url: string | undefined): url is string;
 /**
@@ -216,4 +272,4 @@ declare const TYPED_SCALAR_MARKERS: readonly ["__class__", "__module__"];
 /** Whether a record carries the typed-scalar markers. Informational. */
 declare function hasTypedScalarMarkers(value: unknown): boolean;
 
-export { type CompositeMember, type DateContentView, type DocumentContentView, type HtmlContentView, type ImageContentView, NATIVE_COMPOSITE_CONCEPT_REF, NATIVE_DATE_CONCEPT_REF, NATIVE_HTML_CONCEPT_REF, TYPED_SCALAR_MARKERS, formatDateContent, hasTypedScalarMarkers, isNativeCompositeNode, isNativeDateNode, isNativeHtmlNode, isViewableUrl, readCompositeContent, readDateContent, readDocumentContent, readHtmlContent, readImageContent };
+export { type CompositeMember, type DataUrlView, type DateContentView, type DocumentContentView, type HtmlContentView, type ImageContentView, NATIVE_COMPOSITE_CONCEPT_REF, NATIVE_DATE_CONCEPT_REF, NATIVE_HTML_CONCEPT_REF, TYPED_SCALAR_MARKERS, formatDateContent, hasTypedScalarMarkers, isNativeCompositeNode, isNativeDateNode, isNativeHtmlNode, isNativeValueNode, isViewableUrl, readCompositeContent, readDataUrl, readDateContent, readDocumentContent, readHtmlContent, readImageContent, viewableUrl };

package/dist/core/native-content.js

@@ -1,4 +1,4 @@
-export { NATIVE_COMPOSITE_CONCEPT_REF, NATIVE_DATE_CONCEPT_REF, NATIVE_HTML_CONCEPT_REF, TYPED_SCALAR_MARKERS, formatDateContent, hasTypedScalarMarkers, isNativeCompositeNode, isNativeDateNode, isNativeHtmlNode, isViewableUrl, readCompositeContent, readDateContent, readDocumentContent, readHtmlContent, readImageContent } from '../chunk-45C2MKK6.js';
+export { NATIVE_COMPOSITE_CONCEPT_REF, NATIVE_DATE_CONCEPT_REF, NATIVE_HTML_CONCEPT_REF, TYPED_SCALAR_MARKERS, formatDateContent, hasTypedScalarMarkers, isNativeCompositeNode, isNativeDateNode, isNativeHtmlNode, isNativeValueNode, isViewableUrl, readCompositeContent, readDataUrl, readDateContent, readDocumentContent, readHtmlContent, readImageContent, viewableUrl } from '../chunk-TID7ZN63.js';
 import '../chunk-V3OV2XQT.js';
 //# sourceMappingURL=native-content.js.map
 //# sourceMappingURL=native-content.js.map

package/dist/core/output-form.js

@@ -1,5 +1,5 @@
-export { getPipeOutputForm } from '../chunk-IIU3YK4O.js';
-import '../chunk-XYQ7NXQZ.js';
+export { getPipeOutputForm } from '../chunk-DARLDVJM.js';
+import '../chunk-WYH56SOZ.js';
 import '../chunk-V3OV2XQT.js';
 //# sourceMappingURL=output-form.js.map
 //# sourceMappingURL=output-form.js.map

package/dist/core/readiness.d.ts

@@ -1,6 +1,7 @@
 import { RunField } from './descriptor.js';
 import './contracts.js';
 import 'mthds/protocol';
+import './file-formats.js';
 
 /**
  * Value readiness - the helpers the runner uses to decide whether the Run

package/dist/core/stuff-files.d.ts

@@ -1,6 +1,7 @@
 import { RunField } from './descriptor.js';
 import './contracts.js';
 import 'mthds/protocol';
+import './file-formats.js';
 
 /**
  * One file a stuff carries: what to fetch, and what to call it once saved.

package/dist/core/stuff-files.js

@@ -1,5 +1,5 @@
-export { collectStuffFiles } from '../chunk-4BSBBG2T.js';
-import '../chunk-45C2MKK6.js';
+export { collectStuffFiles } from '../chunk-4JQAJT7C.js';
+import '../chunk-TID7ZN63.js';
 import '../chunk-V3OV2XQT.js';
 //# sourceMappingURL=stuff-files.js.map
 //# sourceMappingURL=stuff-files.js.map

package/dist/core/values.d.ts

@@ -1,6 +1,7 @@
 import { PipeInputContract, PipeIOContract, PipeInputFormDescriptor } from 'mthds/protocol';
 import { RunField } from './descriptor.js';
 import './contracts.js';
+import './file-formats.js';
 
 /**
  * Bridges the `MethodRunner`'s field values to the rest of the host.

package/dist/core/values.js

@@ -1,11 +1,11 @@
-export { apiInputsFromRunValues, fieldsForContract, inputDataFromWorkingMemory, outputsFromPipeOutput, rjsfDataFromRunValues, runValuesFromStore, setValueAtPath, storeInputDataFromRunValues } from '../chunk-T4NSAGOS.js';
-import '../chunk-J4L32LD6.js';
-import '../chunk-2JWRG53S.js';
+export { apiInputsFromRunValues, fieldsForContract, inputDataFromWorkingMemory, outputsFromPipeOutput, rjsfDataFromRunValues, runValuesFromStore, setValueAtPath, storeInputDataFromRunValues } from '../chunk-4KGQ65TQ.js';
+import '../chunk-ZB4RYUKV.js';
+import '../chunk-XCO6GTEC.js';
 import '../chunk-GCXV76WU.js';
 import '../chunk-PM55AHRO.js';
 import '../chunk-GKV77RAS.js';
 import '../chunk-OD3VYXUY.js';
-import '../chunk-XYQ7NXQZ.js';
+import '../chunk-WYH56SOZ.js';
 import '../chunk-V3OV2XQT.js';
 //# sourceMappingURL=values.js.map
 //# sourceMappingURL=values.js.map

package/dist/field-renderer-BSU2hMf6.d.ts

@@ -0,0 +1,34 @@
+import * as react from 'react';
+import { RunField } from './core/descriptor.js';
+
+/**
+ * Ambient state that any field in the tree may need, threaded unchanged through
+ * the recursion so containers don't have to re-plumb it for every child.
+ */
+interface FieldEnv {
+    disabled?: boolean;
+    /** A file field asks its parent to upload; the parent sets the value later. */
+    onDropFile?: (id: string, file: File) => void;
+    /** Ids currently mid-upload. */
+    uploadingIds?: ReadonlySet<string>;
+    /** Resolve a `pipelex-storage://` URI to a browser-viewable URL (for previews
+     *  of already-stored files). */
+    resolveUrl?: (uri: string) => Promise<string | null>;
+}
+interface FieldRendererProps {
+    field: RunField;
+    value: unknown;
+    onChange: (value: unknown) => void;
+    /** Unique, stable id used for label linkage and upload tracking. */
+    id: string;
+    error?: string;
+    env?: FieldEnv;
+}
+/**
+ * The single dispatch point: a normalized `RunField` → the matching control.
+ * Object and list fields recurse back through here, so the whole form is one
+ * data-driven tree with no per-type branching anywhere else.
+ */
+declare function FieldRenderer({ field, value, onChange, id, error, env }: FieldRendererProps): react.JSX.Element;
+
+export { type FieldEnv as F, FieldRenderer as a, type FieldRendererProps as b };