@object-ui/sdui-parser 17.5.0 → 17.6.0

package/dist/codegen.js

@@ -7,6 +7,7 @@
  * fiction — no real React intrinsic named `flex` exists; the interpreter
  * fulfills it via the registry at render time.
  */
+import { inputTypeArms } from './input-type.js';
 export function generateDts(manifest, options = {}) {
     const { standaloneJsx = true } = options;
     const comps = Object.values(manifest.components).sort((a, b) => a.type.localeCompare(b.type));
@@ -50,19 +51,35 @@ ${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.
+ */
 function emitInterface(comp) {
     const lines = comp.inputs
-        .filter((i) => i.type !== 'slot')
+        .filter((i) => valueArms(i).length > 0)
         .map((i) => `  ${propLine(i)}`)
         .join('\n');
     return `export interface ${propsName(comp.type)} extends SduiBaseProps {\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':
@@ -75,15 +92,23 @@ function tsType(input) {
             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';
     }
 }
+/**
+ * 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' */

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

@@ -0,0 +1,95 @@
+/**
+ * ObjectUI — unconsumed dashboard-widget `options` keys (objectui#5709)
+ *
+ * `@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 (objectui#5709). 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`), 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
+ *   `DashboardRenderer.tsx` (`(widget.options as …)?.description`,
+ *   objectui#4032 item 4); the server's `translateDashboard` OVERLAYS the
+ *   `widgets.{id}.subCaption` translation onto this key (objectstack#8056,
+ *   objectstack#5428 item-4: 「两个作者字段两个 key」). Warning on a key the
+ *   platform's own translation pipeline writes would be a false positive on
+ *   legal metadata, so it is in the accepted set even though the dataset-bound
+ *   render path does not currently display it.
+ *
+ * Notably NOT consumed anywhere in this repository: `thresholds` (zero read
+ *   sites repo-wide) and `format` — the dataset-bound value is formatted with
+ *   the MEASURE's own metadata (`measureField(...).format`, from the dataset
+ *   definition), not with `options.format`. Both were widely believed to work;
+ *   both draw this warning, which is the point.
+ *
+ * ## 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,12 @@
  */
 export * from './types.js';
 export { parseJsx, interpretBrace } from './parse.js';
+export { HTML_TIER_NODE, isHtmlTierNode, markHtmlTierNode } from './provenance.js';
 export { validateTree } 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';
 import type { Diagnostic, Manifest, SchemaElement, ManifestValidationResult } from './types.js';
 export interface CompileResult {
     tree: SchemaElement | null;
@@ -34,7 +37,14 @@ export interface RegistryConfigLike {
     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[];
         required?: boolean;
         enum?: Array<string | {
             value: unknown;

package/dist/index.js

@@ -7,10 +7,14 @@
  */
 export * from './types.js';
 export { parseJsx, interpretBrace } from './parse.js';
+export { HTML_TIER_NODE, isHtmlTierNode, markHtmlTierNode } from './provenance.js';
 export { validateTree } 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 { inputTypeArms, canonicalizeInputType, MANIFEST_INPUT_TYPES } from './input-type.js';
 import { parseJsx } from './parse.js';
 import { validateTree } from './validate.js';
+import { canonicalizeInputType } from './input-type.js';
 /**
  * The authoritative pipeline: parse (with the manifest's tags as the whitelist)
  * → validate against the manifest → derive `requires` + binding sites.
@@ -52,19 +56,10 @@ export function assertFullyLoaded(configs) {
         `so every prop an author passes them would be reported as unknown.\n` +
         `Add an eager \`import\` of each block's plugin to the generator entry.`);
 }
-const INPUT_TYPES = new Set([
-    'string',
-    'number',
-    'boolean',
-    'enum',
-    'array',
-    'object',
-    'color',
-    'date',
-    'code',
-    'file',
-    'slot',
-]);
+/* The arm vocabulary and the two projections over it now live in
+ * `input-type.ts` — `manifestFromConfigs` below, `validateTree` and the codegen
+ * all read `ManifestInput.type` and must agree on how, since it holds one arm
+ * or an array of them (objectui#3832). */
 /**
  * Project registry configs into the SDUI manifest.
  *
@@ -95,7 +90,7 @@ export function manifestFromConfigs(configs, opts = {}) {
             isContainer: c.isContainer,
             inputs: (c.inputs ?? []).map((i) => ({
                 name: i.name,
-                type: (INPUT_TYPES.has(i.type) ? i.type : 'string'),
+                type: canonicalizeInputType(i.type),
                 required: i.required,
                 enum: i.enum,
                 binding: i.binding,

package/dist/input-type.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ObjectUI — the arms of a manifest input's coarse type (objectui#3832)
+ *
+ * `ManifestInput.type` carries ONE coarse kind, or an ARRAY of kinds when the
+ * key's contract is a union. Every reader of that field needs the same two
+ * decisions made the same way — how to see the arms, and which single form to
+ * publish — so they live here once instead of at each call site. A reader that
+ * forgets is not loud: `switch (input.type)` handed an array falls through to
+ * the default branch and reports NOTHING, which looks exactly like a value that
+ * validated cleanly.
+ */
+import type { ManifestInput, ManifestInputType } from './types.js';
+/** The eleven coarse kinds, as a runtime set for guarding untyped input. */
+export declare const MANIFEST_INPUT_TYPES: ReadonlySet<string>;
+/**
+ * The declared arms of an input's coarse type, always as an array.
+ *
+ * Exported (not merely internal) so a third-party manifest consumer — a
+ * designer panel, a codegen, a validator of its own — reads the arms through
+ * the same accessor this package's own gate does, rather than re-deriving the
+ * `Array.isArray` branch and getting it subtly wrong on the union form.
+ */
+export declare function inputTypeArms(type: ManifestInput['type'] | undefined): ManifestInputType[];
+/**
+ * Project a DECLARED type (which may come from an untyped registry config) into
+ * the canonical published form: a bare string for one arm, an array for a real
+ * union.
+ *
+ * Two deliberate asymmetries between the single and array forms:
+ *
+ *  - A single unrecognized kind still becomes `'string'`. That coercion predates
+ *    the union work and is kept exactly: with one arm there is no other
+ *    information to fall back on, and a manifest whose `type` is off-vocabulary
+ *    would make every consumer's switch silently inert.
+ *  - An unrecognized arm INSIDE an array is DROPPED, not coerced. Promoting it
+ *    to `'string'` would publish an arm the author never declared — a widening
+ *    invented by the serializer — and the surviving arms already carry the
+ *    declaration. If dropping empties the array, the single-arm fallback applies
+ *    so the output is always a valid manifest.
+ *
+ * Collapsing one arm to the bare string is what keeps this a backward-compatible
+ * extension of `sdui.manifest.json`: every input declared today serializes to
+ * the byte-identical entry it does now, and arrays appear only where a union was
+ * really declared.
+ */
+export declare function canonicalizeInputType(type: unknown): ManifestInputType | ManifestInputType[];

package/dist/input-type.js

@@ -0,0 +1,69 @@
+/**
+ * ObjectUI — the arms of a manifest input's coarse type (objectui#3832)
+ *
+ * `ManifestInput.type` carries ONE coarse kind, or an ARRAY of kinds when the
+ * key's contract is a union. Every reader of that field needs the same two
+ * decisions made the same way — how to see the arms, and which single form to
+ * publish — so they live here once instead of at each call site. A reader that
+ * forgets is not loud: `switch (input.type)` handed an array falls through to
+ * the default branch and reports NOTHING, which looks exactly like a value that
+ * validated cleanly.
+ */
+/** The eleven coarse kinds, as a runtime set for guarding untyped input. */
+export const MANIFEST_INPUT_TYPES = new Set([
+    'string',
+    'number',
+    'boolean',
+    'enum',
+    'array',
+    'object',
+    'color',
+    'date',
+    'code',
+    'file',
+    'slot',
+]);
+/**
+ * The declared arms of an input's coarse type, always as an array.
+ *
+ * Exported (not merely internal) so a third-party manifest consumer — a
+ * designer panel, a codegen, a validator of its own — reads the arms through
+ * the same accessor this package's own gate does, rather than re-deriving the
+ * `Array.isArray` branch and getting it subtly wrong on the union form.
+ */
+export function inputTypeArms(type) {
+    if (type === undefined)
+        return [];
+    return Array.isArray(type) ? type : [type];
+}
+/**
+ * Project a DECLARED type (which may come from an untyped registry config) into
+ * the canonical published form: a bare string for one arm, an array for a real
+ * union.
+ *
+ * Two deliberate asymmetries between the single and array forms:
+ *
+ *  - A single unrecognized kind still becomes `'string'`. That coercion predates
+ *    the union work and is kept exactly: with one arm there is no other
+ *    information to fall back on, and a manifest whose `type` is off-vocabulary
+ *    would make every consumer's switch silently inert.
+ *  - An unrecognized arm INSIDE an array is DROPPED, not coerced. Promoting it
+ *    to `'string'` would publish an arm the author never declared — a widening
+ *    invented by the serializer — and the surviving arms already carry the
+ *    declaration. If dropping empties the array, the single-arm fallback applies
+ *    so the output is always a valid manifest.
+ *
+ * Collapsing one arm to the bare string is what keeps this a backward-compatible
+ * extension of `sdui.manifest.json`: every input declared today serializes to
+ * the byte-identical entry it does now, and arrays appear only where a union was
+ * really declared.
+ */
+export function canonicalizeInputType(type) {
+    const arms = (Array.isArray(type) ? type : [type]).filter((arm) => typeof arm === 'string' && MANIFEST_INPUT_TYPES.has(arm));
+    const distinct = [...new Set(arms)];
+    if (distinct.length === 0)
+        return 'string';
+    if (distinct.length === 1)
+        return distinct[0];
+    return distinct;
+}

package/dist/parse.js

@@ -13,6 +13,7 @@
  *   child    := element | text | jsx-block-comment
  *   tag      := [A-Za-z][A-Za-z0-9:_-]star      (matches registry keys)
  */
+import { markHtmlTierNode } from './provenance.js';
 /** Event handlers and raw-HTML injection are never allowed (parse ≠ execute). */
 const EVENT_ATTR = /^on[A-Z]/;
 const FORBIDDEN_ATTRS = new Set(['dangerouslySetInnerHTML', 'ref', 'key']);
@@ -98,7 +99,15 @@ class Parser {
         else {
             this.error('unterminated-open-tag', `Unterminated <${tag}> open tag`, start, tag);
         }
-        const node = { type: tag, ...props };
+        // Stamp html-tier provenance at the point of production (objectui#4000).
+        // Renderers whose type carries authoring advice aimed at the JSON surface
+        // read this to tell "the author wrote a tag in OUR tier, and there is no
+        // other spelling available to them" apart from "the author wrote this type
+        // in JSON, where the advice applies". Symbol-keyed, so it is invisible to
+        // JSON, to the DOM, and to anything an authored document could forge — see
+        // provenance.ts. Values reached through a braced attribute are NOT marked:
+        // that JSON was written by hand, and the JSON surface's advice does apply.
+        const node = markHtmlTierNode({ type: tag, ...props });
         if (children && children.length)
             node.children = children;
         return node;
@@ -178,10 +187,31 @@ class Parser {
                 continue;
             }
             // text
+            //
+            // HTML collapses a whitespace run to ONE space; it does not delete it. A
+            // bare `.trim()` here deleted the space that separates a text run from an
+            // adjacent sibling element, so `A <strong>x</strong> page` compiled to
+            // `A`/`page` and rendered as `Axpage` (objectui#5661). The rule: collapse
+            // the run, then keep a single leading space only when a sibling precedes
+            // the run, and a single trailing space only when a sibling element
+            // follows it. At the parent's own start/end the edge space is still
+            // dropped, so `<p>  hi  </p>` stays `hi`. A whitespace-only run survives
+            // as one space only when it sits BETWEEN siblings — that is the bounded
+            // over-generosity of this rule inside block containers like `<ul>`,
+            // pinned in the tests.
             const text = this.readTextRun();
-            const trimmed = text.replace(/\s+/g, ' ').trim();
-            if (trimmed)
-                children.push(trimmed);
+            const collapsed = text.replace(/\s+/g, ' ');
+            const core = collapsed.trim();
+            const afterSibling = children.length > 0;
+            const beforeElement = this.peek() === '<' && !this.src.startsWith('</', this.pos);
+            if (core) {
+                const lead = afterSibling && collapsed.startsWith(' ') ? ' ' : '';
+                const trail = beforeElement && collapsed.endsWith(' ') ? ' ' : '';
+                children.push(`${lead}${core}${trail}`);
+            }
+            else if (collapsed && afterSibling && beforeElement) {
+                children.push(' ');
+            }
         }
         return children;
     }

package/dist/provenance.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 first-class,
+ * permanently-supported tag in the html tier — the plain box element is exactly
+ * that. 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,74 @@
+/**
+ * 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 first-class,
+ * permanently-supported tag in the html tier — the plain box element is exactly
+ * that. 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,7 +39,20 @@ 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[];
     required?: boolean;
     /** allowed values for `enum` inputs */
     enum?: Array<string | {

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.js

@@ -6,6 +6,8 @@
  * and binding sites the SERVER must resolve against object schema (we cannot
  * resolve objects/fields here — that check is framework-side by design).
  */
+import { inputTypeArms } from './input-type.js';
+import { checkDashboardWidgetOptions } from './dashboard-widget-options.js';
 /** Base props every node may carry (mirrors BaseSchema) — never "unknown prop". */
 const BASE_PROPS = new Set([
     'type',
@@ -82,6 +84,13 @@ export function validateTree(tree, manifest) {
                     tag: node.type,
                 });
             }
+            // Dashboard widgets: an `options` key riding the spec's `.passthrough()`
+            // that no renderer consumes is legal, silent and inert — warn, naming
+            // the consumed set (objectui#5709 ruling; census + scope in
+            // `./dashboard-widget-options.ts`). Like `not-a-container`, this runs
+            // only for a component the manifest knows: an unresolved tag already
+            // drew `unknown-component`, and deep diagnostics on it would be noise.
+            diagnostics.push(...checkDashboardWidgetOptions(node));
         }
         if (node.children)
             node.children.forEach(visit);
@@ -90,42 +99,98 @@ export function validateTree(tree, manifest) {
         visit(tree);
     return { diagnostics, requires: [...requires], bindings };
 }
-function checkType(tag, input, value) {
-    const mismatch = (expected) => ({
-        severity: 'warning',
-        code: 'type-mismatch',
-        message: `<${tag}> prop "${input.name}" expected ${expected}`,
-        tag,
-    });
-    switch (input.type) {
+/** The values an `enum` arm admits, flattened from either declaration form. */
+const enumValues = (input) => (input.enum ?? []).map((e) => (typeof e === 'object' ? e.value : e));
+/**
+ * Does ONE coarse arm accept this value?
+ *
+ * An arm outside the vocabulary — and `'slot'`, which describes a child
+ * position rather than a value — accepts everything, preserving the old
+ * `default: return null` branch: those inputs never drew a diagnostic and must
+ * not start now.
+ */
+function armAccepts(arm, input, value) {
+    switch (arm) {
         case 'number':
-            return typeof value === 'number' ? null : mismatch('a number');
+            return typeof value === 'number';
         case 'boolean':
-            return typeof value === 'boolean' ? null : mismatch('a boolean');
+            return typeof value === 'boolean';
         case 'string':
         case 'color':
         case 'date':
         case 'code':
         case 'file':
-            return typeof value === 'string' ? null : mismatch('a string');
+            return typeof value === 'string';
         case 'array':
-            return Array.isArray(value) ? null : mismatch('an array');
+            return Array.isArray(value);
         case 'object':
-            return typeof value === 'object' && value !== null && !Array.isArray(value)
-                ? null
-                : mismatch('an object');
-        case 'enum': {
-            const allowed = (input.enum ?? []).map((e) => (typeof e === 'object' ? e.value : e));
-            return allowed.includes(value)
-                ? null
-                : {
-                    severity: 'error',
-                    code: 'invalid-enum',
-                    message: `<${tag}> prop "${input.name}"=${JSON.stringify(value)} is not one of ${JSON.stringify(allowed)}`,
-                    tag,
-                };
-        }
+            return typeof value === 'object' && value !== null && !Array.isArray(value);
+        case 'enum':
+            return enumValues(input).includes(value);
         default:
-            return null;
+            return true;
     }
 }
+/** How one arm is named in a diagnostic message. */
+function armExpectation(arm, input) {
+    switch (arm) {
+        case 'number':
+            return 'a number';
+        case 'boolean':
+            return 'a boolean';
+        case 'array':
+            return 'an array';
+        case 'object':
+            return 'an object';
+        case 'enum':
+            return `one of ${JSON.stringify(enumValues(input))}`;
+        default:
+            return 'a string';
+    }
+}
+/**
+ * Coarse type check, over the arms an input declares (objectui#3832).
+ *
+ * ANY arm accepting the value clears the prop — that is what lets a key whose
+ * contract is a union (`string | number`, or a string plus an inline
+ * translation map) be declared honestly instead of picking one arm and having
+ * this function report the other arm's legal values.
+ *
+ * When NO arm accepts it the prop is still reported; a union widens what counts
+ * as legal, it does not turn the check off. Two properties of the reporting are
+ * deliberate:
+ *
+ *  - A single-arm input produces the byte-identical diagnostic it always did,
+ *    `invalid-enum` included. This change adds a form; it does not restate the
+ *    old one.
+ *  - A multi-arm input produces ONE diagnostic naming every arm, at the
+ *    STRICTEST arm's severity — `error` when an `enum` arm is present, because
+ *    an enum's closed list is the one fact this layer can be certain about, and
+ *    a value outside it should not become dismissible merely because a second
+ *    arm was added next to it. Its code is `type-mismatch` (not `invalid-enum`)
+ *    since the reported fact is "fits none of the declared arms", and the
+ *    message carries the allowed values so the author still sees the list.
+ */
+function checkType(tag, input, value) {
+    const arms = inputTypeArms(input.type);
+    if (arms.length === 0)
+        return null;
+    if (arms.some((arm) => armAccepts(arm, input, value)))
+        return null;
+    if (arms.length === 1 && arms[0] === 'enum') {
+        return {
+            severity: 'error',
+            code: 'invalid-enum',
+            message: `<${tag}> prop "${input.name}"=${JSON.stringify(value)} is not one of ${JSON.stringify(enumValues(input))}`,
+            tag,
+        };
+    }
+    return {
+        severity: arms.includes('enum') ? 'error' : 'warning',
+        code: 'type-mismatch',
+        message: `<${tag}> prop "${input.name}" expected ${arms
+            .map((arm) => armExpectation(arm, input))
+            .join(' or ')}`,
+        tag,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/sdui-parser",
-  "version": "17.5.0",
+  "version": "17.6.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -25,9 +25,9 @@
     "dist"
   ],
   "devDependencies": {
-    "@objectstack/spec": "^17.0.0-rc.6",
-    "@object-ui/core": "17.5.0",
-    "@object-ui/react": "17.5.0"
+    "@objectstack/spec": "^17.0.0",
+    "@object-ui/core": "17.6.0",
+    "@object-ui/react": "17.6.0"
   },
   "scripts": {
     "build": "tsc",