@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/ui/components/tabs-overflow.js

@@ -20,9 +20,16 @@
  */
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 /**
- * Slack used by the hysteresis rule below, in px. Matches
- * 2 x --appkit-tabs-arrow-size (2rem) — the width the two in-flow arrows
- * reclaim from the list when they unmount.
+ * Slack used by the hysteresis rule below, in px. Nominally
+ * 2 x --appkit-tabs-arrow-size (2rem), the width of the two in-flow arrows.
+ *
+ * 🛑 It is a SAFETY MARGIN, not a measurement, and the distinction is what
+ * this file got wrong badly enough to crash production. The arrows are not
+ * the only thing `data-arrows="true"` changes — it also hides the list's
+ * scrollbar — so the real width reclaimed on unmount is this number minus the
+ * platform scrollbar, and on a machine with overlay scrollbars it is this
+ * number exactly. The rule below is written to be stable for every value in
+ * that range rather than assuming one of them.
  */
 const ARROW_SLACK_PX = 64;
 /** Sub-pixel tolerance: scrollWidth/clientWidth can differ by <1px at some zooms. */
@@ -51,19 +58,65 @@ export function useTabsOverflow(listRef, activeKey) {
         const overflow = el.scrollWidth - el.clientWidth;
         const previous = stateRef.current.hasArrows;
         /*
-         * 🛑 HYSTERESIS — do not collapse this to a single threshold.
+         * 🛑 HYSTERESIS — do not collapse this to a single threshold, and do not
+         * "tidy" the negative one below back to a positive number.
          *
          * The arrows are IN-FLOW, so mounting them shrinks the list's clientWidth
-         * by ~ARROW_SLACK_PX, which INCREASES the measured overflow. With one
-         * threshold a strip 10px wider than its container oscillates forever:
-         *   hidden -> overflow 10 -> show -> overflow 74 -> still overflowing
-         *   -> ... -> hide -> overflow -54 -> hide -> widen -> overflow 10 -> show
+         * and INCREASES the measured overflow. With one threshold a strip 10px
+         * wider than its container oscillates forever.
+         *
+         * ## 🛑 THE PREVIOUS RULE WAS `overflow > ARROW_SLACK_PX` AND IT CRASHED
+         * ## EVERY STORE PAGE IN PRODUCTION WITH React #185 (max update depth).
          *
-         * Once the arrows are up they may only come down if the content would
+         * Its stability proof — "they may only come down if the content would
          * STILL fit after reclaiming their width, which by construction leaves
-         * overflow <= 0 afterwards. That makes the rule provably stable.
+         * overflow <= 0" — rests on mounting the arrows changing the measured
+         * overflow by EXACTLY `ARROW_SLACK_PX`. That is true of the arrows alone
+         * and FALSE of the net effect, because of a rule 100 lines away in
+         * `Tabs.style.css`:
+         *
+         *     .appkit-tabs-shell[data-arrows="true"] .appkit-tabs-list {
+         *       scrollbar-width: none;
+         *     }
+         *     …__arrow is 2rem; …-list::-webkit-scrollbar { display: none }
+         *
+         * The same `data-arrows="true"` that mounts the arrows also HIDES the
+         * scrollbar, handing the list back ~15px of clientWidth. So the net
+         * reclaimed width is ~49px, not 64 — and for any strip overflowing by
+         * 2..15px the two thresholds each imply the other:
+         *
+         *   hidden, overflow 10  -> 10 > 1    -> SHOW
+         *   shown,  overflow 59  -> 59 > 64?  -> no -> HIDE
+         *   hidden, overflow 10  -> …forever
+         *
+         * `useLayoutEffect` below runs on every render by design, so the loop is
+         * unbounded and React tears the tree down. The `sameState` guard cannot
+         * help: the state genuinely differs each pass.
+         *
+         * ## The rule now, stable for ANY reclaimed width
+         *
+         * Let r = whatever mounting the arrows adds to `overflow` (unknown, and
+         * provably NOT a constant — it depends on CSS this file cannot see, the
+         * platform's scrollbar width, and whether the user has overlay
+         * scrollbars). All we know is 0 <= r.
+         *
+         *   show:  hidden AND overflow >  EPSILON
+         *   hide:  shown  AND overflow <= -ARROW_SLACK_PX
+         *
+         * After SHOWING:  overflow' = overflow + r > EPSILON >= -ARROW_SLACK_PX,
+         *                 so the hide test cannot fire. No loop.
+         * After HIDING:   overflow' = overflow - r <= -ARROW_SLACK_PX <= EPSILON,
+         *                 so the show test cannot fire. No loop.
+         *
+         * Stable for every r >= 0, which is the point: the previous rule was
+         * stable only for one exact value of r that nothing enforced.
+         *
+         * The cost is deliberate conservatism — once up, the arrows stay up until
+         * the strip has a full ARROW_SLACK_PX of genuine slack. An arrow that
+         * lingers on a strip that just fits is a cosmetic blemish; the thing it
+         * replaces is a white screen.
          */
-        const hasArrows = previous ? overflow > ARROW_SLACK_PX : overflow > EPSILON;
+        const hasArrows = previous ? overflow > -ARROW_SLACK_PX : overflow > EPSILON;
         const max = el.scrollWidth - el.clientWidth;
         // Math.abs: scrollLeft is negative (or inverted) in RTL depending on engine.
         const position = Math.abs(el.scrollLeft);

package/dist/ui/components/toolbar-collapse.d.ts

@@ -1,3 +1,16 @@
+/** Below this the toolbar defaults to collapsed. Matches the `lg` boundary
+ *  that both toolbars already use to switch between their mobile and desktop
+ *  rows, so the default flips at the same width the layout does. */
+/**
+ * Below `lg` — the complement of `DESKTOP_QUERY` in `features/layout`.
+ *
+ * Exported so `OverflowRow` can dock its collapsed control into the bottom bar
+ * at exactly the width the tab bar exists at. It is NOT imported from
+ * `features/layout`: this is `ui/`, and a `ui → features` edge inverts the
+ * layering and is how `audit-import-cycles` regressions start. One literal in
+ * the lower layer, shared, beats two that can drift apart.
+ */
+export declare const MOBILE_QUERY = "(max-width: 1023px)";
 /**
  * Tri-state on purpose: `null` means "the user has never chosen", which is
  * what lets the viewport supply the default. A plain boolean cannot express

package/dist/ui/components/toolbar-collapse.js

@@ -19,7 +19,16 @@ const STORAGE_PREFIX = "appkit:sticky-toolbar-collapsed:";
 /** Below this the toolbar defaults to collapsed. Matches the `lg` boundary
  *  that both toolbars already use to switch between their mobile and desktop
  *  rows, so the default flips at the same width the layout does. */
-const MOBILE_QUERY = "(max-width: 1023px)";
+/**
+ * Below `lg` — the complement of `DESKTOP_QUERY` in `features/layout`.
+ *
+ * Exported so `OverflowRow` can dock its collapsed control into the bottom bar
+ * at exactly the width the tab bar exists at. It is NOT imported from
+ * `features/layout`: this is `ui/`, and a `ui → features` edge inverts the
+ * layering and is how `audit-import-cycles` regressions start. One literal in
+ * the lower layer, shared, beats two that can drift apart.
+ */
+export const MOBILE_QUERY = "(max-width: 1023px)";
 /**
  * Tri-state on purpose: `null` means "the user has never chosen", which is
  * what lets the viewport supply the default. A plain boolean cannot express

package/dist/ui/index.d.ts

@@ -16,6 +16,8 @@ export type { SectionProps, SectionBackgroundConfig, ArticleProps, MainProps, As
 export { Section, sectionBackgroundStyle, Article, Main, Aside, Nav, BlockHeader, BlockFooter, Ul, Ol, Li, Table, Thead, Tbody, Tr, Th, Td, Code, Pre, Blockquote, Figure, Figcaption, Dl, Dt, Dd, } from "./components/Semantic";
 export type { DivProps } from "./components/Div";
 export { Div } from "./components/Div";
+export { Disclaimer } from "./components/Disclaimer";
+export type { DisclaimerProps } from "./components/Disclaimer";
 export type { SpecTableProps, SpecTableRow } from "./components/SpecTable";
 export { SpecTable } from "./components/SpecTable";
 export type { ColorVariant } from "./components/Typography";
@@ -93,6 +95,10 @@ export type { SliderProps } from "./components/Slider";
 export { Slider } from "./components/Slider";
 export type { CheckboxProps } from "./components/Checkbox";
 export { Checkbox } from "./components/Checkbox";
+export type { ChartProps } from "./components/Chart";
+export { Chart, ChartFromJson } from "./components/Chart";
+export type { ChartKind, ChartSeries, ChartSpec, ChartSpecResult, } from "./components/chart-spec";
+export { CHART_KINDS, CHART_MAX_SERIES, exceedsSeriesLimit, parseChartAttr, parseChartSpec, } from "./components/chart-spec";
 export type { RadioGroupProps, RadioOption, RadioItemProps } from "./components/Radio";
 export { RadioGroup, RadioItem } from "./components/Radio";
 export type { ToggleProps } from "./components/Toggle";
@@ -209,6 +215,8 @@ export type { RichTextProps } from "./rich-text/RichText";
 export { RichText } from "./rich-text/RichText";
 export type { RichTextRendererProps } from "./rich-text/RichTextRenderer";
 export { RichTextRenderer } from "./rich-text/RichTextRenderer";
+export type { RichTextSegment } from "./rich-text/chart-blocks";
+export { chartFigureHtml, hasChartBlock, splitChartBlocks, } from "./rich-text/chart-blocks";
 export type { RichTextEditorProps } from "./components/RichTextEditor";
 export { RichTextEditor } from "./components/RichTextEditor";
 export type { ListingLayoutProps, ListingLayoutLabels, } from "./components/ListingLayout";

package/dist/ui/index.js

@@ -30,6 +30,12 @@ export { FormErrorSummary } from "./forms/index.js";
 export { buildColumns, createColumnBuilder, renderBoolean, renderCurrency, renderCurrencyCompact, renderCount, renderNullable, renderRating, getStatusTone, getResourceIcon, } from "./columns/index.js";
 export { Section, sectionBackgroundStyle, Article, Main, Aside, Nav, BlockHeader, BlockFooter, Ul, Ol, Li, Table, Thead, Tbody, Tr, Th, Td, Code, Pre, Blockquote, Figure, Figcaption, Dl, Dt, Dd, } from "./components/Semantic.js";
 export { Div } from "./components/Div.js";
+/*
+ * Phase 12 — the one way to render a disclaimer. `id` only: there is no `text`
+ * prop, because an escape hatch would make it a styled box and the legally
+ * material disclaimers would be written at their call sites again.
+ */
+export { Disclaimer } from "./components/Disclaimer.js";
 export { SpecTable } from "./components/SpecTable.js";
 export { Heading, Text, Label, Caption, Span } from "./components/Typography.js";
 // --- Filter chip group (SB10-C completion, S8 2026-05-13) --------------------
@@ -76,6 +82,8 @@ export { DateInput, DateRangeInput } from "./components/DateInput.js";
 export { Textarea } from "./components/Textarea.js";
 export { Slider } from "./components/Slider.js";
 export { Checkbox } from "./components/Checkbox.js";
+export { Chart, ChartFromJson } from "./components/Chart.js";
+export { CHART_KINDS, CHART_MAX_SERIES, exceedsSeriesLimit, parseChartAttr, parseChartSpec, } from "./components/chart-spec.js";
 export { RadioGroup, RadioItem } from "./components/Radio.js";
 export { Toggle } from "./components/Toggle.js";
 export { QuantityStepper } from "./components/QuantityStepper.js";
@@ -142,6 +150,7 @@ export { classNames, mergeTailwindClasses } from "./style.helper.js";
 export { SideModal } from "./components/SideModal.js";
 export { RichText } from "./rich-text/RichText.js";
 export { RichTextRenderer } from "./rich-text/RichTextRenderer.js";
+export { chartFigureHtml, hasChartBlock, splitChartBlocks, } from "./rich-text/chart-blocks.js";
 export { RichTextEditor } from "./components/RichTextEditor.js";
 export { ListingLayout } from "./components/ListingLayout.js";
 export { SlottedListingView } from "./components/SlottedListingView.js";

package/dist/ui/rich-text/RichText.d.ts

@@ -29,6 +29,15 @@ export interface RichTextProps {
    * ```
      */
     highlightCode?: (code: string, lang: string) => string;
+    /**
+     * Render `<figure data-chart>` placeholders as live charts. Default true.
+     *
+     * Set `false` for untrusted user-generated content where an author should not
+     * be able to mount a component at all — the placeholder then renders as the
+     * empty `<figure>` it is. The JSON is still validated either way; this is
+     * about whether a chart is an affordance on that surface.
+     */
+    charts?: boolean;
 }
 /**
  * RichText renders sanitised HTML from a CMS / ProseMirror output.
@@ -42,4 +51,4 @@ export interface RichTextProps {
  * <RichText html={desc} copyableCode />
  * ```
  */
-export declare function RichText({ html, className, proseClass, copyableCode, highlightCode, }: RichTextProps): import("react").JSX.Element;
+export declare function RichText({ html, className, proseClass, copyableCode, highlightCode, charts, }: RichTextProps): import("react").JSX.Element;

package/dist/ui/rich-text/RichText.js

@@ -3,6 +3,8 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useMemo } from "react";
 import { Div } from "../components/Div.js";
 import { normalizeRichTextHtml } from "../../utils/string.formatter.js";
+import { splitChartBlocks } from "./chart-blocks.js";
+import { ChartFromJson } from "../components/Chart.js";
 // --- Allowed HTML tags (safe subset — no script/object; iframe allowed for YouTube only) -------
 const ALLOWED_TAGS = new Set([
     "p",
@@ -52,6 +54,19 @@ const ALLOWED_ATTRS = {
     "*": ["class", "id", "lang", "dir", "aria-label", "role", "tabindex"],
     a: ["href", "title", "target", "rel"],
     img: ["src", "alt", "width", "height", "loading", "data-align"],
+    /*
+     * `data-chart` carries a JSON ChartSpec that the renderer hydrates into
+     * <Chart>. Safe to allow because it is DATA, never markup: it is read with
+     * `getAttribute`, run through `JSON.parse`, and then validated field-by-field
+     * by `parseChartSpec`, which accepts only a fixed `kind` enum, string labels
+     * and finite numbers. Nothing in it reaches `innerHTML`, so a script payload
+     * smuggled into the string fails validation and renders as an error message.
+     *
+     * 🛑 It must stay on `figure` only. Allowing it via "*" would let it ride on
+     * an <a> or <iframe>, where the surrounding element's own attack surface is
+     * the problem rather than the attribute.
+     */
+    figure: ["data-chart"],
     td: ["colspan", "rowspan"],
     th: ["colspan", "rowspan", "scope"],
     ol: ["type", "start"],
@@ -167,7 +182,7 @@ function attachCopyButtons(container) {
  * <RichText html={desc} copyableCode />
  * ```
  */
-export function RichText({ html, className = "", proseClass = "prose max-w-none dark:prose-invert", copyableCode = false, highlightCode, }) {
+export function RichText({ html, className = "", proseClass = "prose max-w-none dark:prose-invert", copyableCode = false, highlightCode, charts = true, }) {
     const safe = useMemo(() => {
         const sanitized = sanitiseHtml(normalizeRichTextHtml(html));
         if (!highlightCode || typeof document === "undefined")
@@ -186,5 +201,21 @@ export function RichText({ html, className = "", proseClass = "prose max-w-none
             attachCopyButtons(el);
         }
     };
-    return (_jsx(Div, { ref: ref, className: `appkit-rich-text ${proseClass} ${className}`, dangerouslySetInnerHTML: { __html: safe } }));
+    /*
+     * Split AFTER sanitising, never before.
+     *
+     * The sanitiser round-trips through `DOMParser` and re-serialises, which
+     * rewrites the single-quoted `data-chart='{"k":1}'` we emit into
+     * double-quoted `data-chart="{&quot;k&quot;:1}"`. `splitChartBlocks` handles
+     * both spellings precisely because of this step — splitting first would
+     * leave chart segments that the sanitiser never got to inspect.
+     */
+    const segments = useMemo(() => (charts ? splitChartBlocks(safe) : [{ type: "html", html: safe }]), [safe, charts]);
+    // Fast path: no charts. Byte-identical to the pre-chart render.
+    if (segments.length === 1 && segments[0].type === "html") {
+        return (_jsx(Div, { ref: ref, className: `appkit-rich-text ${proseClass} ${className}`, dangerouslySetInnerHTML: { __html: segments[0].html } }));
+    }
+    return (_jsx(Div, { ref: ref, className: `appkit-rich-text ${proseClass} ${className}`, children: segments.map((seg, i) => seg.type === "html" ? (_jsx("div", { className: "appkit-rich-text__seg", dangerouslySetInnerHTML: { __html: seg.html } }, `h${i}`)) : (
+        // eslint-disable-next-line react/no-array-index-key
+        _jsx(ChartFromJson, { json: seg.json }, `c${i}`))) }));
 }

package/dist/ui/rich-text/RichText.style.css

@@ -25,6 +25,24 @@
   border-bottom-color: var(--appkit-color-border);
 }
 
+/*
+ * The chart-draft panel the toolbar's "Chart" button opens.
+ *
+ * It sits between the toolbar and the editable area, so it needs the same
+ * recessive surface the toolbar has — without it the panel reads as part of the
+ * document being edited rather than as editor chrome, which is misleading when
+ * the thing inside it is a block of JSON.
+ */
+.appkit-rich-text-editor__chart {
+  background-color: var(--appkit-color-surface-raised);
+  border-bottom: 1px solid var(--appkit-color-border);
+}
+
+.dark .appkit-rich-text-editor__chart {
+  background-color: var(--appkit-color-slate-900);
+  border-bottom-color: var(--appkit-color-border);
+}
+
 .appkit-rich-text-editor__btn {
   border: 1px solid var(--appkit-color-border);
   color: var(--appkit-color-zinc-700);
@@ -43,77 +61,42 @@
 
 
 /* --------------------------------------------------------------------------
- * THE PROSE PALETTE — rebound to appkit theme tokens.
- *
- * 🛑 `dark:prose-invert` CANNOT COMPILE IN THIS PROJECT. Do not "fix" dark-mode
- * rich text by adding it to a call site, and do not add
- * `@source inline("dark:prose-invert")` to globals.css.
+ * THE PROSE PALETTE LIVES IN THE CONSUMER, NOT HERE.
  *
- * Every `proseClass` string in appkit carries `dark:prose-invert` and NONE of
- * them has ever generated a rule, because:
- *   - the consumer build excludes appkit from scanning
- *     (`src/app/globals.css` → `@source not "../../appkit"`), and
- *   - `appkit/tailwind.config.js` does not load `@tailwindcss/typography`,
- *     so appkit's own `dist/tailwind-utilities.css` cannot emit it either.
+ * 🛑 Do NOT reinstate a `:root .prose { --tw-prose-*: ... !important }` block
+ * in this file. One lived here for months and it NEVER APPLIED.
  *
- * So `--tw-prose-invert-*` is DEFINED and never switched on. Every rich-text
- * surface on the site — product and auction descriptions, blog posts, policy
- * pages, FAQ answers, category `contentBody`, pre-orders, classifieds, digital
- * codes, live items, prize draws, events — rendered the light-theme palette in
- * every theme: body at gray-700 and links at gray-900, i.e. near-black on a
- * dark page. The links were effectively invisible.
+ * The typography plugin emits `.prose { --tw-prose-*: <tailwind gray> }`, and
+ * the consumer's `important: true` makes each of those `!important` inside
+ * `@layer utilities`. The block here was unlayered, and justified itself with
+ * "`:root .prose` is (0,2,0) against `.prose`'s (0,1,0), so specificity
+ * decides and the outcome does not depend on bundle order."
  *
- * It was not merely unstyled, it was OVERRIDING: `important: true` in
- * `tailwind.config.js` emits `.prose :where(a) { color: var(--tw-prose-links)
- * !important }`, which beat the themed `.dark .appkit-rich-text a` rule further
- * down this file. All that theme-aware CSS was dead on arrival.
+ * Specificity is never consulted. For the IMPORTANT tier, cascade-layer order
+ * is REVERSED and unlayered sorts LOWEST, so a layered `!important` beats an
+ * unlayered one at any specificity (Root Cause #106, measured in a browser).
+ * The plugin's hardcoded light-mode grays therefore won in every theme —
+ * links at gray-900, i.e. near-black on the near-black dark page, and
+ * black-instead-of-teal in light. The fix was invisible to every gate because
+ * the CSS was present and correct-looking in `dist/styles.css`; only a
+ * rendered page shows it losing.
  *
- * Rebinding the VARIABLES fixes it at the only point both problems meet: every
- * prose rule reads `var(--tw-prose-*)`, so one block re-themes body, links,
- * headings, bold, lists, quotes, captions, code and tables at once — in both
- * built-in themes AND in any admin-authored custom theme, which `prose-invert`
- * could never have done (its palette is hardcoded Tailwind grays).
+ * Owner is now `tailwind.config.js` → `theme.extend.typography`, which makes
+ * the plugin emit the appkit tokens in the first place so there is exactly
+ * one declaration and no contest. Each binds to an `--appkit-color-*` that is
+ * redefined per theme, so prose re-themes for the built-in themes and for any
+ * admin-authored one.
  *
- * 🛑 The specificity is deliberate and must not be lowered. `.prose` declares
- * these variables with `!important`, so an equal-importance override is decided
- * by EMISSION ORDER between two separate stylesheets — the non-deterministic
- * trap of Root Cause #79. `:root .prose` is (0,2,0) against `.prose`'s (0,1,0),
- * so specificity decides and the outcome does not depend on bundle order. The
- * dark block at (0,3,0) also outranks `.dark .prose-invert` (0,2,0), so this
- * stays correct even if someone later makes `prose-invert` compile.
- *
- * Not scoped to `.appkit-rich-text` on purpose: `PolicyPageView` and the scams
- * FAQ page apply `prose` to a bare `<div>` and had the identical defect.
+ * 🛑 `dark:prose-invert` CANNOT COMPILE IN THIS PROJECT. Do not "fix" dark
+ * rich text by adding it to a call site, and do not add
+ * `@source inline("dark:prose-invert")` to globals.css. Every `proseClass`
+ * string in appkit carries it and none has ever generated a rule, because the
+ * consumer build excludes appkit from scanning (`src/app/globals.css` →
+ * `@source not "../../appkit"`) and `appkit/tailwind.config.js` does not load
+ * `@tailwindcss/typography`, so appkit's own `dist/tailwind-utilities.css`
+ * cannot emit it either. It is moot now regardless: the tokens above invert on
+ * their own, which `prose-invert` could never do with its hardcoded grays.
  * -------------------------------------------------------------------------- */
-:root .prose {
-  --tw-prose-body: var(--appkit-color-text-muted) !important;
-  --tw-prose-headings: var(--appkit-color-text) !important;
-  --tw-prose-lead: var(--appkit-color-text-muted) !important;
-  --tw-prose-links: var(--appkit-color-primary-600) !important;
-  --tw-prose-bold: var(--appkit-color-text) !important;
-  --tw-prose-counters: var(--appkit-color-text-faint) !important;
-  --tw-prose-bullets: var(--appkit-color-text-faint) !important;
-  --tw-prose-hr: var(--appkit-color-border) !important;
-  --tw-prose-quotes: var(--appkit-color-text) !important;
-  --tw-prose-quote-borders: var(--appkit-color-primary) !important;
-  --tw-prose-captions: var(--appkit-color-text-faint) !important;
-  --tw-prose-kbd: var(--appkit-color-text) !important;
-  --tw-prose-kbd-shadows: 24 24 27 !important;
-  --tw-prose-code: var(--appkit-color-text) !important;
-  --tw-prose-pre-code: var(--appkit-color-slate-200) !important;
-  --tw-prose-pre-bg: var(--appkit-color-slate-800) !important;
-  --tw-prose-th-borders: var(--appkit-color-border) !important;
-  --tw-prose-td-borders: var(--appkit-color-border) !important;
-}
-
-/* Only the values that are genuinely theme-specific. Everything above already
- * inverts, because `--appkit-color-text`/`-text-muted`/`-border` are redefined
- * per theme in tokens.css — which is the whole point of binding to them. */
-:root.dark .prose {
-  --tw-prose-links: var(--appkit-color-secondary-400) !important;
-  --tw-prose-kbd-shadows: 250 250 250 !important;
-  --tw-prose-pre-bg: var(--appkit-color-surface) !important;
-}
 
 /* --------------------------------------------------------------------------
  * Base wrapper. All selectors are scoped to .appkit-rich-text so they
@@ -200,27 +183,31 @@
 }
 
 /* --- Links ---------------------------------------------------------------- */
+/* No `.dark` variant, deliberately: `--appkit-color-link` is redefined per
+ * theme, so one rule covers every theme including admin-authored ones. The two
+ * `.dark .appkit-rich-text a` rules that used to sit here were also dead —
+ * non-important against the plugin's `.prose :where(a){color:…!important}`.
+ *
+ * Decoration binds to `currentColor` rather than naming the token a second
+ * time. That matters beyond brevity: the colour here IS still overridden by
+ * the plugin on any element that also carries `.prose`, so a hardcoded
+ * decoration colour could disagree with the ink actually rendered. With
+ * `currentColor` the underline follows whatever won. */
 .appkit-rich-text a {
-  color: var(--appkit-color-primary-600);
+  color: var(--appkit-color-link);
   text-decoration: underline;
-  text-decoration-color: color-mix(in srgb, var(--appkit-color-primary-600) 60%, transparent);
+  text-decoration-color: color-mix(in srgb, currentColor 60%, transparent);
   text-underline-offset: 2px;
   transition: color 150ms, text-decoration-color 150ms;
 }
 
+/* Hover moves the link toward the page's own text colour, which darkens it in
+ * a light theme and lightens it in a dark one — so this needs no per-theme
+ * pair either. The plugin sets no `a:hover`, so unlike the resting colour
+ * above this rule is genuinely the one in effect. */
 .appkit-rich-text a:hover {
-  color: var(--appkit-color-primary-700);
-  text-decoration-color: color-mix(in srgb, var(--appkit-color-primary-700) 70%, transparent);
-}
-
-.dark .appkit-rich-text a {
-  color: var(--appkit-color-secondary-400);
-  text-decoration-color: color-mix(in srgb, var(--appkit-color-secondary-400) 60%, transparent);
-}
-
-.dark .appkit-rich-text a:hover {
-  color: var(--appkit-color-secondary-300);
-  text-decoration-color: color-mix(in srgb, var(--appkit-color-secondary-300) 60%, transparent);
+  color: color-mix(in srgb, var(--appkit-color-link) 80%, var(--appkit-color-text));
+  text-decoration-color: currentColor;
 }
 
 /* --- Tables --------------------------------------------------------------- */
@@ -362,3 +349,20 @@
 .dark .appkit-rich-text del {
   color: var(--appkit-color-zinc-400);
 }
+
+/*
+ * Chart-block segment wrapper.
+ *
+ * `RichTextRenderer` has to split the HTML around `<figure data-chart>` and
+ * each resulting run needs an element to carry `dangerouslySetInnerHTML` —
+ * there is no way to inject HTML without one. `display: contents` removes that
+ * element from the box tree so the runs lay out exactly as they did when they
+ * were one `innerHTML` dump.
+ *
+ * 🛑 Without this, `prose`'s adjacency and first/last-child margin rules
+ * restart at every chart, so paragraphs either side of a chart space
+ * differently from paragraphs anywhere else on the page.
+ */
+.appkit-rich-text__seg {
+  display: contents;
+}

package/dist/ui/rich-text/RichTextRenderer.d.ts

@@ -3,6 +3,14 @@ export interface RichTextRendererProps {
     html?: string | null;
     className?: string;
     proseClass?: string;
+    /**
+     * Render `<figure data-chart>` placeholders as live charts. Default true.
+     *
+     * Pass `false` where a chart cannot work — an email body, a plain-text
+     * export, an OG image — so the placeholder is simply dropped rather than
+     * mounting a client component into a context that cannot hydrate it.
+     */
+    charts?: boolean;
 }
 /**
  * SSR-safe HTML renderer for admin/CMS-authored rich text content.
@@ -12,5 +20,26 @@ export interface RichTextRendererProps {
  *
  * For user-generated content or untrusted HTML, use <RichText> instead
  * (client-only, runs the DOM-based sanitizer).
+ *
+ * ## 🛑 It is no longer a single `innerHTML` dump, and why that is safe
+ *
+ * Chart blocks are stored as `<figure data-chart='{json}'>` and have to become
+ * real components to be theme-aware, so the HTML is split and the chart
+ * segments are replaced with `<ChartFromJson>`. Two properties keep this from
+ * being a regression:
+ *
+ *  - **The fast path is unchanged.** `splitChartBlocks` rejects on a substring
+ *    test, so content with no chart returns one segment and renders through the
+ *    same single `dangerouslySetInnerHTML` as before.
+ *  - **Splitting cannot introduce markup.** Segments are slices of the original
+ *    string, concatenated in document order; nothing is rewritten. A malformed
+ *    chart figure fails the match and stays ordinary HTML.
+ *
+ * 🛑 The prose wrapper stays on the OUTER element, and each segment's own
+ * wrapper is `display: contents` (`.appkit-rich-text__seg`). A segment needs an
+ * element to carry `dangerouslySetInnerHTML`, but leaving that element in the
+ * box tree restarts `prose`'s adjacency and first/last-child margin rules at
+ * every chart — so paragraphs either side of a chart would space differently
+ * from paragraphs anywhere else on the page.
  */
-export declare function RichTextRenderer({ html, className, proseClass, }: RichTextRendererProps): React.JSX.Element | null;
+export declare function RichTextRenderer({ html, className, proseClass, charts, }: RichTextRendererProps): React.JSX.Element | null;

package/dist/ui/rich-text/RichTextRenderer.js

@@ -1,4 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { splitChartBlocks } from "./chart-blocks.js";
+import { ChartFromJson } from "../components/Chart.js";
 /**
  * SSR-safe HTML renderer for admin/CMS-authored rich text content.
  *
@@ -7,9 +9,39 @@ import { jsx as _jsx } from "react/jsx-runtime";
  *
  * For user-generated content or untrusted HTML, use <RichText> instead
  * (client-only, runs the DOM-based sanitizer).
+ *
+ * ## 🛑 It is no longer a single `innerHTML` dump, and why that is safe
+ *
+ * Chart blocks are stored as `<figure data-chart='{json}'>` and have to become
+ * real components to be theme-aware, so the HTML is split and the chart
+ * segments are replaced with `<ChartFromJson>`. Two properties keep this from
+ * being a regression:
+ *
+ *  - **The fast path is unchanged.** `splitChartBlocks` rejects on a substring
+ *    test, so content with no chart returns one segment and renders through the
+ *    same single `dangerouslySetInnerHTML` as before.
+ *  - **Splitting cannot introduce markup.** Segments are slices of the original
+ *    string, concatenated in document order; nothing is rewritten. A malformed
+ *    chart figure fails the match and stays ordinary HTML.
+ *
+ * 🛑 The prose wrapper stays on the OUTER element, and each segment's own
+ * wrapper is `display: contents` (`.appkit-rich-text__seg`). A segment needs an
+ * element to carry `dangerouslySetInnerHTML`, but leaving that element in the
+ * box tree restarts `prose`'s adjacency and first/last-child margin rules at
+ * every chart — so paragraphs either side of a chart would space differently
+ * from paragraphs anywhere else on the page.
  */
-export function RichTextRenderer({ html, className = "", proseClass = "prose max-w-none dark:prose-invert", }) {
+export function RichTextRenderer({ html, className = "", proseClass = "prose max-w-none dark:prose-invert", charts = true, }) {
     if (!html)
         return null;
-    return (_jsx("div", { className: `appkit-rich-text ${proseClass} ${className}`.trim(), dangerouslySetInnerHTML: { __html: html } }));
+    const wrapperClass = `appkit-rich-text ${proseClass} ${className}`.trim();
+    const segments = charts ? splitChartBlocks(html) : [{ type: "html", html }];
+    // Single HTML segment — the overwhelmingly common case. Identical to the
+    // pre-chart behaviour, down to the element shape.
+    if (segments.length === 1 && segments[0].type === "html") {
+        return (_jsx("div", { className: wrapperClass, dangerouslySetInnerHTML: { __html: segments[0].html } }));
+    }
+    return (_jsx("div", { className: wrapperClass, children: segments.map((seg, i) => seg.type === "html" ? (_jsx("div", { className: "appkit-rich-text__seg", dangerouslySetInnerHTML: { __html: seg.html } }, `h${i}`)) : (
+        // eslint-disable-next-line react/no-array-index-key
+        _jsx(ChartFromJson, { json: seg.json }, `c${i}`))) }));
 }

package/dist/ui/rich-text/chart-blocks.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Splitting rich-text HTML around `<figure data-chart>` placeholders.
+ *
+ * ## 🛑 Why this is regex and not a DOM parse
+ *
+ * `RichTextRenderer` is a React Server Component — no `DOMParser`, no
+ * `document`. So the split has to work on the string, and it is only safe to do
+ * that because the shape being matched is one we WRITE: a childless
+ * `<figure data-chart='…'></figure>` emitted by the chart toolbar button.
+ *
+ * This is deliberately not a general HTML parser and must not grow into one. It
+ * matches exactly one element shape and hands everything else through
+ * untouched, so a malformed chart figure degrades to "rendered as ordinary
+ * HTML" rather than corrupting the document around it.
+ *
+ * ## 🛑 Why the JSON needs entity decoding
+ *
+ * A `ChartSpec` is full of `"` characters, so the attribute is written
+ * single-quoted. But anything that round-trips the HTML through a DOM — the
+ * client sanitiser's `DOMParser`, a contenteditable surface, an admin preview —
+ * re-serialises it double-quoted with the inner quotes as `&quot;`. Both
+ * spellings therefore occur in stored content, and a renderer that handles only
+ * the one it writes will fail on its own saved output.
+ *
+ * Pure. No React, no DOM, safe on the server.
+ */
+import type { ChartSpec } from "../components/chart-spec";
+/** A run of ordinary HTML, or a chart placeholder's raw JSON payload. */
+export type RichTextSegment = {
+    type: "html";
+    html: string;
+} | {
+    type: "chart";
+    json: string;
+};
+/**
+ * Decode the entity subset an HTML serialiser can introduce inside an
+ * attribute value.
+ *
+ * 🛑 `&amp;` is decoded LAST. Decoding it first turns a legitimately encoded
+ * `&amp;quot;` into `&quot;` and then into `"`, which injects a quote the
+ * author never wrote and breaks the JSON parse — the classic double-decode bug.
+ */
+export declare function decodeAttrEntities(s: string): string;
+/**
+ * Split HTML into alternating prose and chart segments, in document order.
+ *
+ * Returns a single `html` segment when there are no charts, so the common case
+ * costs one regex test and the caller's fast path stays a plain innerHTML
+ * render.
+ */
+export declare function splitChartBlocks(html: string): RichTextSegment[];
+/** True when the content carries at least one chart placeholder. Stateless. */
+export declare function hasChartBlock(html: string | null | undefined): boolean;
+/**
+ * Build the placeholder a toolbar or a seed fixture should emit.
+ *
+ * Single-quoted, with any single quote in the payload escaped as `&#39;` so the
+ * attribute cannot be terminated early by a label containing an apostrophe —
+ * "Blader's choice" is an entirely ordinary series label.
+ */
+export declare function chartFigureHtml(spec: ChartSpec): string;