@mieweb/ui 0.11.0-dev.54 → 0.11.0-dev.56

package/agent/README.md

@@ -22,8 +22,8 @@ governing spec: later tickets cite it instead of re-deciding.
 | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [mieweb-ui.instructions.md](mieweb-ui.instructions.md) | The rules template. Copied verbatim to the consumer's `.github/instructions/` (VS Code Copilot auto-applies it via the `applyTo` frontmatter) and embedded, minus frontmatter, in a marked block in the consumer's `AGENTS.md` (the cross-tool convention).                                                       |
 | [init-agent.mjs](init-agent.mjs)                       | The `mieweb-ui` bin. Idempotent — rerun after upgrading `@mieweb/ui` to refresh all targets. `--experimental-agents` additionally installs the agent team below.                                                                                                                                                  |
-| [agents/](agents/)                                     | Agent templates: `mieweb-ui-design` (orchestrator) + `mieweb-ui-styling` + `mieweb-ui-install` + `mieweb-ui-a11y` + `mieweb-ui-i18n` + `mieweb-ui-migration`. Installed to the consumer's `.github/agents/` behind `--experimental-agents`.                                                                       |
-| [skills/](skills/)                                     | Skill templates: `mieweb-ui-catalog`, `mieweb-ui-tokens`, `mieweb-ui-icons` (generated — `pnpm agent:skills`, never hand-edit) + `mieweb-ui-brands`, `mieweb-ui-tailwind4`, `mieweb-ui-a11y-checklist`, `mieweb-ui-i18n-checklist` (hand-written). Installed to `.github/skills/` behind `--experimental-agents`. |
+| [agents/](agents/)                                     | Agent templates: `mieweb-ui-design` (orchestrator) + `mieweb-ui-styling` + `mieweb-ui-install` + `mieweb-ui-a11y` + `mieweb-ui-i18n` + `mieweb-ui-migration` + `mieweb-ui-richtext` + `mieweb-ui-grids`. Installed to the consumer's `.github/agents/` behind `--experimental-agents`.                               |
+| [skills/](skills/)                                     | Skill templates: `mieweb-ui-catalog`, `mieweb-ui-tokens`, `mieweb-ui-icons` (generated — `pnpm agent:skills`, never hand-edit) + `mieweb-ui-brands`, `mieweb-ui-tailwind4`, `mieweb-ui-a11y-checklist`, `mieweb-ui-i18n-checklist`, `mieweb-ui-kerebron`, `mieweb-ui-datavis-api` (hand-written). Installed to `.github/skills/` behind `--experimental-agents`. |
 | `evals/` _(Phase 2+)_                                  | Golden-question eval sets per specialist; the regression harness for agent knowledge.                                                                                                                                                                                                                             |
 
 Rule content is sourced from [lessons/component-policy.md](../lessons/component-policy.md);

package/agent/agents/mieweb-ui-design.agent.md

@@ -23,6 +23,14 @@ handoffs:
     agent: MIE UI Migration Agent
     prompt: Audit the code discussed above for @mieweb/ui compliance (raw HTML elements, custom modal/card/badge patterns, hand-rolled icons, CSS foundation) and report findings with a prioritized replacement plan.
     send: false
+  - label: Rich text editors
+    agent: MIE UI Rich Text Agent
+    prompt: Handle the rich-text question above (Kerebron editors, install legs, WASM/patches, collaboration, markdown round-trip, EmailEditor) and report the minimal fix.
+    send: false
+  - label: Grids & eSheet
+    agent: MIE UI Grids Agent
+    prompt: Handle the grid/eSheet question above (DataVis NITRO sources, columns, features, operations, eSheet Builder/Renderer) and report the minimal fix.
+    send: false
 ---
 
 # MIE UI Design Agent (orchestrator)
@@ -60,9 +68,11 @@ comparison tables) and `mieweb-ui-icons` (icon aliases and conventions):
 | ARIA, keyboard nav, screen readers, contrast         | MIE UI A11y Agent      |
 | translations, locale bundles, Intl formats, RTL      | MIE UI i18n Agent      |
 | migrating code to @mieweb/ui, raw-HTML compliance    | MIE UI Migration Agent |
+| rich text editors (RichEditor, TextAreaRich, EmailEditor), Kerebron peers/WASM/patches, collab, Markdown rendering | MIE UI Rich Text Agent |
+| DataVis NITRO config (sources, columns, features, operations), eSheet Builder/Renderer, grid debugging | MIE UI Grids Agent |
 
-More specialists (Grids, DataVis, Views,
-SuperChat, Rich Text) land in later phases; until one ships, answer its domain
+More specialists (DataVis, Views,
+SuperChat) land in later phases; until one ships, answer its domain
 from the skills and the component docs, or defer (below).
 
 **Tie-breakers:**

package/agent/agents/mieweb-ui-grids.agent.md

@@ -0,0 +1,87 @@
+---
+name: MIE UI Grids Agent
+description: Grids specialist for the @mieweb/ui design system — DataVis NITRO (DataVisNitroSource/Grid/Graph, column API, feature flags, grouping/aggregates, operations palette, perspectives) and the eSheet form pair (Builder/Renderer, clinical fields, EncounterVisit). Invoke for configuring or debugging a NITRO grid or graph, source/column/feature questions, row selection and mass operations, grid performance with large datasets, AGGrid deprecation questions, and eSheet Builder/Renderer integration.
+tools: ['search', 'codebase', 'fetch', 'runInTerminal']
+handoffs:
+  - label: Apply Fixes
+    agent: agent
+    prompt: Apply the grid/eSheet integration fixes identified above to the codebase.
+    send: false
+---
+
+# MIE UI Grids Agent
+
+You are the grids specialist for the **@mieweb/ui** design system. Consumers
+come to you after they have a grid (or know they need one) — to configure
+columns, sources and features, to wire selection and mass operations, to
+debug an empty or misbehaving grid, and to integrate the eSheet
+Builder/Renderer pair. You diagnose from evidence and report a minimal fix —
+you do not edit files (offer the **Apply Fixes** handoff instead).
+
+## Your sources of truth (never inline-duplicate them)
+
+- **`mieweb-ui-datavis-api` skill** — the domain bible: the grid policy,
+  Source/Grid/Graph architecture and context coupling, source types
+  (`http`/`local`/`file`) and declarative `groupBy`/`aggregates`, the curated
+  grid props (chrome, columns, features, operations, perspectives), the
+  no-virtualization reality, orders-grid composition patterns, the eSheet
+  pair and clinical fields, and the symptom→fix troubleshooting table. Start
+  every answer here.
+- **`mieweb-ui-catalog` skill** — entry points, the Grids family "Which one?"
+  table, and per-entry peer requirements.
+- **`mieweb-ui-kerebron` skill** — when EncounterVisit's RichEdit mode or
+  eSheet narrative fields drag in the Kerebron editor stack.
+
+## Workflow
+
+1. **Enforce the policy before configuring.** Any plain `<table>` growing
+   sort/filter/page/export features, any new `AGGrid` usage, or `Pagination`
+   bolted onto a NITRO grid is the real finding — redirect to NITRO first,
+   then configure.
+2. **Check the coupling before the props.** An empty or dead grid is usually
+   structural: Grid/Graph not nested inside a `DataVisNitroSource`, a
+   `local` source whose global isn't set at mount, or `datavis-ace` failing
+   to resolve.
+3. **Prefer declarative configuration.** `groupBy`/`aggregates` on the
+   Source, `features`/`columns`/`operations` on the Grid. Imperative
+   `setGroup`/`setAggregate` through `DataVisNitroContext` is library-internal
+   composition, not consumer API.
+4. **Be honest about limits.** There is no row virtualization and no
+   server-side row model — all operations run client-side over the fetched
+   dataset. For very large data, the fix is upstream (serve less, group,
+   aggregate), not a grid prop. Treat genuine capability gaps as NITRO
+   feature requests, never as a reason to reach for AGGrid.
+5. **Match the skill's troubleshooting table**, then report root cause,
+   evidence, and the smallest fix. Offer **Apply Fixes** for the edit.
+
+## Redirects
+
+- "Which component should I use?" → **MIE UI Design Agent** (selection is the
+  orchestrator's domain; you own configuration, APIs and debugging of a
+  chosen grid).
+- Install plumbing — Tailwind setup, `styles.css`, peer errors outside
+  `datavis-ace`/`@esheet/*` → **MIE UI Install Agent**.
+- Token/Tailwind/brand theming of surrounding UI → **MIE UI Styling Agent**.
+- Grid accessibility audits → **MIE UI A11y Agent** — but always carry the
+  caveat yourself: the engine's DOM is not screen-reader friendly; keep
+  critical actions reachable outside the grid.
+- Charts beyond the NITRO Graph (YChart, Deck, Globe, maps) → the DataVis
+  specialist once it ships; until then the orchestrator answers from the
+  catalog skill.
+
+## Rules
+
+1. Never invent grid props, feature flags, or engine capabilities — the grid
+   surface is deliberately curated; verify against the skill or the installed
+   types before recommending a prop.
+2. `AGGrid` is deprecated: never recommend it for new work; when NITRO lacks
+   a capability, say so and point to filing a NITRO feature request.
+3. Never tell a consumer to call `setGroup`/`setAggregate` on
+   `DataVisNitroContext` — declarative props only.
+4. eSheet Builder/Renderer never persist — storage always lives with the
+   host. Submission is either the Renderer's opt-in `onSubmit` button or a
+   host-driven `getValidResponse()` read (which returns
+   `{ response, errors }`, not a bare `FormResponse`) — never both.
+5. Prefer the smallest change that fixes the root cause; no grid rewrites.
+6. The installed `mieweb-ui.instructions.md` rules apply to any code you
+   recommend.

package/agent/agents/mieweb-ui-richtext.agent.md

@@ -0,0 +1,86 @@
+---
+name: MIE UI Rich Text Agent
+description: Rich-text editing specialist for the @mieweb/ui design system — the Kerebron entry (RichEditor, CodeEditor, TextAreaRich), the Kerebron-backed main-barrel Textarea, EmailEditor, MarkdownRenderer, Yjs collaboration, WASM grammar serving, the exact-0.8.12 peer set with ProseMirror overrides, and the consumer-side @kerebron patches. Invoke for integrating or configuring any rich-text editor, typing/toolbar/WASM/collab failures, markdown round-trip or value-contract questions, and email-safe editing.
+tools: ['search', 'codebase', 'fetch', 'runInTerminal']
+handoffs:
+  - label: Apply Fixes
+    agent: agent
+    prompt: Apply the rich-text integration fixes identified above to the codebase.
+    send: false
+---
+
+# MIE UI Rich Text Agent
+
+You are the rich-text editing specialist for the **@mieweb/ui** design
+system. Consumers come to you to wire a Kerebron editor into their app, to
+pick the right configuration for a surface they have already chosen, and when
+an editor misbehaves — typing throws, toolbars are dead, grammars 404, marks
+vanish on save, collaboration silently stops syncing. You diagnose from
+evidence and report a minimal fix — you do not edit files (offer the
+**Apply Fixes** handoff instead).
+
+## Your sources of truth (never inline-duplicate them)
+
+- **`mieweb-ui-kerebron` skill** — the domain bible: surfaces and their value
+  contracts, the three-legged install (exact-0.8.12 peers, ProseMirror
+  overrides, CSS + WASM assets), the consumer-side patches and what breaks
+  without each, RichEditor integration facts (read-once props, `getContent()`
+  on submit, `mediaUpload`, `omitExtensions`), collaboration and its degrade
+  path, Textarea-on-Kerebron behaviour changes, EmailEditor constraints, and
+  the symptom→fix troubleshooting table. Start every answer here.
+- **`mieweb-ui-catalog` skill** — entry-point map and per-entry peer/CSS
+  requirements across the whole library.
+- **`mieweb-ui-tailwind4` skill** — general install/CSS foundation when the
+  problem is upstream of the editors (missing `kerebron.css` is yours;
+  missing `styles.css` plumbing is Install's).
+
+## Workflow
+
+1. **Settle the value contract first.** Markdown → `RichEditor`; HTML in
+   textarea chrome → Kerebron `TextAreaRich`; plain text → `Textarea`; email
+   blocks → `EmailEditor`; display-only Markdown → `MarkdownRenderer`. Most
+   misconfigurations are a surface/format mismatch — e.g. echoing flattened
+   `Textarea` output back into a rich surface.
+2. **Check the three install legs before the component.** Peers at exactly
+   0.8.12, the four ProseMirror overrides in the host, `kerebron.css` +
+   WASM assets at `/kerebron-wasm`. `pnpm why prosemirror-model` (or
+   `npm ls`/`yarn why`) must show a single version.
+3. **Then the patches.** Dead toolbar dropdowns, dropped
+   highlight/sup/sub marks, and the axe `select-name` failure are all
+   missing-host-patch symptoms — the library's own `patchedDependencies` do
+   not propagate.
+4. **Match the skill's troubleshooting table** before reasoning from scratch;
+   it covers the known failure modes with their issue numbers.
+5. **Report, then hand off.** State root cause, evidence, and the smallest
+   fix. Offer **Apply Fixes** for the edit.
+
+## Redirects
+
+- "Which editor/component should I use?" → **MIE UI Design Agent** (selection
+  is the orchestrator's domain; you own configuration, APIs and debugging of
+  a chosen surface).
+- Library-wide install plumbing — Tailwind setup, `styles.css`, dark mode,
+  brand CSS, non-editor peer errors → **MIE UI Install Agent**. You own the
+  Kerebron legs (peers/overrides/WASM/patches/`kerebron.css`).
+- Token choices and visual theming of editor chrome → **MIE UI Styling
+  Agent**.
+- Accessibility audits beyond the editor-specific facts you carry (labelling
+  via `aria-label`, the codecrock patch) → **MIE UI A11y Agent**.
+
+## Rules
+
+1. Never invent editor props, extension names, or Kerebron APIs — verify
+   against the skill, the library's types, or the consumer's installed
+   packages.
+2. The legacy `RichTextEditor` and legacy `TextAreaRich` are deprecated
+   (mieweb/ui#692): never recommend them for new work; steer to the Kerebron
+   surfaces and flag any new usage you encounter.
+3. Respect read-once props: any answer that changes `collab`, `mediaUpload`,
+   `modifyMenu` or `omitExtensions` at runtime must say "remount via `key`".
+4. If documents persist anywhere, insist on an upload hook — base64
+   embedding is a data-size defect, not a style choice. The hook is
+   `mediaUpload.uploadHandler` on the surfaces that expose it (`RichEditor`,
+   Kerebron `TextAreaRich`); `EmailEditor`'s is `onUploadImage`.
+5. Prefer the smallest change that fixes the root cause; no editor rewrites.
+6. The installed `mieweb-ui.instructions.md` rules apply to any code you
+   recommend.

package/agent/evals/README.md

@@ -20,6 +20,8 @@ These files are maintainer-side quality tooling. They are **not** shipped by
 | [a11y.md](./a11y.md)           | Accessibility                        | MIE UI A11y Agent      |
 | [i18n.md](./i18n.md)           | Internationalization / RTL           | MIE UI i18n Agent      |
 | [migration.md](./migration.md) | Migration / compliance (incl. icons) | MIE UI Migration Agent |
+| [richtext.md](./richtext.md)   | Rich text / Kerebron editors         | MIE UI Rich Text Agent |
+| [grids.md](./grids.md)         | DataVis NITRO + eSheet grids         | MIE UI Grids Agent     |
 
 ## Entry format
 

package/agent/evals/grids.md

@@ -0,0 +1,241 @@
+# Evals — DataVis NITRO + eSheet grids
+
+Primary agent: **MIE UI Grids Agent**. See [README.md](./README.md) for
+format and scoring. Selection-level grid questions (Table vs NITRO) live in
+[selection.md](./selection.md); these cover configuration, APIs and
+debugging of a chosen grid.
+
+### GRD-1 — Minimal NITRO setup
+
+- **Ask:** "What's the minimal code to show a sortable, filterable grid over a JSON endpoint?"
+- **Expect:** `DataVisNitroGrid` nested inside
+  `<DataVisNitroSource type="http" url="…">` from `@mieweb/ui/datavis`;
+  parsing/type-inference automatic; sort/filter/group/export come from the
+  engine. No extra installs (`@mieweb/datavis` is bundled, `datavis-ace`
+  arrives as a dependency) and no extra CSS (base stylesheet already imports
+  the datavis styles).
+- **Agent:** MIE UI Grids Agent
+- **Source:** agent/skills/mieweb-ui-datavis-api/SKILL.md — Architecture/Source; DataVisNITRO MAINTAINERS.md
+
+### GRD-2 — Empty grid, no error
+
+- **Ask:** "My DataVisNitroGrid renders nothing and the console is clean."
+- **Expect:** Structural first: the Grid must render **inside** a
+  `DataVisNitroSource` (they're coupled through `DataVisNitroContext`); for
+  `type="local"`, `window[varName]` must be set (shaped `{ typeInfo, data }`)
+  before mount.
+- **Agent:** MIE UI Grids Agent
+- **Source:** datavis-api skill — troubleshooting; DataVisNitro.tsx
+
+### GRD-3 — Source is not a constructor
+
+- **Ask:** "I get `datavis_ace.Source is not a constructor` at runtime."
+- **Expect:** `datavis-ace` is a hard runtime requirement of
+  `DataVisNitroSource`, shipped as a regular dependency of `@mieweb/ui`
+  (external in the bundle) — it's missing or mis-resolved. Reinstall / check
+  `pnpm why datavis-ace`; never import it directly or add it manually as a
+  workaround.
+- **Agent:** MIE UI Grids Agent
+- **Source:** DataVisNITRO MAINTAINERS.md — Dependencies
+
+### GRD-4 — Local data without a server
+
+- **Ask:** "How do I feed an in-memory array of rows to a NITRO grid?"
+- **Expect:** `type="local"` + `varName`: set
+  `window[varName] = { typeInfo, data }` before mounting and delete it on
+  unmount; the engine reads the global. Changing `varName` rebuilds the
+  source.
+- **Agent:** MIE UI Grids Agent
+- **Source:** DataVisNitro.tsx — LocalDataVisNitroSourceProps; demo stories LocalDataset
+
+### GRD-5 — Column API
+
+- **Ask:** "How do I pin a column, set a header label, and render HTML in cells?"
+- **Expect:** `columns` on the grid: string = bare field name; object form
+  `{ field, header, pinned, allowHtml, … }` (plus
+  width/minWidth/maxWidth, visible, align, className,
+  typeInfo/sortable/filterable).
+- **Agent:** MIE UI Grids Agent
+- **Source:** nitro-columns.ts — DataVisNitroColumn; table/types.ts — TableColumn
+
+### GRD-6 — Grouping declaratively
+
+- **Ask:** "I'm calling `view.setGroup(…)` through DataVisNitroContext to group my grid — is that right?"
+- **Expect:** No — configure declaratively via the Source's
+  `groupBy={[ 'status' ]}` (or `{ field, functionName }`) and `aggregates`
+  (`{ functionName, fields }`). Imperative context calls are
+  library-internal composition (e.g. `OrdersGroupPresets`), not consumer
+  API, and fight the declarative props.
+- **Agent:** MIE UI Grids Agent
+- **Source:** DataVisNITRO MAINTAINERS.md — gotchas; datavis-api skill — Source
+
+### GRD-7 — Checkbox selection + bulk actions
+
+- **Ask:** "Users need to select multiple rows and run a bulk delete."
+- **Expect:** `features={{ rowSelection: 'checkbox' }}` (tri-state select-all
+  over the currently filtered rows) + an `operations` array —
+  `{ label, icon?, category?, callback(ctx) }` with `ctx.rows` as the
+  selection; surfaces in the operations palette. `onSelectionChange` for
+  host-side tracking.
+- **Agent:** MIE UI Grids Agent
+- **Source:** table/types.ts — TableFeatures; DataVisNITRO.stories.tsx — Operations
+
+### GRD-8 — Feature flags inventory
+
+- **Ask:** "What built-in behaviours can I toggle on the grid without custom code?"
+- **Expect:** `features`: columnResize, columnReorder, stickyHeaders,
+  rowSelection (true | 'checkbox'), headerContextMenu, zebraStripe,
+  keyboardNav (j/k), drillDown, showMore, rowMode ('wrapped' | 'clipped').
+  Not an invented list — anything else needs verification against the types.
+- **Agent:** MIE UI Grids Agent
+- **Source:** table/types.ts — TableFeatures
+
+### GRD-9 — Virtualization
+
+- **Ask:** "How do I turn on row virtualization for my 50k-row grid?"
+- **Expect:** You can't — the engine has **no row virtualization**; `height`
+  + show-more/limit is the scrolling story. For very large data, fix it
+  upstream: serve a narrower dataset at the http `url`, group/aggregate, or
+  page before the grid. Honest-limit answers pass; invented virtualization
+  props FAIL.
+- **Agent:** MIE UI Grids Agent
+- **Source:** datavis-api skill — Grid chrome/troubleshooting (verified: no virtualization in packages/datavis)
+
+### GRD-10 — Server-side rows?
+
+- **Ask:** "Does NITRO support a server-side row model like AG Grid Enterprise?"
+- **Expect:** No — `type="http"` fetches the dataset and **all operations run
+  client-side** over it. The server-side pattern is serving the right
+  dataset at `url`. No new AGGrid usage either (deprecated); a genuine gap
+  is a NITRO feature request.
+- **Agent:** MIE UI Grids Agent
+- **Source:** datavis-api skill — Source; MAINTAINERS.md — Prefer NITRO over AGGrid
+
+### GRD-11 — Detail rows
+
+- **Ask:** "Can a row expand to show a full-width detail panel?"
+- **Expect:** `renderDetailRow` (adds a disclosure toggle per plain-mode row)
+  + `detailRowsExpanded` to expand/collapse all; leave undefined for per-row
+  control.
+- **Agent:** MIE UI Grids Agent
+- **Source:** DataGrid.tsx — renderDetailRow/detailRowsExpanded
+
+### GRD-12 — Minimal chrome
+
+- **Ask:** "I want the grid without the title bar — just the table with a floating menu."
+- **Expect:** `mode="minimal"` (floating hamburger over the table);
+  `minimalMode` is deprecated in its favor. `'full'` restores the classic
+  title bar with row count and inline buttons; `titleActions` adds custom
+  title-bar controls (hidden in minimal mode).
+- **Agent:** MIE UI Grids Agent
+- **Source:** DataGrid.tsx — mode/minimalMode/titleActions
+
+### GRD-13 — Perspectives on shared devices
+
+- **Ask:** "We deploy on shared kiosk machines — users' pinned grid views are leaking between logins."
+- **Expect:** Pinned-perspective names persist to localStorage by default;
+  set `persistPinnedPerspectives={false}` so pins stay in memory for the
+  session.
+- **Agent:** MIE UI Grids Agent
+- **Source:** DataGrid.tsx — persistPinnedPerspectives
+
+### GRD-14 — Grid + chart over one fetch
+
+- **Ask:** "A dashboard needs the same records as a grid and a chart the user can reconfigure — do I fetch twice?"
+- **Expect:** No — Grid and Graph are two renderers over the same
+  `DataVisNitroSource`/view; render `DataVisNitroGraph`
+  (`config`/`onConfigChange` for user-changed axes/chart type) beside the
+  grid inside one Source. Tiny inline trend → `Sparkline` instead.
+- **Agent:** MIE UI Grids Agent
+- **Source:** Grids.mdx — How they fit together; DataVisNitroGraph.tsx
+
+### GRD-15 — i18n of the grid
+
+- **Ask:** "How do I localize the grid's labels and number/date formats?"
+- **Expect:** `locale` (BCP-47) drives number/date formatting;
+  `DataVisNitroLanguageSelector` switches the engine's own UI language
+  (toolbar/table strings). `trans` only customizes built-in
+  grouping-function labels — answers presenting it as a general grid
+  translator FAIL. Deeper string audits → i18n agent.
+- **Agent:** MIE UI Grids Agent
+- **Source:** DataVisNitro.tsx — trans/locale; stories LocalizedGrid
+
+### GRD-16 — Grid accessibility
+
+- **Ask:** "Is the NITRO grid screen-reader accessible?"
+- **Expect:** Honest caveat: the engine's DOM is **not** screen-reader
+  friendly and automated a11y checks are disabled on the NITRO pages. Keep
+  critical actions reachable outside the grid; provide textual summaries for
+  charts. Full audit → A11y agent.
+- **Agent:** MIE UI Grids Agent
+- **Source:** Grids.mdx — Shared limitations
+
+### GRD-17 — Hover row actions
+
+- **Ask:** "I need per-row edit/delete buttons that appear on hover, consistent with our Table rows."
+- **Expect:** `RowActionToolbar` (main barrel) with `group="grid"` composes
+  with NITRO cells — same component as `Table` rows use.
+- **Agent:** MIE UI Grids Agent
+- **Source:** Grids.mdx — How they fit together
+
+### GRD-18 — Pagination on a NITRO grid
+
+- **Ask:** "Which component adds page controls under my NITRO grid?"
+- **Expect:** None — `Pagination` is for server-paged `Table`/card lists;
+  rows already in a NITRO grid never need it (filter/group/show-more replace
+  paging).
+- **Agent:** MIE UI Grids Agent
+- **Source:** Grids.mdx — Which one? (Pagination row)
+
+### GRD-19 — eSheet pair contract
+
+- **Ask:** "How do Builder and Renderer hand data to each other, and where's the submit button?"
+- **Expect:** Builder `onChange` emits a `FormDefinition`; Renderer takes it
+  as `formDataInput`. Reading answers: the ref's `getValidResponse()`
+  returns `{ response: FormResponse | null, errors }` (store `response`, not
+  the wrapper), or opt into the built-in submit button via
+  `onSubmit`/`submitLabel`. Persistence is host-owned either way. Entry
+  `@mieweb/ui/esheet` needs **all four** matching `@esheet/*` peers
+  (`core`/`fields`/`builder`/`renderer`, `>=0.0.6-17`) even for
+  renderer-only use.
+- **Agent:** MIE UI Grids Agent
+- **Source:** CompositeForms.mdx — the eSheet pair; src/esheet.ts
+
+### GRD-20 — Clinical fields unknown
+
+- **Ask:** "My eSheet definition uses `medicationList` but the Renderer shows an unknown field type."
+- **Expect:** Call `registerMieEsheetFields()` once before rendering
+  definitions that use the Healthcare list fields (`medicationList`,
+  `allergyList`, …) — it plugs them into both Builder and Renderer.
+- **Agent:** MIE UI Grids Agent
+- **Source:** src/esheet.ts; CompositeForms.mdx — two install surfaces
+
+### GRD-21 — EncounterVisit RichEdit stack
+
+- **Ask:** "EncounterVisit's RichEdit mode won't load in my app — what does it need beyond @esheet?"
+- **Expect:** RichEdit rides the Kerebron editor: the `@kerebron/*` peers at
+  exactly 0.8.12 + ProseMirror overrides, `@mieweb/ui/kerebron.css`, and the
+  WASM assets at `/kerebron-wasm` — the full kerebron-skill install legs
+  (route depth to the Rich Text agent / kerebron skill).
+- **Agent:** MIE UI Grids Agent
+- **Source:** src/esheet.ts header; MIGRATION.md — eSheet and EncounterVisit
+
+### GRD-22 — AGGrid escape hatch
+
+- **Ask:** "NITRO doesn't do X that AG Grid does — can I use `@mieweb/ui/ag-grid` for this one grid?"
+- **Expect:** No — `AGGrid` is deprecated, never for new work. Treat the gap
+  as a NITRO feature request (file an issue) so usages can move back; the
+  maintainers' stated policy is to close gaps in NITRO, not fall back.
+- **Agent:** MIE UI Grids Agent
+- **Source:** MAINTAINERS.md — Prefer NITRO over AGGrid; Grids.mdx policy
+
+### GRD-23 — Orders grids as the pattern
+
+- **Ask:** "We're building an order-history grid with group-by chips and bulk status updates — is there prior art?"
+- **Expect:** `ChartOrdersGrid`/`EncounterOrdersGrid` (datavis entry) over
+  the HealthSurveillance order history, with `OrdersGroupPresets` chips and
+  native NITRO `rowSelection: 'checkbox'` + `operations` for mass updates;
+  pure row builders (`buildChartOrderRows`/`buildEncounterOrderRows`) in the
+  main entry. Copy the composition, don't re-implement it.
+- **Agent:** MIE UI Grids Agent
+- **Source:** src/datavis.ts; ordersGridShared.tsx

package/agent/evals/richtext.md

@@ -0,0 +1,229 @@
+# Evals — Rich text / Kerebron editors
+
+Primary agent: **MIE UI Rich Text Agent**. See [README.md](./README.md) for
+format and scoring.
+
+### RT-1 — Which editor for the stored format
+
+- **Ask:** "I need a rich input whose saved value is HTML, looking like a plain textarea until the user asks for the toolbar. Which component?"
+- **Expect:** Kerebron `TextAreaRich` from `@mieweb/ui/kerebron` (HTML
+  contract, one Input row tall, auto-grows, toolbar hidden until asked) — not
+  `RichEditor` (Markdown contract) and not the deprecated main-barrel
+  `TextAreaRich`. Selection may be answered by the orchestrator directly.
+- **Agent:** MIE UI Design Agent (selection) → MIE UI Rich Text Agent for config
+- **Source:** src/catalog/Editors.mdx — Which one? table; agent/skills/mieweb-ui-kerebron/SKILL.md — Surfaces
+
+### RT-2 — Install legs
+
+- **Ask:** "What exactly do I install and configure to use RichEditor in my Vite app?"
+- **Expect:** All three legs: (1) `@kerebron/*` peers at **exactly 0.8.12**
+  (`--save-exact`; `editor`, `editor-kits`, `extension-basic-editor`,
+  `extension-menu`, `wasm`), (2) the four ProseMirror overrides in the host
+  (view 1.42.3, model 1.25.9, state 1.4.3, transform 1.10.4), (3)
+  `@mieweb/ui/kerebron.css` + serve `@kerebron/wasm/assets` at
+  `/kerebron-wasm`. Plus the consumer-side `@kerebron` patches.
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** MIGRATION.md — eSheet and EncounterVisit / 0.12 sections; agent/skills/mieweb-ui-kerebron/SKILL.md — Install
+
+### RT-3 — Fragment RangeError
+
+- **Ask:** "Typing in any editor throws `RangeError: Can not convert <…> to a Fragment (looks like multiple versions of prosemirror-model were loaded)`. What's wrong?"
+- **Expect:** Split ProseMirror resolution (mieweb/ui#709): Kerebron range
+  drifted to 0.8.13+ or transitive `^`-ranges floated on a fresh install. Fix:
+  pin `@kerebron/*` to 0.8.12 exactly + add the four overrides;
+  `pnpm dedupe` cannot fix it; verify with `pnpm why prosemirror-model`
+  (single version).
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** MIGRATION.md — mieweb/ui#709 section; kerebron skill troubleshooting
+
+### RT-4 — Why prosemirror-view 1.42.3
+
+- **Ask:** "Kerebron pins prosemirror-view 1.40.0 — why does the override force 1.42.3?"
+- **Expect:** The protected MDY link bridge uses 1.42.3; two view instances
+  can make decorations incompatible and leave the older view's behavior
+  active.
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** MIGRATION.md — prosemirror-view note
+
+### RT-5 — WASM 404s
+
+- **Ask:** "Code blocks have no syntax highlighting and the console shows 404s for `.wasm` files."
+- **Expect:** The editor loads tree-sitter grammars at runtime from
+  `/kerebron-wasm`; serve `@kerebron/wasm`'s `assets/` dir at that path (copy
+  or symlink into `public/`, or Storybook `staticDirs`), or pass a custom
+  `assetLoad` (`createAssetLoad('/other-path')`).
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** src/kerebron.ts header; RichEditor `assetLoad` prop docs
+
+### RT-6 — Dead toolbar dropdowns
+
+- **Ask:** "The Heading and List dropdowns in the RichEditor toolbar don't open when clicked."
+- **Expect:** Host is missing the `@kerebron/extension-menu` patch — the
+  library's `patchedDependencies` don't propagate; apply
+  `patches/@kerebron__extension-menu@0.8.12.patch` in the host (pnpm-format;
+  npm/yarn convert for patch-package).
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** RichEditor.stories.tsx docs; patches/; kerebron skill — patches table
+
+### RT-7 — Marks dropped on save
+
+- **Ask:** "Highlight, superscript and subscript formatting disappears when the document is saved and reloaded."
+- **Expect:** Missing `@kerebron/extension-markdown` patch (mieweb/ui#536):
+  the serializer's mark table has no entries for those marks, so they're
+  silently dropped on the markdown round-trip; patched they serialize as
+  `<mark>`/`<sup>`/`<sub>` inline HTML.
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** patches/@kerebron__extension-markdown@0.8.12.patch; kerebron skill — patches table
+
+### RT-8 — Reading the value on submit
+
+- **Ask:** "Should I trust my `onChange`-mirrored state when the user hits Save?"
+- **Expect:** No — `onChange` can lag the last keystroke; call the ref's
+  `getContent()` on submit (async, awaits the initial load; rejects if setup
+  failed — see `onError`).
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** RichEditorHandle docs — getContent
+
+### RT-9 — Changing collab/mediaUpload at runtime
+
+- **Ask:** "How do I switch the RichEditor to a different collaboration room without reloading the page?"
+- **Expect:** `collab` (like `mediaUpload`, `modifyMenu`, `omitExtensions`)
+  is read once at mount — **remount via `key`** to switch rooms; collab mode
+  is uncontrolled.
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** RichEditor collab prop docs; kerebron skill — read-once props
+
+### RT-10 — Pasted images bloat the document
+
+- **Ask:** "A pasted screenshot turned my saved markdown into a 6 MB payload. How do I prevent that?"
+- **Expect:** Set `mediaUpload.uploadHandler` — without it images embed as
+  base64 `data:` URLs (and video as reload-dead blob URLs); the handler
+  uploads the file and returns a URL so the document carries a link, not
+  bytes. Required whenever documents persist.
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** RichEditor mediaUpload prop docs
+
+### RT-11 — Removing a feature wholesale
+
+- **Ask:** "How do I remove checklists (toolbar button, `- [ ]` shortcut, paste) from the editor in one move?"
+- **Expect:** `omitExtensions={['task_list', 'task_item']}` — toolbar, input
+  rules and paste handling are all schema-driven, so dropping the nodes
+  removes the whole feature; read once at mount.
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** RichEditor omitExtensions prop docs
+
+### RT-12 — Collab silently local
+
+- **Ask:** "I pass `collab={{ room }}` but edits don't sync between users, and there's no error."
+- **Expect:** `onUnavailable` reports **kit-load failures only** (optional
+  peers `@kerebron/extension-yjs`, `yjs`, `y-protocols` missing): the editor
+  mounts as a local one and the callback fires once, before the editor is
+  created. A reachable-but-disconnected relay is different — the kit stays
+  loaded and the provider retries on its own, with no callback. Fix: install
+  the peers and pass `collab.onUnavailable` to surface load failures; for
+  connectivity, check the `/yjs` websocket relay (`wsUrl` default
+  `<ws|wss>://<location.host>/yjs`).
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** RichEditor collab docs; collabKit.ts; kerebron skill — Collaboration
+
+### RT-13 — MISSING_EXPORT at build
+
+- **Ask:** "My `vite build` fails with `MISSING_EXPORT` from `@kerebron/extension-yjs` in a `collabKit-*` chunk, but I never use collaboration."
+- **Expect:** Optional collab peers absent + an @mieweb/ui version older than
+  the mieweb/ui#706 fix (static named imports in the lazy collab chunk; the
+  optional-peer stub has no named exports). Fix: upgrade @mieweb/ui, or
+  externalize `/^@kerebron\/extension-yjs/` and `/^y-websocket/`.
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** collabKit.ts header (mieweb/ui#706); tailwind4 + kerebron skill troubleshooting
+
+### RT-14 — Legacy RichTextEditor
+
+- **Ask:** "Can I use RichTextEditor for a new templated-letter feature? It has `{{variables}}` and dictation."
+- **Expect:** No — `RichTextEditor` (the `document.execCommand` engine) is
+  deprecated (mieweb/ui#692), never for new work; use Kerebron `TextAreaRich`
+  for HTML with `variableGroups` + dictation, or `RichEditor` for Markdown.
+  Note it emits raw unsanitised `innerHTML`.
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** src/catalog/Editors.mdx — deprecated rows (mieweb/ui#692)
+
+### RT-15 — Textarea DOM shape
+
+- **Ask:** "After upgrading to 0.12 my CSS `textarea { … }` rules and my test's element selectors stopped matching the Textarea."
+- **Expect:** Since 0.12 `Textarea` renders the Kerebron engine: no visible
+  `<textarea>` — a ProseMirror `contenteditable` (`role="textbox"`, class
+  `kb-editor`) plus a hidden mirror `[data-slot="textarea-mirror"]` carrying
+  `name`/`value`. Target the `data-slot` hooks (`[data-slot^="textarea-"]`
+  or a concrete slot); `getByRole('textbox')`
+  keeps working; `TextAreaPlain` / `richText={false}` restores the native
+  element.
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** MIGRATION.md — Textarea is rich text underneath (0.12.0)
+
+### RT-16 — maxLength not enforced
+
+- **Ask:** "Textarea's `maxLength` no longer blocks typing past the limit — bug?"
+- **Expect:** Known behaviour change (0.12): `maxLength` isn't enforced while
+  typing; the `showCount` counter still renders and turns red. Enforce in
+  `onChange` or switch to `TextAreaPlain`.
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** MIGRATION.md — Behaviour changes to review
+
+### RT-17 — Email checklists vanish
+
+- **Ask:** "Why can't users add checklists inside EmailEditor text blocks?"
+- **Expect:** By design (mieweb/ui#695): email `text` blocks are
+  `TextAreaRich` with `omitExtensions={['task_list', 'task_item']}` —
+  checkbox inputs are sanitizer-forbidden and inert in mail clients, so the
+  feature is removed schema-first. Not a bug.
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** EmailBlockSettings.tsx — EMAIL_OMITTED_EXTENSIONS; kerebron skill — EmailEditor
+
+### RT-18 — Compiling EmailEditor output
+
+- **Ask:** "EmailEditor gives me MJML from `renderEmailMjml` — does @mieweb/ui compile it to email HTML?"
+- **Expect:** No — compile with `mjml` (Node) or `mjml-browser` **host-side**;
+  it is not a peer. The editor's document is JSON blocks, not HTML; sending,
+  recipients and templates are the host's concern.
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** src/catalog/Editors.mdx — EmailEditor row + peers table
+
+### RT-19 — Labelling the editor
+
+- **Ask:** "My `<label htmlFor={editorId}>` doesn't give the RichEditor an accessible name."
+- **Expect:** The host is a `div`, not a labelable control — `htmlFor` won't
+  associate; use `aria-label` or `aria-labelledby` (the `id` prop is the
+  anchor). Deeper audits go to the A11y agent.
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** RichEditor id/aria props docs; Editors.mdx — Labelling
+
+### RT-20 — Displaying what RichEditor saved
+
+- **Ask:** "What renders the markdown a RichEditor produced, in a read-only record view with mermaid diagrams?"
+- **Expect:** `MarkdownRenderer` (main barrel, `@mieweb/ui/markdown.css`) —
+  sanitised HTML, code highlighting, `mermaid`/`csv`/`survey`/`html` fences,
+  `streaming` for token-by-token AI output. Conditional deps: `mermaid` for
+  the mermaid fence, `papaparse` for csv, `js-yaml` only for YAML-input
+  surveys (JSON surveys and the html fence need none). Legacy
+  `RichTextEditor` HTML does **not** go through it.
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** src/catalog/Editors.mdx — Markdown row + "Markdown closes the loop"
+
+### RT-21 — Controlled value semantics
+
+- **Ask:** "I set `value` and `onChange` on RichEditor but rejected edits don't revert like a native controlled input."
+- **Expect:** Default is tolerant of read-once hosts (`getContent()` on
+  submit); opt in to native controlled semantics with `strictValue` —
+  converges the document to `value` on every render so un-echoed edits
+  revert. Also: changing `value` reloads the editor (unless `collab`).
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** RichEditor strictValue/value prop docs
+
+### RT-22 — HTML-valued RichEditor
+
+- **Ask:** "Can RichEditor speak HTML instead of Markdown without switching components?"
+- **Expect:** Yes — `valueType="text/html"` governs both how `value` is
+  parsed and what `onChange`/`getContent()` emit (default
+  `'text/x-markdown'`). But if the goal is a textarea-like HTML field,
+  `TextAreaRich` is the intended surface.
+- **Agent:** MIE UI Rich Text Agent
+- **Source:** RichEditor valueType prop docs; Editors.mdx — Which one? table

package/agent/skills/mieweb-ui-datavis-api/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: mieweb-ui-datavis-api
+description: Deep API reference for @mieweb/ui grids — DataVis NITRO (DataVisNitroSource/Grid/Graph, column API, feature flags, grouping/aggregates, operations palette, perspectives) and the eSheet form pair (Builder/Renderer, registerMieEsheetFields, EncounterVisit). USE WHEN configuring or debugging a NITRO grid or graph, choosing columns/features/sources, wiring row selection and mass operations, grouping or aggregating, or integrating eSheet Builder/Renderer and its clinical fields.
+---
+
+# DataVis NITRO + eSheet in @mieweb/ui
+
+Sourced from `src/catalog/Grids.mdx`, `CompositeForms.mdx`, the DataVisNITRO
+MAINTAINERS notes, `packages/datavis` source and `MIGRATION.md`. Grid
+*selection* policy lives in the catalog skill; this is the configuration/API
+layer.
+
+## Policy (non-negotiable)
+
+> **Tables and data grids start with DataVis NITRO.** Use `Table` only for a
+> few static rows the user will not sort, filter, page or export. Never
+> hand-roll grid features on a plain table; `AGGrid` is deprecated.
+
+`Pagination` is for server-paged `Table`/card lists only — rows already in a
+NITRO grid never need it.
+
+## Architecture
+
+- Entry: **`@mieweb/ui/datavis`** — exports `DataVisNitroSource`,
+  `DataVisNitroGrid`, `DataVisNitroGraph`, `DataVisNitroContext`,
+  `DataVisNitroLanguageSelector`, plus `ChartOrdersGrid`/`EncounterOrdersGrid`
+  and `OrdersGroupPresets`.
+- **Two moving parts, zero consumer installs:** `@mieweb/datavis` (the
+  engine's React surface) is **bundled into** the entry; `datavis-ace` (the
+  data engine: fetch/parse/type-inference/aggregation) is a regular
+  **dependency** of `@mieweb/ui` — consumers never install or import either.
+- **Source and Grid are coupled through React context:** a `DataVisNitroGrid`
+  must render inside a `DataVisNitroSource` (which creates the source/view
+  pair and publishes it through `DataVisNitroContext`). **Grid** and
+  **Graph** are two renderers over the same source — a dashboard flips
+  between rows and a chart without refetching.
+- Styles: the base `@mieweb/ui/styles.css` already imports
+  `@mieweb/datavis/styles.css` — no extra CSS wiring.
+
+## DataVisNitroSource
+
+```tsx
+<DataVisNitroSource type="http" url="/api/orders.json" groupBy={['status']}>
+  <DataVisNitroGrid title="Orders" />
+</DataVisNitroSource>
+```
+
+- `type: 'http'` — `url` is fetched by the engine; parsing and type inference
+  are automatic. **All grid operations (sort/filter/group/aggregate) run
+  client-side** over the fetched dataset — there is no server-side row model;
+  the "server-side pattern" is serving the right dataset at `url`.
+- `type: 'local'` — `varName` names a global: set
+  `window[varName] = { typeInfo, data }` **before** mounting (the engine
+  reads it from `globalThis`); clean it up on unmount.
+- `type: 'file'` — user-supplied file (the engine's file picker/parse path).
+- `groupBy?: Array<string | { field, functionName? }>` and
+  `aggregates?: Array<{ functionName, fields }>` configure grouped/aggregated
+  views **declaratively**. Do not reach into `DataVisNitroContext` to call
+  `setGroup`/`setAggregate` — that context is for the library's own
+  composition (e.g. `OrdersGroupPresets`), not the consumer API.
+- Changing `type`/`url`/`varName` rebuilds the source; changing
+  `groupBy`/`aggregates` reconfigures the live view.
+
+## DataVisNitroGrid
+
+A curated surface over the engine's `DataGrid` (the maintainers deliberately
+`Omit` `view`/`children`/`allColumns` and re-add a vetted set — do not assume
+an upstream `DataGrid` prop exists here without checking the types):
+
+- **Chrome:** `title`, `helpText`, `titleActions` (title-bar React nodes),
+  `mode: 'default' | 'full' | 'minimal'` (`minimalMode` is deprecated — use
+  `mode="minimal"`), `showToolbar`, `showControls`, `height` (CSS value —
+  this plus the engine's show-more/limit is the scrolling story; **there is
+  no row virtualization**, so cap very large result sets at the source).
+- **Columns:** `columns?: Array<string | TableColumn>` — a bare string is a
+  field name; the object form is
+  `{ field, header, width/minWidth/maxWidth, visible, pinned, align,
+  className, allowHtml, typeInfo: { type, format }, sortable, filterable }`.
+  Column menus, pinning, resize/reorder persistence and saved
+  **perspectives** come from the engine (`prefs`,
+  `persistPinnedPerspectives={false}` for shared/public devices).
+- **Features** (`features?: TableFeatures`): `columnResize`, `columnReorder`,
+  `stickyHeaders`, `rowSelection: true | 'checkbox'` (checkbox mode adds a
+  tri-state select-all over the currently *filtered* rows),
+  `headerContextMenu`, `zebraStripe`, `keyboardNav` (j/k), `drillDown`,
+  `showMore`, `rowMode: 'wrapped' | 'clipped'`.
+- **Rows:** `formatCell`, `onRowClick`, `onRowDoubleClick`,
+  `onSelectionChange`, `renderDetailRow` + `detailRowsExpanded` (disclosure
+  rows), `onColumnReorder`/`onColumnResize`/`onHeaderContextMenu`.
+- **Mass operations:** `operations?: Operation[]` — each
+  `{ label, icon?, category?, callback(ctx) }` surfaces in the operations
+  palette; `ctx.rows` is the current selection. Pair with
+  `features.rowSelection: 'checkbox'` for bulk edit/delete/export flows.
+- **i18n/formatting:** `locale` (BCP-47) drives number/date formatting.
+  `DataVisNitroLanguageSelector` is the UI-language mechanism — it switches
+  the engine's own i18next language (toolbar/table strings). `trans` is
+  narrower than it looks: it only customizes the built-in grouping-function
+  labels; it does **not** translate the general grid UI.
+- **Hover row actions:** `RowActionToolbar` with `group="grid"` (main
+  barrel) composes with NITRO cells, same as with `Table` rows.
+
+## DataVisNitroGraph
+
+Same source, chart renderer: `columns`, `config?: Partial<GraphConfig>` +
+`onConfigChange` (users may change axes/chart type), `locale`, `height`,
+`className`. For a tiny inline dependency-free trend use `Sparkline` (main
+barrel) instead.
+
+## Real-world composition (orders grids)
+
+`ChartOrdersGrid` / `EncounterOrdersGrid` (this entry) are NITRO grids over
+HealthSurveillance order history; the pure row builders
+(`buildChartOrderRows`/`buildEncounterOrderRows`) live in the **main** entry.
+`OrdersGroupPresets` renders one-click group-by chips. Row selection and mass
+operations there are native NITRO features — the pattern to copy, not
+re-implement.
+
+## Accessibility caveat
+
+The DataVis engine's DOM is **not screen-reader friendly** and automated a11y
+checks are disabled on the NITRO pages. Keep critical actions reachable
+outside the grid and provide textual summaries for charts. Route full audits
+to the A11y agent.
+
+## eSheet (Builder/Renderer)
+
+- Entry: **`@mieweb/ui/esheet`**; optional peers are **all four** `@esheet/*`
+  packages — `@esheet/core`, `@esheet/fields`, `@esheet/builder`,
+  `@esheet/renderer` — at matching versions (`>=0.0.6-17`), even for
+  renderer-only use: the shared entry exports the builder too, so all four
+  must resolve. Styles: Builder and Renderer import their
+  `@esheet/styles` dependency automatically (explicit entry
+  `@esheet/styles/styles.css`); keep loading `@mieweb/ui/styles.css` for
+  composed UI components.
+- **The pair:** `EsheetBuilder` (`definition`/`onChange`) emits a
+  `FormDefinition`; `EsheetRenderer` takes that object as `formDataInput`.
+  Answers come back two ways: imperatively via the ref's
+  `getValidResponse()`, which returns `{ response: FormResponse | null,
+  errors: ValidationError[] }` (`response` is `null` while invalid — store
+  `response`, not the wrapper), or via the opt-in built-in submit button —
+  pass `onSubmit` (+ `submitLabel`) and the Renderer renders it and calls
+  back with the validated `FormResponse`; don't build a duplicate submit
+  flow next to it. **Persistence is host-owned either way** — no autosave,
+  no `name`, no server calls; the host stores definition and response.
+- **Clinical fields:** `registerMieEsheetFields()` plugs the Healthcare list
+  fields (`medicationList`, `allergyList`, …) into both Builder and
+  Renderer — call it once before rendering definitions that use them.
+- **EncounterVisit** (same entry) is the coded clinical visit document; its
+  RichEdit mode rides the Kerebron editor — the `@kerebron/*` peers, WASM
+  assets and `kerebron.css` from the **mieweb-ui-kerebron** skill apply.
+- Known gaps: upstream axe failures (contrast, unlabeled landmarks, role-less
+  drag handles) tracked in the mieweb/eSheet repo; no locale/translation
+  hooks — built-in strings are English — but layout **does** mirror under an
+  inherited `dir="rtl"` (panels swap, toolbar flips), with a handful of
+  physical-direction styling gaps tracked as an upstream eSheet RTL
+  enhancement; it themes via its own `--msprimary` tokens + `dark`
+  class, independent of `ThemeProvider`.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `datavis_ace.Source is not a constructor` | `datavis-ace` missing/unresolved — it is a hard runtime requirement of `DataVisNitroSource` (ships as a regular dependency of `@mieweb/ui`, external in the bundle) | Reinstall; check the host's resolution (`pnpm why datavis-ace`) — never add it as a direct import |
+| Grid renders nothing, no error | `DataVisNitroGrid` not inside a `DataVisNitroSource` (context is null) | Nest Grid/Graph inside the Source |
+| `type="local"` grid is empty | `window[varName]` unset at mount, or not shaped `{ typeInfo, data }` | Set the global before mounting; delete it on unmount |
+| Grouping/aggregation "doesn't stick" | Imperative `setGroup`/`setAggregate` calls on the context fight the declarative props | Use the Source's `groupBy`/`aggregates` props only |
+| Huge dataset scrolls poorly | No virtualization in the engine — `height` + show-more/limit is the mechanism | Reduce the served dataset (http source), group/aggregate, or page upstream |
+| "How do I turn on pagination?" | NITRO has no page controls; `Pagination` is for server-paged `Table`/card lists | Filtering/grouping/show-more replace paging in NITRO |
+| Rows selectable but bulk action missing | `rowSelection` without `operations` | Add `operations` entries — `callback(ctx)` receives `ctx.rows` |
+| Pinned perspectives leak across users on a kiosk | Pins persist to localStorage by default | `persistPinnedPerspectives={false}` |
+| eSheet fields for meds/allergies render as unknown type | `registerMieEsheetFields()` not called | Call it once at startup before rendering such definitions |
+| eSheet looks unstyled | Very old `@esheet/*` versions required manual CSS copying | Upgrade — current Builder/Renderer import `@esheet/styles` automatically |
+| Grid needed AG Grid feature X | `@mieweb/ui/ag-grid` is deprecated | Treat the gap as a NITRO feature request (file an issue); don't start new AGGrid usage |

package/agent/skills/mieweb-ui-kerebron/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: mieweb-ui-kerebron
+description: Integrating @mieweb/ui rich-text editors — the Kerebron entry (RichEditor, CodeEditor, TextAreaRich), the Kerebron-backed main-barrel Textarea, EmailEditor, and MarkdownRenderer — including the exact-0.8.12 peer set, ProseMirror version overrides, WASM grammar serving, the consumer-side @kerebron patches, Yjs collaboration and its degrade path. USE WHEN installing or configuring any rich-text editor, typing/toolbar/WASM/collab misbehaves, markdown round-trip drops marks, or an editor value contract (markdown vs HTML vs plain text) is in question.
+---
+
+# Kerebron rich text in @mieweb/ui
+
+Sourced from `MIGRATION.md`, `src/catalog/Editors.mdx`, the RichEditor/Email
+docs and `patches/` in the mieweb/ui repo. Selection guidance ("which
+editor?") lives in the `mieweb-ui-catalog` skill; general install/CSS
+foundation in `mieweb-ui-tailwind4`.
+
+## Surfaces and their value contracts
+
+The **stored format decides the surface** — this is the first question to
+settle in any integration:
+
+| Surface | Entry | Value contract |
+| --- | --- | --- |
+| `RichEditor` | `@mieweb/ui/kerebron` | **Markdown** in/out (`valueType: 'text/x-markdown'` default; `'text/html'` for an HTML-valued surface) |
+| `CodeEditor` | `@mieweb/ui/kerebron` | Source code (tree-sitter highlighting) |
+| `TextAreaRich` | `@mieweb/ui/kerebron` | **HTML**, textarea-like chrome: one Input row tall, auto-grows, toolbar hidden until asked, markdown block shortcuts, Notion-style `+` gutter menu, `.shortcut` macros |
+| `Textarea` | main barrel | **Plain text** contract over the same engine (since 0.12): `value`/`onChange(event.target.value)` are strings, `name` posts via a hidden mirror `<textarea>`. Opt out per field with `richText={false}` or `TextAreaPlain` |
+| `EmailEditor` + `renderEmailMjml` | main barrel | **JSON blocks** (hero, columns, buttons, images, social, footer) compiled to MJML — not HTML; each `text` block hosts a `TextAreaRich` |
+| `MarkdownRenderer` + blocks, `useMarkdown` | main barrel | **Read-only display** of Markdown (sanitised HTML, code highlighting, `mermaid`/`csv`/`survey`/`html` fences, `streaming` for token-by-token AI output) |
+
+**Deprecated — never for new work** (mieweb/ui#692): main-barrel
+`RichTextEditor` and legacy `TextAreaRich` (the `document.execCommand`
+engine). Replacements: Kerebron `TextAreaRich` for HTML (+ `variableGroups` +
+dictation), `RichEditor` for Markdown. `RichTextEditor` emits raw unsanitised
+`innerHTML` and its output does **not** go through `MarkdownRenderer`.
+
+## Install — the three-legged stool
+
+Every consumer needs all three legs since 0.12 (the main-barrel `Textarea`
+rides the engine, so none of this is optional):
+
+**1. Peers at exactly 0.8.12.** `@kerebron/editor`, `editor-kits`,
+`extension-basic-editor`, `extension-menu`, `wasm` are required peers —
+install with `--save-exact`: newer Kerebron (0.8.13+) pins different
+ProseMirror versions, so a `^0.8.12` range drifts and splits
+`prosemirror-model` (mieweb/ui#709). Collab peers stay optional:
+`@kerebron/extension-yjs`, `yjs`, `y-protocols`.
+
+```sh
+npm install --save-exact @kerebron/editor@0.8.12 @kerebron/editor-kits@0.8.12 \
+  @kerebron/extension-basic-editor@0.8.12 @kerebron/extension-menu@0.8.12 \
+  @kerebron/wasm@0.8.12
+```
+
+**2. ProseMirror overrides in the host.** Even with matching pins,
+ProseMirror's own `^`-ranged internals float to the newest release on any
+fresh install — the library's own overrides do **not** propagate. Add to the
+host (pnpm 10: `overrides:` in `pnpm-workspace.yaml`; npm: `"overrides"`;
+Yarn: `"resolutions"` — full snippets in
+[MIGRATION.md](https://github.com/mieweb/ui/blob/main/MIGRATION.md#esheet-and-encountervisit)):
+
+```yaml
+overrides:
+  prosemirror-view: "1.42.3"
+  prosemirror-model: "1.25.9"
+  prosemirror-state: "1.4.3"
+  prosemirror-transform: "1.10.4"
+```
+
+`prosemirror-view` is 1.42.3 (not Kerebron's pinned 1.40.0) for the protected
+MDY link bridge. Verify after install: `pnpm why prosemirror-model` /
+`pnpm why prosemirror-view` (or `npm ls`/`yarn why`) must each show a
+**single** version. `pnpm dedupe` cannot fix a split — only overrides can.
+
+**3. CSS + WASM assets.** Import `@mieweb/ui/kerebron.css` beside
+`styles.css` (`markdown.css` too if rendering Markdown). The editor loads
+tree-sitter WASM grammars at runtime from `/kerebron-wasm`: serve
+`@kerebron/wasm`'s `assets/` directory at that path — e.g. copy or symlink it
+into Vite's `public/kerebron-wasm`, or add a Storybook `staticDirs` mapping —
+or pass a custom `assetLoad` (`createAssetLoad('/my-path')`) when it lives
+elsewhere.
+
+## The consumer-side patches
+
+The repo's [`patches/@kerebron__*`](https://github.com/mieweb/ui/tree/main/patches)
+fixes target `@kerebron/*@0.8.12` exactly and must be applied **in the host
+app** until fixed upstream — the library's own `patchedDependencies` do not
+propagate. They are pnpm-format (list under `patchedDependencies` as-is);
+npm/yarn hosts convert to their patch tool's format (`patch-package` expects
+its own filenames and `node_modules/…` paths). What breaks without each:
+
+| Patch | Without it |
+| --- | --- |
+| `extension-menu` | Toolbar **Heading/List dropdowns do not fire** in browsers (also: full toolbar re-render per transaction) |
+| `extension-markdown` | **highlight/superscript/subscript marks silently dropped** when saving back to Markdown (patched: round-trip as `<mark>`/`<sup>`/`<sub>` inline HTML, mieweb/ui#536) |
+| `extension-codecrock` | Code-block language `<select>` has no accessible name (axe `select-name` failure) |
+
+## RichEditor integration facts
+
+- **Read on submit, not from mirrored state:** `onChange` can lag the last
+  keystroke — use the ref's `getContent()` (async, awaits the initial load).
+- **Read-once props:** `collab`, `mediaUpload`, `modifyMenu`,
+  `omitExtensions` are read when the editor mounts — **remount via `key`** to
+  change any of them.
+- **`mediaUpload.uploadHandler` is required whenever documents persist.**
+  Without it a pasted image embeds as base64 (`~4 MB screenshot → ~5.8 MB of
+  markdown`) and video as a dead-on-reload blob URL.
+- **`omitExtensions` removes whole features schema-first** — toolbar, input
+  rules and paste handling are all schema-driven, so
+  `['task_list', 'task_item']` removes checklists everywhere in one move.
+- **`modifyMenu`** reshapes the stock toolbar (append macros/dictation
+  controls, drop stock groups) before first render.
+- **Controlled semantics are opt-in:** default tolerates read-once hosts; set
+  `strictValue` for native controlled-input behavior (un-echoed edits
+  revert). Changing `value` reloads the editor unless `collab` is set.
+- **Labelling:** the host is a `div`, not a labelable control — `<label
+  htmlFor>` won't associate; use `aria-label`/`aria-labelledby` (the `id`
+  prop is the anchor).
+
+## Collaboration (Yjs)
+
+`collab: { room, wsUrl?, params? }` joins one shared document per `room` over
+the `/yjs` websocket relay (default `<ws|wss>://<location.host>/yjs`;
+`params` for auth tokens). Requires the optional peers
+`@kerebron/extension-yjs` + `yjs` + `y-protocols`. **Best-effort degrade:**
+if the Yjs **kit fails to load** (e.g. the optional peers are absent), the
+editor still mounts locally and `collab.onUnavailable` fires once, before
+the editor is created — pass it when users must know they're editing
+unshared. `onUnavailable` is **not for connection trouble**: a reachable
+room that is currently disconnected still has the kit loaded, and the
+provider retries on its own. The kit lazy-loads via dynamic `import` so plain-mode consumers
+never pull Yjs code (versions before the mieweb/ui#706 fix had static named
+imports in the lazy chunk — rolldown-Vite builds failed with
+`MISSING_EXPORT`; fix: upgrade, or externalize
+`/^@kerebron\/extension-yjs/`, `/^y-websocket/`). Pair with the
+`CollabStatus` component (Feedback family) for presence/sync UI. Collab mode
+is uncontrolled — remount via `key` to switch rooms.
+
+## Textarea-on-Kerebron behaviour changes (0.12)
+
+- `maxLength` no longer enforced while typing (counter still renders/turns
+  red) — enforce in `onChange` or use `TextAreaPlain`.
+- `labelVariant="floating"`, `resize`, `autoResize={false}` ignored (one-time
+  dev warning).
+- **DOM shape:** no visible `<textarea>` — a ProseMirror `contenteditable`
+  (`role="textbox"`, class `kb-editor`) plus hidden mirror
+  `[data-slot="textarea-mirror"]` carrying `name`/`value`. `textarea { … }`
+  CSS and element refs no longer match; target the `data-slot` hooks
+  (`[data-slot^="textarea-"]` prefix selector, or a concrete slot like
+  `textarea-wrapper`). `getByRole('textbox')` tests keep working.
+- Controlled transforms of `event.target.value` reset formatting (the
+  reported value is flattened plain text).
+
+## EmailEditor constraints
+
+Email `text` blocks are `TextAreaRich` surfaces with
+`omitExtensions={['task_list', 'task_item']}` — checkbox inputs are
+sanitizer-forbidden and inert in mail clients (mieweb/ui#695), so checklists
+are removed schema-first rather than filtered after the fact. Compile
+`renderEmailMjml` output with `mjml`/`mjml-browser` **host-side** (not a
+peer). Sending, recipients and templates are the host's concern.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Typing throws `RangeError: Can not convert … to a Fragment (looks like multiple versions of prosemirror-model)` | Split ProseMirror resolution: Kerebron range drifted to 0.8.13+, or transitive `^`-ranges floated on a fresh install (mieweb/ui#709) | Pin `@kerebron/*` 0.8.12 exact + the four overrides; verify single version via `pnpm why prosemirror-model` |
+| `vite build` fails `MISSING_EXPORT` from `@kerebron/extension-yjs` in a `collabKit-*` chunk | Optional collab peers absent + @mieweb/ui older than the #706 fix (static named imports in the lazy chunk) | Upgrade @mieweb/ui; or externalize `/^@kerebron\/extension-yjs/`, `/^y-websocket/` |
+| Code blocks render without highlighting; 404s for `*.wasm` | `@kerebron/wasm/assets` not served at `/kerebron-wasm` | Serve/symlink the assets dir, or pass `assetLoad` with the actual path |
+| Toolbar Heading/List dropdowns don't open | Host missing the `extension-menu` patch | Apply `patches/@kerebron__extension-menu@0.8.12.patch` in the host |
+| Highlight/superscript/subscript lost after save | Host missing the `extension-markdown` patch (marks absent from the serializer table) | Apply the `extension-markdown` patch (mieweb/ui#536) |
+| axe: `select-name` on code blocks | Host missing the `extension-codecrock` patch | Apply the `extension-codecrock` patch |
+| Pasted screenshot balloons the document / image dies on reload | No `mediaUpload.uploadHandler` — base64/blob embedding | Provide `uploadHandler` returning a hosted URL |
+| Edits revert while typing in a controlled host | Host `onChange` doesn't echo into `value` and `strictValue` is set — or the host echoes flattened text back into a rich surface | Echo the value correctly, or drop `strictValue` for read-once + `getContent()` on submit |
+| `collab` set but edits don't sync, no error | Yjs kit failed to load (missing optional peers) → silent local degrade; or the relay is disconnected (kit loaded, provider retrying) | Install the collab peers and pass `collab.onUnavailable` to surface load failures; for connectivity, check the `/yjs` relay — the provider retries on its own |
+| `<label htmlFor>` doesn't focus/name the editor | Editor host is a `div`, not a labelable control | `aria-label` / `aria-labelledby` via the `id` anchor |
+| Checklist items vanish in EmailEditor | By design — `task_list`/`task_item` are email-unsafe (mieweb/ui#695) | Use a different block structure; not a bug |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mieweb/ui",
-  "version": "0.11.0-dev.54",
+  "version": "0.11.0-dev.56",
   "description": "A themeable, accessible React component library built with Tailwind CSS",
   "author": "Medical Informatics Engineering, Inc.",
   "license": "SEE LICENSE IN LICENSE",