@object-ui/plugin-chatbot 17.2.0 → 17.5.0

package/CHANGELOG.md

@@ -1,5 +1,324 @@
 # @object-ui/plugin-chatbot
 
+## 17.5.0
+
+### Minor Changes
+
+- 3256b14: `@object-ui/plugin-chatbot`'s `ChatMessage` is now one type instead of two
+
+  The barrel exported two different `ChatMessage` types: a minimal one it declared itself (`id` / `role` / `content` / `timestamp` / `avatar` / `avatarFallback`) and the shape `<ChatbotEnhanced>` actually renders, re-exported under the alias `ChatbotEnhancedMessage`. The natural name resolved to the narrow one, so an importer reaching for `ChatMessage` silently got the wrong contract — and the compiler could not object, because both shapes existed on purpose and every construction site spreads the extra keys conditionally, which defeats excess-property checking. That is how app-shell's `AiChatPage` ended up unable to read `toolInvocations` off its own function's return value (objectui#4040; re-pointed in PR #4379, but the collision itself was left standing). objectui#4383.
+
+  **Breaking semantics** (declared `minor` per AGENTS.md §版本号策略 — objectui never declares `major` outside an `@objectstack` major sync): `ChatMessage` exported from `@object-ui/plugin-chatbot` now denotes the enhanced shape. In practice this is a widening rather than a removal — every field of the retired shape survives with the same type, and the enhanced shape adds only optional keys (`streaming`, `toolInvocations`, `reasoning`, `sources`, `traceId`, `buildProgress`, `blueprintProgress`, `charts`), so anything that was a valid `ChatMessage` still is, and `<Chatbot messages={…} />` keeps accepting the same values. Code that relied on the name meaning _exactly_ the six-key shape (exhaustive `keyof` maps, `Equal`-style assertions) is the case that changes.
+
+  `ChatbotEnhancedMessage` is kept as a `@deprecated` alias of the same type, so importers that spelled the disambiguating name keep compiling; new code should import `ChatMessage`. Pinned at compile time by `packages/plugin-chatbot/src/__tests__/chat-message-contract.test.ts`.
+
+- eec2e4f: `useObjectChat` declares the message shape it actually hands back
+
+  The hook typed `messages` — and the `onSend(content, messages)` callback fed from it — as `@object-ui/types`' authoring `ChatMessage`. That was true in local mode only. In API mode the values came out of the runtime mapper and were asserted into place with `as OuiChatMessage[]`, and the authoring contract declares none of what they carry: `buildProgress`, `blueprintProgress`, `charts`, and `pendingActionId` / `draftReview` / `proposedPlan` / `proposedChanges` / `builderHandoff` on every tool invocation. Those keys are the HITL approval card, the "Review N changes" affordance, the proposed-plan card, the build panel and the inline charts. They survived only because nothing on the path ever rebuilt a message; anyone writing the obvious thing — reconstruct a message field-by-field from its declared type — deleted all of them, with the compiler agreeing, because the declared type genuinely did not have them.
+
+  The declaration is now the truth, published as `ObjectChatMessage`. The survey behind it found the honest type to be neither of the two `ChatMessage` types on either side, because neither is true of both modes: it stays **wide** where local mode is wide (an authored `'tool'` role and the legacy `'partial-call'` / `'call'` / `'result'` tool states reach this surface unchanged and are folded only at the render seam), **narrow** where both modes are narrow (`timestamp` is `string`, never `Date` — API mode never produces one and local mode absorbs it before emitting), and adds the render-only keys API mode really carries. The `as OuiChatMessage[]` assertion is deleted rather than moved: the mapper's output satisfies the declared type, so the compiler checks that assignment instead of being told to stop looking.
+
+  Nothing about the values changed, and nothing correct breaks. `ObjectChatMessage` is a **subtype** of the authoring `ChatMessage` it replaces, so every consumer that accepted the old declaration still accepts these values — including a host `onSend` callback that types its parameter as `ChatMessage[]`, which keeps type-checking by contravariance. Naming `ObjectChatMessage` is what lets a host _read_ the keys above. The one observable narrowing is deliberate: code that branched on `timestamp instanceof Date` was handling a value this hook cannot emit, and now says so at compile time.
+
+  The seam below it (`chatMessageAdapter.ts`, from objectui#4399) is still necessary and unchanged in behaviour — `'tool'` and the legacy tool states still have to be narrowed for the renderers. What changed is that its pass-through is no longer an act of faith: its input type (`SeamChatMessage`, also exported, alongside `SeamToolInvocation`) names the render-only keys, so the spread preserves them as declared properties the compiler can see, and the pass-through tests type their API-mode fixture directly instead of casting it past the compiler. A cast returning to the hook is now caught by a test rather than by a future outage.
+
+  App-shell carries a comment-only correction on the same family: `AiChatPage` still described `@object-ui/plugin-chatbot` as exporting a second, minimal legacy `ChatMessage` alongside the enhanced one. That collision was retired in objectui#4383 — the barrel publishes one contract and `ChatbotEnhancedMessage` is a deprecated alias of it — so the paragraph was sending readers to look for a hazard that no longer exists.
+
+### Patch Changes
+
+- dde7283: `chatbot` and `chatbot-enhanced` now pass only whitelisted DOM props to their host element (objectui#4431)
+
+  Both registrations destructured `schema` and `className` and forwarded everything else. `SchemaRenderer` hands a registered component the authored node's own keys, the contents of its `props` container, the ARIA it resolved and the host's trailing props — so all of it became attributes on the chat root `div`, because React passes unknown lowercase attributes through in silence and stringifies object values. Measured through the real SDUI path with a data-source adapter attached: **14 non-DOM attributes on each widget**, including `datasource="[object Object]"` (the injected adapter, which only appears on a deployment that really loads data) and a camelCase `arialabel` sitting next to the resolved `aria-label`, so the element carried each ARIA value twice under two spellings — one of them meaningless to assistive technology.
+
+  Both are now consume-or-whitelist: configuration is read off `schema` as before, the evaluated `disabled` verdict is consumed by name, and only `toDomProps`' output reaches the element. The resolved `aria-label` / `aria-describedby`, `role`, `id`, `tabIndex` and the `data-*` family still arrive — dropping them would have been an accessibility regression dressed as a leak fix, so the pin asserts the delivered set exactly, not just the absent one. `chatbot-floating` is untouched: its content mounts through a portal and its root never spread.
+
+  `@object-ui/core` gains the shared executor this migration needs (`utils/dom-props.ts`): `toDomProps` for the SDUI widget contract, plus `pickDomProps` — the mechanism — for a package whose own contract declares a different key set. That is the objectui#4409 dependency direction: plugin packages declare `@object-ui/core` and must not grow a dependency on `@object-ui/fields` to reach a whitelist.
+
+  `@object-ui/fields` keeps its own key list and its compile-time bindings, and now executes them through core's mechanism. Its behaviour is unchanged and its exported `DomProps<P>` is the same structural type. The two lists differ for measured reasons and no longer can drift silently: `name` and `disabled` are legal only on form controls, which is what every field widget renders and what `FieldWidgetComponentProps` declares, while `role` is resolved by `SchemaRenderer` for every SDUI node and is not part of the field contract. A new assertion binds every shared key in both directions, with `role` named as the single deliberate exception.
+
+- 37bbc42: Replace the three `messages as any` casts at the `@object-ui/types` ↔
+  `@object-ui/plugin-chatbot` `ChatMessage` boundary with one explicit typed
+  adapter (`toRuntimeMessages` / `authoredToRuntimeMessage`, now exported).
+
+  The authoring contract (`ChatbotSchema['messages']`) and the runtime contract
+  `<ChatbotEnhanced>` renders are both deliberate and deliberately different; the
+  casts erased ALL of that drift rather than the intentional parts, so a future
+  vocabulary move would have surfaced as rendering behaviour instead of a type
+  error. Each narrowing is now named, documented and tested: an authored
+  `role: 'tool'` message is an assistant message (unchanged rendering — the
+  implicit fallthrough is now the recorded decision), a `Date` timestamp becomes
+  its ISO string (one expression, consumed by both the seam and the hook's
+  `normalizeMessages`), and the legacy tool-invocation states
+  `'partial-call'`/`'call'`/`'result'` map to their AI SDK v6 equivalents as the
+  authoring type's own documentation declares — previously they reached the tool
+  chip unrecognised and rendered a status badge with no label.
+
+- Updated dependencies [0e67b53]
+- Updated dependencies [ceccdcf]
+- Updated dependencies [d6e5124]
+- Updated dependencies [debad27]
+- Updated dependencies [dc2aa3e]
+- Updated dependencies [ee66e2e]
+- Updated dependencies [ee26e65]
+- Updated dependencies [5900ac5]
+- Updated dependencies [932cbcd]
+- Updated dependencies [734d186]
+- Updated dependencies [f650253]
+- Updated dependencies [3d9769a]
+- Updated dependencies [8f85f8b]
+- Updated dependencies [d0c3b26]
+- Updated dependencies [3fc2971]
+- Updated dependencies [aca27fa]
+- Updated dependencies [dde7283]
+- Updated dependencies [f7c6430]
+- Updated dependencies [4dadf0d]
+- Updated dependencies [ae10a01]
+- Updated dependencies [92876f0]
+- Updated dependencies [f279deb]
+- Updated dependencies [4b70d28]
+- Updated dependencies [eb7f586]
+- Updated dependencies [e901131]
+- Updated dependencies [d9d3463]
+- Updated dependencies [2a40f69]
+- Updated dependencies [bec3e14]
+- Updated dependencies [613b167]
+- Updated dependencies [b4d3c22]
+- Updated dependencies [1f9b905]
+- Updated dependencies [cb13400]
+- Updated dependencies [828549a]
+- Updated dependencies [e1ade8f]
+- Updated dependencies [bc64bfe]
+- Updated dependencies [abb0f81]
+- Updated dependencies [38ab505]
+- Updated dependencies [3e19fe7]
+- Updated dependencies [bb58d1d]
+- Updated dependencies [5cc847c]
+- Updated dependencies [fa21254]
+- Updated dependencies [33c32bf]
+- Updated dependencies [66fb4fa]
+- Updated dependencies [b953a97]
+- Updated dependencies [d7f3e30]
+- Updated dependencies [6d641c9]
+- Updated dependencies [7e4f0e5]
+- Updated dependencies [a84385b]
+- Updated dependencies [45e1949]
+- Updated dependencies [92250d6]
+- Updated dependencies [c1d939f]
+- Updated dependencies [58bebf6]
+- Updated dependencies [405e808]
+- Updated dependencies [49ae9f4]
+- Updated dependencies [a3ae404]
+- Updated dependencies [bfdf3d4]
+- Updated dependencies [bb68488]
+- Updated dependencies [c0f9a4b]
+- Updated dependencies [b1e42d0]
+- Updated dependencies [2459a3e]
+- Updated dependencies [ac853ce]
+- Updated dependencies [fa51109]
+- Updated dependencies [d6aa172]
+- Updated dependencies [fe52a04]
+- Updated dependencies [d46f9b8]
+- Updated dependencies [3f5f87c]
+- Updated dependencies [2fea4d2]
+- Updated dependencies [f5e1143]
+- Updated dependencies [7f1cb33]
+- Updated dependencies [f148a64]
+- Updated dependencies [bb68488]
+- Updated dependencies [2e3b0c0]
+- Updated dependencies [9461dd3]
+- Updated dependencies [78fa331]
+- Updated dependencies [47f551b]
+- Updated dependencies [31ab1ac]
+- Updated dependencies [0082db8]
+- Updated dependencies [ab04728]
+- Updated dependencies [5bf09fd]
+- Updated dependencies [06915b0]
+- Updated dependencies [ff84b05]
+  - @object-ui/i18n@17.5.0
+  - @object-ui/react@17.5.0
+  - @object-ui/components@17.5.0
+  - @object-ui/core@17.5.0
+  - @object-ui/types@17.5.0
+
+## 17.4.0
+
+### Minor Changes
+
+- d9ce385: `ApproveOutcome` / `RejectOutcome` are now derived from `@objectstack/spec`
+  instead of hand-transcribed (objectui#3783). Same failure class #3220 cleared
+  from the same file for `PendingActionRow` / `PendingActionStatus` — but this pair
+  wore local names rather than spec names, so `check-spec-symbol-derivation.mjs`,
+  which fires on a spec export name being occupied, had no handle on it. A renamed
+  hand copy is invisible to a name-based guard by construction.
+
+  Both types now re-export the spec's decision responses
+  (`ApproveAiPendingActionResponse` / `RejectAiPendingActionResponse` from
+  `@objectstack/spec/api` — the same schemas `@objectstack/client`'s
+  `ai.pendingActions.approve()` / `.reject()` type their returns with). The public
+  export names do not change. The shapes do, in three ways:
+
+  - **`ApproveOutcome` no longer declares `id`.** The approve response has never
+    carried one — `id` is on the _reject_ response. This was the one drift that
+    was not dormant: `useHitlInChat`'s public `onDecided` callback promised
+    consumers `id: string` and handed them `undefined` at runtime, with nothing
+    in the compiler to say so. **If you read `outcome.id` after an approve, that
+    read was already `undefined` and now fails to compile** — take the id from
+    `ContinueContext.pendingActionId` or from the row you decided on.
+  - **`status` is closed.** `'executed' | 'failed' | string` and
+    `'rejected' | string` were both just `string`: a union with `string` absorbs
+    the literals, so neither annotation carried any information. They are now
+    `'executed' | 'failed'` and `'rejected'`.
+  - **The `[k: string]: unknown` index signature on `ApproveOutcome` is gone.** The
+    objectstack#4075 mechanism: with it, any structural comparison against the
+    spec answers "identical" however far the copy has drifted, so a parity test
+    bolted onto the old type would have been green from its first day.
+
+  **Breaking at the type level for importers of `@object-ui/plugin-chatbot`** —
+  narrowing a published type is a break even when the old type was lying, which is
+  why it is spelled out here. Shipped as `minor` per AGENTS.md §版本号策略: the
+  family's `major` tracks `@objectstack`'s, and objectui's own breaking changes go
+  out as `minor` with the break named in the changeset.
+
+  Runtime behaviour is unchanged — including the hook's decision handling for a
+  status outside the spec vocabulary, and the locally synthesized failure envelope
+  on a non-2xx, both now pinned by tests. The consumer-side tolerances that remain
+  in `useHitlInChat` are recorded in objectui#3790 for a maintainer decision.
+
+### Patch Changes
+
+- 2a54e86: `parseAiQuotaError` now reads the AI quota refusal code from all three shapes the
+  cloud 429 producers use, instead of only the flat `error`-holds-the-code dialect.
+
+  The two live producers fill the same `error` key in opposite ways — the token
+  guardrail puts the **code** there, `service-ai` puts the **message** there and the
+  code in a `code` sibling — while ADR-0112 declares a third shape both are
+  converging on: `{ success: false, error: { code, message } }`. The consumer had to
+  learn the declared shape **first**, or the producers' convergence would silently
+  turn every quota refusal back into a generic "Response failed" banner (the same
+  consumer-first sequencing as objectui#2992).
+
+  - Code lookup order is a total order — declared envelope, then the flat guardrail
+    code, then the `code` sibling — so a transitional producer that double-emits the
+    new envelope alongside the legacy top-level keys has one defined outcome.
+  - Only the code's **location** widens. The recognized code set is unchanged, and
+    any unrecognized shape still degrades to today's behavior (`null`), so no
+    non-quota error is newly captured by the quota CTA.
+  - Companion fields (`upgrade`, `topUp`, `messageEn`) keep their established
+    top-level read; their position inside the declared envelope is deliberately not
+    presumed, and is aligned once the producer PR fixes the real shape.
+
+- Updated dependencies [794c497]
+- Updated dependencies [993336f]
+- Updated dependencies [f0a625a]
+- Updated dependencies [b5980f4]
+- Updated dependencies [8aad9fd]
+- Updated dependencies [6719877]
+- Updated dependencies [56ff091]
+- Updated dependencies [7864f03]
+- Updated dependencies [0cbdca8]
+- Updated dependencies [d229dfa]
+- Updated dependencies [ecae400]
+- Updated dependencies [4bc6c23]
+- Updated dependencies [d3e738a]
+- Updated dependencies [c3b01a7]
+- Updated dependencies [f5f8744]
+- Updated dependencies [7ed3360]
+- Updated dependencies [69becd2]
+- Updated dependencies [5e52495]
+- Updated dependencies [0fa5e4d]
+- Updated dependencies [b750823]
+- Updated dependencies [5bfaabd]
+- Updated dependencies [e06810e]
+- Updated dependencies [ab3ad4f]
+- Updated dependencies [c2fd122]
+- Updated dependencies [ac2139c]
+- Updated dependencies [b14ab3a]
+- Updated dependencies [e24d767]
+- Updated dependencies [8c60819]
+- Updated dependencies [aca561a]
+- Updated dependencies [e64a52e]
+- Updated dependencies [844d17f]
+- Updated dependencies [48132f7]
+- Updated dependencies [4dcd52a]
+- Updated dependencies [42ae5c6]
+- Updated dependencies [0ef9dfd]
+- Updated dependencies [1d723e3]
+- Updated dependencies [0109f54]
+- Updated dependencies [7e5bb5d]
+- Updated dependencies [fbc23e0]
+- Updated dependencies [6d762da]
+- Updated dependencies [e6fdbdc]
+- Updated dependencies [54233b1]
+- Updated dependencies [f9faa7d]
+- Updated dependencies [97b63d7]
+- Updated dependencies [6bb454a]
+- Updated dependencies [523be48]
+- Updated dependencies [7e2b7e9]
+- Updated dependencies [33526fd]
+- Updated dependencies [32413ec]
+- Updated dependencies [c1e1e6b]
+  - @object-ui/components@17.4.0
+  - @object-ui/react@17.4.0
+  - @object-ui/core@17.4.0
+  - @object-ui/i18n@17.4.0
+  - @object-ui/types@17.4.0
+
+## 17.3.0
+
+### Patch Changes
+
+- Updated dependencies [18cd432]
+- Updated dependencies [532cf8b]
+- Updated dependencies [680080a]
+- Updated dependencies [a7651e6]
+- Updated dependencies [d915c47]
+- Updated dependencies [b71fc92]
+- Updated dependencies [65516ba]
+- Updated dependencies [94c5b7c]
+- Updated dependencies [ca0fa8f]
+- Updated dependencies [34595eb]
+- Updated dependencies [3889ffb]
+- Updated dependencies [5781fb1]
+- Updated dependencies [7e2406a]
+- Updated dependencies [9e9e9a9]
+- Updated dependencies [56409c2]
+- Updated dependencies [042e09d]
+- Updated dependencies [9cbcbf4]
+- Updated dependencies [85c4c9c]
+- Updated dependencies [fd54c3e]
+- Updated dependencies [4eeb932]
+- Updated dependencies [5c856ec]
+- Updated dependencies [23018cc]
+- Updated dependencies [53811d1]
+- Updated dependencies [68b6a28]
+- Updated dependencies [0554e88]
+- Updated dependencies [d915c47]
+- Updated dependencies [f44d872]
+- Updated dependencies [28b2e65]
+- Updated dependencies [509104a]
+- Updated dependencies [825bbe3]
+- Updated dependencies [6195841]
+- Updated dependencies [5dd0127]
+- Updated dependencies [06632e9]
+- Updated dependencies [a415684]
+- Updated dependencies [a4cff5b]
+- Updated dependencies [175bd79]
+- Updated dependencies [5af2852]
+- Updated dependencies [f833d3a]
+- Updated dependencies [a6ec93d]
+- Updated dependencies [2a9513d]
+- Updated dependencies [71be406]
+- Updated dependencies [d22ae31]
+- Updated dependencies [c7ed4c3]
+- Updated dependencies [2409e1d]
+- Updated dependencies [789fe3e]
+- Updated dependencies [8d8094a]
+  - @object-ui/core@17.3.0
+  - @object-ui/components@17.3.0
+  - @object-ui/types@17.3.0
+  - @object-ui/i18n@17.3.0
+  - @object-ui/react@17.3.0
+
 ## 17.2.0
 
 ### Minor Changes
@@ -944,6 +1263,7 @@ type:'chart', … }}/>` (decoupled — no hard dep on `plugin-charts`), giving t
 - 0335ec4: Polish the AI chat surface based on real-world dogfooding feedback.
 
   **`@object-ui/plugin-chatbot`** — new display helpers shared by `ChatbotEnhanced`:
+
   - `unwrapToolResult(value)` peels the MCP-style `{ type: 'text', value: '<json>' }`
     envelope that backend tools emit (`@objectstack/service-ai`'s data/metadata
     tools, in particular), and JSON-parses the inner payload. The result panel
@@ -964,6 +1284,7 @@ type:'chart', … }}/>` (decoupled — no hard dep on `plugin-charts`), giving t
   so wrappers can compose richer titles.
 
   **`@object-ui/app-shell`** — `AiChatPage`:
+
   - Removes the fake "Hello! I'm X" assistant welcome bubble so the empty-state
     suggestion chips can actually render.
   - Adds per-agent default suggestion sets (`data_chat`, `metadata_assistant`)
@@ -1416,6 +1737,7 @@ Assistant…  (try "系统里有多少个用户？")`).
 ### Patch Changes
 
 - 1b6dc64: fix: complete Tailwind v3→v4 migration cleanup
+
   - Rename deprecated `flex-shrink-0` → `shrink-0` and `flex-grow-N` →
     `grow-N` (Tailwind v4 dropped the long-form aliases). Affects
     data-table, fields/index, FileField, ChatbotEnhanced,
@@ -1476,6 +1798,7 @@ Assistant…  (try "系统里有多少个用户？")`).
   Library builds (vite lib mode) now externalize every non-relative import instead of bundling third-party CJS dependencies into the published dist. This avoids inlined `require("react")` / `require("react-dom")` calls that cause `Calling \`require\` for "react" in an environment that doesn't expose the \`require\` function` runtime errors when consumer apps re-bundle the published dist.
 
   Specifically fixes:
+
   - `@object-ui/plugin-dashboard` no longer inlines `react-grid-layout` (and its transitive `react-draggable` / `react-resizable` CJS bundles). `react-grid-layout` is now declared as a peer dependency so consumers install a single ESM-friendly copy.
   - `@object-ui/components`, `@object-ui/plugin-calendar`, `@object-ui/plugin-charts`, `@object-ui/plugin-designer` no longer inline `react-i18next` / `i18next` / `use-sync-external-store` CJS shims.
   - All plugin packages now use a unified `external: (id) => !/^[./]/.test(id) && !id.startsWith(__dirname)` rule, ensuring future additions of CJS deps are automatically externalized.

package/README.md

@@ -55,7 +55,7 @@ function App() {
 ### AI Streaming Mode (service-ai)
 
 When `api` is set in the schema, the chatbot connects to a backend SSE endpoint
-using `@ai-sdk/react` v3 (Vercel UI Message Stream protocol) for streaming,
+using `@ai-sdk/react` v4 (Vercel UI Message Stream protocol) for streaming,
 tool-calling, and production-grade chat:
 
 ```tsx
@@ -110,6 +110,30 @@ function MyChat() {
 }
 ```
 
+#### What `messages` actually contains
+
+`messages` — and the `onSend(content, messages)` callback fed from it — is
+typed `ObjectChatMessage[]`, exported from this package. It is deliberately
+neither of the two `ChatMessage` types nearby, because neither is true of both
+modes (objectui#4424):
+
+- **Not `@object-ui/types`' authoring `ChatMessage`.** In API mode the values
+  come from the runtime mapper and carry `buildProgress`, `blueprintProgress`,
+  `charts`, and `pendingActionId` / `draftReview` / `proposedPlan` /
+  `proposedChanges` / `builderHandoff` on each tool invocation — the approval
+  card, the "Review N changes" affordance, the plan card, the build panel and
+  the inline charts. The authoring contract declares none of them, so rebuilding
+  a message field-by-field from it deletes all of them, and the compiler agrees.
+- **Not this package's runtime `ChatMessage` either.** In local mode an authored
+  `'tool'` role and the legacy `'partial-call'` / `'call'` / `'result'` tool
+  states pass through untouched; they are folded only at the render seam
+  (`toRuntimeMessages`, `chatMessageAdapter.ts`).
+
+`ObjectChatMessage` is a subtype of the authoring `ChatMessage`, so anything
+already typed against that keeps compiling — naming `ObjectChatMessage` is what
+lets you *read* the keys above. `timestamp` is always a `string` here: both
+modes absorb an authored `Date` before emitting.
+
 ## Schema-Driven Usage
 
 ### Discovering Backend Agents
@@ -211,17 +235,6 @@ const aiSchema = {
 | Stop/Reload | Stop cancels timer | Stop interrupts stream |
 | Backend | None required | service-ai (IAIService) |
 
-<!-- release-metadata:v3.3.0 -->
-
-## Compatibility
-
-- **React:** 18.x or 19.x
-- **Node.js:** ≥ 18
-- **TypeScript:** ≥ 5.0 (strict mode)
-- **`@objectstack/spec`:** ^3.3.0
-- **`@objectstack/client`:** ^3.3.0
-- **Tailwind CSS:** ≥ 3.4 (for packages with UI)
-
 ## Links
 
 - 📚 [Documentation](https://www.objectui.org/docs/plugins/plugin-chatbot)
@@ -267,6 +280,62 @@ import { AIElements } from '@object-ui/plugin-chatbot';
 </AIElements.Conversation>;
 ```
 
+### The `ChatMessage` type
+
+`ChatMessage` is this package's one message contract — the shape
+`<ChatbotEnhanced>` renders and the mappers below produce. On top of the core
+`id` / `role` / `content` / `timestamp` / `avatar` / `avatarFallback` fields it
+carries the streaming and agent-process keys (`streaming`, `toolInvocations`,
+`reasoning`, `sources`, `traceId`, `buildProgress`, `blueprintProgress`,
+`charts`), all optional.
+
+```tsx
+import type { ChatMessage } from '@object-ui/plugin-chatbot';
+```
+
+> This barrel used to export **two** different `ChatMessage` types: a minimal
+> one declared here, plus the enhanced shape aliased as
+> `ChatbotEnhancedMessage`. Reaching for the natural name got you the narrow
+> contract with no compiler complaint (objectui#4383). The minimal shape is
+> retired; `ChatbotEnhancedMessage` is now a **deprecated alias of the same
+> type**, kept only so existing importers keep compiling.
+
+Note that `@object-ui/types` also exports a `ChatMessage`. That one is the
+**JSON/SDUI schema** type (`ChatbotSchema['messages']`, `role` includes
+`'tool'`, `timestamp` may be a `Date`) — the authoring contract, not the React
+runtime one. Import the schema type from `@object-ui/types` and the runtime
+type from this package.
+
+### Authoring → runtime: `toRuntimeMessages`
+
+The two contracts are both deliberate, so they drift — and the conversion
+between them is a real decision, not a formality. If you hold **authored**
+messages (`@object-ui/types`) and want to render them with the components in
+this package, convert them; do not cast:
+
+```tsx
+import type { ChatMessage as AuthoredChatMessage } from '@object-ui/types';
+import { ChatbotEnhanced, toRuntimeMessages } from '@object-ui/plugin-chatbot';
+
+function MyAuthoredChat({ messages }: { messages: AuthoredChatMessage[] }) {
+  return <ChatbotEnhanced messages={toRuntimeMessages(messages)} />;
+}
+```
+
+| key | authoring (`@object-ui/types`) | runtime (this package) | what the adapter decides |
+|---|---|---|---|
+| `role` | `'user' \| 'assistant' \| 'system' \| 'tool'` | `'user' \| 'assistant' \| 'system'` | a `'tool'` message **is an assistant message**: it renders as an assistant bubble with its content shown. `'system'` keeps its own role (`<Chatbot>` renders it as a centred pill). |
+| `timestamp` | `string \| Date` | `string` | a `Date` becomes its ISO 8601 string. The runtime renders the timestamp straight into a React child, where an object throws. |
+| `toolInvocations[].state` | AI SDK v6 states **+ legacy** `'partial-call' \| 'call' \| 'result'` | v6 states only | the legacy spellings map to `'input-streaming'` / `'input-available'` / `'output-available'` — the mapping the authoring type's own docs declare. |
+| everything else | — | — | passed through untouched, including keys the runtime contract does not declare. |
+
+The three registered SDUI renderers (`chatbot`, `chatbot-enhanced`,
+`chatbot-floating`) use this adapter; they used to use `messages as any`, which
+compiled away the intentional drift and any accidental drift with it
+(objectui#4399). `authoredToRuntimeMessage` is the single-message variant, and
+`toRuntimeRole` / `toRuntimeTimestamp` / `toRuntimeToolState` are the individual
+decisions if you need one on its own.
+
 ### Message mapping helpers
 
 If you wire `@ai-sdk/react`'s `useChat()` directly and want to render its

package/dist/chatMessageAdapter.d.ts

@@ -0,0 +1,134 @@
+import { ChatMessage as AuthoredChatMessage, ChatToolInvocation as AuthoredToolInvocation } from '@object-ui/types';
+import { ChatMessage as RuntimeChatMessage, ChatToolInvocation as RuntimeToolInvocation } from './ChatbotEnhanced';
+/**
+ * The render-only MESSAGE keys — declared by the runtime contract, never by the
+ * authoring one. Named here (rather than spelled out at each use) so that
+ * adding a render-only key to `ChatbotEnhanced.ChatMessage` and forgetting this
+ * list is a one-line fix in one place. objectui#4424.
+ */
+type RuntimeOnlyMessageKeys = Pick<RuntimeChatMessage, 'buildProgress' | 'blueprintProgress' | 'charts'>;
+/**
+ * The render-only TOOL-INVOCATION keys — the HITL approval id, the ADR-0033
+ * draft review, the proposed plan / changes cards and the ADR-0057 P4 builder
+ * handoff. `mapMessages.ts` lifts every one of them out of a tool result; the
+ * authoring contract declares none of them. objectui#4424.
+ */
+type RuntimeOnlyToolInvocationKeys = Pick<RuntimeToolInvocation, 'pendingActionId' | 'draftReview' | 'proposedPlan' | 'proposedChanges' | 'builderHandoff'>;
+/**
+ * One tool invocation as it actually crosses this seam: the authoring contract,
+ * plus the render-only extensions it may ALREADY be carrying when it arrives
+ * from API mode.
+ *
+ * `AuthoredToolInvocation` stays assignable to this (every added key is
+ * optional), so a host holding plain authored invocations is unaffected.
+ */
+export type SeamToolInvocation = AuthoredToolInvocation & Partial<RuntimeOnlyToolInvocationKeys>;
+/**
+ * One message as it actually crosses this seam — the seam's INPUT contract.
+ *
+ * The authoring shape (`role: 'tool'`, `timestamp: Date`, legacy tool states —
+ * all still narrowed below) widened by the render-only keys an API-mode value
+ * already carries. This is what lets the pass-through spread preserve those
+ * keys as declared properties rather than as invisible runtime baggage
+ * (objectui#4424); see "Pass-through" in the module doc.
+ *
+ * `AuthoredChatMessage` is assignable to it, and so is the hook's
+ * `ObjectChatMessage` — the two callers this seam serves.
+ */
+export type SeamChatMessage = Omit<AuthoredChatMessage, 'toolInvocations'> & {
+    toolInvocations?: SeamToolInvocation[];
+} & Partial<RuntimeOnlyMessageKeys>;
+/**
+ * `timestamp: string | Date` -> `string | undefined`.
+ *
+ * The authoring schema declares `z.union([z.string(), z.date()])`, and the
+ * runtime renders `{message.timestamp}` straight into a React child — a `Date`
+ * there is the classic "Objects are not valid as a React child" throw.
+ *
+ * This is the SINGLE expression of that absorption in the package: it was
+ * inlined in `useObjectChat`'s `normalizeMessages`, which now calls this
+ * function instead (objectui#4399). `normalizeMessages` keeps applying it
+ * because the hook's own `messages` output — and the `onSend(content,
+ * messages)` callback it feeds — has always handed hosts an ISO string, not a
+ * `Date`; the absorption is expressed once here and consumed at both points.
+ *
+ * The `instanceof` check (rather than an unconditional `.toISOString()`) is
+ * deliberate: authored JSON is not type-checked at runtime, so a value that is
+ * neither `string` nor `Date` must be dropped rather than thrown on. That is
+ * the behaviour the inlined version had.
+ */
+export declare function toRuntimeTimestamp(timestamp: AuthoredChatMessage['timestamp']): string | undefined;
+/**
+ * `role: 'user' | 'assistant' | 'system' | 'tool'` -> the runtime's three roles.
+ *
+ * **The named decision (objectui#4399): an authored `'tool'` message renders as
+ * an assistant bubble, with its content shown.** That was already the outcome
+ * before this module existed — the cast let `'tool'` reach `<ChatbotEnhanced>`,
+ * whose `formatMessageProps` maps everything that is not `'user'` to the
+ * assistant bubble — but it was an implicit fallthrough that nothing recorded
+ * and nothing tested. It is now a decision this seam makes, by name.
+ *
+ * Note this is NOT the same decision as `formatMessageProps`: that one maps a
+ * runtime role to one of the vendored `<Message>` element's two BUBBLE styles
+ * (and folds `'system'` in as well). This one answers a different question —
+ * which runtime role an authored `'tool'` message IS. `'system'` keeps its own
+ * runtime role here and still renders as the centred system pill in
+ * `<Chatbot>`.
+ *
+ * Changing the rendering of tool messages (a transcript-style tool block, say)
+ * is a UX card, not this one; it would start here.
+ */
+export declare function toRuntimeRole(role: AuthoredChatMessage['role']): RuntimeChatMessage['role'];
+/**
+ * Tool-invocation `state` -> the runtime's AI SDK v6 lifecycle states.
+ *
+ * The authoring type accepts three extra legacy values and its own doc comment
+ * already declares the mapping: "the legacy `partial-call`/`call`/`result`
+ * values are kept for back-compat; the AI SDK v6 lifecycle states map cleanly
+ * to `input-streaming`/`input-available`/`output-available`". This implements
+ * exactly that sentence — the fourth drift the `as any` was hiding, which the
+ * issue's table did not list.
+ *
+ * Rendered-output note: an authored legacy state used to reach `getToolState`
+ * unrecognised, which fell through to `'running'` and rendered a status badge
+ * with no label. Only schema-authored `toolInvocations` can carry the legacy
+ * spelling (API-mode messages come from `mapMessages`, which emits v6 states
+ * already), so this is the one place where the seam's honesty changes a
+ * rendered result — from a blank badge to the state the author declared.
+ */
+export declare function toRuntimeToolState(state: AuthoredToolInvocation['state']): RuntimeToolInvocation['state'];
+/**
+ * One authored tool invocation -> one runtime tool invocation.
+ *
+ * Only `state` drifts; everything else is spread through, which is what keeps
+ * the runtime-only extensions (`pendingActionId`, `draftReview`,
+ * `proposedPlan`, `proposedChanges`, `builderHandoff`) alive on the API-mode
+ * path. Since objectui#4424 the parameter names them ({@link
+ * SeamToolInvocation}), so `passthrough` carries them as declared properties
+ * instead of as keys the compiler cannot see — see the module doc.
+ */
+export declare function toRuntimeToolInvocation(tool: SeamToolInvocation): RuntimeToolInvocation;
+/**
+ * One chat message -> the message shape the chat components render.
+ *
+ * This is the seam. The three `messages as any` casts in `renderer.tsx` are
+ * this function now.
+ *
+ * The parameter is {@link SeamChatMessage} rather than the bare authoring type
+ * (objectui#4424): both are accepted — `AuthoredChatMessage` is assignable to
+ * it — but naming the render-only keys is what makes the pass-through
+ * compiler-visible instead of a documented act of faith.
+ */
+export declare function authoredToRuntimeMessage(message: SeamChatMessage): RuntimeChatMessage;
+/**
+ * Array form of {@link authoredToRuntimeMessage} — what the three registered
+ * renderers call.
+ *
+ * Call sites memoize on the input array (`useMemo(..., [messages])`) so the
+ * runtime array's identity stays exactly as stable as the hook's own output:
+ * local mode holds its messages in state, and the chat components key effects
+ * and memos off the `messages` prop.
+ */
+export declare function toRuntimeMessages(messages: readonly SeamChatMessage[] | undefined): RuntimeChatMessage[];
+export {};
+//# sourceMappingURL=chatMessageAdapter.d.ts.map

package/dist/chatMessageAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chatMessageAdapter.d.ts","sourceRoot":"","sources":["../src/chatMessageAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAEH,OAAO,KAAK,EACV,WAAW,IAAI,mBAAmB,EAClC,kBAAkB,IAAI,sBAAsB,EAC7C,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EACV,WAAW,IAAI,kBAAkB,EACjC,kBAAkB,IAAI,qBAAqB,EAC5C,MAAM,mBAAmB,CAAC;AAE3B;;;;;GAKG;AACH,KAAK,sBAAsB,GAAG,IAAI,CAChC,kBAAkB,EAClB,eAAe,GAAG,mBAAmB,GAAG,QAAQ,CACjD,CAAC;AAEF;;;;;GAKG;AACH,KAAK,6BAA6B,GAAG,IAAI,CACvC,qBAAqB,EACrB,iBAAiB,GAAG,aAAa,GAAG,cAAc,GAAG,iBAAiB,GAAG,gBAAgB,CAC1F,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,GACrD,OAAO,CAAC,6BAA6B,CAAC,CAAC;AAEzC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,GAAG;IAC3E,eAAe,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACxC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAEpC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,mBAAmB,CAAC,WAAW,CAAC,GAC1C,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAChC,kBAAkB,CAAC,MAAM,CAAC,CAE5B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,sBAAsB,CAAC,OAAO,CAAC,GACrC,qBAAqB,CAAC,OAAO,CAAC,CAahC;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,kBAAkB,GACvB,qBAAqB,CAGvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,eAAe,GACvB,kBAAkB,CAQpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,GAC/C,kBAAkB,EAAE,CAEtB"}