@pipelex/mthds-form 0.3.0 → 0.5.0

package/dist/core/normalize-schema.d.ts

@@ -0,0 +1,30 @@
+export { hoistDefsToRoot } from './schema-utils.js';
+
+/**
+ * Normalizes a JSON Schema for RJSF compatibility.
+ *
+ * Pydantic v2 generates `anyOf: [{type: "string"}, {type: "null"}]` for optional
+ * fields (`str | None`). RJSF renders this as a dropdown selector asking the user
+ * to pick a sub-schema, which is terrible UX. The normalizer flattens those
+ * patterns on every node (see `flattenAnyOf` in `schema-utils.ts` for the exact
+ * rules) and hoists nested `$defs` to the root so composed sub-schemas keep
+ * their refs resolvable.
+ *
+ * The collapse and hoist engines live in `schema-utils.ts` - the
+ * consolidated home for the kernel's JSON-Schema plumbing; this module owns the
+ * recursive application over a whole schema tree.
+ */
+
+/**
+ * Recursively normalize a JSON Schema for RJSF.
+ * Walks the entire schema tree and flattens anyOf patterns on every node.
+ */
+declare function normalizeSchemaForRjsf(schema: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Prepare a schema for RJSF: hoist all nested `$defs` to the root, then normalize
+ * anyOf patterns. Call this on any schema that composes multiple sub-schemas
+ * (each of which may ship its own `$defs`).
+ */
+declare function prepareSchemaForRjsf(schema: Record<string, unknown>): Record<string, unknown>;
+
+export { normalizeSchemaForRjsf, prepareSchemaForRjsf };

package/dist/core/normalize-schema.js

@@ -0,0 +1,4 @@
+export { normalizeSchemaForRjsf, prepareSchemaForRjsf } from '../chunk-LBFZXYCY.js';
+export { hoistDefsToRoot } from '../chunk-OD3VYXUY.js';
+//# sourceMappingURL=normalize-schema.js.map
+//# sourceMappingURL=normalize-schema.js.map

package/dist/core/normalize-schema.js.map

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

package/dist/core/own-property.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Read a property a record OWNS, never one it merely inherits.
+ *
+ * Every name this package indexes a record by - an input variable name, a
+ * structure's property name, a pipe code, a concept's content key - is chosen
+ * by the METHOD AUTHOR, and the records they index are plain objects the host
+ * built (`{}` from a form's state, `JSON.parse` of a request body, a map keyed
+ * by pipe ref). A plain object inherits `Object.prototype`, so a name that
+ * collides with a prototype member - `constructor`, `toString`, `valueOf`,
+ * `hasOwnProperty`, … - does NOT read as `undefined`: it reads as the inherited
+ * function, which is truthy.
+ *
+ * That is a verdict bug wherever a bare read decides one. An input named
+ * `constructor` with nothing entered used to resolve to `Object`, which
+ * `isFilled` had no branch for and therefore called filled - a live Run button
+ * over an empty required input. `getPipeIOContract` returned the same function
+ * for a prototype-named pipe code, which sailed past the `if (!contract)` guard
+ * hosts are shown writing.
+ *
+ * What it does NOT close, stated so nobody reads a fixed read as a fixed class:
+ * the WRITE twin. `out[name] = value` on a plain object invokes the inherited
+ * `__proto__` setter for that one name, so an input actually called `__proto__`
+ * is dropped from a payload rather than added to it. That is fail-loud (the
+ * runtime rejects a run whose input is missing) where the read bug was
+ * fail-open, and `__proto__` is not a name an author writes, so the writes are
+ * left plain and legible.
+ *
+ * Spelled with `Object.prototype.hasOwnProperty.call` rather than `Object.hasOwn`
+ * deliberately. `hasOwn` is an ES2022 runtime API and `tsconfig.json` compiles
+ * to **ES2020**, so a browser inside the declared target has no such function
+ * and every read here would throw before a form could render a single field -
+ * a whole-package failure in service of a shorter spelling. TypeScript cannot
+ * catch that: `lib` is what types a runtime API, `target` is what states the
+ * baseline, and the two are allowed to disagree.
+ *
+ * Deliberately module-private: this is a spelling of `record[key]`, not a
+ * concept a consumer needs. Reachability is low - only a method author picks
+ * these names - but the cost of being wrong is a form that says a field is
+ * filled when it is empty, so the package spells the read one way everywhere
+ * rather than guarding the sites someone happened to notice.
+ */
+declare function ownProp<T>(record: Record<string, T> | null | undefined, key: string): T | undefined;
+/** `key in record` with the prototype chain left out. */
+declare function hasOwnProp(record: object | null | undefined, key: string): boolean;
+
+export { hasOwnProp, ownProp };

package/dist/core/own-property.js

@@ -0,0 +1,3 @@
+export { hasOwnProp, ownProp } from '../chunk-V3OV2XQT.js';
+//# sourceMappingURL=own-property.js.map
+//# sourceMappingURL=own-property.js.map

package/dist/core/own-property.js.map

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

package/dist/core/readiness.d.ts

@@ -0,0 +1,91 @@
+import { RunField } from './descriptor.js';
+import './contracts.js';
+import 'mthds/protocol';
+
+/**
+ * Value readiness - the helpers the runner uses to decide whether the Run
+ * button may fire and which inputs are still missing.
+ */
+
+/** True when a value is meaningfully filled (not empty / blank / empty container). */
+declare function isFilled(value: unknown): boolean;
+/**
+ * True when a slot holds something AND every required field inside it has a
+ * value.
+ *
+ * The two halves are both load-bearing, and the first one is the one that is
+ * easy to leave out. A structure is satisfied only if there is something in it:
+ * a struct whose concept declares no required child used to be *vacuously*
+ * satisfied by an absent value - every child passed the `!f.required` test, so
+ * `every` returned true over a value that was not there. Readiness reported
+ * nothing missing and the Run button lit up, while the value bridge omitted the
+ * untouched structure and the gate then rejected the run on the combined
+ * schema's `required` list, naming an input the form had just declared ready.
+ *
+ * `isFilled` is the SAME predicate `toRjsf` uses to decide whether a structure
+ * collapses to an absence (`values.ts`), which is what makes the two halves
+ * agree by construction rather than by parallel edits: readiness calls an input
+ * present exactly when the bridge keeps it. Absence is what a singular slot
+ * expresses, so a required one has to be touched - the button stays dark until
+ * the user puts a value somewhere inside, and then the whole shell travels,
+ * empty children and all, so a required child left blank still fails loudly.
+ *
+ * Its own recursion follows the DESCRIPTOR, not the value, so it needs no depth
+ * cap of its own: a `RunField` tree only exists because `buildRunFields`
+ * finished walking a contract's schema, which bounds it. `isFilled` is where
+ * the caller's data is walked, and where the cap lives.
+ */
+declare function fieldFilled(field: RunField, value: unknown): boolean;
+interface Readiness {
+    total: number;
+    ready: number;
+    missing: string[];
+}
+/**
+ * True when the user must put a value in this field before the run can start.
+ *
+ * Distinct from `required`, which also drives layout (a required field always
+ * shows; an optional one may collapse). A **variable-plural** field stays
+ * required - it is a first-class input and keeps its place in the form - but it
+ * never gates: a plural slot is never "absent" in MTHDS, its empty form IS the
+ * empty list, and no method can declare "at least one item". A **fixed-count**
+ * list (`[N]`) is the exception the wire now states, and it gates like any other
+ * slot - there the method HAS ruled the empty form out.
+ *
+ * **For a field this package built, the answer comes from `inputMustBeFilled`**
+ * (`contracts.ts`) - the SAME predicate the method viewer's Run button, its ajv
+ * `required` list and its missing-inputs toast all read. `buildRunFields`
+ * stamps it onto `gating`. This used to be re-derived here as
+ * `required && kind !== 'list'`: the same rule expressed against the MAPPED
+ * field instead of the contract, and the two could disagree - `kind` is `'list'`
+ * for a `conceptRef` ending in `[]` OR an array schema, while the contract's
+ * plural test is the array schema alone, so a plural input carrying a non-array
+ * schema gated on one surface and not the other.
+ *
+ * The shape heuristic survives only as the fallback for a **hand-authored**
+ * `RunField` - story fixtures and unit tests, which have no contract to consult
+ * and therefore nothing to disagree with. Every field a host renders comes from
+ * `buildRunFields` and carries `gating`, so a host is on the contract's answer
+ * alone. (The fallback cannot see a fixed count either - one more thing only the
+ * contract knows.)
+ */
+declare function mustBeFilled(field: RunField): boolean;
+/**
+ * How many top-level inputs stand between the current values and a run.
+ *
+ * Two kinds count, and the second is easy to miss. An input the method DEMANDS
+ * counts always (`mustBeFilled`). An input the method left optional counts once
+ * the user has put something in it - because a structure that has been touched
+ * owes its concept every field the concept declares, and the gate enforces
+ * exactly that. Left out, an optional struct opened and half-filled was ignored
+ * here and refused there: the button stayed live and the run came back rejected
+ * on a required child, which is the same disagreement the demanded case had.
+ *
+ * So an optional input moves INTO the denominator the moment it is touched, and
+ * out of `missing` as soon as it is complete: 3 of 3 while it is untouched, 3
+ * of 4 once it is started, 4 of 4 once it is done. `total` answers "how many
+ * things stand between me and Run", which is the number a host is displaying.
+ */
+declare function computeReadiness(fields: RunField[], values: Record<string, unknown>): Readiness;
+
+export { type Readiness, computeReadiness, fieldFilled, isFilled, mustBeFilled };

package/dist/core/readiness.js

@@ -0,0 +1,4 @@
+export { computeReadiness, fieldFilled, isFilled, mustBeFilled } from '../chunk-PM55AHRO.js';
+import '../chunk-V3OV2XQT.js';
+//# sourceMappingURL=readiness.js.map
+//# sourceMappingURL=readiness.js.map

package/dist/core/readiness.js.map

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

package/dist/core/schema-utils.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The ONE place JSON-Schema plumbing lives for the run form kernel: nullable
+ * `anyOf` collapsing, `$defs` collection/hoisting, `$ref` resolution, and type
+ * extraction. Consolidated from three drifted private copies (`field-model.ts`,
+ * `normalize-schema.ts`, `input-format.ts`) during the form-kernel extraction.
+ *
+ * Two collapse engines are exported ON PURPOSE - their semantics genuinely
+ * differ, and each caller's observable behavior is characterized and preserved
+ * (see `schema-utils-characterization.test.ts`):
+ *
+ * - `collapseNullable` (the field mapper's rule): collapse ONLY when exactly one
+ *   non-null branch remains, dropping the null. A multi-branch union stays an
+ *   `anyOf` and maps to the raw-JSON escape hatch.
+ * - `flattenAnyOf` (the RJSF/ajv rule): a union of simple primitives becomes a
+ *   `type` ARRAY (null preserved as a type entry - ajv validates `type:
+ *   ["number","null"]` natively); a 2-branch nullable non-primitive drops the
+ *   null branch.
+ *
+ * Whether these converge (and which semantics win) is an M1 question, decided
+ * when the descriptor derivation moves server-side - not silently here.
+ */
+type JsonSchema = Record<string, unknown>;
+/** Pydantic emits `anyOf: [T, {type:'null'}]` for Optional[T]; collapse to T.
+ *  Collapses ONLY when exactly one non-null branch remains; the branch merges
+ *  OVER the outer schema (its constraints win). */
+declare function collapseNullable(schema: JsonSchema): JsonSchema;
+/**
+ * The RJSF/ajv collapse: a union of simple primitives flattens to a `type`
+ * array (`anyOf: [{string},{null}]` → `type: ["string","null"]`, which RJSF
+ * renders as a plain input instead of a sub-schema picker); an exactly-two
+ * `[T, {null}]` union of anything else drops the null branch and merges T over
+ * the outer schema. Anything else passes through unchanged.
+ */
+declare function flattenAnyOf(schema: JsonSchema): JsonSchema;
+/** The schema's non-null type: a bare `type` string, or the first non-null
+ *  entry of a `type` array (`["number","null"]` → `"number"`). */
+declare function schemaTypeOf(schema: JsonSchema): string | undefined;
+/** Resolve `{ $ref: "#/$defs/Foo" }` against a collected `$defs` map. Sibling
+ *  keys on the referencing schema override the definition's. */
+declare function derefSchema(schema: JsonSchema, defs: Record<string, JsonSchema>): JsonSchema;
+/**
+ * Resolve the indirection layers pydantic puts in front of a value schema - a
+ * `#/$defs/...` ref, a nullable `anyOf: [T, {null}]` wrapper, or a stack of
+ * both - until a plain schema remains. This is the resolver `healStringWrappers`
+ * and `pruneEmptyOptionals` apply before reading `type`. Unlike `derefSchema`
+ * it REPLACES the schema with the definition (no sibling merge) - exactly what
+ * the callers did inline.
+ */
+declare function resolveSchemaIndirection(schema: JsonSchema, defs: Record<string, JsonSchema>): JsonSchema;
+/**
+ * Resolve one schema node to its fixpoint under `derefSchema` +
+ * `collapseNullable`, so a nullable REFERENCE - pydantic's `anyOf: [{$ref},
+ * {type:'null'}]` for an Optional concept-typed field - resolves the same way
+ * a bare `$ref` or an inline nullable does. One pass of either helper cannot:
+ * collapsing the nullable surfaces a `$ref` that was inside a branch, and
+ * dereferencing can surface a nullable the definition holds. Sibling keys
+ * still merge over the definition (`derefSchema`'s semantics - unlike
+ * `resolveSchemaIndirection`, which replaces). Identity is the fixpoint test:
+ * both helpers return the schema unchanged when they have nothing to do.
+ */
+declare function resolveSchemaNode(schema: JsonSchema, defs: Record<string, JsonSchema>): JsonSchema;
+interface CollectDefsOptions {
+    /**
+     * Whether the walk descends into JSON arrays (`anyOf`/`allOf` branches,
+     * tuple `items`). The field mapper always has (so a def declared inside an
+     * `anyOf` branch resolves); the wire-format heal path historically has NOT -
+     * both behaviors are characterized, and each caller states its mode
+     * explicitly until M1 retires the difference.
+     */
+    traverseArrays: boolean;
+}
+/**
+ * Collect every nested `$defs` entry into one flat map so `#/$defs/...` refs
+ * resolve from anywhere. First definition of a name wins. The input schema is
+ * NOT modified (see `hoistDefsToRoot` for the stripping variant).
+ */
+declare function collectSchemaDefs(schema: JsonSchema, into: Record<string, JsonSchema>, options: CollectDefsOptions): Record<string, JsonSchema>;
+/**
+ * Hoist every nested `$defs` to the schema root, so a wrapper schema composed
+ * from several pydantic sub-schemas keeps its `#/$defs/...` refs resolvable.
+ * (Pydantic emits one `$defs` per model; composing models as properties of a
+ * wrapper object leaves those maps below the root the refs point to.)
+ */
+declare function hoistDefsToRoot(schema: JsonSchema): JsonSchema;
+
+export { type CollectDefsOptions, type JsonSchema, collapseNullable, collectSchemaDefs, derefSchema, flattenAnyOf, hoistDefsToRoot, resolveSchemaIndirection, resolveSchemaNode, schemaTypeOf };

package/dist/core/schema-utils.js

@@ -0,0 +1,3 @@
+export { collapseNullable, collectSchemaDefs, derefSchema, flattenAnyOf, hoistDefsToRoot, resolveSchemaIndirection, resolveSchemaNode, schemaTypeOf } from '../chunk-OD3VYXUY.js';
+//# sourceMappingURL=schema-utils.js.map
+//# sourceMappingURL=schema-utils.js.map

package/dist/core/schema-utils.js.map

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

package/dist/core/validation-message.d.ts

@@ -0,0 +1,39 @@
+import { RunInputError } from './gate-validator.js';
+
+/** The message keys this module renders, relative to the caller's namespace
+ *  (a host passes its own translator for that namespace). */
+type ValidationMessageKey = 'inputPanel.aDateField' | 'inputPanel.pickValidDate' | 'inputPanel.pickValidDateEmpty' | 'inputPanel.dateCarriesTime' | 'inputPanel.invalidValue' | 'inputPanel.invalidValueWithData';
+/**
+ * The translate function the caller injects. Typed on the EXACT keys this
+ * module uses - not a loose `(key: string) => string` - for two reasons: a
+ * typo'd key still fails the build here, and next-intl's translator (whose
+ * `key` parameter is the namespace's real key union, a SUPERSET of these)
+ * remains assignable by parameter contravariance. Kernel-owned: this module
+ * must not import next-intl's types.
+ */
+type Translate = (key: ValidationMessageKey, values?: Record<string, string>) => string;
+/**
+ * The value the validator actually rejected, read back out of the submitted data.
+ *
+ * RJSF builds `property` from ajv's `instancePath` by swapping `/` for `.`
+ * (`.quote_date.date`), so the segments index straight into the form data.
+ * Array indices arrive as digit strings and index arrays natively.
+ */
+declare function valueAtProperty(data: unknown, property: string | undefined): unknown;
+/**
+ * The rejected value rendered for a toast, or `null` when there is nothing
+ * worth showing (an absent or blank value - "you left it empty" is what the
+ * message says on its own, and `“”` adds noise).
+ */
+declare function displayValue(value: unknown): string | null;
+/**
+ * One validation error as a human line naming the offending value.
+ *
+ * The date branch is special-cased because ajv's own complaint (`'Date' must
+ * match format "date-time"`) is opaque, and because the carries-a-time case has
+ * a specific fix the user cannot guess: move the time into the sibling `time`
+ * field, which is exactly what the runtime's own error says.
+ */
+declare function describeValidationError(error: RunInputError, t: Translate, formData: unknown): string;
+
+export { type Translate, type ValidationMessageKey, describeValidationError, displayValue, valueAtProperty };

package/dist/core/validation-message.js

@@ -0,0 +1,4 @@
+export { describeValidationError, displayValue, valueAtProperty } from '../chunk-RPA7DNSK.js';
+import '../chunk-GKV77RAS.js';
+//# sourceMappingURL=validation-message.js.map
+//# sourceMappingURL=validation-message.js.map

package/dist/core/validation-message.js.map

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

package/dist/core/values.d.ts

@@ -0,0 +1,98 @@
+import { PipeInputContract, PipeIOContract, PipeInputFormDescriptor } from 'mthds/protocol';
+import { RunField } from './descriptor.js';
+import './contracts.js';
+
+/**
+ * Bridges the `MethodRunner`'s field values to the rest of the host.
+ *
+ * The method-store keeps inputs in the *simplified* format and runs send the
+ * *full* RJSF form shape - both already handled by `inflate/deflateAllInputs`.
+ * The only gap is that a few field controls use a friendlier value than RJSF: a
+ * scalar is the bare scalar where the full shape is the content model its
+ * concept declares (`{ text }`, `{ number }`, `{ yes_no }`), and a file is
+ * `{ url, filename }`. `fromRjsf`/`toRjsf` translate just those, so store
+ * reads/writes and run payloads stay byte-for-byte compatible with the proven
+ * playground path.
+ *
+ * Which property a scalar wraps into is NOT decided here - it arrives on the
+ * descriptor as `contentKey`, derived from the contract by `buildRunFields`.
+ *
+ * Pure module - no React, unit-tested.
+ */
+
+type Dict = Record<string, unknown>;
+type InputSchemas = Record<string, PipeInputContract>;
+/** Seed the runner's form values from the method-store's simplified inputData. */
+declare function runValuesFromStore(inputData: Dict | undefined, fields: RunField[], inputSchemas: InputSchemas): Dict;
+/**
+ * The runner's form values in **schema shape** - the same shape an RJSF panel
+ * holds, and therefore the shape `gate.ts` validates against the per-input
+ * JSON Schemas.
+ *
+ * Deliberately stops short of `deflateAllInputs`: deflation is the STORE's
+ * compact form, and ajv validates the full one.
+ */
+declare function rjsfDataFromRunValues(values: Dict, fields: RunField[]): Dict;
+/** Convert the runner's form values back to the store's simplified inputData. */
+declare function storeInputDataFromRunValues(values: Dict, fields: RunField[], inputSchemas: InputSchemas): Dict;
+/**
+ * Build the `{ concept, content }` map a run expects from the form values.
+ *
+ * The two ways a method says "this may be nothing" land differently on the wire,
+ * and both matter:
+ * - an **optional (`?`)** input left blank is OMITTED, so the runtime records a
+ *   real absence the method can branch on - sending `{ text: "" }` would look
+ *   like the caller supplied an empty string;
+ * - a **plural (`[]`)** input keeps its key, because a plural slot is never
+ *   absent - its empty form IS the empty list, and the runtime requires the key.
+ *   When that list is EMPTY it is sent BARE, without the envelope: the envelope
+ *   is the runtime's "explicit form", which bypasses the top-down shaper and
+ *   hands the value to the bottom-up factory, and that factory types a list from
+ *   its first item - so an empty list there raises "Cannot create Stuff from
+ *   empty list in content". The bare form keeps the shaper, which reads the
+ *   DECLARED concept and builds the empty list correctly. (pipelex/#1096 makes
+ *   the envelope agree; the bare form runs today and stays correct after.)
+ */
+declare function apiInputsFromRunValues(values: Dict, fields: RunField[], inputSchemas: InputSchemas): Record<string, unknown>;
+/** One named output pulled out of a run's working memory, ready to render. */
+interface OutputEntry {
+    /** The output variable key (mono). */
+    key: string;
+    conceptRef?: string;
+    value: unknown;
+}
+/**
+ * Split a run's pipe output into the main result and any intermediate outputs,
+ * excluding the inputs. The main output's identity comes from the working
+ * memory's `main_stuff` alias (the authoritative pointer to the output variable)
+ * - so its label is the REAL stuff name, not a positional guess. Falls back to
+ * the last produced stuff only when the alias is absent.
+ */
+declare function outputsFromPipeOutput(pipeOutput: unknown, inputKeys: string[]): {
+    main: OutputEntry;
+    intermediates: OutputEntry[];
+} | null;
+/**
+ * Recover the inputs a run was executed with from its working memory. The run's
+ * `working_memory.root` holds every named stuff - inputs AND outputs - keyed by
+ * variable name; we pull the entries whose keys are declared inputs and deflate
+ * their `content` (the full form shape) back into the store's simplified
+ * `inputData`. Lets the runner repopulate the form for a past/shared run - the
+ * inputs that produced the result. Returns `null` when no inputs are present.
+ */
+declare function inputDataFromWorkingMemory(workingMemory: unknown, inputSchemas: InputSchemas): Dict | null;
+/**
+ * Field descriptors for a method's main pipe - the wire descriptor mapped over
+ * the contract, or `[]` while either artifact has not arrived yet. The
+ * descriptor comes back from `validate` beside `pipe_io_contracts` when the
+ * request opts in with `views: ["input_form"]`; `getPipeInputForm` is the
+ * lookup that matches `getPipeIOContract`.
+ */
+declare function fieldsForContract(contract: PipeIOContract | undefined, descriptor: PipeInputFormDescriptor | undefined): RunField[];
+/**
+ * Immutably set a value at a dotted/indexed path (`a.0.b`). Used to write an
+ * uploaded file's URL back to a field anywhere in the (possibly nested) tree.
+ */
+declare function setValueAtPath(root: Dict, path: string[], value: unknown): Dict;
+
+export { type OutputEntry, apiInputsFromRunValues, fieldsForContract, inputDataFromWorkingMemory, outputsFromPipeOutput, rjsfDataFromRunValues, runValuesFromStore, setValueAtPath, storeInputDataFromRunValues };

package/dist/core/values.js

@@ -0,0 +1,10 @@
+export { apiInputsFromRunValues, fieldsForContract, inputDataFromWorkingMemory, outputsFromPipeOutput, rjsfDataFromRunValues, runValuesFromStore, setValueAtPath, storeInputDataFromRunValues } from '../chunk-5Q2W6HBA.js';
+import '../chunk-IIJRJGZQ.js';
+import '../chunk-GCXV76WU.js';
+import '../chunk-PM55AHRO.js';
+import '../chunk-GKV77RAS.js';
+import '../chunk-OD3VYXUY.js';
+import '../chunk-XYQ7NXQZ.js';
+import '../chunk-V3OV2XQT.js';
+//# sourceMappingURL=values.js.map
+//# sourceMappingURL=values.js.map

package/dist/core/values.js.map

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

package/dist/core/wire-format.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Converts between the simplified inputs.json format and the full RJSF form format.
+ *
+ * The inputs.json file uses a SIMPLIFIED format for users:
+ * - Text:       "my text"                     (instead of { text: "my text" })
+ * - Document:   "file.pdf" or { url: "..." }  (instead of { url: "...", ... })
+ * - Image:      same as Document
+ * - Text[]:     ["t1", "t2"]
+ * - Document[]: ["f1.pdf"] or [{ url: "..." }]
+ * - Custom:     { concept, content }           (no simplification)
+ *
+ * The RJSF form uses the FULL concept structure from the json_schema.
+ *
+ * Two directions:
+ * - deflate: form (full) → inputs.json (simplified) - for writing inputs.json / API calls
+ * - inflate: inputs.json (simplified) → form (full)  - for populating the form from inputs.json
+ */
+/**
+ * Convert a single form value to the simplified inputs.json format.
+ * Used when writing inputs.json and when calling the run API.
+ *
+ * Rules:
+ * - Text { text: "hello" } → "hello"
+ * - Document { url: "file.pdf", ... } → "file.pdf" (if only url) or { url, ... }
+ * - Image: same as Document
+ * - Page: same as Document
+ * - List types → array of deflated items
+ * - Custom → { concept, content }
+ */
+declare function deflateInput(value: unknown, conceptCode: string): unknown;
+/**
+ * Convert a simplified inputs.json value to the full form structure.
+ * Used when populating the RJSF form from inputs.json.
+ *
+ * Rules:
+ * - "hello" → { text: "hello" } (for Text concepts)
+ * - "file.pdf" → { url: "file.pdf" } (for Document/Image/Page concepts)
+ * - { url: "..." } → passthrough (already full)
+ * - ["t1", "t2"] → inflated array of items
+ * - { concept, content } → content (for custom concepts)
+ */
+declare function inflateInput(value: unknown, conceptCode: string): unknown;
+interface InputSchema {
+    concept_ref: string;
+    json_schema?: Record<string, unknown>;
+}
+/**
+ * The validation API returns concept_ref WITHOUT the [] suffix for list inputs.
+ * The array-ness is only encoded in json_schema.type === "array".
+ * This helper resolves the correct concept ref by checking the schema.
+ */
+declare function resolveConceptCode(schema: InputSchema): string;
+/**
+ * Deflate all inputs from form format to simplified inputs.json format.
+ * Used by InputConfigPanel when preparing data for the run API.
+ */
+declare function deflateAllInputs(formData: Record<string, unknown>, inputSchemas: Record<string, InputSchema>): Record<string, unknown>;
+/**
+ * Heal values against their json_schema: the run-form bridge used to
+ * double-wrap plain string properties as `{ text: "..." }` (fixed in
+ * run-values.ts, but the corrupted shape survives in persisted inputData -
+ * store and server copies). Wherever the schema expects a string but the
+ * value is a lone `{ text: string }` wrapper, unwrap it. Walks nested
+ * objects and arrays, resolving `#/$defs/...` refs against the root schema;
+ * anything already valid passes through untouched.
+ */
+declare function healStringWrappers(value: unknown, rawSchema: Record<string, unknown> | undefined, defs?: Record<string, Record<string, unknown>>): unknown;
+/**
+ * Drop optional properties the user never filled, so an untouched field cannot
+ * fail validation or reach the API as an empty string.
+ *
+ * RJSF fills EVERY unset string property with `""` on mount. That is harmless
+ * for a plain string, but `prepareSchemaForRjsf` collapses pydantic's
+ * `anyOf: [T, null]` by dropping the null branch, so an optional *constrained*
+ * field - `DateContent.time`, declared `datetime.time | None` and rendered
+ * `{ type: "string", format: "time" }` - is left demanding a well-formed time.
+ * `""` is not one, and the run was blocked on a field the user never opened.
+ *
+ * Pruning is the semantically correct repair, not a validation dodge: for
+ * pipelex an absent optional field IS `None`, and `""` would fail pydantic at
+ * the runner just as it fails ajv here. Only properties absent from their
+ * parent's `required` are dropped - an empty REQUIRED field must still fail, so
+ * the user is told about it.
+ *
+ * What counts as empty is `isEmptyAfterPruning`, and it includes an optional
+ * STRUCTURE the user never opened, on exactly the same grounds.
+ */
+declare function pruneEmptyOptionals(value: unknown, rawSchema: Record<string, unknown> | undefined, defs?: Record<string, Record<string, unknown>>): unknown;
+/**
+ * Inflate all inputs from simplified inputs.json format to form format.
+ * Used by onInputUpdate when receiving inputs.json changes from the sandbox.
+ */
+declare function inflateAllInputs(simplifiedData: Record<string, unknown>, inputSchemas: Record<string, InputSchema>): Record<string, unknown>;
+
+export { deflateAllInputs, deflateInput, healStringWrappers, inflateAllInputs, inflateInput, pruneEmptyOptionals, resolveConceptCode };

package/dist/core/wire-format.js

@@ -0,0 +1,6 @@
+export { deflateAllInputs, deflateInput, healStringWrappers, inflateAllInputs, inflateInput, pruneEmptyOptionals, resolveConceptCode } from '../chunk-GCXV76WU.js';
+import '../chunk-GKV77RAS.js';
+import '../chunk-OD3VYXUY.js';
+import '../chunk-V3OV2XQT.js';
+//# sourceMappingURL=wire-format.js.map
+//# sourceMappingURL=wire-format.js.map

package/dist/core/wire-format.js.map

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

package/dist/react/index.d.ts

@@ -1,6 +1,8 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { R as RunField, B as BooleanRunField, D as DateRunField, E as EnumRunField, F as FileRunField, L as ListRunField, N as NumberRunField, O as ObjectRunField, P as ProseRunField, T as TextRunField, U as UnknownRunField, C as ConceptCategory } from '../descriptor-DPrrfAjL.js';
+import { RunField, BooleanRunField, DateRunField, EnumRunField, FileRunField, ListRunField, NumberRunField, ObjectRunField, ProseRunField, TextRunField, UnknownRunField, ConceptCategory } from '../core/descriptor.js';
+import '../core/contracts.js';
+import 'mthds/protocol';
 
 /**
  * Ambient state that any field in the tree may need, threaded unchanged through
@@ -114,6 +116,25 @@ interface ListFieldProps {
  * own remove control; "Add" appends a fresh entry. The element renders through
  * the same `FieldRenderer`, so a list of documents gets dropzones and a list of
  * structured concepts gets nested cards - no special-casing per element type.
+ *
+ * **A row is a thing, not a slot.** Its React key is generated when the row
+ * appears and travels with it, so removing an earlier row moves the later ones
+ * instead of renumbering them into each other - which is what used to drop a
+ * half-typed value or a pending preview onto the neighbouring row. The row's
+ * field ID stays POSITIONAL (`cvs.1`), because that ID is a PATH: a host writes
+ * an upload back with `setValueAtPath(values, id.split('.'), value)`, and
+ * `setValueAtPath` is a pure function of the value tree. Handing out an opaque
+ * token instead would mean the kernel keeping a live token-to-index registry for
+ * that function to consult, which is exactly the kind of hidden state the
+ * headless core does not have.
+ *
+ * The positional ID is why removal is BLOCKED while a file is arriving anywhere
+ * in this list - see `listIsBusy`. Together those two are the whole fix: a
+ * generated key cannot rescue a write-back either, because the keys live in this
+ * control's state and not in the value, so a host that replaces `values`
+ * wholesale reconciles by length just as positions do. What a stable identity
+ * buys over a position is exactly the reorderings the KERNEL performs, and it
+ * performs one.
  */
 declare function ListField({ field, value, onChange, id, error, env }: ListFieldProps): react.JSX.Element;
 
@@ -249,6 +270,8 @@ interface FieldStrings {
     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;
     uploading: string;
     dropToUpload: string;
     dropOrBrowse: string;
@@ -273,6 +296,24 @@ declare function FieldStringsProvider({ strings, children, }: {
 /** The strings the nearest provider supplies (English defaults when none does). */
 declare function useFieldStrings(): FieldStrings;
 
+declare function FieldDomIdProvider({ prefix, children, }: {
+    /**
+     * Omit to mint one from `useId`; `''` writes the path unprefixed. An explicit
+     * prefix must be unique in the document - one provider, one form.
+     */
+    prefix?: string;
+    children: ReactNode;
+}): react.JSX.Element;
+/**
+ * The DOM id for a field path - the ONE place a path becomes an attribute.
+ *
+ * Called once per control so the `<label for>` and the control's `id` are the
+ * same string by construction: the pairing cannot drift, because there is only
+ * one call. `useId` runs unconditionally (hooks must) and is simply unused when
+ * a provider supplies the prefix.
+ */
+declare function useFieldDomId(path: string): string;
+
 /**
  * How a field's LABEL chrome should read. The control itself never changes.
  *
@@ -303,4 +344,4 @@ declare function useFieldPresentation(): FieldPresentation;
  */
 declare function humanizeFieldName(name: string): string;
 
-export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, DocumentField, EnumField, type FieldEnv, type FieldPresentation, FieldPresentationProvider, FieldRenderer, type FieldRendererProps, FieldShell, type FieldStrings, FieldStringsProvider, type FileValue, ImageField, ListField, NumberField, ObjectField, OptionalToggle, ProseField, TextField, UnknownField, fieldControlClass, humanizeFieldName, useFieldPresentation, useFieldStrings };
+export { BooleanField, ConceptPill, DEFAULT_FIELD_STRINGS, DateField, DocumentField, EnumField, FieldDomIdProvider, type FieldEnv, type FieldPresentation, FieldPresentationProvider, FieldRenderer, type FieldRendererProps, FieldShell, type FieldStrings, FieldStringsProvider, type FileValue, ImageField, ListField, NumberField, ObjectField, OptionalToggle, ProseField, TextField, UnknownField, fieldControlClass, humanizeFieldName, useFieldDomId, useFieldPresentation, useFieldStrings };