basalt-ui 1.11.0 → 1.12.0

package/AGENTS.md

@@ -6,27 +6,27 @@ Toolchain: Bun runtime, oxlint + oxfmt, conventional commits (empty scope), `mas
 
 ## Subpath ownership
 
-| Subpath                     | Layer           | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| --------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `basalt-ui`                 | mantine-coupled | BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, SettingsSection/SettingsRow/DangerZone)                                                                                                                                                                                                                                                                                                                                          |
-| `basalt-ui/charts`          | headless        | visx chart primitives, sparklines, hooks, and token re-exports (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `basalt-ui/tokens`          | headless        | VX token refs, buildPaletteCss, defineSeries, seriesTokens, groupTokens, alpha (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `basalt-ui/theme-lab`       | mantine-coupled | ThemeLabControls, applyOverrides, COLOR_GROUPS — a low-level inspector for the non-derived structural tokens; identity/color tuning lives in DeriveControls                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `basalt-ui/vite`            | mantine-coupled | basaltViteConfig(opts) — Vite preset for basalt-ui consumer apps; basaltAppPlugin(opts) — PWA head, manifest, and icon metadata derived from the token palette                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `basalt-ui/guard`           | headless        | checkSource, GUARD_RULES, Finding types — the headless theme-guard core                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `basalt-ui/query`           | headless        | createBasaltQueryClient, transport-agnostic unwrap, lazy BasaltQueryDevtools                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `basalt-ui/router-tanstack` | headless        | TanStack Router bridge: useBasaltNav (active route) + useRouterBreadcrumbs + createSearchParamStore (single-select URL-state store) + createMultiSearchParamStore (multi-select URL-state store)                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `basalt-ui/forms`           | mantine-coupled | Mantine form adapter: useBasaltForm, field, FormErrorSummary, useFormDraft (Standard Schema)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `basalt-ui/notifications`   | mantine-coupled | Mantine notifications: notify helpers, typed registry, persisted history, NotificationBell, NotificationCenter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `basalt-ui/commands`        | mantine-coupled | typed command bus + overlay controller, toSpotlightActions, ShortcutsHelp, BasaltOverlays                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `basalt-ui/data`            | mantine-coupled | Convenience barrel pulling both TanStack Table + Virtual peer groups: BasaltDataTable, BasaltVirtualList (Mantine-rendered) — prefer ./data/table or ./data/virtual for per-feature opt-in                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `basalt-ui/data/table`      | mantine-coupled | BasaltDataTable: a sortable data table over TanStack Table, rendered with Mantine (Mantine-rendered)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `basalt-ui/data/virtual`    | mantine-coupled | BasaltVirtualList: a windowed virtual list over TanStack Virtual, rendered with Mantine (Mantine-rendered)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `basalt-ui/agent`           | headless        | Headless streaming-chat layer: useAgentStream, aiSdkTransport (recommended default) + edenTransport, isResumable/ResumableAgentTransport (stream-resumption seam), PartList, coalesceParts, the ForeignPart/definePartRenderers/narrowAgentPart open part-registry seam, plus the multi-thread createThreadsStore + useAgentThreadRuns + outcome-resolver seam (Mantine-free)                                                                                                                                                                                                                                       |
-| `basalt-ui/agent-chat`      | mantine-coupled | Mantine-styled thread-chat components over basalt-ui/agent: ThreadWorkspace, ThreadFeed, ThreadOutcomeCard, ThreadDetailPanel, Composer, ThreadTranscript (open part-renderer registry via its renderers/fallbackRenderer props), threadPartRenderers, ToolChip (Mantine-coupled). remend and motion are required, not optional — ThreadTranscript imports content/markdown.tsx (remend eagerly), and ThreadFeed/ThreadDetailPanel import motion/react eagerly, so this subpath fails to resolve without both installed even though peerDependenciesMeta marks them optional (npm has no per-subpath optionality).  |
-| `basalt-ui/content`         | mantine-coupled | Prose (article/chat typography), CodeBlock (shiki, optional peer), Callout, TableOfContents, ReadingProgress, Markdown (react-markdown + remark-gfm, optional peers, streaming-aware), MermaidDiagram (beautiful-mermaid, optional peer), mdxComponents/createMdxComponents, ArticleLayout (docs-page frame), ArticleCard/ArticleGrid (overview cards), Article model (sortArticles/filterArticles/formatArticleDate), ArticleFilterBar (category/tags filter UI), toArticleActions (Spotlight projector, @mantine/spotlight type-only), GuideLink/GuideDrawer (contextual-help drawer) — the content/prose surface |
-| `basalt-ui/state`           | headless        | createPersistedState (versioned localStorage) + useOnlineStatus — Mantine-free state primitives                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `basalt-ui/connectivity`    | mantine-coupled | ConnectivityProvider (aggregates browser online/offline, React Query onlineManager, SSE, and health-check pings into one status), useConnectivity, and ConnectivityIndicator — auto-mounted by BasaltProvider                                                                                                                                                                                                                                                                                                                                                                                                       |
+| Subpath                     | Layer           | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| --------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `basalt-ui`                 | mantine-coupled | BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, SettingsSection/SettingsRow/DangerZone)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `basalt-ui/charts`          | headless        | visx chart primitives, sparklines, hooks, and token re-exports (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `basalt-ui/tokens`          | headless        | VX token refs, buildPaletteCss, defineSeries, seriesTokens, groupTokens, alpha (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `basalt-ui/theme-lab`       | mantine-coupled | ThemeLabControls, applyOverrides, COLOR_GROUPS — a low-level inspector for the non-derived structural tokens; identity/color tuning lives in DeriveControls                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `basalt-ui/vite`            | mantine-coupled | basaltViteConfig(opts) — Vite preset for basalt-ui consumer apps; basaltAppPlugin(opts) — PWA head, manifest, and icon metadata derived from the token palette                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `basalt-ui/guard`           | headless        | checkSource, GUARD_RULES, Finding types — the headless theme-guard core                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `basalt-ui/query`           | headless        | createBasaltQueryClient, transport-agnostic unwrap, lazy BasaltQueryDevtools                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `basalt-ui/router-tanstack` | headless        | TanStack Router bridge: useBasaltNav (active route) + useRouterBreadcrumbs + createSearchParamStore (single-select URL-state store) + createMultiSearchParamStore (multi-select URL-state store)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `basalt-ui/forms`           | mantine-coupled | Mantine form adapter: useBasaltForm, field, FormErrorSummary, useFormDraft (Standard Schema)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `basalt-ui/notifications`   | mantine-coupled | Mantine notifications: notify helpers, typed registry, persisted history, NotificationBell, NotificationCenter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `basalt-ui/commands`        | mantine-coupled | typed command bus + overlay controller, toSpotlightActions, ShortcutsHelp, BasaltOverlays                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `basalt-ui/data`            | mantine-coupled | Convenience barrel pulling both TanStack Table + Virtual peer groups: BasaltDataTable, BasaltVirtualList (Mantine-rendered) — prefer ./data/table or ./data/virtual for per-feature opt-in                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `basalt-ui/data/table`      | mantine-coupled | BasaltDataTable: a sortable data table over TanStack Table, rendered with Mantine (Mantine-rendered)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `basalt-ui/data/virtual`    | mantine-coupled | BasaltVirtualList: a windowed virtual list over TanStack Virtual, rendered with Mantine (Mantine-rendered)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `basalt-ui/agent`           | headless        | Headless streaming-chat layer: useAgentStream, aiSdkTransport (recommended default) + edenTransport, isResumable/ResumableAgentTransport (stream-resumption seam), PartList, coalesceParts, the ForeignPart/definePartRenderers/narrowAgentPart open part-registry seam, plus the multi-thread createThreadsStore + useAgentThreadRuns + outcome-resolver seam (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `basalt-ui/agent-chat`      | mantine-coupled | Mantine-styled thread-chat components over basalt-ui/agent: ThreadWorkspace, ThreadFeed, ThreadOutcomeCard, ThreadDetailPanel, Composer, ThreadTranscript (open part-renderer registry via its renderers/fallbackRenderer props), threadPartRenderers, ToolChip (Mantine-coupled). motion is required, not optional — ThreadFeed/ThreadDetailPanel import motion/react eagerly, so this subpath fails to resolve without it installed even though peerDependenciesMeta marks it optional (npm has no per-subpath optionality). remend is genuinely optional here — ThreadTranscript reaches it only through the lazy dynamic import() inside content/markdown.tsx.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `basalt-ui/content`         | mantine-coupled | Prose (article/chat typography), CodeBlock (shiki, optional peer), Callout, TableOfContents, ReadingProgress, Markdown (react-markdown + remark-gfm, optional peers; `streaming` is a rendering mode ONLY — `contentTrust` is the independent security input, and any surface rendering agent/model output must pin `contentTrust="untrusted"`, the sole input to the image-origin allowlist; a `fenceRenderers` registry — settledOnly/FenceRenderer/FenceRenderers/FenceRenderContext; `sanitizeSchema`, an additions-only SanitizeSchemaExtension merged over BASALT_SANITIZE_SCHEMA via mergeSanitizeSchema; the remend streaming-repair pass is now a lazy optional peer), MermaidDiagram (beautiful-mermaid, optional peer), mdxComponents/createMdxComponents, ArticleLayout (docs-page frame), ArticleCard/ArticleGrid (overview cards), Article model (sortArticles/filterArticles/formatArticleDate), ArticleFilterBar (category/tags filter UI), toArticleActions (Spotlight projector, @mantine/spotlight type-only), GuideLink/GuideDrawer (contextual-help drawer) — the content/prose surface |
+| `basalt-ui/state`           | headless        | createPersistedState (versioned localStorage) + useOnlineStatus — Mantine-free state primitives                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `basalt-ui/connectivity`    | mantine-coupled | ConnectivityProvider (aggregates browser online/offline, React Query onlineManager, SSE, and health-check pings into one status), useConnectivity, and ConnectivityIndicator — auto-mounted by BasaltProvider                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 ## Hard rules
 

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+# [1.12.0](https://github.com/jkrumm/basalt-ui/compare/v1.11.0...v1.12.0) (2026-08-03)
+
+
+### Bug Fixes
+
+* stop the tool-part fold carrying stale state and dropping parts ([d47a35f](https://github.com/jkrumm/basalt-ui/commit/d47a35f7d58d985037814b8771b0e426c5396403))
+
+
+### Features
+
+* give the composer its slots and a way to write into them ([e115b7e](https://github.com/jkrumm/basalt-ui/commit/e115b7efd428a09701307f9fe7448f72e69606bb))
+* let a server-backed store stand behind the threads API ([dfdf9c5](https://github.com/jkrumm/basalt-ui/commit/dfdf9c543554167ff9d780dda2cb662238eff419))
+* open the markdown seams and split trust from streaming ([90d406e](https://github.com/jkrumm/basalt-ui/commit/90d406e13311a107a6a160d8f66ff42e41085a75))
+* prove the 1.12.0 seams from outside the package ([0231345](https://github.com/jkrumm/basalt-ui/commit/0231345f88f9d8f7191db6c733ac124d5fae85fd))
+
 # [1.11.0](https://github.com/jkrumm/basalt-ui/compare/v1.10.0...v1.11.0) (2026-08-03)
 
 

package/README.md

@@ -236,7 +236,7 @@ deleted rather than silently surviving into the next real skew.
 | `./data/table`      | coupled  | `BasaltDataTable` — sortable data table over TanStack Table, rendered with Mantine                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `./data/virtual`    | coupled  | `BasaltVirtualList` — windowed virtual list over TanStack Virtual, rendered with Mantine                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `./agent`           | **free** | Headless streaming layer (`useAgentStream`, `PartList`) + multi-thread `createThreadsStore` / `useAgentThreadRuns` / outcome seam                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `./agent-chat`      | coupled  | Mantine-styled thread-chat components over `./agent`: `ThreadWorkspace`, `ThreadFeed`, `ThreadOutcomeCard`, `ThreadDetailPanel`, `Composer`, `ThreadTranscript`, `threadPartRenderers` — **requires `remend` and `motion`**, not merely optional peers; see [Requirements](#requirements)                                                                                                                                                                                                                                          |
+| `./agent-chat`      | coupled  | Mantine-styled thread-chat components over `./agent`: `ThreadWorkspace`, `ThreadFeed`, `ThreadOutcomeCard`, `ThreadDetailPanel`, `Composer`, `ThreadTranscript`, `threadPartRenderers` — **requires `motion`**, not merely an optional peer; see [Requirements](#requirements)                                                                                                                                                                                                                                                     |
 | `./state`           | **free** | `createPersistedState` (versioned localStorage) + `useOnlineStatus` — Mantine-free state primitives                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `./connectivity`    | coupled  | `ConnectivityProvider` (aggregates browser/React-Query/SSE/health-check status), `useConnectivity`, `ConnectivityIndicator` — auto-mounted by `BasaltProvider`                                                                                                                                                                                                                                                                                                                                                                     |
 | `./content`         | coupled  | `Prose`, `CodeBlock`, `Callout`, `TableOfContents`, `ReadingProgress`, `Markdown`, `MermaidDiagram`, `ArticleLayout`, `ArticleCard` / `ArticleGrid`, `GuideLink` / `GuideDrawer`, `mdxComponents`                                                                                                                                                                                                                                                                                                                                  |
@@ -443,20 +443,19 @@ import { BasaltVirtualList } from 'basalt-ui/data/virtual'
 ### `./content` — prose + markdown
 
 ````bash
-bun add remend                      # required — `Markdown` imports it eagerly, so the subpath won't resolve without it
-bun add react-markdown remark-gfm   # Markdown
-bun add shiki                       # CodeBlock / fenced-code highlighting (brings @shikijs/langs, @shikijs/themes as optional peers)
-bun add beautiful-mermaid           # MermaidDiagram / ```mermaid fences
+bun add react-markdown remark-gfm     # Markdown
+bun add remend                        # `Markdown`'s streaming-tail repair — optional, lazy dynamic import
+bun add rehype-sanitize               # `Markdown`'s sanitize pass — optional, lazy dynamic import
+bun add shiki                         # CodeBlock / fenced-code highlighting (brings @shikijs/langs, @shikijs/themes as optional peers)
+bun add beautiful-mermaid             # MermaidDiagram / ```mermaid fences
 ````
 
-`remend` is the one peer here that is not lazy: `Markdown` imports it at the top of the module, so
-`basalt-ui/content` fails to resolve without it even if you never render `Markdown` yourself. That
-eager import also reaches past this subpath: both the root `.` entry and `./agent-chat`'s
-`ThreadWorkspace` / `ThreadTranscript` import `Markdown` directly (not lazily) as their text
-renderer, so `remend` is listed as **required** in the [Requirements](#requirements) table too, not
-only here.
-Everything else degrades gracefully when absent (markdown falls back to plain text, fences to
-plain mono, mermaid renders nothing). `Markdown` is the package's **only** markdown
+Every peer here is lazy: `Markdown` reaches all of them through a dynamic `import()`, so
+`basalt-ui/content` resolves and renders with none of them installed. Absence degrades gracefully
+— never a crash: without `react-markdown`/`remark-gfm`, markdown falls back to plain text; without
+`remend`, the streaming tail renders unrepaired; without `rehype-sanitize`, the sanitize pass is
+skipped (dev-warned once); without `shiki`, fences fall back to plain mono; without
+`beautiful-mermaid`, mermaid fences render nothing. `Markdown` is the package's **only** markdown
 renderer — it backs long-form content and AI chat alike:
 
 ```tsx
@@ -465,12 +464,16 @@ import { Markdown, Prose, CodeBlock, TableOfContents } from 'basalt-ui/content'
 // Long-form: 72ch measure, article typography, heading anchors + slug dedup.
 <Markdown>{article.body}</Markdown>
 
-// AI output: chat density, block-split + memoized, `remend`-repaired in-flight tail.
-<Markdown streaming density="chat">{part.text}</Markdown>
+// AI output: chat density, block-split + memoized, `remend`-repaired in-flight tail. Model-generated
+// text is untrusted regardless of whether it has finished streaming — pin `contentTrust` explicitly.
+<Markdown streaming density="chat" contentTrust="untrusted">{part.text}</Markdown>
 ```
 
-`streaming` also tightens image URLs to same-origin — LLM-authored markdown can otherwise exfiltrate
-via a remote image URL. Full doctrine: `agent/rules/basalt-content.md`.
+`streaming` is a rendering mode only — it says the text is still arriving, not who wrote it. The
+security input is the separate `contentTrust` prop (`'trusted' | 'untrusted'`), the sole driver of
+the `allowedImagePrefixes` default: same-origin-only when untrusted, since LLM-authored markdown can
+otherwise exfiltrate via a remote image URL. Any surface rendering agent/model output must pin
+`contentTrust="untrusted"` explicitly. Full doctrine: `agent/rules/basalt-content.md`.
 
 ### `./agent` — streaming-chat layer
 
@@ -606,16 +609,22 @@ Wire the drift gate to catch doctrine falling behind after a basalt-ui upgrade:
 
 ## Requirements
 
-| Peer                    | Version   | Notes                                                                                                                                                                                                                                                                             |
-| ----------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `react` / `react-dom`   | `^19`     | required                                                                                                                                                                                                                                                                          |
-| `@mantine/core`         | `^9.3`    | required                                                                                                                                                                                                                                                                          |
-| `@mantine/hooks`        | `^9.3`    | required                                                                                                                                                                                                                                                                          |
-| `@tanstack/react-query` | —         | required for the root `.` entry — `BasaltProvider` hard-requires it at build time; NOT required by `./agent-chat`, which doesn't touch it                                                                                                                                         |
-| `remend`                | `1.3.0`   | required for both the root `.` entry and `./agent-chat` — both export `ThreadWorkspace`/`ThreadTranscript` (`agent-chat/thread-message.tsx`), which statically imports `content/markdown.tsx`, which imports `remend` eagerly; see [`./content`](#content--prose--markdown) below |
-| `motion`                | `12.42.0` | required for both the root `.` entry and `./agent-chat` — both export `ThreadFeed`/`ThreadDetailPanel` (`agent-chat/thread-feed.tsx` / `thread-detail-panel.tsx`), which import `motion/react` eagerly; the root's `ThemeToggle` also uses it                                     |
-
-`./agent-chat`'s `optionalPeers` in `llms.txt`/`surfaces.ts` still lists `remend` and `motion` (npm has no per-subpath optionality in `peerDependenciesMeta`), but treat both as required when installing just this subpath — see the subpath table above.
+| Peer                    | Version   | Notes                                                                                                                                                                                                                                         |
+| ----------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `react` / `react-dom`   | `^19`     | required                                                                                                                                                                                                                                      |
+| `@mantine/core`         | `^9.3`    | required                                                                                                                                                                                                                                      |
+| `@mantine/hooks`        | `^9.3`    | required                                                                                                                                                                                                                                      |
+| `@tanstack/react-query` | —         | required for the root `.` entry — `BasaltProvider` hard-requires it at build time; NOT required by `./agent-chat`, which doesn't touch it                                                                                                     |
+| `motion`                | `12.42.0` | required for both the root `.` entry and `./agent-chat` — both export `ThreadFeed`/`ThreadDetailPanel` (`agent-chat/thread-feed.tsx` / `thread-detail-panel.tsx`), which import `motion/react` eagerly; the root's `ThemeToggle` also uses it |
+
+`remend` was required through 1.10.x — `content/markdown.tsx` imported it at the top of the module,
+so both the root `.` entry and `./agent-chat`'s `ThreadWorkspace`/`ThreadTranscript` hard-required it
+transitively. It is now a genuinely optional, lazy peer (dynamic `import()`); see
+[`./content`](#content--prose--markdown) below.
+
+`./agent-chat`'s `optionalPeers` in `llms.txt`/`surfaces.ts` lists `remend` and `motion` (npm has no
+per-subpath optionality in `peerDependenciesMeta`) — only `motion` needs to be treated as required
+when installing just this subpath; `remend` is accurately optional there too now.
 
 Optional peer batteries and their packages are listed per battery above.
 

package/agent/rules/basalt-content.md

@@ -76,10 +76,23 @@ token, no debouncing needed.
 - The LAST (in-flight) block is repaired via `remend` before rendering — unclosed `**`/`` ` ``/
   `~~`/`$$`, an incomplete `[text](url` link (remend rewrites it to
   `streamdown:incomplete-link` — any `streamdown:` href is dropped by the link hardening below).
+  `remend` is a lazy optional peer (dynamic `import()`); the root `.` entry no longer hard-requires
+  it.
+- **`streaming` is a RENDERING mode only** — it says the text is still arriving, not who wrote it.
+  Trust is a separate prop, `contentTrust: 'trusted' | 'untrusted'`, and it is the sole input to the
+  image allowlist below. Any surface rendering agent/model output must pin
+  `contentTrust="untrusted"` explicitly — a finished agent message is still model-generated, so
+  don't lean on `streaming` as a stand-in for trust.
 - **Hardening is ALWAYS ON**, streaming or not: `allowedLinkPrefixes` (default `['https://',
-'mailto:', '#', '/']`) / `allowedImagePrefixes` (default `['https://', '/']`) / `defaultOrigin`
-  (resolves a relative URL before the allowlist check's result is used). A disallowed `href`/`src`
-  renders as an unlinked `<span>` / a dropped image — never a raw unsafe URL.
+'mailto:', '#', '/']`) / `defaultOrigin` (resolves a relative URL before the allowlist check's
+  result is used) / a `rehype-sanitize` pass (optional peer; `sanitizeSchema` only ADDS to the
+  default schema, never removes from it). `allowedImagePrefixes` defaults off `contentTrust`, NOT
+  `streaming`: `['https://', '/']` when trusted, same-origin-only `['/']` when untrusted — an
+  auto-fetched image is the classic prompt-injection exfiltration channel. `contentTrust` itself
+  defaults to `'untrusted'` when `streaming` is set, `'trusted'` otherwise — a backward-compat
+  floor, not the policy (see the bullet above). An explicit `allowedImagePrefixes` always overrides
+  the `contentTrust` default. A disallowed `href`/`src` renders as an unlinked `<span>` / a dropped
+  image — never a raw unsafe URL.
 - Fenced code highlights/upgrades per BLOCK on settle, not per token — the in-flight fence renders
   plain mono (`CodeBlock showCopy={false}`) until its block settles.
 - Heading ids: a document-wide `SlugTracker` in non-streaming mode gives correct cross-heading

package/dist/agent/adapter.d.ts

@@ -0,0 +1,146 @@
+import type { ChatMessage } from './history.js';
+import type { AgentOutcome } from './outcome.js';
+import type { AgentPart } from './parts.js';
+import type { AgentThread, ThreadStatus, ThreadsStore } from './thread.js';
+/**
+ * The async persistence contract behind a `ThreadsStore`. Every method may reject; the wrapping
+ * store treats a rejection as "the optimistic edit did not happen" and rolls it back.
+ *
+ * Implement this against whatever owns the transcript (Postgres, an HTTP API, IndexedDB) and
+ * verify it with `threadsStoreAdapterContract` — the suite pins the parts of the contract that
+ * prose cannot enforce, chiefly `appendMessage`'s idempotency.
+ *
+ * ## What `createAdapterThreadsStore` guarantees you
+ *
+ * **Per-thread write ordering.** Writes carrying the same thread id reach this adapter strictly in
+ * issue order, each one awaiting the previous, so a write that depends on a row existing is never
+ * issued before that row's `createThread` has RESOLVED. This matters because the primary send path
+ * is one synchronous block — `create()`, `select()`, `markRead()`, `appendMessage()`,
+ * `setStatus()` — which without ordering would hand you three dependent writes against a row you
+ * have not created yet. You therefore never have to tolerate (or invent an upsert for) an
+ * out-of-order write. Writes for DIFFERENT thread ids stay concurrent and carry no ordering
+ * guarantee relative to each other.
+ *
+ * ## What it requires of you
+ *
+ * **Read-after-write consistency on `listThreads`.** A `listThreads` STARTED after a write has
+ * resolved must reflect that write. The store keeps a write's optimistic patch applied until such
+ * a list lands, then drops it; an eventually-consistent backend (a stale read replica, a cached
+ * list) will therefore flash the pre-write state back into the UI. `threadsStoreAdapterContract`
+ * pins this.
+ *
+ * @example
+ * const postgresThreadsAdapter = (api: Api): ThreadsStoreAdapter => ({
+ *   listThreads: (signal) => api.threads.get({ fetch: { signal } }),
+ *   loadThread: (id, signal) => api.threads({ id }).get({ fetch: { signal } }),
+ *   createThread: ({ id, meta }) => api.threads.post({ id, meta }),
+ *   // ...
+ * })
+ */
+export type ThreadsStoreAdapter<TPart = AgentPart> = {
+    /** All threads, NEWEST-FIRST (same ordering contract as `ThreadsStore.threads`). */
+    readonly listThreads: (signal?: AbortSignal) => Promise<readonly AgentThread<TPart>[]>;
+    /** One thread by id, or `null` when it does not exist. Must not throw on an unknown id. */
+    readonly loadThread: (id: string, signal?: AbortSignal) => Promise<AgentThread<TPart> | null>;
+    /**
+     * Materialize a new thread under the CLIENT-MINTED `id`. The id is minted client-side because
+     * `ThreadsStore.create()` returns synchronously — there is no await to hand a server id back
+     * through. The created thread starts empty: `messages: []`, `outcome: null`,
+     * `status: 'pending'`, `read: false`, with `createdAt`/`updatedAt` set.
+     */
+    readonly createThread: (i: {
+        readonly id: string;
+        readonly meta?: Record<string, unknown>;
+    }) => Promise<void>;
+    /**
+     * CONTRACT: idempotent on `message.id`. The id is client-minted and is the ONLY idempotency
+     * key — a retried or double-fired write with the same id must be a no-op, not a second row.
+     */
+    readonly appendMessage: (i: {
+        readonly threadId: string;
+        readonly message: ChatMessage<TPart>;
+    }) => Promise<void>;
+    readonly setStatus: (i: {
+        readonly threadId: string;
+        readonly status: ThreadStatus;
+    }) => Promise<void>;
+    readonly setOutcome: (i: {
+        readonly threadId: string;
+        readonly outcome: AgentOutcome;
+    }) => Promise<void>;
+    /** `token: undefined` CLEARS the token — the stored thread must then read `resumeToken` as absent. */
+    readonly setResumeToken: (i: {
+        readonly threadId: string;
+        readonly token: string | undefined;
+    }) => Promise<void>;
+    readonly markRead: (threadId: string) => Promise<void>;
+    /** Removing an unknown id is a no-op, not an error. */
+    readonly removeThread: (threadId: string) => Promise<void>;
+};
+export type AdapterThreadsStoreOptions = {
+    /**
+     * Re-list threads whenever the window regains focus. Off by default — a background tab that
+     * refocuses should not surprise a consumer with a network round-trip it did not ask for.
+     * @default false
+     */
+    readonly revalidateOnFocus?: boolean;
+};
+/**
+ * Wraps an async `ThreadsStoreAdapter` into the synchronous `ThreadsStore` every component takes.
+ *
+ * Call this ONCE per module (not inside a component), exactly like `createThreadsStore`. All
+ * components calling the returned hook share one registry, backed by `useSyncExternalStore`.
+ *
+ * Semantics:
+ * - **Optimistic.** Every mutation applies locally first, so `create()` can return an id
+ *   synchronously and the UI never waits on a round-trip.
+ * - **Ordered per thread.** Writes for one thread id reach the adapter in issue order, each
+ *   awaiting the previous — so the dependent writes of a `create()`-then-send land after
+ *   `createThread` has resolved. Different threads stay concurrent. See `ThreadsStoreAdapter`.
+ * - **Revalidate on success, coalesced.** When a write resolves the store re-lists; the patch is
+ *   dropped only once a list has actually refreshed the confirmed base, so server-side derivations
+ *   win over the local guess with no gap in between. Writes that resolve while a list is already in
+ *   flight share ONE follow-up instead of each restarting it, so a burst of writes costs at most
+ *   two round trips (the in-flight one, plus one follow-up), not one per write — see `revalidate`.
+ * - **Roll back on rejection.** A rejected write's patch is discarded, the rejection is surfaced
+ *   on `error`, and the store re-lists to converge on whatever the server really did. Patches are
+ *   tracked individually, so a failing write rolls back only itself and not whatever else was in
+ *   flight beside it.
+ * - **`hydrated` means "a `listThreads` has succeeded"**, not "a load has been attempted". A
+ *   store that is `!hydrated` with a non-undefined `error` failed to load; check both.
+ * - **`error` latches the most recent failure until something disproves it.** A successful
+ *   `listThreads` clears a LOAD failure; it leaves a WRITE failure alone, since a working list is
+ *   no evidence the rejected write landed. A write clears a latched write failure only if it was
+ *   issued after that failure (a retry) — never the writes that were already queued behind it.
+ *
+ * `select` is local-only — which thread is active is UI state, not something the adapter owns.
+ * `clear()` maps onto `removeThread` for each known thread, since the adapter has no bulk delete.
+ *
+ * @example
+ * export const useThreads = createAdapterThreadsStore(myAdapter, { revalidateOnFocus: true })
+ */
+export declare function createAdapterThreadsStore<TPart = AgentPart>(adapter: ThreadsStoreAdapter<TPart>, opts?: AdapterThreadsStoreOptions): () => ThreadsStore<TPart>;
+/** One conformance case. `run` rejects with a plain Error describing the violation. */
+export type ThreadsStoreAdapterContractCase = {
+    readonly name: string;
+    readonly run: () => Promise<void>;
+};
+/**
+ * A test-runner-agnostic conformance suite for a `ThreadsStoreAdapter` implementation.
+ *
+ * This ships in the published package, so it deliberately imports NO test framework and depends
+ * on no assertion library — each case throws a plain `Error`. Drive it from whatever runner the
+ * consumer uses.
+ *
+ * `makeAdapter` is called ONCE PER CASE and must hand back a fresh, empty backend: the cases are
+ * independent and none of them cleans up after itself.
+ *
+ * @example
+ * import { threadsStoreAdapterContract } from 'basalt-ui/agent'
+ *
+ * for (const c of threadsStoreAdapterContract(() => postgresThreadsAdapter(freshDb()))) {
+ *   test(c.name, () => c.run())
+ * }
+ */
+export declare function threadsStoreAdapterContract<TPart>(makeAdapter: () => ThreadsStoreAdapter<TPart> | Promise<ThreadsStoreAdapter<TPart>>): readonly ThreadsStoreAdapterContractCase[];
+//# sourceMappingURL=adapter.d.ts.map

package/dist/agent/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/agent/adapter.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAE5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAIvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,mBAAmB,CAAC,KAAK,GAAG,SAAS,IAAI;IACnD,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,SAAS,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IACtF,2FAA2F;IAC3F,QAAQ,CAAC,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAA;IAC7F;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE;QACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;QACnB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACxC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnB;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC,EAAE;QAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;QACzB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,KAAK,CAAC,CAAA;KACrC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnB,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE;QACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;QACzB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;KAC9B,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnB,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE;QACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;QACzB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;KAC/B,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnB,sGAAsG;IACtG,QAAQ,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE;QAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;QACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;KACnC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD,uDAAuD;IACvD,QAAQ,CAAC,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3D,CAAA;AAID,MAAM,MAAM,0BAA0B,GAAG;IACvC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;CACrC,CAAA;AAgCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,GAAG,SAAS,EACzD,OAAO,EAAE,mBAAmB,CAAC,KAAK,CAAC,EACnC,IAAI,CAAC,EAAE,0BAA0B,GAChC,MAAM,YAAY,CAAC,KAAK,CAAC,CA0e3B;AAID,uFAAuF;AACvF,MAAM,MAAM,+BAA+B,GAAG;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAClC,CAAA;AAYD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAC/C,WAAW,EAAE,MAAM,mBAAmB,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,GAClF,SAAS,+BAA+B,EAAE,CA0K5C"}