The theme TYPE surface (`Theme`, `ThemeMode`, `ColorPalette`, …) still derives from `@objectstack/spec/ui`, which retired it — objectui cannot refresh its spec pin past 17.1.0 until this is re-homed or dropped, and the choice needs a ruling

[os-zhuang]

Found while executing #5710 (session session_01EuPCi56cnGyykygi3z9w4m, PR #5713). That card removed the six value-level re-exports (the Console-Pin-Gate leg ruled on objectstack-ai/objectstack#10856). This card records the type-level half, which that ruling did not name and which no gate currently reddens — it detonates on objectui's next @objectstack/spec dependency refresh instead.

Measurement (objectstack origin/main 95437e7 — no theme file remains under packages/spec/src/ui/)

Everything below compiles today only because objectui's installed pin is @objectstack/spec 17.1.0, which still publishes the retired names. Against any spec release cut after objectstack-ai/objectstack#10695:

• packages/types/src/theme.ts — export type { ColorPalette | Typography | BorderRadius | Shadow | ThemeMode | Theme } from '@objectstack/spec/ui' (6 statements) plus a local import type { Theme } feeding the ThemeDefinition alias: all TS2305.
• packages/providers/src/types.ts:2 — import type { ThemeModeSchema } feeding ThemePreference = (typeof ThemeModeSchema)['_zod']['input'] | 'system': TS2305.
• packages/providers/src/__tests__/spec-symbol-batch7.test.ts and theme-mode-spec-parity.test.tsx — value imports of ThemeModeSchema (test-only, outside every bundle graph): import errors. The batch7 file's own comment declares this a designed tripwire: "if the spec retires Theme, this stops compiling and the rename is up for re-triage".
• packages/types/src/index.ts:978 — export type * as UI from '@objectstack/spec/ui' re-exports whatever namespace the pin publishes (degrades silently rather than erroring, but the UI.Theme members consumers may rely on vanish).

Why this needs a ruling rather than a dev's judgment call

The maintainer retained objectui's theme SYSTEM (ThemeEngine, ThemeProvider, theme documents) while the spec dropped theme as a spec-owned contract entirely. ThemeEngine/ThemeProvider consume the Theme/ThemePreference types, so the type surface cannot simply be deleted. The two shapes:

• Localize: objectui assumes ownership of the theme document type (hand-write Theme + ThemeMode, authority = the last-published 17.1.0 pin the engine was actually built against). This is the type-level twin of the localization branch the objectstack#10856 ruling left untaken at the value level — it should not happen silently.
• Shrink: reduce the retained engine surface to what its real consumers use and drop the rest of the type re-exports. Needs the consumer census first.

Until one is ruled, any objectui spec-pin refresh past the retirement breaks @object-ui/types and @object-ui/providers builds. Related retirement-era guards that will also trip on that refresh and get cleaned then: the ThemeModeSchema deny-list row in spec-ui-schema-reexports.test.ts (its ratchet is designed for exactly that moment).

Refs: #5710 · PR #5713 · objectstack-ai/objectstack#10485 · objectstack-ai/objectstack#10695 · objectstack-ai/objectstack#10856

---

Generated by Claude Code

[os-zhuang]

Triage: 入决策箱(needs-user-decision + domain:ui)。类型面归属需要裁定,且本卡有开放下游依赖:spec 一旦发出 >17.1.0(ui#5668 的 Restart-when: 出口等的正是这次发版),pin 刷新立即撞上这颗雷 —— 宜早裁。

一句话问题:上游已把「主题」整个撤出契约,但本仓的类型层还从上游拿主题类型;下一次升级依赖版本,@object-ui/types 和 @object-ui/providers 直接编译失败。要裁的是:本仓自己接管主题类型(localize),还是把保留的主题引擎面缩小到真实用量(shrink)。

选项(客户可感知代价):

• A — localize:objectui 手写 Theme/ThemeMode 等(以 17.1.0 发布内容为蓝本),ThemeEngine/ThemeProvider 照常。代价:本仓永久拥有主题文档类型的维护义务;换来 pin 刷新解锁。
• B — shrink:先做消费者普查,把保留面缩到真实读点,删掉其余类型转出口。代价:普查工作量前置,pin 刷新继续被卡;可能砍掉外部应用在用的名字。

业务直译:A = 供应商停产零件后,把图纸买断自己造;B = 先盘点哪些机器还用这个零件,再决定造多少。

四轴:业务需求——pin 刷新被卡是现实且带引信的拉动(spec 发版是人工动作,随时可能发生);长远合理——维护者已裁定保留 objectui 主题系统,类型应跟着系统走:系统在哪,类型的家就在哪,不留跨包悬挂;防 AI 错——export type * as UI 那条在升级日是静默降级而非编译错,A 消灭静默半边;阶段聚焦——A 不是能力扩张,是「保留主题系统」既有承诺的完成件。

推荐 A,回退 B。回一个字母即可;「A,但顺手缩」= A 落地时把零读点类型不迁、直接删。

裁后执行:A ⇒ ui 席派发:手写类型(蓝本 = 17.1.0 已发布形状)、替换 6 条 re-export、清 spec-ui-schema-reexports.test.ts 的 deny-list ratchet 行与 batch7 tripwire,消费者普查作为 PR 内验证件;B ⇒ 先派普查卡,结果回本卡再裁二轮。

[facets-block]

• 业务需求:指向 A —— pin 刷新被卡且引信在别人手里(spec 随时发版)
• 长远合理:指向 A —— 类型跟着被保留的系统走,不留跨包悬挂
• 防 AI 错:指向 A —— 消灭 export type * as UI 升级日静默降级的半边
• 阶段聚焦:指向 A —— 既有承诺的完成件,非能力扩张
  推荐:A(objectui 接管主题类型,蓝本 17.1.0)· 置信缺口:消费者普查未做,外部应用是否 import 这些类型名无读数

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling recorded (2026-08-23, live PM chat, verbatim: 「其他同意你的意见」— adopting recommendation A): localize — objectui assumes ownership of the theme document types. Hand-write Theme / ThemeMode / ColorPalette / Typography / BorderRadius / Shadow with the last-published @objectstack/spec 17.1.0 shapes as the authority (the pin the engine was actually built against); replace the six type re-exports in packages/types/src/theme.ts and the ThemeModeSchema-derived ThemePreference in packages/providers; clean the retirement-era tripwires in the same PR (batch7 deny-list row in spec-ui-schema-reexports.test.ts, the designed-to-trip parity tests). The "A,但顺手缩" rider applies: a type with ZERO in-repo readers is not migrated — deleted, with the zero-reader grep in the PR body. export type * as UI from '@objectstack/spec/ui' at types/src/index.ts:978 must stop silently narrowing: re-point or replace it explicitly.

State: needs-user-decision → pm:queue, domain:ui (same stroke). This unblocks the post-release spec-pin refresh chain (#5668's Restart-when: exit; #5601 / #4935 ride the same bump) — dispatch with priority once claimed.

---

Generated by Claude Code