basalt-ui 1.40.3 → 2.0.0

package/src/commands/shortcut-format.ts

@@ -18,7 +18,8 @@
 /**
  * Returns true when running on macOS. SSR-safe — returns false when navigator is unavailable.
  * Uses userAgentData.platform when available; falls back to userAgent string regex.
- * Never call during render — use only inside useEffect to avoid hydration mismatches.
+ * Reads the client's platform, so during SSR/hydration render it through `useSyncExternalStore`
+ * with a `false` server snapshot (as `ShortcutsHelp` does) rather than calling it bare in render.
  */
 export function detectMac(): boolean {
   if (typeof navigator === 'undefined') return false
@@ -64,14 +65,14 @@ function plainKey(key: string): string {
 /**
  * Convert a shortcut string to a list of Kbd-friendly tokens.
  * 'Mod+S' → ['⌘', 'S'] (mac) or ['Ctrl', 'S'] (other).
- * 'Shift+Mod+P' → ['⇧', '⌘', 'P'] (mac) or ['Shift', 'Ctrl', 'P'] (other).
+ * 'Mod+Shift+P' → ['⌘', '⇧', 'P'] (mac) or ['Ctrl', 'Shift', 'P'] (other).
  * Named keys read as glyphs on mac and Title-case words elsewhere:
  * 'Mod+Backspace' → ['⌘', '⌫'] (mac) or ['Ctrl', 'Backspace'] (other).
  * isMac is the post-mount platform flag; defaults false on SSR / first render.
  *
  * @example
  * parseShortcut('Mod+S', true)         // ['⌘', 'S']
- * parseShortcut('Shift+Mod+P', false)  // ['Shift', 'Ctrl', 'P']
+ * parseShortcut('Mod+Shift+P', false)  // ['Ctrl', 'Shift', 'P']
  * parseShortcut('ArrowLeft', true)     // ['←']
  */
 export function parseShortcut(shortcut: string, isMac: boolean): string[] {
@@ -114,7 +115,7 @@ export function parseShortcut(shortcut: string, isMac: boolean): string[] {
  * formatShortcutDisplay('Mod+S', true)          // '⌘S'
  * formatShortcutDisplay('Mod+Backspace', true)  // '⌘⌫'
  * formatShortcutDisplay('Mod+S', false)         // 'Ctrl+S'
- * formatShortcutDisplay('Shift+Mod+P', true)    // '⇧⌘P'
+ * formatShortcutDisplay('Mod+Shift+P', true)    // '⌘⇧P'
  */
 export function formatShortcutDisplay(shortcut: string, isMac: boolean): string {
   const tokens = parseShortcut(shortcut, isMac)

package/src/common/errors.ts

@@ -3,7 +3,7 @@
  * here, so the prefix, the `Component: …` shape and the em-dash-then-remedy rhythm are one decision
  * instead of 60. It is the generalisation of `assertQueryStateLike`, which was the ONLY component
  * in the library naming itself in its own failure (isomorphic finding F-ERR-1: the other 54 fail as
- * raw `TypeError`s that `BasaltErrorBoundary` swallows into a blank subtree).
+ * raw `TypeError`s that `RootBoundary` swallows into a blank subtree).
  *
  * Every builder returns a string; nothing here throws or logs. The caller decides which it is —
  * `assertRequiredProps` throws, `useValidateProps` logs, the mount guards log.
@@ -62,8 +62,8 @@ export function deprecatedProp(
  *
  * Distinct from {@link deprecatedProp} (still read, going away) and {@link oneOf} (read, and the
  * value is out of range): this one renders something the caller did not ask for and nothing in the
- * type system, the linter or the console says so. `ChartFrame`'s `height` under `fill` is the
- * reference case — meteo passed both for the life of the file and never learnt that eight height
+ * type system, the linter or the console says so. A 1.x chart's `height` under `fill` was the
+ * reference case — weatherorb passed both for the life of the file and never learnt that eight height
  * constants and a whole `compact` branch changed no pixel.
  */
 export function ignoredProp(component: string, prop: string, because: string): string {

package/src/common/use-measured-widths.ts

@@ -44,11 +44,14 @@ export function useMeasuredWidths(options: UseMeasuredWidthsOptions): UseMeasure
 
   // Read through refs so a fresh closure each render does not re-run the effect.
   const resolveRef = useRef(resolveRoot)
-  resolveRef.current = resolveRoot
   const extraRef = useRef(extra)
-  extraRef.current = extra
   const onMeasureRef = useRef(onMeasure)
-  onMeasureRef.current = onMeasure
+  // Declared before the measuring effect, so the refs are current by the time it reads them.
+  useIsomorphicLayoutEffect(() => {
+    resolveRef.current = resolveRoot
+    extraRef.current = extra
+    onMeasureRef.current = onMeasure
+  })
 
   useIsomorphicLayoutEffect(() => {
     if (signatureRef.current !== signature) {

package/src/common/validate.ts

@@ -60,7 +60,7 @@ export function useValidateProps(
 /**
  * The same once-per-`(component, message)` dev diagnostic {@link useValidateProps} logs, for a
  * caller that already owns the effect a check would otherwise race — a decision made synchronously
- * inside a `useLayoutEffect` (e.g. `ChartFrame`'s header-slot claim, P2-9) has no business waiting a
+ * inside a `useLayoutEffect` (e.g. a card's header-slot claim, P2-9) has no business waiting a
  * further render for a REACTIVE check on state that effect itself just set: that state update lags
  * one commit behind the decision, and a passive-effect check racing it warns about instances that
  * are about to win in the very next render.
@@ -83,7 +83,7 @@ export function resetValidatedProps(): void {
  *
  * This is the F-ERR-1 remedy, and the reason it is not dev-gated: the component was going to crash
  * either way (`undefined is not an object (evaluating 'field.use')`), so the only thing in question
- * is whether the stack reaching `BasaltErrorBoundary` names the component and the prop. It does
+ * is whether the stack reaching `RootBoundary` names the component and the prop. It does
  * now. A prop that is merely questionable belongs in `useValidateProps`, not here.
  *
  * @example

package/src/content/article-layout.tsx

@@ -129,9 +129,9 @@ export function ArticleLayout({
   // THIS component, not the Popover, so crossing back below the breakpoint would otherwise remount
   // it already open with no user action. Adjusted during render (React's own pattern for resetting
   // state when a derived value changes), not an effect, so there is no open-then-close flash.
-  const prevShowTocRailRef = useRef(showTocRail)
-  if (prevShowTocRailRef.current !== showTocRail) {
-    prevShowTocRailRef.current = showTocRail
+  const [prevShowTocRail, setPrevShowTocRail] = useState(showTocRail)
+  if (prevShowTocRail !== showTocRail) {
+    setPrevShowTocRail(showTocRail)
     if (tocOpen) setTocOpen(false)
   }
 
@@ -167,41 +167,40 @@ export function ArticleLayout({
         </div>
       )}
 
-      {toc &&
-        !showTocRail && (
-          // `.tocTrigger`'s `grid-row: 2` (article-layout.module.css) is EXPLICIT, matching
-          // `.content`'s own row — not left to CSS Grid's auto-placement, which used to land this
-          // in its own row below the content instead of at its top (both are `grid-column: 1`, and
-          // the auto-placement cursor moves past row 2 once `.content` claims it).
-          <Popover
-            opened={tocOpen}
-            onChange={setTocOpen}
-            onDismiss={() => setTocOpen(false)}
-            position="bottom-end"
-            withinPortal
-            shadow="md"
-            radius="sm"
-            trapFocus
-          >
-            <Popover.Target>
-              <Button
-                variant="subtle"
-                color="gray"
-                size="compact-xs"
-                className={classes.tocTrigger}
-                classNames={{ label: classes.tocTriggerLabel }}
-                onClick={() => setTocOpen((current) => !current)}
-              >
-                On this page
-              </Button>
-            </Popover.Target>
-            <Popover.Dropdown className={classes.tocDropdown}>
-              <ScrollArea.Autosize mah="calc(100vh - 108px)" type="hover">
-                <TableOfContents containerRef={articleRef} onNavigate={() => setTocOpen(false)} />
-              </ScrollArea.Autosize>
-            </Popover.Dropdown>
-          </Popover>
-        )}
+      {toc && !showTocRail && (
+        // `.tocTrigger`'s `grid-row: 2` (article-layout.module.css) is EXPLICIT, matching
+        // `.content`'s own row — not left to CSS Grid's auto-placement, which used to land this
+        // in its own row below the content instead of at its top (both are `grid-column: 1`, and
+        // the auto-placement cursor moves past row 2 once `.content` claims it).
+        <Popover
+          opened={tocOpen}
+          onChange={setTocOpen}
+          onDismiss={() => setTocOpen(false)}
+          position="bottom-end"
+          withinPortal
+          shadow="md"
+          radius="sm"
+          trapFocus
+        >
+          <Popover.Target>
+            <Button
+              variant="subtle"
+              color="gray"
+              size="compact-xs"
+              className={classes.tocTrigger}
+              classNames={{ label: classes.tocTriggerLabel }}
+              onClick={() => setTocOpen((current) => !current)}
+            >
+              On this page
+            </Button>
+          </Popover.Target>
+          <Popover.Dropdown className={classes.tocDropdown}>
+            <ScrollArea.Autosize mah="calc(100vh - 108px)" type="hover">
+              <TableOfContents containerRef={articleRef} onNavigate={() => setTocOpen(false)} />
+            </ScrollArea.Autosize>
+          </Popover.Dropdown>
+        </Popover>
+      )}
 
       {(prev !== undefined || next !== undefined) && (
         <footer className={classes.footer}>

package/src/content/article-model.ts

@@ -1,87 +1,4 @@
-/**
- * Article — the structured data model behind `ArticleCard`/`ArticleLayout` (docs/CONTENT-SPEC.md).
- * Pure data + pure functions: no React, no `@mantine/*`. Sortable/filterable article metadata
- * replaces the old preformatted `meta` string so a consumer can build a filter bar or a Spotlight
- * projector on top of it (both are a later stage — this module only ships the model).
- */
-
-export type Article<C extends string = string, T extends string = string> = {
-  readonly slug: string
-  readonly title: string
-  readonly description?: string
-  /** ISO 8601 — sortable. Articles without a date sort last regardless of `ArticleOrder`. */
-  readonly date?: string
-  readonly category?: C
-  readonly tags?: readonly T[]
-  /** Minutes. */
-  readonly readingTime?: number
-}
-
-export type ArticleOrder = 'date-desc' | 'date-asc' | 'title'
-
-/**
- * Sorts articles. Pure — never mutates `articles`, always returns a new array.
- *
- * - `'date-desc'` (default) / `'date-asc'` — compares `date` lexicographically (ISO 8601 sorts
- *   chronologically as a string, so no `Date` parsing is needed). Articles missing a `date` sort
- *   LAST in both directions — a missing date is not "oldest", it's unranked.
- * - `'title'` — `localeCompare` with a PINNED `'en-US'` locale, not the runtime default, so sort
- *   order doesn't drift between environments.
- *
- * Stable: articles that compare equal keep their input order (native `toSorted` is a stable sort).
- */
-export function sortArticles<A extends Article>(
-  articles: readonly A[],
-  order: ArticleOrder = 'date-desc',
-): readonly A[] {
-  if (order === 'title') {
-    return articles.toSorted((a, b) => a.title.localeCompare(b.title, 'en-US'))
-  }
-
-  const direction = order === 'date-asc' ? 1 : -1
-  return articles.toSorted((a, b) => {
-    if (a.date === undefined && b.date === undefined) return 0
-    if (a.date === undefined) return 1
-    if (b.date === undefined) return -1
-    if (a.date === b.date) return 0
-    return a.date < b.date ? -direction : direction
-  })
-}
-
-export type ArticleFilterQuery = {
-  readonly category?: string
-  readonly tags?: readonly string[]
-}
-
-/**
- * Filters articles. Pure — never mutates `articles`.
- *
- * - `category` — exact match. `undefined`/`''` applies no constraint.
- * - `tags` — ANY-OF (OR): an article matches if it carries at least one queried tag.
- *   `undefined`/`[]` applies no constraint.
- * - Both axes given: AND between category and tags, OR within tags — matches the multi-facet
- *   `filterFn` semantics in `data/data-table.tsx`.
- *
- * An empty query (`{}`, or a query where both axes are unset) returns `articles` unchanged.
- */
-export function filterArticles<A extends Article>(
-  articles: readonly A[],
-  query: ArticleFilterQuery,
-): readonly A[] {
-  const { category, tags } = query
-  const hasCategory = category !== undefined && category !== ''
-  const hasTags = tags !== undefined && tags.length > 0
-
-  if (!hasCategory && !hasTags) return articles
-
-  return articles.filter((article) => {
-    if (hasCategory && article.category !== category) return false
-    if (hasTags && tags !== undefined && !tags.some((tag) => article.tags?.includes(tag))) {
-      return false
-    }
-    return true
-  })
-}
+/** Article date formatting for `ArticleLayout` — pure, no React, no `@mantine/*`. */
 
 /**
  * Formats an ISO 8601 date string via `Intl.DateTimeFormat` → `'Jul 16, 2026'`.

package/src/content/copy-action.tsx

@@ -6,7 +6,7 @@
  *
  * The check + tooltip are the entire success signal — no notification (docs/CONTENT-SPEC.md §7).
  * `color="teal"` resolves through the bridged Mantine family, so it stays on the token layer in
- * both schemes (see the package CLAUDE.md on `cssVariablesResolver`).
+ * both schemes (see the package MAINTAINING.md on `cssVariablesResolver`).
  *
  * Not part of the public surface — reach it through `CodeBlock` / `HeadingAnchor`.
  */

package/src/content/glyphs.tsx

@@ -4,7 +4,7 @@
  * hand-drawn ones that drift apart.
  *
  * Inline SVG rather than an icon dep: the framework takes icons as `ReactNode` from the consumer
- * (see the package CLAUDE.md) and ships none, but these are internal chrome of a shipped component,
+ * (see the package MAINTAINING.md) and ships none, but these are internal chrome of a shipped component,
  * not a consumer-facing slot. `currentColor` + `1em`-agnostic sizing keeps them steerable from CSS
  * — the heading anchor sizes its glyph as an optical ratio of whatever step the heading lands on
  * (docs/DESIGN-SPEC.md §3), while the code-block chrome pins a fixed 14px.

package/src/content/index.ts

@@ -1,91 +1,20 @@
 /**
- * `basalt-ui/content` — the content/prose surface (docs/CONTENT-SPEC.md).
+ * `basalt-ui/content` — prose, markdown and the docs-page frame (docs/CONTENT-SPEC.md).
  *
- * Mantine-coupled (like `./forms`/`./notifications`/`./data`): prose typography, a shiki-backed
- * code block (optional peer, lazy singleton), a semantic callout, a scroll-spy TOC rail, a
- * scroll-driven reading-progress bar, a streaming-aware `Markdown` renderer (react-markdown +
- * remark-gfm + rehype-sanitize + remend, all optional peers) with its fence-renderer registry,
- * `MermaidDiagram` (beautiful-mermaid, optional peer), the MDX
- * component map, the docs-page frame (`ArticleLayout`), overview cards (`ArticleCard`/
- * `ArticleGrid`), the contextual-help drawer (`GuideLink`/`GuideDrawer`), and a re-export of the
- * three `basalt-ui/controls` filters an article list needs (`FilterSet`/`ViewTabs`/
- * `MultiSelectFilter`, which replaced the controlled `ArticleFilterBar`). See
- * `agent/rules/basalt-content.md` for the full doctrine + the content-collections recipe.
+ * Mantine-coupled. `Markdown` renders code and mermaid fences itself (`CodeBlock` and
+ * `MermaidDiagram` are internal); `fenceRenderers` is the extension point. Optional peers
+ * (shiki, react-markdown stack, beautiful-mermaid) load lazily; the sanitizer is always on.
  */
-export { Prose } from './prose'
-export type { ProseDensity, ProseProps } from './prose'
-
-export { CodeBlock } from './code-block'
-export type { CodeBlockProps } from './code-block'
 
+export { Prose } from './prose'
 export { Callout } from './callout'
-export type { CalloutKind, CalloutProps } from './callout'
-
+export type { CalloutKind } from './callout'
 export { TableOfContents } from './toc'
-export type { TableOfContentsProps, TocItem } from './toc'
-
-export { ReadingProgress } from './reading-progress'
-export type { ReadingProgressProps } from './reading-progress'
-
-// `SlugTracker` is a PascalCase utility class, not a component — see its own JSDoc `@remarks`
-// (isomorphic harness finding F-DET-1). `new SlugTracker()`, never `<SlugTracker />`.
-export { headingSlug, readingTime, SlugTracker } from './slug'
-export type { ReadingTime } from './slug'
-
-export { HeadingAnchor } from './heading-anchor'
-export type { HeadingAnchorProps } from './heading-anchor'
-
+export type { TocItem } from './toc'
 export { Markdown, settledOnly } from './markdown'
-export type {
-  FenceRenderContext,
-  FenceRenderer,
-  FenceRenderers,
-  MarkdownComponents,
-  MarkdownContentTrust,
-  MarkdownProps,
-} from './markdown'
-
-export { BASALT_SANITIZE_SCHEMA, mergeSanitizeSchema } from './sanitize'
-export type {
-  SanitizePropertyDefinition,
-  SanitizeSchema,
-  SanitizeSchemaExtension,
-  SanitizeSchemaInput,
-} from './sanitize'
-
-export { MermaidDiagram } from './mermaid'
-export type { MermaidDiagramProps } from './mermaid'
-
-export { blockSplit } from './block-split'
-
-export { createMdxComponents, mdxComponents } from './mdx'
-export type { CreateMdxComponentsOptions } from './mdx'
-
+export type { FenceRenderer, FenceRenderers, MarkdownComponents, MarkdownProps } from './markdown'
+export { mergeSanitizeSchema } from './sanitize'
+export type { SanitizeSchemaExtension, SanitizeSchemaInput } from './sanitize'
 export { ArticleLayout } from './article-layout'
-export type { ArticleLayoutMeta, ArticleLayoutProps, ArticleNavTarget } from './article-layout'
-
-export { ArticleCard, ArticleGrid } from './article-card'
-export type { ArticleCardProps, ArticleGridProps } from './article-card'
-
-export { filterArticles, formatArticleDate, sortArticles } from './article-model'
-export type { Article, ArticleFilterQuery, ArticleOrder } from './article-model'
-
-export { toArticleActions } from './article-actions'
-export type { ToArticleActionsOptions } from './article-actions'
-
-// The article filter UI is no longer content's own: `ArticleFilterBar` (controlled,
-// `value`/`onChange`, its own responsive twin) was replaced by the store-bound controls of
-// `basalt-ui/controls` (`docs/CONTROLS-SPEC.md` §3, C2/C9). Re-exported here — not merely
-// documented as moved — so a content-only consumer that never imports `./controls` still gets the
-// three it needs from the surface it was already using. Both spellings are the same module: one
-// component, two import paths.
-export { FilterSet, MultiSelectFilter, ViewTabs } from '../controls'
-export type {
-  FilterSetProps,
-  MultiSelectFilterProps,
-  ViewTabsOption,
-  ViewTabsProps,
-} from '../controls'
-
-export { GuideDrawer, GuideLink } from './guide'
-export type { GuideDrawerProps, GuideLinkProps } from './guide'
+export type { ArticleLayoutMeta } from './article-layout'
+export { GuideLink } from './guide'

package/src/content/markdown.tsx

@@ -29,7 +29,7 @@
  *    through (`./callout-alert`).
  *  - `a`/`img` — hardened via `allowedLinkPrefixes`/`allowedImagePrefixes`/`defaultOrigin`
  *    (`./url-hardening`); a disallowed URL (including remend's `streamdown:incomplete-link`
- *    sentinel) drops the `href`/`src`, and the component renders an unlinked span / nothing.
+ *    sentinel) drops the `href`/`src`, and the component renders an unlinked span / the image's alt text.
  *
  * Streaming mode (`streaming`): `blockSplit` splits `children` into top-level blocks. Every block
  * except the last renders through a memoized renderer (`React.memo`, referentially stable
@@ -183,8 +183,9 @@ function LinkRenderer({ href, children, node: _node, ...rest }: LinkProps) {
 
 function ImageRenderer({ src, alt }: ImgProps) {
   // A blocked src arrives as undefined OR '' depending on how urlTransform dropped it — an
-  // `<img src="">` renders the broken-image glyph, so both cases must skip the element entirely.
-  if (typeof src !== 'string' || src === '') return <span aria-label={alt} />
+  // `<img src="">` renders the broken-image glyph, so both cases skip the element and keep the alt
+  // as plain text — the same "text, never a destination" degrade an unfinished link gets.
+  if (typeof src !== 'string' || src === '') return alt ? <span>{alt}</span> : null
   return <img src={src} alt={alt ?? ''} loading="lazy" />
 }
 

package/src/content/mermaid.tsx

@@ -20,7 +20,7 @@
  * <MermaidDiagram code={'graph TD\n  A --> B'} />
  */
 import type { CSSProperties, ReactNode } from 'react'
-import { useEffect, useMemo, useRef, useState } from 'react'
+import { useEffect, useMemo, useState } from 'react'
 import { CodeBlock } from './code-block'
 import classes from './mermaid.module.css'
 
@@ -67,7 +67,7 @@ export type MermaidDiagramProps = {
 
 export function MermaidDiagram({ code, className, style, fallback }: MermaidDiagramProps) {
   const [mod, setMod] = useState<MermaidModule | null | undefined>(undefined)
-  const lastGoodRef = useRef<string | null>(null)
+  const [lastGood, setLastGood] = useState<string | null>(null)
 
   useEffect(() => {
     let cancelled = false
@@ -82,16 +82,18 @@ export function MermaidDiagram({ code, className, style, fallback }: MermaidDiag
 
   // Pure and synchronous once `mod` is resolved — parse errors keep the last successfully
   // rendered SVG (docs/CONTENT-SPEC.md §2 decision 4) instead of blanking a settled diagram.
-  const html = useMemo(() => {
+  // Three states: `null` = module not resolved yet, `undefined` = this `code` failed to parse (show
+  // the last good SVG), `string` = fresh SVG.
+  const rendered = useMemo(() => {
     if (!mod) return null
     try {
-      const svg = mod.renderMermaidSVG(code, MERMAID_THEME_OPTIONS)
-      lastGoodRef.current = svg
-      return svg
+      return mod.renderMermaidSVG(code, MERMAID_THEME_OPTIONS)
     } catch {
-      return lastGoodRef.current
+      return undefined
     }
   }, [mod, code])
+  if (typeof rendered === 'string' && rendered !== lastGood) setLastGood(rendered)
+  const html = rendered === undefined ? lastGood : rendered
 
   if (html === null) {
     return (

package/src/content/slug.ts

@@ -1,5 +1,5 @@
 /**
- * headingSlug + readingTime — small, pure, zero-dep utils for the content surface.
+ * headingSlug + SlugTracker — small, pure, zero-dep utils for the content surface.
  *
  * `headingSlug` follows the github-slugger algorithm (lowercase, strip punctuation, spaces → `-`)
  * so headings authored in `<Prose>`, markdown, or MDX land on the SAME anchor ids GitHub itself
@@ -44,18 +44,3 @@ export class SlugTracker {
     return seen === 0 ? base : `${base}-${seen}`
   }
 }
-
-/** The distilled reading-time estimate for a body of text. */
-export type ReadingTime = {
-  readonly minutes: number
-  readonly words: number
-}
-
-const WORDS_PER_MINUTE = 225
-
-/** Estimate reading time at 225 wpm, rounded up to the nearest whole minute. */
-export function readingTime(text: string): ReadingTime {
-  const words = text.trim().split(WHITESPACE_RE).filter(Boolean).length
-  const minutes = Math.ceil(words / WORDS_PER_MINUTE)
-  return { minutes, words }
-}

package/src/content/url-hardening.ts

@@ -11,6 +11,11 @@ import type { UrlTransform } from 'react-markdown'
 
 const SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i
 
+// remend's repair sentinels (`[text](streamdown:incomplete-link)`, `![alt](streamdown:incomplete-image)`)
+// are placeholders for a half-streamed URL, never a destination. Rejected before the allowlist so a
+// permissive consumer prefix (`''`, `'streamdown:'`) can't turn one into a real `href`/`img src`.
+const INCOMPLETE_SENTINEL_RE = /^streamdown:incomplete-(?:link|image)$/i
+
 function isAllowedUrl(url: string, prefixes: readonly string[]): boolean {
   return prefixes.some((prefix) => url.startsWith(prefix))
 }
@@ -33,12 +38,13 @@ export type CreateUrlTransformOptions = {
 
 /**
  * Builds the `urlTransform` passed to `<ReactMarkdown>`. Disallowed URLs (including remend's
- * `streamdown:incomplete-link` sentinel — never a member of the default allowlist) resolve to
+ * `streamdown:incomplete-link` / `streamdown:incomplete-image` sentinels, which no allowlist can admit) resolve to
  * `null`, which react-markdown renders as an `href`/`src`-less element; the `a`/`img` component
- * overrides in `./markdown` turn that into an unlinked span / dropped image.
+ * overrides in `./markdown` turn that into an unlinked span / the image's alt text in a plain span.
  */
 export function createUrlTransform(opts: CreateUrlTransformOptions): UrlTransform {
   return (url, key) => {
+    if (INCOMPLETE_SENTINEL_RE.test(url)) return null
     const prefixes = key === 'src' ? opts.allowedImagePrefixes : opts.allowedLinkPrefixes
     if (!isAllowedUrl(url, prefixes)) return null
     return resolveRelativeUrl(url, opts.defaultOrigin)

package/src/controls/actions.tsx

@@ -26,7 +26,7 @@ import classes from './actions.module.css'
 
 /**
  * A button-shaped action. `Anchor` is the router seam basalt HOSTS (the same seam `SidebarItem`
- * uses — pass the one `useNav` builds, or your router's `Link`); `link` is the no-router fallback
+ * uses — pass your router's `Link`); `link` is the no-router fallback
  * and only its `to` is honoured, since resolving `search`/`params` needs a router. Supply `Anchor`
  * whenever the destination carries either.
  */
@@ -74,6 +74,29 @@ export type BarActionCustom = {
 
 export type BarAction = BarActionItem | BarActionMenu | BarActionCustom
 
+/** The one primary action of a page bar (law C6): the first tuple entry, flagged `primary: true`. */
+type PrimaryBarAction = BarAction & { primary: true }
+/** Every other page-bar action; `primary` may only be absent or `false`. */
+type MoreBarAction = BarAction & { primary?: false }
+
+/**
+ * `PageBar.actions`: exactly one primary first, then up to four more. Law C6 as a type — a missing
+ * or second primary and a sixth entry are tsc errors (`docs/V2-SPEC.md` §3).
+ */
+export type PageBarActions =
+  | [PrimaryBarAction]
+  | [PrimaryBarAction, MoreBarAction]
+  | [PrimaryBarAction, MoreBarAction, MoreBarAction]
+  | [PrimaryBarAction, MoreBarAction, MoreBarAction, MoreBarAction]
+  | [PrimaryBarAction, MoreBarAction, MoreBarAction, MoreBarAction, MoreBarAction]
+
+/** `Section.actions`: at most three (law C6). */
+export type SectionActions =
+  | []
+  | [BarAction]
+  | [BarAction, BarAction]
+  | [BarAction, BarAction, BarAction]
+
 /**
  * A home's `actions` slot. `primary` is SINGULAR by type — that is the whole enforcement of law
  * C6's "exactly one primary"; there is no runtime check because a second one cannot be written.

package/src/controls/enum-filter.tsx

@@ -29,7 +29,7 @@
 import { Radio, Stack } from '@mantine/core'
 import type { ReactNode } from 'react'
 import type { BasaltProps } from '../common/props'
-import type { FieldOption } from '../state'
+import type { FieldOption } from '../state/fields'
 import classes from './controls.module.css'
 import { POPOVER_ROW_HIT_GAP, useFilterRegistration, useFilterSurface } from './filter-context'
 import { FilterClearButton, FilterPill } from './filter-pill'

package/src/controls/filter-context.tsx

@@ -114,7 +114,9 @@ export function useFilterRegistration(isActive: boolean, reset: () => void): voi
   // A ref, so a `reset` closure that is fresh every render does not re-run the effect (and so
   // `Reset all` always calls the LATEST setter, not the one captured at registration).
   const resetRef = useRef(reset)
-  resetRef.current = reset
+  useEffect(() => {
+    resetRef.current = reset
+  })
   const stableReset = useCallback(() => {
     resetRef.current()
   }, [])

package/src/controls/filter-set.tsx

@@ -6,7 +6,7 @@
  * **Desktop.** One row, `wrap: nowrap`, and it NEVER scrolls (C7). When the measured pill widths
  * exceed the container the tail folds into a `+N` menu pill — a `ResizeObserver` on the row plus
  * per-slot `offsetWidth`, because the fold point depends on the labels actually painted (the same
- * reasoning as the charts' `autoMargin`), not on a guessed pill width.
+ * reasoning as the charts' measured margins), not on a guessed pill width.
  *
  * **Mobile (`< sm`).** The first `inline` children stay pills; every child — inline ones included —
  * also renders its full-width sheet form inside the `Filters (n)` Drawer — which exists only when
@@ -173,14 +173,12 @@ export function FilterSet({
 function useOverflowFit(rowRef: RefObject<HTMLDivElement | null>, count: number): number {
   const [fit, setFit] = useState(count)
   const widths = useRef<number[]>([])
+  const canObserve = typeof ResizeObserver !== 'undefined'
 
   useEffect(() => {
     const row = rowRef.current
     if (row === null) return
-    if (typeof ResizeObserver === 'undefined') {
-      setFit(count)
-      return
-    }
+    if (!canObserve) return
 
     const measure = (): void => {
       const slots = [...row.querySelectorAll<HTMLElement>('[data-filter-slot]')]
@@ -213,9 +211,9 @@ function useOverflowFit(rowRef: RefObject<HTMLDivElement | null>, count: number)
     return () => {
       observer.disconnect()
     }
-  }, [rowRef, count])
+  }, [rowRef, count, canObserve])
 
-  return fit
+  return canObserve ? fit : count
 }
 
 function fitCount(

package/src/controls/form-layout.tsx

@@ -26,8 +26,8 @@ import type { BasaltProps, SlotStylesProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
 import { BarActionSlot } from './actions'
 import type { SlotActions } from './actions'
-import { WidgetHeader } from '../dashboard'
-import type { WidgetHeaderTitleProps } from '../dashboard'
+import { WidgetHeader } from '../dashboard/widget-header'
+import type { WidgetHeaderTitleProps } from '../dashboard/widget-header'
 import { useFormState } from '../forms/form-state'
 import classes from './form-layout.module.css'