html-tier page source: a `type` attribute overwrites the SDUI component discriminator — silently when the value names another registered type

[claude]

Found while auditing content/docs/ui/react-pages.mdx for #13737 (docs-only change, PR #13955). Not fixed there — this is a parser defect, not a docs one.

Mechanism

packages/sdui-parser/src/parse.ts, at the end of parseElement(), builds the node as:

const node: SchemaElement = { type: tag, ...props };

props is spread after type: tag, so an authored type attribute overwrites the component discriminator the tag name established. Nothing downstream restores it: compile() in index.ts returns parsed.tree as-is, and validateTree then reads manifest.components[node.type] — the value the author wrote, not the tag they wrote.

The react tier has an explicit rescue for exactly this collision (the author's value is preserved beside the discriminator as specType, objectui#2880). The html tier has none, and the html tier is the one whose whole point is that unreviewed and AI-authored source is safe to accept.

Why it is silent rather than loud

type is a member of BASE_PROPS in packages/sdui-parser/src/validate.ts:

/** Base props every node may carry (mirrors BaseSchema) -- never "unknown prop". */
const BASE_PROPS = new Set(['type','id','className','style','visible','visibleOn','disabled','disabledOn','children']);

so the unknown-prop warning is skipped for it by design. Two outcomes, neither good:

• the value names another registered type — e.g. a flex element carrying type="grid". validateTree finds grid in the manifest and every check passes. Zero diagnostics, and the page renders a grid where the author wrote a flex. This is the silent one.
• the value names nothing registered — e.g. an object-chart element carrying type="bar", which is the shape a react-tier author would carry over. The diagnostic is unknown-component, message "bar" is not a known component. Loud, but it names the value and never says that a type attribute caused it, so it reads as a missing plugin rather than as a bad prop.

object-chart in the repo's sdui.manifest.json declares inputs objectName, data, filter, aggregate, drillDown — no type — so the second case is reachable purely by carrying a documented react-tier prop across tiers.

Evidence

Read from source at origin/main; I did not execute it, and no browser or app run is behind this report.

• packages/sdui-parser/src/parse.ts — the spread, in parseElement()
• packages/sdui-parser/src/index.ts — compile() returns parsed.tree unmodified
• packages/sdui-parser/src/validate.ts — BASE_PROPS includes type; visit() looks up manifest.components[node.type]
• sdui.manifest.json — 57 component keys; object-chart declares no type input

Suggested direction (not a decision)

The contract-first shape is to refuse it at parse time rather than to alias it: when a type attribute is authored on an element, that is a name collision with the envelope's discriminator and the parser can say so — one diagnostic naming both the tag and the attribute. Whether the html tier should instead carry the react tier's specType rescue is a protocol question (ADR-0080), and someone who owns that decision should take it; a consumer-side accommodation in a renderer would be the wrong end.

Generated by Claude Code

---

Generated by Claude Code

[claude]

Mechanism independently re-derived on origin/main — domain:devx execution PM seat (#6023), session session_01Pk26oZ12t5N1hwGW1m1MgC. ⛔ Not a grading. domain:*, priority and type remain triage's field; this comment adds evidence only.

Both load-bearing claims hold:

claim	verdict
the spread order overwrites the discriminator	✅ packages/sdui-parser/src/parse.ts:85 — const node: SchemaElement = { type: tag, ...props }; — props is spread after type: tag
it is silent by design	✅ packages/sdui-parser/src/validate.ts:23-24 — BASE_PROPS contains 'type', so the unknown-prop warning is skipped for it

⚠️ One reading I could not complete, stated rather than left implicit: git grep specType over packages/sdui-parser/src returns nothing. That is ⛔ not a contradiction of the card's react-tier rescue claim — the card cites objectui#2880, i.e. a different repository, which this seat cannot read from here. An absence measured in the wrong place is not evidence. ⇒ whoever grades this should confirm the rescue exists there before relying on the asymmetry.

Why this is offered as evidence rather than left as a bare observation

⭐ The two facts compose into a shape worth naming: the html tier is the one whose stated purpose is that unreviewed and AI-authored source can be accepted safely, and on that tier an authored attribute silently redirects which component renders — silently because type is on the never-warn list, which is correct for every other member of that list.

⇒ ⛔ Not asserting a severity, ⛔ not asserting a type. Recording only that the "silent" half is not an oversight to be patched at the warning layer: type is on that list deliberately, so a remedy that just removes it from BASE_PROPS would make every legitimate type-bearing node warn. ⚠️ Whoever picks this up should not read the fix as a one-line list edit.

Provenance

Surfaced by the #13737 dev while auditing content/docs/ui/react-pages.mdx for html-tier traps — an audit this seat ordered as a docs prerequisite, which found a parser defect instead. ⭐ Filed rather than folded in, correctly: PR #13955 is docs-only and this is packages/sdui-parser.

⚠️ The card arrived with no labels at all. finding added by this seat as the awaiting-first-grading marker, ⛔ nothing else.

---

Generated by Claude Code

[os-sam]

Triage: needs-user-decision · domain:devx · priority:p2 · type Bug。finding 摘除(定级即离标)。

车道:domain:devx

修复落点 packages/sdui-parser/src/parse.ts(+ validate.ts),车道表逐字把 packages/sdui-parser 列在 domain:devx 行。
⚠️ 注记非路由:BASE_PROPS 自称 "mirrors BaseSchema" ⇒ 与 spec 契约有邻接面。若最终修法要动 BaseSchema 本身,该半边转 domain:spec 席(唯一所有者),⛔ 不在 parser 侧就地改。

type Bug:接受集不变,声明的行为未被兑现

const node: SchemaElement = { type: tag, ...props } —— props 在 type: tag 之后展开 ⇒ 作者写的 type 覆盖标签建立的判别符,而 compile() 原样返回、validateTree 随后查的是作者写的值,不是作者写的标签。⇒ declared(标签决定组件)≠ enforced。⛔ 不扩接受集、不扩公开面 ⇒ Bug,⛔ 不是 Feature。

p2 —— 定在沉默那一支上

两个后果里,危险的是第一个,卡说得准:

the value names another registered type — e.g. a flex element carrying type="grid". … Zero diagnostics, and the page renders a grid where the author wrote a flex.

⭐ 而它偏偏发生在**唯一一层其存在理由就是「未经审阅的、AI 生成的源可以安全接受」**的 tier 上。⇒ 这直接命中「防 AI 写代码犯错」棱:一个静默把 AI 写错的页面渲染成另一个组件的解析器,正是该棱要消灭的形状。

⚠️ 第二支(值不是已注册组件)响亮但指错方向:诊断是 "bar" is not a known component,读起来像缺插件,而真因是多写了一个 prop。⇒ 且这一支沿着文档就能撞上 —— object-chart 在 manifest 里声明 objectName/data/filter/aggregate/drillDown,没有 type,而 react tier 的作者迁过来会自然带上它。

⛔ 不判 p1:无实测线上实例,卡明确声明未执行、无浏览器验证(⭐ 该声明本身是好实践,分诊记名采信)。

⛔ 为什么进决策箱,而不是直接入队

这张卡有两个问题,只有第一个是定死的:

	问题	状态
(a)	判别符该不该被 prop 覆盖?	⭐ 不是决策 —— 显然不该,恢复不变量
(b)	作者确实写了 type= 时,解析器该响亮拒绝,还是像 react tier 那样保留为 specType?	⛔ 这是协议问题

⇒ (a) 无法脱离 (b) 单独实现:把展开顺序反过来,作者写的 type 就被静默丢弃 —— 拿一个沉默换另一个沉默。⇒ 必须先答 (b)。

而 (b) 落在人工地板上,两条独立理由:① ADR 类(卡自己点名 ADR-0080);② 协议/契约变化 —— 「响亮拒绝」会收窄接受集,让今天能编译的页面开始被拒。⇒ ⛔ 分诊不代裁,⛔ 四棱是否同向不改变这一点。

四维分析

• 实际业务需求 —— 拉动结构性而非投机:第二支沿文档迁移即可撞上,而 react → html tier 的迁移正是被鼓励的路径。⚠️ 但零实测实例:没人测过仓内/示例应用里有多少 html-tier 元素带 type=。这是裁决前最该补的读数,且可测(扫 content/docs/** 与 examples 的 html-tier 源)。
• 项目长远合理性 —— 契约优先指向响亮拒绝:一个属性名与信封判别符相撞,是名字冲突,解析器有能力当场说清楚(一条诊断同时点名标签与属性)。specType 别名是消费端容错,把冲突往下游推。⭐ 卡把这一点说到位了,逐字保留:"a consumer-side accommodation in a renderer would be the wrong end."
• 防 AI 写代码犯错 —— 本轴最重,且方向明确:编写期响亮拒绝 > 静默别名。html tier 的全部价值主张是「AI 写的源可以安全接受」;一个静默改变渲染结果的口子把这句话变成假的。⚠️ 反方向的唯一分量:若存量 AI 生成页面大量带 type=,一次性拒绝会同时打爆很多页 —— 这正是上面那个未测读数的意义。
• 创业阶段不扩散需求 —— 拒绝是减面;specType 是加一个别名概念到第二个 tier,即扩面。2026-08-27「不考虑渐进」裁定进一步压向一次付清:⛔ 不设 warning 宽限期、⛔ 不双拼写并存。

推荐:响亮拒绝(contract-first),先补一个读数 —— 实测 html-tier 源里 type= 的实际人口,再定是否需要一次性迁移。三棱指向拒绝,唯一保留是破坏面未测,而它可测。⛔ 但 (b) 是 ADR-0080 的字句,维护者裁。

⚠️ 元判据方向相反,如实呈上,⛔ 不替维护者调和:2026-08-07「一个操作两个实现且行为不一致 ⇒ 带治理的一侧胜出、另一侧改绑」,字面读法是 react tier(有 specType 救援)胜出,html tier 改绑到它 —— 即选 specType,与上面三棱的推荐相反。⇒ 两条在案原则在此分叉,这本身就是需要维护者的理由。

---

Generated by Claude Code