docs(thermidor): refresh the demo sample and package architecture docs j:KIT-6348 by jfcere-coveo · Pull Request #8706 · coveo/ui-kit

jfcere-coveo · 2026-10-16T14:11:28Z

https://coveord.atlassian.net/browse/KIT-6348

Motivation

During review of #8678, @fbeaudoincoveo noted that much of the demo sample's IMPLEMENTATION.md was out of date and asked for a separate PR. Auditing it against the code showed the sample README and @coveo/thermidor's README and docs/architecture.md had drifted too (the last one still described the removed remote controller). Docs only, no code change.

Changes

samples/thermidor/demo-schema-react/IMPLEMENTATION.md

State model: links ADR-012 (inline state) instead of ADR-011, notes the sample injects the contract, and corrects the formatting claim (prices and counts are formatted client-side).
Node identity: nodes are flat (ADR-013); the props wrapper example is gone.
"Zod version mismatch" (Zod 4 + asCatalog* casts) replaced by "Catalog and Zod version": zod@3, @coveo/thermidor-schema/zod3, createReactComponent + new Catalog(...).
New sections: rendering every turn on one page (turn-scoped render ids, read-only earlier turns, follow-up exchanges) and optimistic updates (held values, stale results region, facet-search text).
Action dispatch rewritten for the actual path: context.dispatchAction → AppShell onAction → session action queue.
Removed: schema conformity table (wrong counts, belongs in thermidor-schema), PR generated a2ui #8088 history, done/obsolete DX rows, use-navigation.ts / React Router / unified-search items, thermidor-schema internals.
Workarounds and DX tables rebuilt from what exists today.
New known limitation: inbound updateDataModel ops are validated only into response.state, while the renderer is fed from response.a2uiMessages, built from the raw stream, so a non-conforming op still reaches the screen.

samples/thermidor/demo-schema-react/README.md

Mock route (/schema/api/preview/..., not /converse-schema), scenarios (no demo-react rows; bundle slots are ProductSummary), Breadbox in the search composition, buildChild instead of children().
Component tree, key modules and data flow match the code; the "Key differences from demo-react" section and the duplicated state model are removed.

packages/thermidor/docs/architecture.md

Remote controller removed (public surface + diagram, section, type threading, {turnId} invariant, comparison table).
Added: validation boundaries, action queue and optimistic helpers, v0.9 renderer projection, a2uiMessages in the model and serialization, Zod 3/4 peer range.
Fixed: a prompt cancels a stream in flight instead of being ignored, cancel() semantics, no STATE_SNAPSHOT handling, no 'commerce-search' literal in the fold, package structure.

packages/thermidor/README.md

Zod 3 or 4, onAction on A2UIProvider, prompt preemption, a2uiMessages in TurnResponse and serialization, interim debt updated.

Validation

Each claim checked against src/ of the sample and @coveo/thermidor, the mocks (platform-mock-api, mock-converse-api), and the thermidor-schema ADRs on beta.
oxfmt --check and cspell on the four files; relative links and anchors checked.
Links are valid and pages render correctly

Checklist

PR title follows Conventional Commits 1.0.0 format (docs(<scope>): <description>)
Added a changeset (pnpm changeset) if the public API surface is affected (not needed: docs only)

changeset-bot · 2026-10-16T14:11:34Z

⚠️ No Changeset found

Latest commit: 5202ee4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

svcsnykcoveo · 2026-10-16T14:11:45Z

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

pkg-pr-new · 2026-10-16T14:14:17Z

@coveo/pkg-new-template

@samples/thermidor-demo-schema-react

npm i https://pkg.pr.new/@coveo/thermidor@8706

commit: 5202ee4

Copilot

🟢 Approval recommended

The documentation-only changes align with the reviewed implementation, with no unresolved findings.

0 open findings

What changed in this PR

Refreshes Thermidor’s package and demo documentation to reflect the current implementation, without changing code.

Changes:

Replaces obsolete remote-controller descriptions with inline-state rendering.
Documents action queues, optimistic updates, follow-up exchanges, and validation limitations.
Corrects mock routes, component composition, and Zod compatibility guidance.

File	Description
samples/thermidor/demo-schema-react/README.md	Updates sample setup, component tree, and data flow.
samples/thermidor/demo-schema-react/IMPLEMENTATION.md	Refreshes implementation details, workarounds, and limitations.
packages/thermidor/README.md	Updates public usage and session behavior documentation.
packages/thermidor/docs/architecture.md	Aligns architecture descriptions with the current session client.

🧠 Review effort: Balanced

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

chromatic-com · 2026-10-16T14:18:11Z

Tip

All tests passed and all changes approved!

🟢 UI Tests: 439 tests unchanged
🟢 UI Review: No changes
Storybook Publish: 471 stories published

chromatic-com · 2026-10-16T14:18:12Z

Tip

All tests passed and all changes approved!

🟢 UI Tests: 439 tests unchanged
🟢 UI Review: No changes
Storybook Publish: 471 stories published

…s j:KIT-6348 Bring demo-schema-react's IMPLEMENTATION.md and README.md, and @coveo/thermidor's README.md and docs/architecture.md, in line with the shipped code: inline state through the A2-UI data model, flat nodes, the Zod 3 catalog, the session-wide renderer stream, follow-up exchanges, the action queue and optimistic updates. Drop the removed remote controller, the demo-react comparisons, and resolved or obsolete tracking tables, and record that the renderer stream bypasses in-transit validation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

- architecture.md: show the prompt path to the endpoint client, describe the v0.9 projection's data-model seeding and orphan-delete filtering, pass contracts in the sequence diagram, list resolve-operation.ts and createSettledDispatch, and add contracts to the Session box. - IMPLEMENTATION.md: facet and breadbox types come from the zod3 entry; the Zod 4 migration switches every zod3 import. - README.md: /converse-schema also serves the schema templates. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

- Known limitation: the createSurface.dataModel seed also reaches the renderer without validation; a fix must cover it, not only the projected updateDataModel ops. - response.state holds validated /state/<id> component state, not the A2-UI data model; ops outside /state are dropped as unresolved-path. - Pagination freezes rather than dims while results are stale. - The dispatch tracker is scoped for removal with the coordinator. - Sort, Pagination, PageSize and NextActionsBar call useOptimisticValue directly; only facets and breadbox have use-optimistic-*.ts hooks. - Explain why actions are dropped while an exchange streams (splitTurn attribution, not a race). - Note that the sample treats the latest turn as the active one, which retry(turnId) can break. - List the /schema/rest/... mock route. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

jfcere-coveo requested review from a team, alexprudhomme, jpmarceau, jsmith2-coveo, louis-bompart, tbaxter-coveo and y-lakhdar and a balanced review from Copilot October 16, 2026 14:11

jfcere-coveo deployed to pr-workflows October 16, 2026 14:11 — with GitHub Actions Active

coveo-code-areas-pr-checks Bot added area:documentation area:thermidor team:dev-writers team:dxui labels Oct 16, 2026

Copilot started reviewing on behalf of jfcere-coveo October 16, 2026 14:12

View session

jfcere-coveo deployed to PR Artifacts October 16, 2026 14:12 — with GitHub Actions Active

jfcere-coveo had a problem deploying to PR Artifacts October 16, 2026 14:13 — with GitHub Actions Error

developer-experience-bot Bot deployed to pr-workflows October 16, 2026 14:14 Active

developer-experience-bot Bot deployed to PR Artifacts October 16, 2026 14:15 Active

Copilot AI reviewed Oct 16, 2026

View reviewed changes

developer-experience-bot Bot deployed to PR Artifacts October 16, 2026 14:16 Active

jfcere-coveo deployed to pr-workflows October 16, 2026 14:23 — with GitHub Actions Active

jfcere-coveo deployed to PR Artifacts October 16, 2026 14:24 — with GitHub Actions Active

jfcere-coveo deployed to PR Artifacts October 16, 2026 14:25 — with GitHub Actions Active

jfcere-coveo marked this pull request as draft October 16, 2026 14:59

jfcere-coveo mentioned this pull request Oct 16, 2026

fix(ci): stop caching hand-written docs as build outputs j:KIT-6381 #8708

Merged

2 tasks done

jfcere-coveo and others added 2 commits October 16, 2026 12:13

jfcere-coveo force-pushed the KIT-6348-implementation-doc-refresh branch from 6ce83a0 to 239c470 Compare October 16, 2026 16:14

jfcere-coveo deployed to pr-workflows October 16, 2026 16:14 — with GitHub Actions Active

jfcere-coveo marked this pull request as ready for review October 16, 2026 16:14

jfcere-coveo deployed to PR Artifacts October 16, 2026 16:14 — with GitHub Actions Active

jfcere-coveo deployed to PR Artifacts October 16, 2026 16:15 — with GitHub Actions Active

jfcere-coveo deployed to pr-workflows October 16, 2026 16:31 — with GitHub Actions Active

jfcere-coveo deployed to PR Artifacts October 16, 2026 16:31 — with GitHub Actions Active

jfcere-coveo deployed to PR Artifacts October 16, 2026 16:32 — with GitHub Actions Active

alexprudhomme approved these changes Oct 16, 2026

View reviewed changes

fbeaudoincoveo approved these changes Oct 16, 2026

View reviewed changes

jfcere-coveo added this pull request to the merge queue Oct 16, 2026

Merged via the queue into main with commit 7fcadcd Oct 16, 2026
47 checks passed

jfcere-coveo deleted the KIT-6348-implementation-doc-refresh branch October 16, 2026 17:25

Navigation Menu

Repository navigation

docs(thermidor): refresh the demo sample and package architecture docs j:KIT-6348 - #8706

docs(thermidor): refresh the demo sample and package architecture docs j:KIT-6348#8706
jfcere-coveo merged 3 commits into
mainfrom
KIT-6348-implementation-doc-refresh

jfcere-coveo commented Oct 16, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Oct 16, 2026 •

edited

Loading

Uh oh!

svcsnykcoveo commented Oct 16, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Oct 16, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

chromatic-com Bot commented Oct 16, 2026

All tests passed and all changes approved!

Uh oh!

chromatic-com Bot commented Oct 16, 2026 •

edited

Loading

All tests passed and all changes approved!

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

jfcere-coveo commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Changes

Validation

Checklist

Uh oh!

changeset-bot Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

svcsnykcoveo commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Snyk checks have passed. No issues have been found so far.

Uh oh!

pkg-pr-new Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

chromatic-com Bot commented Oct 16, 2026

All tests passed and all changes approved!

Uh oh!

chromatic-com Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

All tests passed and all changes approved!

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jfcere-coveo commented Oct 16, 2026 •

edited

Loading

changeset-bot Bot commented Oct 16, 2026 •

edited

Loading

svcsnykcoveo commented Oct 16, 2026 •

edited

Loading

pkg-pr-new Bot commented Oct 16, 2026 •

edited

Loading

chromatic-com Bot commented Oct 16, 2026 •

edited

Loading