@hotmeshio/long-tail 0.10.2 → 0.10.4

package/build/shared/form-validation/field-validator.d.ts

@@ -0,0 +1,45 @@
+export interface FieldError {
+    field: string;
+    message: string;
+}
+interface ChecklistItem {
+    id: string;
+    label: string;
+    required?: boolean;
+}
+/**
+ * Resolve a checklist widget's item definitions from its `x-lt-source`
+ * "domain.path" against the escalation context. Missing domain/path or a
+ * non-array value yields an empty list.
+ */
+export declare function resolveChecklistItems(sourcePath: unknown, ctx: Record<string, unknown> | undefined): ChecklistItem[];
+/**
+ * The checklist completion guard (`x-lt-require-all`): every rendered item must
+ * be checked, except items whose definition carries `required: false` (the
+ * explicit opt-out). Vacuous when the source resolves to no items — never
+ * blocks on zero. Returns the panel message, or undefined when satisfied.
+ * Stricter than (and composes with) the field-level required-array entry,
+ * which remains the at-least-one check.
+ */
+export declare function validateRequireAll(value: unknown, fieldSchema: Record<string, unknown> | undefined, ctx?: Record<string, unknown>): string | undefined;
+/**
+ * Runtime type check against the field's declared JSON Schema `type`. Guards
+ * the payload contract for API-first callers (a form widget already produces
+ * the right primitive; a script or agent submitting `"1"` for a number field
+ * does not). Absent/empty values pass — presence is the required check's job.
+ */
+export declare function validateFieldType(value: unknown, fieldSchema: Record<string, unknown> | undefined): string | undefined;
+/**
+ * Per-field JSON Schema validation — subset used by the resolver form.
+ *
+ * Returns a human-readable error string when the value fails a constraint,
+ * or undefined when the value is valid. Callers are responsible for the
+ * required check (empty-when-required) before calling this for constraint checks.
+ *
+ * `ctx` is optional context (ShowIfContext-shaped) used to resolve dynamic
+ * constraint paths like `x-lt-minimum: "envelope.min_score"`.
+ */
+export declare function validateFieldConstraints(value: unknown, fieldSchema: Record<string, unknown> | undefined, ctx?: Record<string, unknown>): string | undefined;
+/** Full field error including required check then constraints. */
+export declare function validateField(value: unknown, fieldSchema: Record<string, unknown> | undefined, isRequired: boolean, isTouched: boolean, ctx?: Record<string, unknown>): string | undefined;
+export {};

package/build/shared/form-validation/field-validator.js

@@ -0,0 +1,214 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveChecklistItems = resolveChecklistItems;
+exports.validateRequireAll = validateRequireAll;
+exports.validateFieldType = validateFieldType;
+exports.validateFieldConstraints = validateFieldConstraints;
+exports.validateField = validateField;
+/**
+ * Resolve a checklist widget's item definitions from its `x-lt-source`
+ * "domain.path" against the escalation context. Missing domain/path or a
+ * non-array value yields an empty list.
+ */
+function resolveChecklistItems(sourcePath, ctx) {
+    if (typeof sourcePath !== 'string' || !ctx)
+        return [];
+    const dot = sourcePath.indexOf('.');
+    if (dot === -1)
+        return [];
+    const domainObj = ctx[sourcePath.slice(0, dot)];
+    if (!domainObj || typeof domainObj !== 'object')
+        return [];
+    let cur = domainObj;
+    for (const p of sourcePath.slice(dot + 1).split('.')) {
+        cur = cur[p];
+        if (cur === undefined)
+            return [];
+    }
+    return Array.isArray(cur) ? cur : [];
+}
+/**
+ * The checklist completion guard (`x-lt-require-all`): every rendered item must
+ * be checked, except items whose definition carries `required: false` (the
+ * explicit opt-out). Vacuous when the source resolves to no items — never
+ * blocks on zero. Returns the panel message, or undefined when satisfied.
+ * Stricter than (and composes with) the field-level required-array entry,
+ * which remains the at-least-one check.
+ */
+function validateRequireAll(value, fieldSchema, ctx) {
+    if (fieldSchema?.['x-lt-widget'] !== 'checklist')
+        return undefined;
+    if (fieldSchema['x-lt-require-all'] !== true)
+        return undefined;
+    const items = resolveChecklistItems(fieldSchema['x-lt-source'], ctx);
+    const mandatory = items.filter((i) => i.required !== false);
+    if (mandatory.length === 0)
+        return undefined;
+    const state = (typeof value === 'object' && value !== null && !Array.isArray(value))
+        ? value
+        : {};
+    const incomplete = mandatory.filter((i) => !state[i.id]).length;
+    if (incomplete === 0)
+        return undefined;
+    return `${incomplete} of ${mandatory.length} checks incomplete`;
+}
+/**
+ * Runtime type check against the field's declared JSON Schema `type`. Guards
+ * the payload contract for API-first callers (a form widget already produces
+ * the right primitive; a script or agent submitting `"1"` for a number field
+ * does not). Absent/empty values pass — presence is the required check's job.
+ */
+function validateFieldType(value, fieldSchema) {
+    const declared = fieldSchema?.type;
+    if (typeof declared !== 'string')
+        return undefined;
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    switch (declared) {
+        case 'string':
+            return typeof value === 'string' ? undefined : 'Expected text';
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value) ? undefined : 'Expected a number';
+        case 'integer':
+            return typeof value === 'number' && Number.isInteger(value) ? undefined : 'Expected a whole number';
+        case 'boolean':
+            return typeof value === 'boolean' ? undefined : 'Expected true or false';
+        case 'array':
+            return Array.isArray(value) ? undefined : 'Expected a list';
+        case 'object':
+            return typeof value === 'object' && !Array.isArray(value) ? undefined : 'Expected an object';
+        default:
+            return undefined;
+    }
+}
+/**
+ * Per-field JSON Schema validation — subset used by the resolver form.
+ *
+ * Returns a human-readable error string when the value fails a constraint,
+ * or undefined when the value is valid. Callers are responsible for the
+ * required check (empty-when-required) before calling this for constraint checks.
+ *
+ * `ctx` is optional context (ShowIfContext-shaped) used to resolve dynamic
+ * constraint paths like `x-lt-minimum: "envelope.min_score"`.
+ */
+function validateFieldConstraints(value, fieldSchema, ctx) {
+    if (!fieldSchema)
+        return undefined;
+    // Enum membership — the form's select widget constrains choices; API-first
+    // callers are unconstrained, so the schema's enum is the contract.
+    const allowed = fieldSchema.enum;
+    if (Array.isArray(allowed) && allowed.length > 0
+        && value !== undefined && value !== null && value !== ''
+        && !allowed.includes(value)) {
+        return `Must be one of: ${allowed.map((v) => String(v)).join(', ')}`;
+    }
+    if (typeof value === 'string') {
+        const s = value.trim();
+        if (s === '')
+            return undefined; // empty string: required check is the caller's job
+        const minLength = resolveNumericConstraint(fieldSchema.minLength, fieldSchema['x-lt-min-length'], ctx);
+        if (minLength !== undefined && s.length < minLength) {
+            return `Minimum ${minLength} character${minLength === 1 ? '' : 's'}`;
+        }
+        const maxLength = resolveNumericConstraint(fieldSchema.maxLength, fieldSchema['x-lt-max-length'], ctx);
+        if (maxLength !== undefined && s.length > maxLength) {
+            return `Maximum ${maxLength} characters (${s.length} entered)`;
+        }
+        const pattern = fieldSchema.pattern;
+        if (pattern) {
+            try {
+                if (!new RegExp(pattern).test(s)) {
+                    const patternError = fieldSchema['x-lt-pattern-error'];
+                    return patternError ?? 'Invalid format';
+                }
+            }
+            catch {
+                // Malformed pattern in schema — silently skip
+            }
+        }
+        const fmt = fieldSchema.format;
+        if (fmt === 'email' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s)) {
+            return 'Enter a valid email address';
+        }
+        if (fmt === 'uri' && !/^https?:\/\/.+/.test(s)) {
+            return 'Enter a valid URL';
+        }
+    }
+    if (typeof value === 'number') {
+        const minimum = resolveNumericConstraint(fieldSchema.minimum, fieldSchema['x-lt-minimum'], ctx);
+        const exclusiveMinimum = resolveNumericConstraint(fieldSchema.exclusiveMinimum, undefined, ctx);
+        const maximum = resolveNumericConstraint(fieldSchema.maximum, fieldSchema['x-lt-maximum'], ctx);
+        const exclusiveMaximum = resolveNumericConstraint(fieldSchema.exclusiveMaximum, undefined, ctx);
+        if (minimum !== undefined && value < minimum) {
+            return `Minimum value is ${minimum}`;
+        }
+        if (exclusiveMinimum !== undefined && value <= exclusiveMinimum) {
+            return `Must be greater than ${exclusiveMinimum}`;
+        }
+        if (maximum !== undefined && value > maximum) {
+            return `Maximum value is ${maximum}`;
+        }
+        if (exclusiveMaximum !== undefined && value >= exclusiveMaximum) {
+            return `Must be less than ${exclusiveMaximum}`;
+        }
+    }
+    return undefined;
+}
+function resolveNumericConstraint(staticVal, dynamicPath, ctx) {
+    if (typeof staticVal === 'number')
+        return staticVal;
+    if (typeof dynamicPath === 'string' && ctx) {
+        const dot = dynamicPath.indexOf('.');
+        if (dot !== -1) {
+            const domain = dynamicPath.slice(0, dot);
+            const path = dynamicPath.slice(dot + 1);
+            const domainObj = ctx[domain];
+            if (domainObj && typeof domainObj === 'object') {
+                const parts = path.split('.');
+                let cur = domainObj;
+                for (const p of parts) {
+                    cur = cur[p];
+                    if (cur === undefined)
+                        break;
+                }
+                if (typeof cur === 'number')
+                    return cur;
+                if (typeof cur === 'string') {
+                    const n = Number(cur);
+                    if (!Number.isNaN(n))
+                        return n;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/** Full field error including required check then constraints. */
+function validateField(value, fieldSchema, isRequired, isTouched, ctx) {
+    if (!isTouched)
+        return undefined;
+    if (isRequired) {
+        if (value === undefined || value === null)
+            return 'Required';
+        if (typeof value === 'boolean' && !value)
+            return 'Required';
+        if (typeof value === 'string' && value.trim() === '')
+            return 'Required';
+        if (typeof value === 'object' && !Array.isArray(value) && value !== null) {
+            const vals = Object.values(value);
+            if (vals.length === 0 || vals.every((v) => !v))
+                return 'Required';
+        }
+    }
+    // Declared-type check runs before constraints: a mis-typed value would make
+    // the numeric/string constraint branches silently inapplicable.
+    const typeError = validateFieldType(value, fieldSchema);
+    if (typeError)
+        return typeError;
+    // Checklist completion — the stricter guard runs regardless of the
+    // required-array entry (which stays at-least-one when present).
+    const requireAll = validateRequireAll(value, fieldSchema, ctx);
+    if (requireAll)
+        return requireAll;
+    return validateFieldConstraints(value, fieldSchema, ctx);
+}

package/build/shared/form-validation/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Isomorphic form-validation library for the x-lt-* enriched form_schema
+ * vocabulary. The dashboard renders and pre-validates resolver forms with it;
+ * the API layer enforces the same contract on every resolve surface. Pure
+ * functions only — no React, no DOM, no database.
+ */
+export * from './derive-field-label';
+export * from './x-lt-bind';
+export * from './x-lt-help';
+export * from './x-lt-show-if';
+export * from './field-validator';
+export * from './validate-resolver-payload';

package/build/shared/form-validation/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Isomorphic form-validation library for the x-lt-* enriched form_schema
+ * vocabulary. The dashboard renders and pre-validates resolver forms with it;
+ * the API layer enforces the same contract on every resolve surface. Pure
+ * functions only — no React, no DOM, no database.
+ */
+__exportStar(require("./derive-field-label"), exports);
+__exportStar(require("./x-lt-bind"), exports);
+__exportStar(require("./x-lt-help"), exports);
+__exportStar(require("./x-lt-show-if"), exports);
+__exportStar(require("./field-validator"), exports);
+__exportStar(require("./validate-resolver-payload"), exports);

package/build/shared/form-validation/validate-resolver-payload.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The full pre-submission validation pass over a resolver form schema — the
+ * same pass on both sides of the wire. The dashboard runs it on the flat form
+ * values before submitting; the API layer runs it on the submitted (bound,
+ * nested) payload by inverting x-lt-bind first. Because both entry points
+ * funnel into one loop, a payload that passes the client panel passes the
+ * server gate, and a 422's violation list is exactly what the panel shows.
+ *
+ * Semantics per field:
+ *   - x-lt-showIf-hidden fields are skipped entirely (a field the submitter
+ *     cannot see never blocks submission)
+ *   - required (schema.required membership), with checklist/empty-object rules
+ *   - declared-type check (string/number/integer/boolean/array/object)
+ *   - enum membership
+ *   - x-lt-require-all against the checklist items resolved from context
+ *   - static + dynamic bounds (minimum/x-lt-minimum, lengths, patterns)
+ *
+ * The showIf/`resolver.*` domain is always the FLAT form representation, so a
+ * condition like `resolver.approved` reads the same on both sides.
+ */
+import { type FieldError } from './field-validator';
+import { type ShowIfContext } from './x-lt-show-if';
+export type { FieldError } from './field-validator';
+/**
+ * The escalation-surface context the pass evaluates showIf conditions and
+ * dynamic constraints against. `resolver` is supplied by the pass itself
+ * (the flat form values under validation) — callers provide the rest.
+ */
+export type ResolverValidationContext = Omit<ShowIfContext, 'resolver'>;
+/**
+ * Validate FLAT form values against the form schema. This is the dashboard's
+ * entry point (the values the user edits, keyed by field name).
+ */
+export declare function validateResolverForm(schema: Record<string, unknown> | null | undefined, formValues: Record<string, unknown>, ctx?: ResolverValidationContext | null): FieldError[];
+/**
+ * Validate a SUBMITTED resolver payload (the bound, nested shape the workflow
+ * consumes) against the form schema. This is the API layer's entry point: the
+ * payload is inverted through each field's x-lt-bind path back to the flat
+ * form representation, then run through the same pass the client uses.
+ */
+export declare function validateResolverPayload(schema: Record<string, unknown> | null | undefined, payload: Record<string, unknown>, ctx?: ResolverValidationContext | null): FieldError[];

package/build/shared/form-validation/validate-resolver-payload.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateResolverForm = validateResolverForm;
+exports.validateResolverPayload = validateResolverPayload;
+/**
+ * The full pre-submission validation pass over a resolver form schema — the
+ * same pass on both sides of the wire. The dashboard runs it on the flat form
+ * values before submitting; the API layer runs it on the submitted (bound,
+ * nested) payload by inverting x-lt-bind first. Because both entry points
+ * funnel into one loop, a payload that passes the client panel passes the
+ * server gate, and a 422's violation list is exactly what the panel shows.
+ *
+ * Semantics per field:
+ *   - x-lt-showIf-hidden fields are skipped entirely (a field the submitter
+ *     cannot see never blocks submission)
+ *   - required (schema.required membership), with checklist/empty-object rules
+ *   - declared-type check (string/number/integer/boolean/array/object)
+ *   - enum membership
+ *   - x-lt-require-all against the checklist items resolved from context
+ *   - static + dynamic bounds (minimum/x-lt-minimum, lengths, patterns)
+ *
+ * The showIf/`resolver.*` domain is always the FLAT form representation, so a
+ * condition like `resolver.approved` reads the same on both sides.
+ */
+const field_validator_1 = require("./field-validator");
+const x_lt_show_if_1 = require("./x-lt-show-if");
+const x_lt_bind_1 = require("./x-lt-bind");
+/**
+ * Validate FLAT form values against the form schema. This is the dashboard's
+ * entry point (the values the user edits, keyed by field name).
+ */
+function validateResolverForm(schema, formValues, ctx) {
+    if (!schema)
+        return [];
+    const properties = (schema.properties ?? {});
+    const required = new Set(schema.required ?? []);
+    const liveCtx = {
+        ...(ctx ?? {}),
+        resolver: formValues,
+    };
+    const errors = [];
+    for (const [field, fieldSchema] of Object.entries(properties)) {
+        if (!(0, x_lt_show_if_1.evaluateShowIf)(fieldSchema['x-lt-showIf'], liveCtx))
+            continue;
+        const err = (0, field_validator_1.validateField)(formValues[field], fieldSchema, required.has(field), true, liveCtx);
+        if (err)
+            errors.push({ field, message: err });
+    }
+    return errors;
+}
+/**
+ * Validate a SUBMITTED resolver payload (the bound, nested shape the workflow
+ * consumes) against the form schema. This is the API layer's entry point: the
+ * payload is inverted through each field's x-lt-bind path back to the flat
+ * form representation, then run through the same pass the client uses.
+ */
+function validateResolverPayload(schema, payload, ctx) {
+    if (!schema)
+        return [];
+    const formValues = (0, x_lt_bind_1.mapPayloadToForm)(payload, schema);
+    return validateResolverForm(schema, formValues, ctx);
+}

package/build/shared/form-validation/x-lt-bind.d.ts

@@ -0,0 +1,41 @@
+/**
+ * x-lt-bind — maps the escalation FORM (flat field values the user edits) to and
+ * from the PAYLOAD (the nested JSON the workflow consumes). A form_schema property
+ * may declare `x-lt-bind: "a.b[0].c"`, the path its value occupies in the payload;
+ * a property with no bind sits at its own name at the root (1:1). This module is
+ * isomorphic — the dashboard renders forms with it, and the API layer inverts a
+ * submitted payload through it to validate against the form contract. One
+ * implementation, both sides.
+ *
+ *   mapPayloadToForm  — payload → flat form values, to PREFILL/display the form
+ *                       (server-side: to validate a submitted payload)
+ *   mapFormToPayload  — flat form values → payload, the shape submitted/stored
+ */
+type PathSeg = {
+    key: string;
+} | {
+    index: number;
+};
+/** Parse a bind path — dot keys with optional `[n]` indices. Rejects pollution keys. */
+export declare function parsePath(path: string): PathSeg[];
+/** Set `value` at `path` inside `root`, creating intermediate objects/arrays. */
+export declare function setDeep(root: Record<string, any>, path: string, value: unknown): void;
+/** Read the value at `path` inside `root` (undefined if any segment is missing). */
+export declare function getDeep(root: unknown, path: string): unknown;
+/** The bind path for a form property (its `x-lt-bind`, or the property name). */
+export declare function bindPathFor(propName: string, propDef: Record<string, any> | undefined): string;
+/**
+ * Assemble the payload from the form's flat values. A field absent from
+ * `formValues` is omitted (so clearing/deleting a field drops it from the
+ * payload). Unknown keys not declared in the schema are dropped. With no schema
+ * properties, values pass through unchanged.
+ */
+export declare function mapFormToPayload(formValues: Record<string, any>, formSchema: Record<string, any> | null | undefined): Record<string, any>;
+/**
+ * Reverse of {@link mapFormToPayload}: pull each form field's value out of the
+ * payload via its bind path, to prefill/display the form. A field whose bound
+ * path is missing from the payload is omitted (the caller falls back to the
+ * schema default).
+ */
+export declare function mapPayloadToForm(payload: Record<string, any> | null | undefined, formSchema: Record<string, any> | null | undefined): Record<string, any>;
+export {};

package/build/shared/form-validation/x-lt-bind.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * x-lt-bind — maps the escalation FORM (flat field values the user edits) to and
+ * from the PAYLOAD (the nested JSON the workflow consumes). A form_schema property
+ * may declare `x-lt-bind: "a.b[0].c"`, the path its value occupies in the payload;
+ * a property with no bind sits at its own name at the root (1:1). This module is
+ * isomorphic — the dashboard renders forms with it, and the API layer inverts a
+ * submitted payload through it to validate against the form contract. One
+ * implementation, both sides.
+ *
+ *   mapPayloadToForm  — payload → flat form values, to PREFILL/display the form
+ *                       (server-side: to validate a submitted payload)
+ *   mapFormToPayload  — flat form values → payload, the shape submitted/stored
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePath = parsePath;
+exports.setDeep = setDeep;
+exports.getDeep = getDeep;
+exports.bindPathFor = bindPathFor;
+exports.mapFormToPayload = mapFormToPayload;
+exports.mapPayloadToForm = mapPayloadToForm;
+const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/** Parse a bind path — dot keys with optional `[n]` indices. Rejects pollution keys. */
+function parsePath(path) {
+    const segs = [];
+    for (const raw of path.split('.')) {
+        const m = raw.match(/^([^[\]]*)((?:\[\d+\])*)$/);
+        if (!m)
+            throw new Error(`invalid x-lt-bind path segment: "${raw}"`);
+        const [, name, brackets] = m;
+        if (name) {
+            if (BLOCKED_KEYS.has(name))
+                throw new Error(`x-lt-bind path may not target "${name}"`);
+            segs.push({ key: name });
+        }
+        for (const b of brackets.match(/\d+/g) ?? [])
+            segs.push({ index: Number(b) });
+    }
+    if (segs.length === 0)
+        throw new Error(`empty x-lt-bind path: "${path}"`);
+    return segs;
+}
+/** Set `value` at `path` inside `root`, creating intermediate objects/arrays. */
+function setDeep(root, path, value) {
+    const segs = parsePath(path);
+    let node = root;
+    for (let i = 0; i < segs.length - 1; i++) {
+        const seg = segs[i];
+        const next = segs[i + 1];
+        const childKey = 'key' in seg ? seg.key : seg.index;
+        const wantArray = 'index' in next;
+        if (node[childKey] == null || typeof node[childKey] !== 'object') {
+            node[childKey] = wantArray ? [] : {};
+        }
+        node = node[childKey];
+    }
+    const last = segs[segs.length - 1];
+    node['key' in last ? last.key : last.index] = value;
+}
+/** Read the value at `path` inside `root` (undefined if any segment is missing). */
+function getDeep(root, path) {
+    let node = root;
+    for (const seg of parsePath(path)) {
+        if (node == null || typeof node !== 'object')
+            return undefined;
+        node = node['key' in seg ? seg.key : seg.index];
+    }
+    return node;
+}
+/** The bind path for a form property (its `x-lt-bind`, or the property name). */
+function bindPathFor(propName, propDef) {
+    const bind = propDef?.['x-lt-bind'];
+    return typeof bind === 'string' && bind.length > 0 ? bind : propName;
+}
+/**
+ * Assemble the payload from the form's flat values. A field absent from
+ * `formValues` is omitted (so clearing/deleting a field drops it from the
+ * payload). Unknown keys not declared in the schema are dropped. With no schema
+ * properties, values pass through unchanged.
+ */
+function mapFormToPayload(formValues, formSchema) {
+    const props = formSchema?.properties;
+    if (!props)
+        return { ...formValues };
+    const payload = {};
+    for (const [name, def] of Object.entries(props)) {
+        if (!(name in formValues))
+            continue;
+        setDeep(payload, bindPathFor(name, def), formValues[name]);
+    }
+    return payload;
+}
+/**
+ * Reverse of {@link mapFormToPayload}: pull each form field's value out of the
+ * payload via its bind path, to prefill/display the form. A field whose bound
+ * path is missing from the payload is omitted (the caller falls back to the
+ * schema default).
+ */
+function mapPayloadToForm(payload, formSchema) {
+    const props = formSchema?.properties;
+    if (!props)
+        return payload ? { ...payload } : {};
+    const form = {};
+    for (const [name, def] of Object.entries(props)) {
+        const v = getDeep(payload, bindPathFor(name, def));
+        if (v !== undefined)
+            form[name] = v;
+    }
+    return form;
+}

package/build/shared/form-validation/x-lt-help.d.ts

@@ -0,0 +1,21 @@
+/** The token domains a help template may reference. */
+export declare const HELP_DOMAINS: readonly ["escalation", "metadata", "envelope", "payload", "resolver"];
+export type HelpDomain = (typeof HELP_DOMAINS)[number];
+export type HelpTokenContext = Partial<Record<HelpDomain, Record<string, unknown> | null>>;
+/** Replace every `{{domain.path}}` token with its value from the context. */
+export declare function interpolateHelp(template: string, ctx: HelpTokenContext): string;
+/** The schema's help source: `x-lt-help` first, `x-lt-context` as fallback. */
+export declare function resolveHelpSource(schema: Record<string, unknown> | null | undefined): string | null;
+/** The schema's help content, interpolated. Null when the schema declares none. */
+export declare function buildHelpMarkdown(schema: Record<string, unknown> | null | undefined, ctx: HelpTokenContext): string | null;
+export interface HelpStateHint {
+    isTerminal: boolean;
+    status?: string;
+    claimed: boolean;
+    claimedByMe: boolean;
+}
+/**
+ * State-aware guidance shown when the schema carries no help content — the
+ * panel always tells the user what this page expects of them right now.
+ */
+export declare function defaultHelpMarkdown({ isTerminal, status, claimed, claimedByMe }: HelpStateHint): string;