@object-ui/sdui-parser 17.5.0 → 17.7.0

package/dist/provenance.d.ts

@@ -0,0 +1,68 @@
+/**
+ * ObjectUI — html-tier provenance (ADR-0080, objectui#4000)
+ *
+ * Records the one fact a renderer cannot otherwise recover: whether the node it
+ * is about to render was EMITTED BY THIS PARSER (an author's `kind:'html'`
+ * source, compiled tag-name-straight-through) or AUTHORED AS JSON metadata.
+ *
+ * Why a renderer needs it: the two surfaces have different vocabularies. A type
+ * the JSON surface is steering authors away from can still be a supported tag
+ * in the html tier — the plain inline element (`span`) is exactly that. (The
+ * plain box element was too, until objectui#10757 deprecated `div` on the html
+ * surface as well; the console's html compile now refuses it outright, so no
+ * notice is involved there.) Advice aimed at the JSON surface, delivered to an
+ * html-tier author, is advice they cannot act on: in that tier there is no
+ * other spelling. The
+ * deprecation notice fired at them anyway (objectui#4000), which is also why the
+ * type could never be retired — the engine's own compiler keeps emitting it.
+ *
+ * The judgement therefore has to be PROVENANCE, established by the producer,
+ * not a guess made at the consumer from the node's shape.
+ *
+ * ## Why a symbol, and why `Symbol.for`
+ *
+ * The marker is deliberately NOT a JSON-visible key:
+ *
+ *  - `JSON.stringify` skips symbol keys, so provenance never lands in a
+ *    persisted tree. That is the point, not a limitation: "our parser produced
+ *    this node in this process" is not a fact about the saved document, and a
+ *    saved document must not be able to REPLAY it. A string key like
+ *    `_provenance: 'html'` would be copyable — an authored (or AI-generated)
+ *    JSON page could paste it in and buy itself silence from a notice that is
+ *    meant for it. Provenance that authored metadata can forge is not
+ *    provenance.
+ *  - `Object.keys` / `for...in` skip symbol keys, so the marker cannot leak out
+ *    of a renderer onto a host element as a stray DOM attribute.
+ *
+ * It IS enumerable, which matters more than it looks: `SchemaRenderer` hands
+ * renderers a shallow copy of the node (`{ ...schema }`), and object spread
+ * copies own ENUMERABLE symbol keys while dropping non-enumerable ones. A
+ * non-enumerable marker would be lost in that copy and the misfire would come
+ * back — silently, and only in the render path. `render.test.tsx` and the
+ * components-side pin both go through the real `SchemaRenderer` for this reason.
+ *
+ * `Symbol.for` (the cross-realm registry) rather than a module-local `Symbol()`:
+ * this package ships as both ESM and CJS and is consumed from several packages,
+ * so two module instances are possible. Two local symbols would not compare
+ * equal, and the failure mode of that mismatch is the ORIGINAL BUG returning
+ * with no error anywhere. A registry key cannot drift.
+ */
+/**
+ * The provenance marker itself. Exported for tests and for any consumer that
+ * needs to reason about the key; prefer {@link isHtmlTierNode} for reading.
+ */
+export declare const HTML_TIER_NODE: symbol;
+/**
+ * Stamp a node as html-tier output. Called by the parser as it builds each
+ * element — the producer is the only place that knows this for certain.
+ */
+export declare function markHtmlTierNode<T extends object>(node: T): T;
+/**
+ * True when this node came out of the html tier's parser.
+ *
+ * Deliberately a plain boolean read of the marker — no fallback to a
+ * string-keyed spelling, no shape heuristic ("looks like a raw tag"). Either
+ * the producer marked it or it did not; a consumer-side guess is precisely what
+ * this replaces.
+ */
+export declare function isHtmlTierNode(node: unknown): boolean;

package/dist/provenance.js

@@ -0,0 +1,77 @@
+/**
+ * ObjectUI — html-tier provenance (ADR-0080, objectui#4000)
+ *
+ * Records the one fact a renderer cannot otherwise recover: whether the node it
+ * is about to render was EMITTED BY THIS PARSER (an author's `kind:'html'`
+ * source, compiled tag-name-straight-through) or AUTHORED AS JSON metadata.
+ *
+ * Why a renderer needs it: the two surfaces have different vocabularies. A type
+ * the JSON surface is steering authors away from can still be a supported tag
+ * in the html tier — the plain inline element (`span`) is exactly that. (The
+ * plain box element was too, until objectui#10757 deprecated `div` on the html
+ * surface as well; the console's html compile now refuses it outright, so no
+ * notice is involved there.) Advice aimed at the JSON surface, delivered to an
+ * html-tier author, is advice they cannot act on: in that tier there is no
+ * other spelling. The
+ * deprecation notice fired at them anyway (objectui#4000), which is also why the
+ * type could never be retired — the engine's own compiler keeps emitting it.
+ *
+ * The judgement therefore has to be PROVENANCE, established by the producer,
+ * not a guess made at the consumer from the node's shape.
+ *
+ * ## Why a symbol, and why `Symbol.for`
+ *
+ * The marker is deliberately NOT a JSON-visible key:
+ *
+ *  - `JSON.stringify` skips symbol keys, so provenance never lands in a
+ *    persisted tree. That is the point, not a limitation: "our parser produced
+ *    this node in this process" is not a fact about the saved document, and a
+ *    saved document must not be able to REPLAY it. A string key like
+ *    `_provenance: 'html'` would be copyable — an authored (or AI-generated)
+ *    JSON page could paste it in and buy itself silence from a notice that is
+ *    meant for it. Provenance that authored metadata can forge is not
+ *    provenance.
+ *  - `Object.keys` / `for...in` skip symbol keys, so the marker cannot leak out
+ *    of a renderer onto a host element as a stray DOM attribute.
+ *
+ * It IS enumerable, which matters more than it looks: `SchemaRenderer` hands
+ * renderers a shallow copy of the node (`{ ...schema }`), and object spread
+ * copies own ENUMERABLE symbol keys while dropping non-enumerable ones. A
+ * non-enumerable marker would be lost in that copy and the misfire would come
+ * back — silently, and only in the render path. `render.test.tsx` and the
+ * components-side pin both go through the real `SchemaRenderer` for this reason.
+ *
+ * `Symbol.for` (the cross-realm registry) rather than a module-local `Symbol()`:
+ * this package ships as both ESM and CJS and is consumed from several packages,
+ * so two module instances are possible. Two local symbols would not compare
+ * equal, and the failure mode of that mismatch is the ORIGINAL BUG returning
+ * with no error anywhere. A registry key cannot drift.
+ */
+/** Registry key for the marker. Stable — it is a cross-instance contract. */
+const HTML_TIER_NODE_KEY = '@object-ui/sdui-parser.html-tier-node';
+/**
+ * The provenance marker itself. Exported for tests and for any consumer that
+ * needs to reason about the key; prefer {@link isHtmlTierNode} for reading.
+ */
+export const HTML_TIER_NODE = Symbol.for(HTML_TIER_NODE_KEY);
+/**
+ * Stamp a node as html-tier output. Called by the parser as it builds each
+ * element — the producer is the only place that knows this for certain.
+ */
+export function markHtmlTierNode(node) {
+    node[HTML_TIER_NODE] = true;
+    return node;
+}
+/**
+ * True when this node came out of the html tier's parser.
+ *
+ * Deliberately a plain boolean read of the marker — no fallback to a
+ * string-keyed spelling, no shape heuristic ("looks like a raw tag"). Either
+ * the producer marked it or it did not; a consumer-side guess is precisely what
+ * this replaces.
+ */
+export function isHtmlTierNode(node) {
+    return (typeof node === 'object' &&
+        node !== null &&
+        node[HTML_TIER_NODE] === true);
+}

package/dist/types.d.ts

@@ -2,7 +2,7 @@
  * ObjectUI — SDUI JSX-source parser (ADR-0080)
  *
  * Types shared by the constrained JSX-source compiler. The parser turns a
- * constrained JSX/HTML+Tailwind *text* into the existing SDUI `SchemaNode`
+ * constrained JSX *text* into the existing SDUI `SchemaNode`
  * tree. It PARSES — it never executes. No `import`, no `eval`, no JS.
  */
 /** A node in the compiled SDUI tree. Mirrors `@object-ui/types` BaseSchema. */
@@ -39,23 +39,123 @@ export interface ParseResult {
 export type ManifestInputType = 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'object' | 'color' | 'date' | 'code' | 'file' | 'slot';
 export interface ManifestInput {
     name: string;
-    type: ManifestInputType;
+    /**
+     * The input's coarse type: ONE kind, or an ARRAY of kinds when the key's
+     * contract is a union (objectui#3832).
+     *
+     * A value passes {@link validateTree}'s coarse check when ANY arm accepts it,
+     * and is reported when none does — the array widens what is legal, it does
+     * not switch the check off.
+     *
+     * The single-kind form is unchanged and stays the canonical spelling for a
+     * one-arm key: `manifestFromConfigs` collapses a one-element array back to
+     * the bare string, so a manifest gains arrays only where a union was really
+     * declared and every already-published entry serializes byte-identically.
+     */
+    type: ManifestInputType | ManifestInputType[];
+    /**
+     * The coarse kind of the input's MEMBERS — array elements, or the values of
+     * an object used as a map — as ONE kind or an ARRAY of kinds for a member
+     * contract that is a union (objectui#8067).
+     *
+     * Absent means "not declared", which is what every input published before
+     * this key existed says: {@link validateTree} checks no member and the
+     * codegen emits the unnarrowed element type, exactly as before. So a
+     * manifest gains this key only where a member kind was really declared, and
+     * every already-published entry serializes byte-identically.
+     *
+     * Read the arms through `inputTypeArms(input.of)` — the same accessor
+     * `type`'s arms go through, since the two fields carry the same shape and a
+     * reader that forgets the array form is silently inert on it.
+     */
+    of?: ManifestInputType | ManifestInputType[];
     required?: boolean;
     /** allowed values for `enum` inputs */
     enum?: Array<string | {
         value: unknown;
         label?: string;
     }>;
-    /** marks a data-binding input the server must resolve (ADR-0080 §6.3) */
-    binding?: 'object' | 'field';
+    /**
+     * Marks a data-binding input the server must resolve (ADR-0080 §6.3):
+     * `binding: 'object'` says the input NAMES an object, so the server-side
+     * binding check knows what to resolve it against. Unrelated to
+     * `type: 'object'`, the coarse control kind — a record-shaped value and an
+     * object-naming input are two different facts.
+     *
+     * ## The vocabulary is exactly `'object'` — `'field'` is retired on this face too
+     *
+     * `'field'` stood beside it from the first draft of ADR-0080 and was never
+     * written. It was retired on the serializer's INPUT boundary
+     * (`RegistryConfigLike` in `index.ts`) under ADR-0049 enforce-or-remove by
+     * the maintainer ruling of 2026-09-07 (decision batch #69), and on THIS
+     * face by objectui#8315 — the residue that ruling did not name, which left
+     * one published package narrow on one face and wide on the other.
+     *
+     * ⚠️ The argument for leaving this face wide was ANSWERED, not overlooked.
+     * It runs: producer → reader is a subset relation, so a reader accepting a
+     * value no producer emits is permissive rather than wrong. Three measured
+     * facts decided against it (objectui#8315):
+     *
+     *   1. **This is not a pure reader face.** `manifestFromConfigs` RETURNS a
+     *      `Manifest`, so `ManifestInput` is also this package's OUTPUT type,
+     *      and this key is fed straight from the already-narrowed boundary. A
+     *      union wider than the producer's is imprecision on the way out, not
+     *      permissiveness on the way in.
+     *   2. **Its sibling is a pure producer face.**
+     *      `ManifestValidationResult.bindings[].kind` is written by
+     *      `validateTree` by copying this key, so the subset relation runs the
+     *      other way there — see that declaration. The two are COUPLED by that
+     *      assignment: narrowing one alone needs a cast at the only conversion
+     *      site, which is the lenient fallback AGENTS.md #0.1 bans. So "both
+     *      narrow" and "both wide" were the only self-consistent states, and
+     *      only one of them can be justified on the producer face.
+     *   3. **The permissiveness protected nothing.** `binding: 'field'` has
+     *      zero writers here and zero in the objectstack copy of this package
+     *      (measured 2026-09-09 on both heads, each with a firing
+     *      `binding: 'object'` control), and the only manifest producer in
+     *      either tree is `manifestFromConfigs`, whose input face is narrow.
+     *
+     * The reopen route is the ruling's own: a MEASURED need for field bindings
+     * is filed as a widening with the vocabulary decided then — not
+     * pre-declared here for a producer that does not exist.
+     */
+    binding?: 'object';
     description?: string;
 }
 export interface ManifestComponent {
     type: string;
     /** plugin namespace — provenance that drives `requires` */
     namespace?: string;
+    /**
+     * The declared authoring surface. An input named `children` (type `slot`)
+     * is ALSO the containment declaration: `validateTree` draws
+     * `not-a-container` on a child list under any component whose `inputs`
+     * carry no such entry (objectui#9910; `acceptsChildren` in `validate.ts`).
+     */
     inputs: ManifestInput[];
+    /**
+     * LAYOUT containment (objectui#6804, objectui#9910 Q2-A): the flag the
+     * react-page JSX scope builder skips and the public layout ledger lists.
+     * ⛔ Not "accepts children" — this tier's containment check does not read it.
+     */
     isContainer?: boolean;
+    /**
+     * The authoring tier this entry belongs to (objectui#10735).
+     *
+     * Absent = the curated PUBLIC tier (ADR-0080 §4), the JSON-surface
+     * AI-authoring vocabulary. `'html'` = one of the intrinsic HTML elements a
+     * `kind:'html'` page may author (ADR-0081 §2), declared by the registry's
+     * `HTML_TIER_INTRINSICS` roster and carried here so the ONE flat `components`
+     * map can serve both of its readers: a whitelist reader (`compile`, the
+     * objectstack gate) takes every key and needs no change; a reader that means
+     * the curated vocabulary — the `kind:'react'` scope, the block list, a census
+     * of curated blocks — filters this key out.
+     *
+     * ⛔ Not the registration's `tier` copied through. `manifestFromConfigs`
+     * writes exactly `'html'` or nothing, so every entry published before this
+     * key existed serialises byte-identically.
+     */
+    tier?: 'html';
 }
 export interface Manifest {
     /** keyed by component `type` */
@@ -81,11 +181,22 @@ export interface ManifestValidationResult {
     diagnostics: Diagnostic[];
     /** unique plugin namespaces referenced — the page's `requires` */
     requires: string[];
-    /** binding sites (object/field) the server must resolve against object schema */
+    /**
+     * Binding sites the server must resolve against object schema.
+     *
+     * `kind` is a PRODUCER face, not a reader face: `validateTree` writes it,
+     * copying {@link ManifestInput.binding} at the one site that builds this
+     * array. So the subset relation that licenses a permissive READER runs the
+     * other way here — a wider union accepts nothing extra, it obliges every
+     * consumer to handle an arm this package cannot emit. That is why the
+     * retired `'field'` arm (`9e37d9b39` on the input boundary, objectui#8315
+     * here) is gone from this end as well; the measurements are on
+     * {@link ManifestInput.binding}.
+     */
     bindings: Array<{
         tag: string;
         input: string;
-        kind: 'object' | 'field';
+        kind: 'object';
         value: unknown;
     }>;
 }

package/dist/types.js

@@ -2,7 +2,7 @@
  * ObjectUI — SDUI JSX-source parser (ADR-0080)
  *
  * Types shared by the constrained JSX-source compiler. The parser turns a
- * constrained JSX/HTML+Tailwind *text* into the existing SDUI `SchemaNode`
+ * constrained JSX *text* into the existing SDUI `SchemaNode`
  * tree. It PARSES — it never executes. No `import`, no `eval`, no JS.
  */
 export {};

package/dist/validate.d.ts

@@ -2,9 +2,116 @@
  * ObjectUI — SDUI tree validation against the registry manifest (ADR-0080 §3/§6)
  *
  * Shallow, author-time validation: unknown component, unknown/missing prop,
- * wrong coarse type, illegal enum value. Collects `requires` (plugin provenance)
- * and binding sites the SERVER must resolve against object schema (we cannot
- * resolve objects/fields here — that check is framework-side by design).
+ * wrong coarse type, illegal enum value, and containment — a child list under
+ * a component whose registration declares no `children` input draws
+ * `not-a-container` (objectui#9910; see `acceptsChildren`). Collects
+ * `requires` (plugin provenance) and binding sites the SERVER must resolve
+ * against object schema (we cannot resolve objects/fields here — that check is
+ * framework-side by design).
  */
-import type { Manifest, SchemaElement, ManifestValidationResult } from './types.js';
+import type { Manifest, ManifestComponent, SchemaElement, ManifestValidationResult } from './types.js';
+/**
+ * The protocol's ONE child-list key — `BaseSchema.children` — and therefore the
+ * name of the `inputs` entry a registration declares when its renderer puts
+ * that list on the page: `{ name: 'children', type: 'slot' }` (objectui#9910).
+ */
+export declare const CHILD_LIST_KEY = "children";
+/**
+ * Does this component ACCEPT an authored child list? (objectui#9910)
+ *
+ * Read from exactly ONE declaration: an input named {@link CHILD_LIST_KEY} in
+ * the component's `inputs`. That is the shape ten registrations already
+ * carried when the maintainer ruled it the containment contract
+ * (2026-09-24, objectui#9910 Q1-A "declare-and-pin"), and it is held in both
+ * directions by the runtime census in
+ * `packages/components/src/renderers/__tests__/container-declaration-ratchet.test.tsx`:
+ * a renderer that puts `schema.children` on the page without declaring the
+ * input is red, and a declaration whose renderer never renders the list is
+ * red too.
+ *
+ * ⛔ `isContainer` is NOT consulted and is NOT a fallback. It used to decide
+ * this branch and it lied both ways: a hand-kept flag drifted from the code
+ * (objectui#3900 / `7c9b044f4` / #6764 / #6779 found the same drift four times),
+ * and after objectui#6771 converged a dozen registrations onto `children`
+ * the flag put a FALSE `not-a-container` on the one key they read
+ * (objectui#9910). The flag now means LAYOUT containment only — the
+ * react-page JSX scope and the public layout ledger read it; this tier does
+ * not (objectui#6804, objectui#9910 Q2-A).
+ */
+export declare function acceptsChildren(comp: Pick<ManifestComponent, 'inputs'>): boolean;
+/**
+ * Where a base prop is legal without a declaration (objectui#11044).
+ *
+ *  - `'every-node'` — on every node, and a registration's own input of the
+ *    same name is not consulted: {@link validateTree} skips the key before the
+ *    declared-input lookup.
+ *  - `'where-undeclared'` — on a type whose registration declares NO input of
+ *    that name. Where one does, the declared input wins, its `type-mismatch`
+ *    check included, and the generated JSX types take the declared type too.
+ */
+export type SduiBasePropScope = 'every-node' | 'where-undeclared';
+/** One entry of {@link SDUI_BASE_PROPS}. */
+export interface SduiBaseProp {
+    /** The `BaseSchema` member (`@object-ui/types`). */
+    readonly name: string;
+    readonly scope: SduiBasePropScope;
+    /**
+     * The attribute's type in the generated JSX surface (`SduiBaseProps` in
+     * `sdui-intrinsics.d.ts`), or `null` for the one key that is no attribute:
+     * `type`, which the tag name carries (`parse.ts` refuses a `type` attribute).
+     */
+    readonly tsType: string | null;
+}
+/**
+ * The base props: the `BaseSchema` members this tier accepts on a node without
+ * a registration declaring them. ONE list, read by BOTH of its consumers —
+ * {@link validateTree}'s `unknown-prop` branch and `generateDts`'s
+ * `SduiBaseProps` (objectui#11044). Before this list the two were separate
+ * hand-kept copies and had drifted: the validator accepted `bind` and `hidden`
+ * (objectui#11008) while the generated types still refused both.
+ *
+ * `bind` and `hidden` are `'every-node'` (objectui#11008). `BaseSchema` declares
+ * both for every node and no registration declares either as an input, so
+ * before they joined, the undeclared-key branch below answered every authored
+ * one with `unknown-prop` — "has no prop" about a key the protocol declares,
+ * on the nodes that honour it: `hidden` is read for every node by
+ * `SchemaRenderer`'s hide chain, and `bind` by every renderer that calls
+ * `useDataScope` (`list`, `tree-view`, the `object-*` widgets). The
+ * declaration outranks the implementation, so the parser's view is the
+ * declared type's, not a per-registration subset. The cost is accepted and
+ * named: a `bind` on a node that does not read it — `data-table`
+ * (objectui#6575) — draws nothing here either, and its render-time console
+ * warning is the one signal left.
+ *
+ * `visibleWhen`, `hiddenOn` and `testId` are `'every-node'` for the same reason
+ * (objectui#11044): no registration declares any of them, `SchemaRenderer`'s
+ * hide chain reads the first two for every node, and it strips `testId` and
+ * re-emits it as `data-testid`. `visibleWhen` is the canonical ADR-0089
+ * predicate; before it joined, the deprecated `visibleOn` was silent while it
+ * drew `unknown-prop`.
+ *
+ * The `'where-undeclared'` members (objectui#11044, triage ruling) are the
+ * `BaseSchema` members some registrations DECLARE as typed inputs — the input
+ * family's `placeholder`, `label`, `name`, … . Skipping them the way the
+ * `'every-node'` members are skipped would silence those registrations'
+ * `type-mismatch`, so they are base props only where the type declares no
+ * input of that name. ⛔ Never move one to `'every-node'` to accept a key: that
+ * silences a declared type check.
+ *
+ * Held over the live registry by `base-props-one-list-11044.test.tsx` in
+ * `@object-ui/components` — every member a `BaseSchema` member, and `body` the
+ * one member left out.
+ *
+ * ⛔ `body` is NOT here and must not be added. It was `BaseSchema`'s second
+ * child-list spelling until objectui#6771 retired it; teaching this list the
+ * key was the option that ruling refused, because it would have blessed a
+ * second permanent spelling of one concept. `./body-dialect.ts` answers it by
+ * name instead.
+ *
+ * `children` IS here: the key is legal on every node, so it never draws
+ * `unknown-prop` and its declared `slot` input is never type-checked. Whether
+ * a given component RENDERS it is the containment question below, answered by
+ * {@link acceptsChildren} from the declared input.
+ */
+export declare const SDUI_BASE_PROPS: readonly SduiBaseProp[];
 export declare function validateTree(tree: SchemaElement | null, manifest: Manifest): ManifestValidationResult;