@object-ui/sdui-parser 17.5.0 → 17.7.0

package/dist/body-dialect.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ObjectUI — the retired `body` child-list dialect (objectui#6771)
+ *
+ * `body` was a declared twin of `children` on `BaseSchema`, and for a long
+ * while it was the ONLY child-list key a dozen registrations read. This tier
+ * never knew it: `BASE_PROPS` lists `children` and not `body`, so the one
+ * spelling that resolved drew `unknown-prop` — the same warning a typo draws,
+ * on the tier built to accept AI-authored pages, where the diagnostic IS the
+ * contract. The maintainer ruled the retirement (2026-09-01, option B): one
+ * concept, one spelling, and the spelling is `children`.
+ *
+ * This module is the tier's half of that ruling. It REPLACES the diagnostic the
+ * prop walk would otherwise emit for `body`, rather than adding to it — two
+ * diagnostics for one mistake is the shape `checkMemberTypes` already refuses
+ * (objectui#8067).
+ *
+ * WHY A REPLACEMENT AND NOT A BARE `unknown-prop`. After the retirement
+ * "`<badge>` has no prop body" is TRUE — but it is the answer that sent authors
+ * the wrong way in the first place. Every `body` node in this repository's own
+ * docs, examples and READMEs was migrated in the same change, and an author
+ * carrying the old spelling in from anywhere else needs the replacement NAMED,
+ * not merely the key refused. The two codes below are the ruling's own words:
+ * the tier teaches `children` only, and a `body` child list under a
+ * non-container draws the same `not-a-container` the `children` spelling draws.
+ *
+ * SCOPE — asked INSIDE the `!input` branch, because its claim is about a key
+ * nobody declares, so a
+ * component that publishes its own `body` input keeps its declared type check
+ * untouched. Re-derived against the registry rather than recalled: exactly one
+ * registration in the tree declares an input named `body`, and it is
+ * `record:alert` (`plugin-detail`, `register('alert', …, { namespace: 'record' })`),
+ * whose `body` takes an inline translation map and is not this spelling.
+ * Control on the same sweep: `name: 'children'` fires seven times.
+ */
+import type { Diagnostic } from './types.js';
+/** The child-list spelling objectui#6771 retired. `children` replaced it. */
+export declare const RETIRED_CHILD_LIST_KEY = "body";
+/**
+ * The diagnostic for an authored `body`, or `null` when this module has nothing
+ * to say about the key.
+ *
+ * @param tag              the node's component type, for the message and the `tag` field
+ * @param key              the authored prop name
+ * @param value            its authored value
+ * @param acceptsChildren  whether the component declares the `children` slot
+ *                         input — `acceptsChildren(comp)` in `./validate.ts`,
+ *                         the ONE containment predicate this tier has. It used
+ *                         to be `comp.isContainer`; objectui#9910 moved both
+ *                         sites together so the retired spelling and the live
+ *                         one can never disagree about who takes a list.
+ */
+export declare function checkRetiredBodyDialect(tag: string, key: string, value: unknown, acceptsChildren: boolean): Diagnostic | null;

package/dist/body-dialect.js

@@ -0,0 +1,85 @@
+/**
+ * ObjectUI — the retired `body` child-list dialect (objectui#6771)
+ *
+ * `body` was a declared twin of `children` on `BaseSchema`, and for a long
+ * while it was the ONLY child-list key a dozen registrations read. This tier
+ * never knew it: `BASE_PROPS` lists `children` and not `body`, so the one
+ * spelling that resolved drew `unknown-prop` — the same warning a typo draws,
+ * on the tier built to accept AI-authored pages, where the diagnostic IS the
+ * contract. The maintainer ruled the retirement (2026-09-01, option B): one
+ * concept, one spelling, and the spelling is `children`.
+ *
+ * This module is the tier's half of that ruling. It REPLACES the diagnostic the
+ * prop walk would otherwise emit for `body`, rather than adding to it — two
+ * diagnostics for one mistake is the shape `checkMemberTypes` already refuses
+ * (objectui#8067).
+ *
+ * WHY A REPLACEMENT AND NOT A BARE `unknown-prop`. After the retirement
+ * "`<badge>` has no prop body" is TRUE — but it is the answer that sent authors
+ * the wrong way in the first place. Every `body` node in this repository's own
+ * docs, examples and READMEs was migrated in the same change, and an author
+ * carrying the old spelling in from anywhere else needs the replacement NAMED,
+ * not merely the key refused. The two codes below are the ruling's own words:
+ * the tier teaches `children` only, and a `body` child list under a
+ * non-container draws the same `not-a-container` the `children` spelling draws.
+ *
+ * SCOPE — asked INSIDE the `!input` branch, because its claim is about a key
+ * nobody declares, so a
+ * component that publishes its own `body` input keeps its declared type check
+ * untouched. Re-derived against the registry rather than recalled: exactly one
+ * registration in the tree declares an input named `body`, and it is
+ * `record:alert` (`plugin-detail`, `register('alert', …, { namespace: 'record' })`),
+ * whose `body` takes an inline translation map and is not this spelling.
+ * Control on the same sweep: `name: 'children'` fires seven times.
+ */
+/** The child-list spelling objectui#6771 retired. `children` replaced it. */
+export const RETIRED_CHILD_LIST_KEY = 'body';
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * Is this value shaped like the child list the dialect used to carry?
+ *
+ * A list of nodes, or the bare single node `FlatContent` and `renderChildren`
+ * have always accepted. A scalar is not — `body="hi"` is a dead key and nothing
+ * more, so it does not get the containment sentence, which would name a shape
+ * its author did not write.
+ */
+const isChildList = (value) => Array.isArray(value) || isPlainObject(value);
+/**
+ * The diagnostic for an authored `body`, or `null` when this module has nothing
+ * to say about the key.
+ *
+ * @param tag              the node's component type, for the message and the `tag` field
+ * @param key              the authored prop name
+ * @param value            its authored value
+ * @param acceptsChildren  whether the component declares the `children` slot
+ *                         input — `acceptsChildren(comp)` in `./validate.ts`,
+ *                         the ONE containment predicate this tier has. It used
+ *                         to be `comp.isContainer`; objectui#9910 moved both
+ *                         sites together so the retired spelling and the live
+ *                         one can never disagree about who takes a list.
+ */
+export function checkRetiredBodyDialect(tag, key, value, acceptsChildren) {
+    if (key !== RETIRED_CHILD_LIST_KEY)
+        return null;
+    if (isChildList(value) && !acceptsChildren) {
+        // The ruling, verbatim: "a `body` child list under a non-container draws
+        // the same `not-a-container` the `children` spelling draws". Same code, so
+        // a consumer keying on the code cannot tell the two spellings apart — which
+        // is the single-spelling rule stated in the diagnostic stream. The sentence
+        // carries the extra fact the `children` path has no need of.
+        return {
+            severity: 'warning',
+            code: 'not-a-container',
+            message: `<${tag}> does not accept children — and "body" is the retired spelling of ` +
+                `"children" (objectui#6771), so this child list has no door here at all`,
+            tag,
+        };
+    }
+    return {
+        severity: 'warning',
+        code: 'unknown-prop',
+        message: `<${tag}> has no prop "body" — the child-list key is "children" ` +
+            `("body" was retired by objectui#6771)`,
+        tag,
+    };
+}

package/dist/codegen.d.ts

@@ -19,5 +19,10 @@ export declare function propsName(type: string): string;
 /**
  * Generate the human-facing PUBLIC block list (the curated "清单") from a
  * manifest — a Markdown table. Derived, never hand-maintained (ADR-0046).
+ *
+ * The html tier's intrinsic elements (`tier: 'html'`, objectui#10735) are
+ * listed in a section of their own, under their own count: they are in the
+ * manifest because a `kind:'html'` page may author them, not because they are
+ * curated blocks, and a single table would read them as the latter.
  */
 export declare function generateBlockList(manifest: Manifest): string;

package/dist/codegen.js

@@ -7,6 +7,24 @@
  * fiction — no real React intrinsic named `flex` exists; the interpreter
  * fulfills it via the registry at render time.
  */
+import { inputTypeArms } from './input-type.js';
+import { SDUI_BASE_PROPS } from './validate.js';
+/**
+ * `SduiBaseProps`, emitted from {@link SDUI_BASE_PROPS} — the list
+ * `validateTree` reads — so the generated types and the validator cannot
+ * disagree about a base prop (objectui#11044). ⛔ Never a second hand-kept
+ * copy of the list here: that is how this interface came to refuse `bind` and
+ * `hidden` after the validator accepted them.
+ */
+const emitBaseProps = () => `export interface SduiBaseProps {\n${SDUI_BASE_PROPS.filter((prop) => prop.tsType !== null)
+    .map((prop) => `  ${prop.name}?: ${prop.tsType};`)
+    .join('\n')}\n}`;
+/**
+ * The attributes `SduiBaseProps` carries — every entry of the list but `type`,
+ * whatever its scope. A declared input of the same name outranks each of them
+ * in the generated types (objectui#11044, objectui#11075).
+ */
+const BASE_ATTRIBUTES = new Set(SDUI_BASE_PROPS.filter((prop) => prop.tsType !== null).map((prop) => prop.name));
 export function generateDts(manifest, options = {}) {
     const { standaloneJsx = true } = options;
     const comps = Object.values(manifest.components).sort((a, b) => a.type.localeCompare(b.type));
@@ -26,16 +44,7 @@ export function generateDts(manifest, options = {}) {
 // Source of truth: ComponentRegistry inputs (ADR-0080 §3). Regenerate via codegen.
 /* eslint-disable */
 
-export interface SduiBaseProps {
-  id?: string;
-  className?: string;
-  style?: Record<string, unknown>;
-  visible?: boolean;
-  visibleOn?: string;
-  disabled?: boolean;
-  disabledOn?: string;
-  children?: unknown;
-}
+${emitBaseProps()}
 
 ${interfaces}
 
@@ -50,40 +59,105 @@ ${intrinsics}
 export {};
 `;
 }
+/**
+ * A `'slot'` arm names a child position, not a prop value — `SduiBaseProps`
+ * already types `children`, so a slot input contributes no attribute. An input
+ * is therefore emitted when it has at least one NON-slot arm, and typed from
+ * those arms only (objectui#3832): the old test was `i.type !== 'slot'`, which a
+ * union like `['slot', 'string']` would have passed while `tsType` fell through
+ * to the default and typed it `string` anyway.
+ *
+ * A base attribute the component declares is `Omit`ted from the base it
+ * extends, whatever its scope: the declared input wins with its type. So a
+ * declared type the base one does not admit is no TS2430 conflict — neither
+ * `label?: string | Record<string, unknown>` on a `'where-undeclared'` member
+ * (objectui#11044) nor `record:alert`'s
+ * `visible?: boolean | string | Record<string, unknown>` on an `'every-node'`
+ * one (objectui#11075) — and one the base admits (`className?: string`) types
+ * the same either way.
+ *
+ * The scope is the VALIDATOR's distinction — `validateTree` skips an
+ * `'every-node'` key before the declared-input lookup — and does not reach this
+ * surface. ⛔ Every declared base attribute is `Omit`ted, not only the ones
+ * whose types conflict: assignability is TypeScript's judgement, and a
+ * conflicts-only rule here would re-derive it from type strings.
+ *
+ * A slot-only input emits no attribute, so a declared `children: 'slot'` is
+ * not `Omit`ted and the base `children` stays.
+ */
 function emitInterface(comp) {
-    const lines = comp.inputs
-        .filter((i) => i.type !== 'slot')
-        .map((i) => `  ${propLine(i)}`)
-        .join('\n');
-    return `export interface ${propsName(comp.type)} extends SduiBaseProps {\n${lines}\n}`;
+    const emitted = comp.inputs.filter((i) => valueArms(i).length > 0);
+    const lines = emitted.map((i) => `  ${propLine(i)}`).join('\n');
+    const yielded = emitted.filter((i) => BASE_ATTRIBUTES.has(i.name)).map((i) => JSON.stringify(i.name));
+    const base = yielded.length > 0 ? `Omit<SduiBaseProps, ${yielded.join(' | ')}>` : 'SduiBaseProps';
+    return `export interface ${propsName(comp.type)} extends ${base} {\n${lines}\n}`;
 }
+/** The arms that describe a VALUE (every arm except `'slot'`). */
+const valueArms = (input) => inputTypeArms(input.type).filter((arm) => arm !== 'slot');
 function propLine(input) {
     const opt = input.required ? '' : '?';
     return `${quoteKeyIfNeeded(input.name)}${opt}: ${tsType(input)};`;
 }
-function tsType(input) {
-    switch (input.type) {
+/**
+ * The TypeScript type for one arm. Kinds that are a string with a narrower
+ * authoring control (`color`, `date`, `code`, `file`) are `string` here, as
+ * before — the JSX surface types the VALUE, and the control kind is the
+ * designer's business.
+ */
+function armTsType(arm, input) {
+    switch (arm) {
         case 'number':
             return 'number';
         case 'boolean':
             return 'boolean';
         case 'array':
-            return 'unknown[]';
+            return `${memberTsType(input)}[]`;
         case 'object':
-            return 'Record<string, unknown>';
+            return `Record<string, ${memberTsType(input)}>`;
         case 'enum': {
             const vals = (input.enum ?? []).map((e) => (typeof e === 'object' ? e.value : e));
             return vals.length ? vals.map((v) => JSON.stringify(v)).join(' | ') : 'string';
         }
-        case 'string':
-        case 'color':
-        case 'date':
-        case 'code':
-        case 'file':
         default:
             return 'string';
     }
 }
+/**
+ * The TypeScript type of a container's MEMBERS, from `ManifestInput.of`
+ * (objectui#8067).
+ *
+ * `unknown` when nothing is declared, which is what every input published
+ * before `of` existed says — so an undeclared array still emits `unknown[]` and
+ * an undeclared object still emits `Record<string, unknown>`, byte for byte.
+ * A declared member kind narrows it: `of: 'string'` on `page:header.actions`
+ * turns `unknown[]` into `string[]`, and the JSX surface finally types the
+ * action IDs the contract has always required.
+ *
+ * `'slot'` is dropped for the same reason {@link valueArms} drops it one level
+ * up: it names a child position, not a value, so it contributes no member type.
+ * If that leaves nothing, the result is `unknown` — a declaration that types no
+ * member must not silently type them all as strings.
+ */
+function memberTsType(input) {
+    const arms = inputTypeArms(input.of).filter((arm) => arm !== 'slot');
+    if (arms.length === 0)
+        return 'unknown';
+    const emitted = [...new Set(arms.map((arm) => armTsType(arm, { ...input, of: undefined })))];
+    return emitted.length === 1 ? emitted[0] : `(${emitted.join(' | ')})`;
+}
+/**
+ * A union declaration emits a TypeScript union, so the `.d.ts` an author
+ * type-checks their page against accepts exactly the arms the manifest gate
+ * accepts. Arms that collapse to the same TS type (`string` and `color`, say)
+ * are de-duplicated rather than emitted as `string | string`.
+ */
+function tsType(input) {
+    const arms = valueArms(input);
+    if (arms.length === 0)
+        return 'string';
+    const emitted = [...new Set(arms.map((arm) => armTsType(arm, input)))];
+    return emitted.join(' | ');
+}
 const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 const quoteKeyIfNeeded = (name) => (IDENT.test(name) ? name : JSON.stringify(name));
 /** 'object-grid' -> 'ObjectGrid', 'record:details' -> 'RecordDetails' */
@@ -98,23 +172,40 @@ export function propsName(type) {
 /**
  * Generate the human-facing PUBLIC block list (the curated "清单") from a
  * manifest — a Markdown table. Derived, never hand-maintained (ADR-0046).
+ *
+ * The html tier's intrinsic elements (`tier: 'html'`, objectui#10735) are
+ * listed in a section of their own, under their own count: they are in the
+ * manifest because a `kind:'html'` page may author them, not because they are
+ * curated blocks, and a single table would read them as the latter.
  */
 export function generateBlockList(manifest) {
-    const rows = Object.values(manifest.components)
-        .sort((a, b) => a.type.localeCompare(b.type))
-        .map((c) => {
+    const sorted = Object.values(manifest.components).sort((a, b) => a.type.localeCompare(b.type));
+    const curated = sorted.filter((c) => c.tier !== 'html');
+    const htmlTier = sorted.filter((c) => c.tier === 'html');
+    const row = (c) => {
         const req = c.inputs.filter((i) => i.required).map((i) => i.name);
         const binds = c.inputs.filter((i) => i.binding).map((i) => `${i.name}:${i.binding}`);
         return `| \`${c.type}\` | ${c.namespace ?? '—'} | ${c.isContainer ? '✓' : ''} | ${req.join(', ') || '—'} | ${binds.join(', ') || '—'} |`;
-    });
+    };
+    const header = ['| block | plugin | container | required props | bindings |', '|---|---|---|---|---|'];
     return [
-        `# SDUI public blocks (${Object.keys(manifest.components).length})`,
+        `# SDUI public blocks (${curated.length})`,
         '',
         '> Auto-generated from the registry `tier:\'public\'` set (ADR-0080). Do not edit by hand.',
         '',
-        '| block | plugin | container | required props | bindings |',
-        '|---|---|---|---|---|',
-        ...rows,
+        ...header,
+        ...curated.map(row),
+        ...(htmlTier.length
+            ? [
+                '',
+                `## html tier intrinsic elements (${htmlTier.length})`,
+                '',
+                "> The intrinsic HTML tags a `kind:'html'` page may author (ADR-0081 §2), declared by the registry's `HTML_TIER_INTRINSICS` roster and marked `tier: 'html'` in the manifest. Not part of the curated vocabulary above.",
+                '',
+                ...header,
+                ...htmlTier.map(row),
+            ]
+            : []),
         '',
     ].join('\n');
 }

package/dist/dashboard-widget-options.d.ts

@@ -0,0 +1,129 @@
+/**
+ * ObjectUI — unconsumed dashboard-widget `options` keys (`8d58f46b4`)
+ *
+ * `@objectstack/spec`'s `DashboardWidgetOptionsSchema` ends in `.passthrough()`
+ * ("declared query keys + open renderer extras"), so ANY key parses, validates
+ * and lints cleanly — including one no renderer reads. That is how a showcase
+ * dashboard shipped `options: { invert: true }` on a gauge with a comment
+ * saying what it was believed to do, and rendered the un-inverted measure with
+ * no diagnostic anywhere (`8d58f46b4`). The 2026-08-23 maintainer ruling:
+ * open extras stay open — they just stop being SILENT. A key that reaches no
+ * renderer draws a WARNING naming the consumed set. Not an error: no gate
+ * weakening and no new red gates were ruled.
+ *
+ * ## The census (measured on origin/main @ 8689166f6, spec 17.1.0)
+ *
+ * The spec REQUIRES `dataset` on every widget (`DashboardWidgetSchema` —
+ * re-read for objectui#7293 against the PUBLISHED `@objectstack/spec@17.4.0`,
+ * whose required keys are exactly `id` / `dataset` / `values`), and
+ * both dashboard surfaces route a dataset-bound widget to `DatasetWidget`
+ * (`DashboardRenderer.tsx` renders `<DatasetWidget>` when `widget.dataset` is
+ * set; `DashboardGridLayout.tsx` mirrors the fork, objectui#4614). On that —
+ * the only spec-legal — path, the renderer-consumed `options` keys are exactly
+ * the five the spec DECLARES, all read as direct `options.<key>` accesses in
+ * `packages/plugin-dashboard/src/DatasetWidget.tsx`:
+ *
+ *   dateGranularity, sortBy, sortOrder, limit   (query-affecting, framework#3588)
+ *   stageOrder                                  (funnel/pyramid stage order)
+ *
+ * plus ONE undeclared key with a real read site:
+ *
+ *   description — the metric-card sub-caption channel. Read at
+ *   `widgetSubCaption.ts` (`(widget.options as …)?.description`, objectui#4032
+ *   item 4 — that read sat inline in `DashboardRenderer.tsx` until
+ *   objectui#8889 moved it, verbatim, into the hook BOTH dashboard surfaces
+ *   now call, so the authored and bundle channels compose at one decision
+ *   point) and, since objectui#7293, at `DatasetWidget.tsx`'s
+ *   metric branch, which renders it in the caption row; the server's
+ *   `translateDashboard` OVERLAYS the `widgets.{id}.subCaption` translation
+ *   onto this key (objectstack#8056, objectstack#5428 item-4: 「两个作者字段两个
+ *   key」). It entered the accepted set on the translation-pipeline evidence
+ *   alone — warning on a key the platform's own pipeline writes would be a
+ *   false positive on legal metadata — while the dataset-bound render path
+ *   displayed it nowhere. #7293 closed that gap, so `description` is now
+ *   accepted for the same reason as the declared five and the accepted set no
+ *   longer outruns the measured read set.
+ *
+ * Notably NOT consumed on the path a widget really renders through:
+ * `thresholds` and `format`. Both were widely believed to work; both draw this
+ * warning, which is the point. They are NOT the same kind of claim, and since
+ * the 2026-08-25 maintainer ruling (batch adjudication close-out, decision B1 —
+ * a closure claim must be BOUNDED or DERIVABLE, and a claim written in two
+ * places is single-sourced) they are written separately (objectui#6186):
+ *
+ *   `thresholds` — zero read sites repo-wide. This paragraph is the CANONICAL
+ *     statement of that closure claim. `content/docs/plugins/plugin-dashboard.mdx`
+ *     used to assert it a second time in its own words; two copies of one
+ *     closure claim drift apart independently and neither knows when the other
+ *     stopped being true, so the page now POINTS here rather than restating it.
+ *     Single-sourcing is what makes this copy load-bearing, so it is DERIVED
+ *     rather than trusted:
+ *     `scripts/__tests__/unconsumed-widget-option-claim-6186.test.ts` re-scans
+ *     every JS/TS file git tracks for an access to a key of that name and fails
+ *     if one appears. Land a renderer that reads it and this module goes red in
+ *     the same run.
+ *   `format` — not read ON THE DATASET-BOUND PATH; the value is formatted with
+ *     the MEASURE's own metadata (`measureField(...).format`, from the dataset
+ *     definition), not from the widget's bag. Deliberately a BOUNDED claim and
+ *     not a repo-wide one: `format` is a live key in other vocabularies, so a
+ *     repo-wide scan would red on a TRUE claim — and an assertion that reds on
+ *     legitimate code gets deleted by the next person who hits it, which puts
+ *     the claim back where it started. Leg 2 of
+ *     `__tests__/dashboard-widget-options-census.test.ts` derives exactly this
+ *     bound: the DatasetWidget read set is the declared set plus the
+ *     sub-caption key, and neither `format` nor `thresholds` is in it. Since
+ *     objectui#7293 that absence is asserted in its OWN right rather than
+ *     riding on an equality whose right-hand side can grow.
+ *
+ * ## Scope — where the warning deliberately does NOT fire
+ *
+ *   - Widgets WITHOUT `dataset`: the legacy inline forms (`options.data`
+ *     arrays, `provider: 'object'` bags) consume a much larger, spread-shaped
+ *     key set (`{ ...options }` into `metric` / `object-metric` /
+ *     `data-table` / …), whose true reach is each child component's prop
+ *     surface. That form is spec-illegal today (`dataset` is required) and its
+ *     census would be the unmaintainable one; skipping it keeps every warning
+ *     this module emits a statement about the path the widget actually renders
+ *     through.
+ *   - Widgets in the legacy COMPONENT format (`widget.component`): `options`
+ *     is not part of that contract.
+ *   - Widgets carrying the spec's own escape hatch
+ *     `suppressWarnings: ['unconsumed-widget-option']` — the spec models
+ *     per-widget diagnostic suppression (`DashboardWidgetSchema`), so an
+ *     author with a genuine out-of-band consumer can say so in metadata.
+ *
+ * ## Maintenance — how this list stays true
+ *
+ * `__tests__/dashboard-widget-options-census.test.ts` re-runs the census on
+ * every test run: it re-derives the five declared keys from the installed
+ * `@objectstack/spec`, re-extracts the `options.<key>` reads from
+ * `DatasetWidget.tsx` source text (and fails loudly if that file gains a
+ * consumption shape the extractor cannot see — a spread, a destructuring, a
+ * computed access), re-checks the sub-caption read site, and trips on any NEW
+ * file in `packages/*\/src` or `apps/*\/src` that starts reading
+ * `widget.options`. A renderer change that adds or removes a consumed key
+ * fails that test until this list is updated — the cost of keeping this
+ * warning honest is editing ONE array below plus re-reading the census notes.
+ */
+import type { Diagnostic, SchemaElement } from './types.js';
+/** The diagnostic `code` — also the id `suppressWarnings` suppresses. */
+export declare const UNCONSUMED_WIDGET_OPTION = "unconsumed-widget-option";
+/**
+ * Component types that host a dashboard `widgets` array. Both resolve to the
+ * surfaces measured by the census above (`DashboardRenderer`,
+ * `DashboardGridLayout`), which share one dispatch (`widgetDispatch.ts`).
+ */
+export declare const DASHBOARD_WIDGET_HOST_TYPES: ReadonlySet<string>;
+/**
+ * The accepted set: every `options` key with a renderer read site on the
+ * dataset-bound path, plus the sub-caption convention key. Alphabetical; the
+ * warning message prints it verbatim. Derivation and evidence: file header.
+ */
+export declare const CONSUMED_WIDGET_OPTION_KEYS: readonly string[];
+/**
+ * Diagnostics for `options` keys no renderer consumes, over one dashboard-host
+ * node's `widgets` array. Pure and shallow by design: it never descends into
+ * `children` (the caller's walk owns that) and answers `[]` for every shape
+ * outside its census — see the scope notes in the file header.
+ */
+export declare function checkDashboardWidgetOptions(node: SchemaElement): Diagnostic[];

package/dist/dashboard-widget-options.js

@@ -0,0 +1,73 @@
+/** The diagnostic `code` — also the id `suppressWarnings` suppresses. */
+export const UNCONSUMED_WIDGET_OPTION = 'unconsumed-widget-option';
+/**
+ * Component types that host a dashboard `widgets` array. Both resolve to the
+ * surfaces measured by the census above (`DashboardRenderer`,
+ * `DashboardGridLayout`), which share one dispatch (`widgetDispatch.ts`).
+ */
+export const DASHBOARD_WIDGET_HOST_TYPES = new Set([
+    'dashboard',
+    'dashboard-grid',
+]);
+/**
+ * The accepted set: every `options` key with a renderer read site on the
+ * dataset-bound path, plus the sub-caption convention key. Alphabetical; the
+ * warning message prints it verbatim. Derivation and evidence: file header.
+ */
+export const CONSUMED_WIDGET_OPTION_KEYS = [
+    'dateGranularity',
+    'description',
+    'limit',
+    'sortBy',
+    'sortOrder',
+    'stageOrder',
+];
+const CONSUMED = new Set(CONSUMED_WIDGET_OPTION_KEYS);
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** The parser's deferred-expression marker — opaque here, never evaluated. */
+const isExpr = (v) => isPlainObject(v) && '$expr' in v;
+/**
+ * Diagnostics for `options` keys no renderer consumes, over one dashboard-host
+ * node's `widgets` array. Pure and shallow by design: it never descends into
+ * `children` (the caller's walk owns that) and answers `[]` for every shape
+ * outside its census — see the scope notes in the file header.
+ */
+export function checkDashboardWidgetOptions(node) {
+    if (!DASHBOARD_WIDGET_HOST_TYPES.has(node.type))
+        return [];
+    const widgets = node.widgets;
+    if (!Array.isArray(widgets))
+        return [];
+    const diagnostics = [];
+    widgets.forEach((widget, index) => {
+        if (!isPlainObject(widget) || isExpr(widget))
+            return;
+        // Legacy component format: `options` is not part of that contract.
+        if (widget.component !== undefined)
+            return;
+        // Only the dataset-bound (spec-legal) path is censused — see file header.
+        if (widget.dataset === undefined || widget.dataset === null || widget.dataset === '')
+            return;
+        const options = widget.options;
+        if (!isPlainObject(options) || isExpr(options))
+            return;
+        if (Array.isArray(widget.suppressWarnings) &&
+            widget.suppressWarnings.includes(UNCONSUMED_WIDGET_OPTION)) {
+            return;
+        }
+        const label = typeof widget.id === 'string' && widget.id !== '' ? widget.id : `#${index}`;
+        const widgetType = typeof widget.type === 'string' && widget.type !== '' ? widget.type : 'widget';
+        for (const key of Object.keys(options)) {
+            if (CONSUMED.has(key))
+                continue;
+            diagnostics.push({
+                severity: 'warning',
+                code: UNCONSUMED_WIDGET_OPTION,
+                message: `<${node.type}> widget "${label}" (${widgetType}): options.${key} reaches no renderer — ` +
+                    `dashboard widget renderers read only: ${CONSUMED_WIDGET_OPTION_KEYS.join(', ')}`,
+                tag: node.type,
+            });
+        }
+    });
+    return diagnostics;
+}

package/dist/index.d.ts

@@ -7,9 +7,14 @@
  */
 export * from './types.js';
 export { parseJsx, interpretBrace } from './parse.js';
-export { validateTree } from './validate.js';
+export { HTML_TIER_NODE, isHtmlTierNode, markHtmlTierNode } from './provenance.js';
+export { validateTree, acceptsChildren, CHILD_LIST_KEY, SDUI_BASE_PROPS } from './validate.js';
+export type { SduiBaseProp, SduiBasePropScope } from './validate.js';
+export { checkDashboardWidgetOptions, CONSUMED_WIDGET_OPTION_KEYS, DASHBOARD_WIDGET_HOST_TYPES, UNCONSUMED_WIDGET_OPTION, } from './dashboard-widget-options.js';
 export { generateDts, propsName, generateBlockList } from './codegen.js';
 export type { CodegenOptions } from './codegen.js';
+export { inputTypeArms, canonicalizeInputType, MANIFEST_INPUT_TYPES } from './input-type.js';
+export { checkRetiredBodyDialect, RETIRED_CHILD_LIST_KEY } from './body-dialect.js';
 import type { Diagnostic, Manifest, SchemaElement, ManifestValidationResult } from './types.js';
 export interface CompileResult {
     tree: SchemaElement | null;
@@ -27,20 +32,72 @@ export declare function compile(source: string, manifest: Manifest): CompileResu
 export interface RegistryConfigLike {
     type: string;
     namespace?: string;
+    /**
+     * LAYOUT containment — the registration's `ComponentMeta.isContainer`,
+     * carried through to the manifest for the consumers that read it there.
+     * ⛔ It does not mean "accepts children" and `validateTree` does not read
+     * it: whether a component takes an authored child list is declared as an
+     * input named `children` (objectui#9910; `acceptsChildren` in `validate.ts`).
+     */
     isContainer?: boolean;
-    /** ADR-0080 contract tier — only 'public' configs form the AI/contract surface. */
-    tier?: 'public' | 'internal';
+    /**
+     * ADR-0080 contract tier — only 'public' configs form the AI/contract
+     * surface under `publicOnly`. `'html'` is the projection-only stamp
+     * `ComponentRegistry.getPublicConfigs()` puts on the html tier's intrinsic
+     * elements (objectui#10735); it is the one value {@link manifestFromConfigs}
+     * carries into `ManifestComponent.tier`.
+     */
+    tier?: 'public' | 'internal' | 'html';
     label?: string;
     category?: string;
     inputs?: Array<{
         name: string;
-        type: string;
+        /**
+         * One coarse kind, or the arms of a union (objectui#3832). Typed loosely
+         * (`string`) on purpose — this interface is the STRUCTURAL boundary that
+         * keeps this package free of a dependency on the registry, so an
+         * off-vocabulary value has to be representable here and is normalized by
+         * `canonicalizeInputType` on the way in.
+         */
+        type: string | string[];
+        /**
+         * The declared member kind(s) — array elements, or an object map's values
+         * (objectui#8067). Typed as loosely as `type` above and for the same
+         * reason: this interface is the STRUCTURAL boundary that keeps the package
+         * free of a registry dependency, so an off-vocabulary value has to be
+         * representable here and is normalized on the way in.
+         */
+        of?: string | string[];
         required?: boolean;
         enum?: Array<string | {
             value: unknown;
             label?: string;
         }>;
-        binding?: 'object' | 'field';
+        /**
+         * The binding marker — exactly `'object'` (`9e37d9b39`).
+         *
+         * `'field'` was declared beside it from the first draft of ADR-0080 §6.3
+         * and never written: every `binding:` literal in `packages/`, `apps/`
+         * and `examples/` is `'object'` (7 of 7, measured 2026-09-06 and
+         * re-measured at the retiring PR's merge-base), and nothing on either
+         * side of the manifest resolved a field binding. Retired under ADR-0049
+         * enforce-or-remove by the maintainer ruling of 2026-09-07 (decision
+         * batch #69): a config that spells the arm is a `tsc` error here rather
+         * than an entry the server would never resolve.
+         *
+         * The retirement then reached the two faces the ruling did not name
+         * (objectui#8315): `ManifestInput.binding` and
+         * `ManifestValidationResult.bindings[].kind` in `types.ts` read `'object'`
+         * too, so the published package no longer narrows on one face and stays
+         * wide on the other. The argument for keeping the manifest face wide —
+         * producer → reader is a subset relation — is answered at
+         * `ManifestInput.binding`, which is where a later reader lands.
+         *
+         * Only the framework writes the key: `InjectedComponentInput` in
+         * `@object-ui/types`, spliced by `Registry.register`. `ComponentInput`
+         * itself has no `binding` member, deliberately.
+         */
+        binding?: 'object';
         description?: string;
     }>;
     /**