@uniweb/kit 0.9.46 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.9.46",
+  "version": "0.10.0",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
@@ -40,7 +40,8 @@
     "fuse.js": "^7.0.0",
     "shiki": "^3.0.0",
     "tailwind-merge": "^3.6.0",
-    "@uniweb/core": "0.7.34",
+    "@uniweb/semantic-parser": "1.2.0",
+    "@uniweb/core": "0.8.0",
     "@uniweb/scene": "0.1.2"
   },
   "peerDependencies": {

package/src/hooks/useEntityDetail.js

@@ -44,7 +44,7 @@
  * }
  */
 
-import { getUniweb } from '@uniweb/core'
+import { getUniweb, recordDataUrl } from '@uniweb/core'
 import { useFetched } from './useFetched.js'
 
 /**
@@ -63,7 +63,19 @@ export function useEntityDetail(record, options = {}) {
   return useFetched(request)
 }
 
-function buildDetailRequest(record, collection) {
+/**
+ * Build the fetch request for one record's full payload.
+ *
+ * Exported for tests only — not re-exported from the package index. The
+ * static-file branch has to resolve to the same URL the build writes and the
+ * same URL core's dynamic-route auto-detail injects; a test can only assert
+ * that if it can call this without a React tree.
+ *
+ * @param {Object|null} record
+ * @param {string} collection
+ * @returns {{path?: string, url?: string, schema: string}|null}
+ */
+export function buildDetailRequest(record, collection) {
   const slug = record?.slug
   if (!slug || !collection) return null
 
@@ -83,10 +95,11 @@ function buildDetailRequest(record, collection) {
     return { url, schema: collection }
   }
 
-  // Static-file default — the build emitted per-record JSON files.
-  // Phase 5 of the CDN migration moved storage from /data/ to /_data/;
-  // the site router accepts both URL shapes during the transition.
-  return { path: `/_data/${collection}/${slug}.json`, schema: collection }
+  // Static-file default — the build emitted per-record JSON files. Shares
+  // `recordDataUrl` with the build that writes them and with core's
+  // dynamic-route auto-detail injection, which is the other half of this
+  // same feature: the three must resolve one record to one URL.
+  return { path: recordDataUrl(collection, slug), schema: collection }
 }
 
 export default useEntityDetail

package/src/index.js

@@ -131,7 +131,8 @@ export {
 // Styled Components (Tailwind-based)
 // ============================================================================
 
-export { Section, Render } from './styled/Section/index.js'
+export { Section } from './styled/Section/index.js'
+export { Render, SequenceElement } from './styled/Render/index.jsx'
 export { Prose } from './styled/Prose/index.jsx'
 export { Article } from './styled/Article/index.jsx'
 export { Code, Alert, Warning, Table, Details, Divider } from './styled/Section/renderers/index.js'

package/src/styled/Article/index.jsx

@@ -1,84 +1,54 @@
 /**
- * Article Component
+ * Article — a document, in a semantic <article>.
  *
- * Semantic article wrapper with prose typography.
- * Use for blog posts, news articles, documentation pages, etc.
+ * `<Prose>` with the right tag. That is the whole component now, and the point
+ * of it is the element: an article is a self-contained composition, and saying
+ * so in markup is what assistive technology and reader modes act on.
+ *
+ * It used to be its own thing — a prose container wrapped around a SECOND node
+ * walker that read raw ProseMirror. That is why articles rendered with no bold,
+ * no links and no math until 2026-07-30: the walker's `paragraph` case
+ * flattened inline content to plain text, and it had no case for math at all.
+ * Going through `<Render>` means there is one walk, and inline content arrives
+ * from the parser already correct.
  *
  * @module @uniweb/kit/styled/Article
  */
 
 import React from 'react'
-import { cn } from '../../utils/index.js'
-import { Render } from '../Section/Render.jsx'
-
-/**
- * Prose sizes
- */
-const SIZE_CLASSES = {
-  sm: 'prose-sm',
-  base: 'prose-base',
-  lg: 'prose-lg',
-  xl: 'prose-xl',
-  '2xl': 'prose-2xl'
-}
+import { Prose } from '../Prose/index.jsx'
 
 /**
  * Article - Semantic article with prose typography
  *
- * Renders content inside a semantic <article> tag with prose styling.
- * Can accept either children or a content prop (ProseMirror JSON).
- *
  * @param {Object} props
- * @param {Object|Array} [props.content] - ProseMirror content to render
+ * @param {Object|Array} [props.content] - Parsed content (`.sequence`), a
+ *   ProseMirror doc, or an array of ProseMirror nodes
+ * @param {Object} [props.block] - Block instance (supplies content; resolves insets)
+ * @param {Object} [props.components] - Per-element-type renderer overrides
  * @param {string} [props.size='lg'] - Text size: sm, base, lg, xl, 2xl
  * @param {string} [props.className] - Additional CSS classes
- * @param {React.ReactNode} [props.children] - Content to render (alternative to content prop)
+ * @param {React.ReactNode} [props.children] - Content to render (alternative to content)
  *
  * @example
- * // With ProseMirror content
  * <Article content={articleData.content} />
  *
  * @example
- * // With children
- * <Article>
- *   <h1>My Article</h1>
- *   <p>Article content...</p>
- * </Article>
- *
- * @example
- * // Composing with Render
- * <Article size="base" className="dark:prose-invert">
- *   <Render content={proseMirrorContent} />
- * </Article>
+ * <Article block={block} components={{ blockquote: PullQuote }} />
  */
-export function Article({
-  content,
-  block,
-  size = 'lg',
-  className,
-  children,
-  ...props
-}) {
-  const sizeClass = SIZE_CLASSES[size] || SIZE_CLASSES.lg
-
-  // Get content from block if not provided directly
-  let resolvedContent = content
-  if (!resolvedContent && block) {
-    resolvedContent = block.rawContent
-  }
-
-  // If it's a ProseMirror doc, get the content array
-  if (resolvedContent?.type === 'doc') {
-    resolvedContent = resolvedContent.content
-  }
-
+export function Article({ content, block, components, size = 'lg', className, children, ...props }) {
   return (
-    <article
-      className={cn('prose', sizeClass, 'max-w-none', className)}
+    <Prose
+      as="article"
+      content={content}
+      block={block}
+      components={components}
+      size={size}
+      className={className}
       {...props}
     >
-      {children || (resolvedContent && <Render content={resolvedContent} />)}
-    </article>
+      {children}
+    </Prose>
   )
 }
 

package/src/styled/Media/Media.jsx

@@ -202,11 +202,34 @@ function PlayButton({ onClick, className }) {
  * @example
  * // Local video
  * <Media src="/videos/intro.mp4" controls autoplay={false} />
+ *
+ * @example
+ * // A video authored in markdown, delivered via content.videos[]
+ * // ![Demo](./demo.mp4){role=video poster=./thumb.jpg autoplay muted loop}
+ * <Visual video={content.videos[0]} />
  */
 export function Media({
   src,
   media,
   thumbnail,
+  // Same concept, three producers. `thumbnail` is this component's own prop;
+  // `poster` is the authored markdown spelling (`{role=video poster=…}`, and
+  // what @uniweb/build auto-generates when it is absent); `coverImg` is what
+  // the editor's Video node carries. All three named here because a video
+  // entry from `content.videos[]` is spread straight in — `<Media {...video} />`
+  // via <Visual> — so an unrecognised one would land on the wrapper div, where
+  // it does nothing and React warns.
+  poster,
+  coverImg,
+  // Also part of the delivered video shape. Absorbed rather than forwarded:
+  // the reference documents wrapping media in a link as the FOUNDATION's job
+  // (docs/reference/content-structure.md, "Clickable Images and Videos"), so
+  // these are the author's to use, not this component's to consume.
+  alt,
+  role,
+  href,
+  target,
+  caption: captionProp,
   autoplay = false,
   muted = false,
   loop = false,
@@ -222,13 +245,14 @@ export function Media({
 
   // Normalize source
   const videoSrc = typeof src === 'string' ? src : (src?.src || media?.src || '')
-  const caption = media?.caption || src?.caption || ''
+  const caption = captionProp || media?.caption || src?.caption || ''
 
   // Detect video type
   const mediaType = detectMediaType(videoSrc)
 
   // Get thumbnail
-  const thumbnailSrc = thumbnail || getVideoThumbnail(videoSrc, mediaType)
+  const thumbnailSrc =
+    thumbnail || poster || coverImg || getVideoThumbnail(videoSrc, mediaType)
 
   // Handle play click (for facade mode)
   const handlePlay = useCallback(() => {

package/src/styled/Prose/index.jsx

@@ -1,27 +1,29 @@
 /**
- * Prose Component
+ * Prose — content plus prose typography.
  *
- * Renders the prose (narrative) portions of parsed content from content.sequence.
- * Data blocks (tagged code blocks, dataBlocks) are skipped — they're structured
- * data, not prose. Access them via content.data instead.
+ * `<Render>` walks the sequence; this adds the Tailwind Typography container
+ * that styles the semantic markup it emits. Two concerns, deliberately separate:
+ * a foundation with its own type system uses `<Render>` and lays out the
+ * elements itself.
  *
- * Also works as a pure typography wrapper when given children instead of content.
+ * Typography comes from a plugin the FOUNDATION installs — kit ships no
+ * stylesheet — and answers to the site's `theme.yml` through
+ * `@uniweb/kit/prose-tokens.css`. See that file for the two rules that bite:
+ * one prose container per subtree (the variables are inherited, so a nested one
+ * silently resets its subtree), and no palette modifier (`prose-gray` and
+ * friends re-declare every variable and defeat the theme bridge).
+ *
+ * Also works as a pure typography wrapper when given children instead of
+ * content.
  *
  * @module @uniweb/kit/styled/Prose
  */
 
 import React from 'react'
-import { cn, getChildBlockRenderer, headingId } from '../../utils/index.js'
-import { SafeHtml } from '../../components/SafeHtml/index.js'
-import { Image } from '../../components/Image/index.js'
-import { Media } from '../../components/Media/index.js'
-import { Icon } from '../../components/Icon/index.js'
-import { Link } from '../../components/Link/index.js'
-import { Code } from '../Section/renderers/Code.jsx'
+import { cn } from '../../utils/index.js'
+import { Render } from '../Render/index.jsx'
 
-/**
- * Prose sizes
- */
+/** Prose sizes */
 const SIZE_CLASSES = {
   sm: 'prose-sm',
   base: 'prose-base',
@@ -30,215 +32,14 @@ const SIZE_CLASSES = {
   '2xl': 'prose-2xl'
 }
 
-
-const INLINE_INSET_RE = /<uniweb-inset data-ref-id="([^"]+)"><\/uniweb-inset>/g
-
 /**
- * Render an HTML paragraph fragment that contains inline-inset markers
- * (`<uniweb-inset data-ref-id="…">`). The fragment is split at marker
- * boundaries; HTML chunks render via SafeHtml, marker positions render
- * via the framework's child-block renderer (the same path block-level
- * insets use, scoped to a single inset block).
- *
- * Components rendered through this path return an inline element
- * (typically a `<span>`) so the paragraph stays a single line of prose.
- */
-function renderParagraphWithInsets(html, block) {
-  if (!block) return <SafeHtml value={html} as="span" />
-  const InsetRenderer = getChildBlockRenderer()
-  const parts = []
-  let lastIdx = 0
-  INLINE_INSET_RE.lastIndex = 0
-  let match
-  while ((match = INLINE_INSET_RE.exec(html)) !== null) {
-    if (match.index > lastIdx) {
-      parts.push(
-        <SafeHtml
-          key={`t${lastIdx}`}
-          value={html.slice(lastIdx, match.index)}
-          as="span"
-        />
-      )
-    }
-    const refId = match[1]
-    const insetBlock = block.getInset?.(refId)
-    if (insetBlock && InsetRenderer) {
-      parts.push(<InsetRenderer key={`i${refId}`} blocks={[insetBlock]} />)
-    }
-    lastIdx = match.index + match[0].length
-  }
-  if (lastIdx < html.length) {
-    parts.push(
-      <SafeHtml key={`t${lastIdx}`} value={html.slice(lastIdx)} as="span" />
-    )
-  }
-  return parts
-}
-
-/**
- * Render a single sequence element to React
- */
-function SequenceElement({ element, block }) {
-  if (!element) return null
-
-  switch (element.type) {
-    case 'heading': {
-      const level = Math.min(element.level || 1, 6)
-      const Tag = `h${level}`
-      const id = headingId(element.text || '')
-      return <Tag id={id}><SafeHtml value={element.text} as="span" /></Tag>
-    }
-
-    case 'paragraph': {
-      if (!element.text) return null
-      // Inline insets ride through the paragraph text as
-      // `<uniweb-inset data-ref-id="…"></uniweb-inset>` markers (see
-      // semantic-parser's getTextContent). When any are present, walk
-      // the text once and intersperse React-rendered insets at the
-      // marker positions; otherwise stick to the fast SafeHtml path.
-      if (/<uniweb-inset/.test(element.text)) {
-        return <p>{renderParagraphWithInsets(element.text, block)}</p>
-      }
-      return <p><SafeHtml value={element.text} as="span" /></p>
-    }
-
-    case 'image': {
-      const { url, alt, caption, role } = element.attrs || {}
-      if (role === 'icon') {
-        return <Icon {...element.attrs} />
-      }
-      return (
-        <figure>
-          <Image src={url} alt={alt || caption || ''} />
-          {caption && <figcaption>{caption}</figcaption>}
-        </figure>
-      )
-    }
-
-    case 'video': {
-      return <Media src={element.attrs?.src} />
-    }
-
-    case 'codeBlock': {
-      return <Code content={element.text || ''} language={element.attrs?.language || ''} />
-    }
-
-    case 'dataBlock':
-      return null
-
-    case 'math': {
-      // Math from $$...$$ on its own line, ```math fence, or inline
-      // $...$ (the inline form doesn't reach the sequence walker — it
-      // rides inside paragraph HTML — but render the same way for
-      // safety in case a future caller surfaces it here). Mathml is
-      // pre-compiled at parse time; the browser renders real MathML
-      // natively. Foundations that want to style errors can target
-      // .temml-error inside this wrapper.
-      if (!element.mathml) return null
-      const display = element.display !== false
-      const Tag = display ? 'div' : 'span'
-      return (
-        <Tag
-          className={display ? 'math-display' : 'math-inline'}
-          dangerouslySetInnerHTML={{ __html: element.mathml }}
-        />
-      )
-    }
-
-    case 'list': {
-      const Tag = element.style === 'ordered' ? 'ol' : 'ul'
-      return (
-        <Tag>
-          {element.children?.map((itemSeq, i) => (
-            <li key={i}>
-              {itemSeq.map((el, j) => (
-                <SequenceElement key={j} element={el} block={block} />
-              ))}
-            </li>
-          ))}
-        </Tag>
-      )
-    }
-
-    case 'blockquote': {
-      return (
-        <blockquote>
-          {element.children?.map((el, i) => (
-            <SequenceElement key={i} element={el} block={block} />
-          ))}
-        </blockquote>
-      )
-    }
-
-    case 'inset_block': {
-      // A component reference that carries block content — the block form of
-      // an inset. Children recurse; flattening them to text is what the
-      // sequence's default branch used to do, and it lost the body.
-      //
-      // Reaching this case means the container was NOT lifted — `@uniweb/core`
-      // rewrites `inset_block` to `inset_placeholder` when it builds the render
-      // graph, and the `inset` case resolves that against the foundation. This
-      // is the fallback for a document rendered without a Block behind it.
-      //
-      // kit does NOT map the name to one of its own components — see the longer
-      // note in Section/Render. A visible generic box; never a drop.
-      const body = element.children?.map((el, i) => (
-        <SequenceElement key={i} element={el} block={block} />
-      ))
-
-      return (
-        <div
-          data-inset-block={element.component || 'unknown'}
-          className="border border-border rounded-md p-4 my-4"
-        >
-          {body}
-        </div>
-      )
-    }
-
-    case 'link': {
-      const { href, label, role } = element.attrs || {}
-      // Standalone links promoted from paragraphs
-      return <p><Link to={href}>{label}</Link></p>
-    }
-
-    case 'button': {
-      return <p><Link to={element.attrs?.href}>{element.text}</Link></p>
-    }
-
-    case 'divider':
-      return <hr />
-
-    case 'inset': {
-      if (!block || !element.refId) return null
-      const insetBlock = block.getInset(element.refId)
-      if (!insetBlock) return null
-      const InsetRenderer = getChildBlockRenderer()
-      if (!InsetRenderer) return null
-      return <InsetRenderer blocks={[insetBlock]} />
-    }
-
-    case 'icon': {
-      return <Icon {...element.attrs} />
-    }
-
-    default:
-      return null
-  }
-}
-
-/**
- * Prose - Renders the narrative content from a parsed content sequence
- *
- * Skips data blocks (tagged code blocks, dataBlocks) — those are structured
- * data accessible via content.data, not prose to render.
- *
- * Pass `content` (the parsed content object from component props).
- * Optionally pass `block` for inset resolution.
+ * Prose - Rendered content with prose typography
  *
  * @param {Object} props
- * @param {Object} [props.content] - Parsed content object (has .sequence)
- * @param {Object} [props.block] - Block instance (needed for inset resolution)
+ * @param {Object|Array} [props.content] - Parsed content (`.sequence`), a
+ *   ProseMirror doc, or an array of ProseMirror nodes
+ * @param {Object} [props.block] - Block instance (supplies content; resolves insets)
+ * @param {Object} [props.components] - Per-element-type renderer overrides
  * @param {string} [props.size='lg'] - Text size: sm, base, lg, xl, 2xl
  * @param {string} [props.as='div'] - HTML element to render as
  * @param {string} [props.className] - Additional CSS classes
@@ -251,20 +52,24 @@ function SequenceElement({ element, block }) {
  * }
  *
  * @example
- * // Access data blocks separately
+ * // Render one element type your own way — the foundation's design, kit's walk
+ * <Prose content={content} block={block} components={{ concept_block: Faq }} />
+ *
+ * @example
+ * // Access data blocks separately — they are deliberately not rendered
  * <Prose content={content} block={block} />
  * {content.data.quiz && <Quiz data={content.data.quiz} />}
  *
  * @example
- * // Pure typography wrapper (backward compatible)
+ * // Pure typography wrapper
  * <Prose size="base">
  *   <h2>Title</h2>
- *   <p>Content...</p>
  * </Prose>
  */
 export function Prose({
   block,
   content,
+  components,
   size = 'lg',
   as: Component = 'div',
   className,
@@ -272,19 +77,10 @@ export function Prose({
   ...props
 }) {
   const sizeClass = SIZE_CLASSES[size] || SIZE_CLASSES.lg
-  const sequence = content?.sequence
 
   return (
-    <Component
-      className={cn('prose', sizeClass, 'max-w-none', className)}
-      {...props}
-    >
-      {sequence
-        ? sequence.map((element, i) => (
-            <SequenceElement key={i} element={element} block={block} />
-          ))
-        : children
-      }
+    <Component className={cn('prose', sizeClass, 'max-w-none', className)} {...props}>
+      {children ?? <Render content={content} block={block} components={components} />}
     </Component>
   )
 }

package/src/styled/Render/index.jsx

@@ -0,0 +1,377 @@
+/**
+ * Render — the content engine.
+ *
+ * Walks a parsed content SEQUENCE and emits React. One node table, used by
+ * everything in kit that renders authored content: `<Prose>` adds typography on
+ * top, `<Article>` adds semantics on top of that, and a foundation can call
+ * this directly.
+ *
+ * ── Why there is one table now ──
+ *
+ * There were two. This component predated the semantic parser's `sequence` and
+ * walked raw ProseMirror by hand; `<Prose>` was written later against the
+ * parsed shape. Same job, two implementations, and the older one rotted because
+ * nothing exercised it. Measured 2026-07-30, before this rewrite:
+ *
+ *   - it dropped every inline mark. Its `paragraph` case called `extractText`,
+ *     a helper written to extract PLAIN text, which concatenates `node.text`
+ *     and discards `marks`. `Hello **world**` rendered as `Hello world`, and
+ *     every link in an article vanished.
+ *   - it dropped block math entirely — no `math_display` case, so a `$$…$$`
+ *     fell to `default:`, which recurses `content`, which math has none of.
+ *   - `<Prose>` meanwhile dropped every table, and that one was not even its
+ *     fault: the sequence did not carry tables at all until the same day.
+ *
+ * All three were invisible because each renderer's own tests passed. Going
+ * through the parser fixes the marks by construction — inline content arrives
+ * already rendered to HTML with marks applied — and one table means math and
+ * tables cannot be present in one lane and missing from the other.
+ *
+ * ── What it does NOT do ──
+ *
+ * Decorate. The defaults resolve references and supply behaviour — an icon's
+ * library, a link's base path, a code block's highlighting, a video's playback
+ * attributes — and otherwise emit semantic HTML with no classes. What a
+ * blockquote LOOKS like is a foundation's decision and a site's `theme.yml`,
+ * the same rule that keeps fixed palettes out of kit (framework CLAUDE.md
+ * gotcha #8). The previous version carried 23 hardcoded utility strings,
+ * including `italic text-subtle` on blockquote — kit deciding a foundation's
+ * design, and unreachable without forking the walker.
+ *
+ * `components` is the seam instead: pass a component for any element type and
+ * it replaces the default, receiving `{ element, block, children }`. That is
+ * how a foundation renders a concept block as its own accordion, or a
+ * blockquote as its own pull-quote, without kit knowing either exists.
+ *
+ * @module @uniweb/kit/styled/Render
+ */
+
+import React from 'react'
+import { parseContent } from '@uniweb/semantic-parser'
+import { getChildBlockRenderer, headingId } from '../../utils/index.js'
+import { SafeHtml } from '../../components/SafeHtml/index.js'
+import { Image } from '../../components/Image/index.js'
+import { Media } from '../../components/Media/index.js'
+import { Icon } from '../../components/Icon/index.js'
+import { Link } from '../../components/Link/index.js'
+import { Code } from '../Section/renderers/Code.jsx'
+import { Divider } from '../Section/renderers/Divider.jsx'
+
+const INLINE_INSET_RE = /<uniweb-inset data-ref-id="([^"]+)"><\/uniweb-inset>/g
+
+/**
+ * Element types this engine knows about and deliberately renders NOTHING for.
+ *
+ * Listed rather than left to fall through `default:`, so a drop is a decision
+ * someone wrote down. `tests/renderer-coverage.test.js` checks this set plus
+ * the rendered set against the vocabulary the parser can actually emit, which
+ * is what makes a NEW element type fail a test instead of vanishing.
+ */
+export const NOT_RENDERED = {
+  dataBlock:
+    'structured data, not prose — a component reads it from content.data[tag]',
+  inset_ref:
+    'a BUILD-TIME intermediate. The reader emits it for `![](@Component)`; the ' +
+    'build\'s content-collector extracts it into the section\'s insets and leaves ' +
+    'an `inset_placeholder`, which is what the `inset` case resolves. Its attrs ' +
+    'carry a component NAME and no refId, so there is nothing here to look up — ' +
+    'and kit answering for the name is the shadowing the inset_block case ' +
+    'refuses. Consequence worth knowing: a document rendered straight from ' +
+    'markdown without that build step (a collection record body, say) loses its ' +
+    'inline component references.',
+  form: 'an editor node; its data reaches components as content.data[schemaId]',
+  'card-group': 'an editor node, deprecated — maps to content.data[cardType]',
+  'document-group': 'an editor node — its documents reach content.links',
+}
+
+/**
+ * Normalize whatever a caller passed into a sequence.
+ *
+ * Accepts a parsed content object (`content.sequence`), a Block (its content is
+ * already parsed), a ProseMirror doc, or an array of ProseMirror nodes. A raw
+ * document is run through the parser rather than walked directly — that is the
+ * whole point of having one table, and it is what makes inline marks work.
+ */
+function toSequence(content, block) {
+  if (Array.isArray(content?.sequence)) return content.sequence
+
+  if (content?.type === 'doc') return parseContent(content).sequence
+  if (Array.isArray(content)) return parseContent({ type: 'doc', content }).sequence
+
+  if (block) {
+    if (Array.isArray(block.parsedContent?.sequence)) return block.parsedContent.sequence
+    const raw = block.rawContent?.doc ?? block.rawContent
+    if (raw?.type === 'doc') return parseContent(raw).sequence
+  }
+
+  return null
+}
+
+/**
+ * Render an HTML paragraph fragment containing inline-inset markers
+ * (`<uniweb-inset data-ref-id="…">`). HTML chunks render via SafeHtml, marker
+ * positions via the framework's child-block renderer — the same path
+ * block-level insets take, scoped to one inset.
+ */
+function renderParagraphWithInsets(html, block) {
+  if (!block) return <SafeHtml value={html} as="span" />
+  const InsetRenderer = getChildBlockRenderer()
+  const parts = []
+  let lastIdx = 0
+  INLINE_INSET_RE.lastIndex = 0
+  let match
+  while ((match = INLINE_INSET_RE.exec(html)) !== null) {
+    if (match.index > lastIdx) {
+      parts.push(<SafeHtml key={`t${lastIdx}`} value={html.slice(lastIdx, match.index)} as="span" />)
+    }
+    const refId = match[1]
+    const insetBlock = block.getInset?.(refId)
+    if (insetBlock && InsetRenderer) {
+      parts.push(<InsetRenderer key={`i${refId}`} blocks={[insetBlock]} />)
+    }
+    lastIdx = match.index + match[0].length
+  }
+  if (lastIdx < html.length) {
+    parts.push(<SafeHtml key={`t${lastIdx}`} value={html.slice(lastIdx)} as="span" />)
+  }
+  return parts
+}
+
+/** Render a list of sequence elements. */
+function renderAll(sequence, block, components) {
+  return (sequence || []).map((element, i) => (
+    <SequenceElement key={i} element={element} block={block} components={components} />
+  ))
+}
+
+/**
+ * One element of a sequence.
+ *
+ * A `components` entry for the element's type replaces the default entirely and
+ * receives `{ element, block, children }` — `children` being the rendered
+ * sub-elements for the container types, so an override can rewrap without
+ * re-implementing the walk.
+ */
+export function SequenceElement({ element, block, components }) {
+  if (!element) return null
+
+  const Override = components?.[element.type]
+  if (Override) {
+    const children = element.children ? renderAll(element.children, block, components) : undefined
+    return <Override element={element} block={block} children={children} />
+  }
+
+  switch (element.type) {
+    case 'heading': {
+      const level = Math.min(element.level || 1, 6)
+      const Tag = `h${level}`
+      // The id is the anchor `useHeadings()` and every in-page nav link
+      // resolve against, so it is behaviour rather than decoration.
+      return (
+        <Tag id={headingId(element.text || '')}>
+          <SafeHtml value={element.text} as="span" />
+        </Tag>
+      )
+    }
+
+    case 'paragraph': {
+      if (!element.text) return null
+      if (/<uniweb-inset/.test(element.text)) {
+        return <p>{renderParagraphWithInsets(element.text, block)}</p>
+      }
+      return (
+        <p>
+          <SafeHtml value={element.text} as="span" />
+        </p>
+      )
+    }
+
+    case 'image': {
+      const { url, src, alt, caption, role } = element.attrs || {}
+      if (role === 'icon') return <Icon {...element.attrs} />
+      return (
+        <figure>
+          <Image src={url || src} alt={alt || caption || ''} />
+          {caption && <figcaption>{caption}</figcaption>}
+        </figure>
+      )
+    }
+
+    // Spread rather than cherry-pick: a markdown video carries poster and the
+    // playback flags, and <Media> reads all of them.
+    case 'video':
+      return <Media {...element.attrs} />
+
+    case 'icon':
+      return <Icon {...element.attrs} />
+
+    case 'codeBlock':
+      return <Code content={element.text || ''} language={element.attrs?.language || ''} />
+
+    case 'math': {
+      // MathML is pre-compiled at parse time; the browser renders it natively,
+      // so no runtime math library ships. Missing here until 2026-07-30, which
+      // is why math vanished from every <Article>.
+      if (!element.mathml) return null
+      const display = element.display !== false
+      const Tag = display ? 'div' : 'span'
+      return (
+        <Tag
+          className={display ? 'math-display' : 'math-inline'}
+          dangerouslySetInnerHTML={{ __html: element.mathml }}
+        />
+      )
+    }
+
+    case 'list': {
+      const Tag = element.style === 'ordered' ? 'ol' : 'ul'
+      return (
+        <Tag>
+          {element.children?.map((itemSequence, i) => (
+            <li key={i}>{renderAll(itemSequence, block, components)}</li>
+          ))}
+        </Tag>
+      )
+    }
+
+    case 'table': {
+      // Semantic markup, no decoration: `<thead>` when the first row is
+      // headers, `<th>`/`<td>` from each cell's own flag, and alignment and
+      // spans carried through. Cells render their nested sequence, so a cell
+      // keeps its marks and may hold any block.
+      const rows = element.rows || []
+      if (!rows.length) return null
+      const [first, ...rest] = rows
+      const hasHeader = first.cells?.some((cell) => cell.header)
+
+      const renderRow = (row, key) => (
+        <tr key={key}>
+          {row.cells?.map((cell, i) => {
+            const CellTag = cell.header ? 'th' : 'td'
+            return (
+              <CellTag
+                key={i}
+                style={cell.align ? { textAlign: cell.align } : undefined}
+                colSpan={cell.colspan > 1 ? cell.colspan : undefined}
+                rowSpan={cell.rowspan > 1 ? cell.rowspan : undefined}
+              >
+                {renderAll(cell.children, block, components)}
+              </CellTag>
+            )
+          })}
+        </tr>
+      )
+
+      // The one class the engine emits, and it is behaviour rather than
+      // decoration: a table wider than its column has to scroll inside its own
+      // box or it pushes the whole page sideways. Nothing about how the table
+      // LOOKS is decided here — borders, padding and header weight come from
+      // the typography layer, which answers to the site's theme.yml.
+      //
+      // Kept deliberately when the rest of kit's table styling went: a real
+      // docs site (uniweb-site) has no table CSS of its own and relied on kit
+      // for exactly this, so dropping it would have broken every wide
+      // reference table on a phone.
+      return (
+        <div className="overflow-x-auto">
+          <table>
+            {hasHeader && <thead>{renderRow(first, 'h')}</thead>}
+            <tbody>{(hasHeader ? rest : rows).map((row, i) => renderRow(row, i))}</tbody>
+          </table>
+        </div>
+      )
+    }
+
+    case 'blockquote':
+      return <blockquote>{renderAll(element.children, block, components)}</blockquote>
+
+    case 'inset_block': {
+      // A container reaching this case was NOT lifted — @uniweb/core rewrites
+      // every `inset_block` to an `inset_placeholder` when it builds the render
+      // graph, so the normal path is the `inset` case below, which resolves the
+      // component against the FOUNDATION. This is what is left for a document
+      // rendered without a Block behind it.
+      //
+      // kit does not map the name to one of its own components. A foundation
+      // shipping its own Alert would be shadowed by ours, which inverts who
+      // owns a site's vocabulary. A visible container that keeps its body,
+      // never a drop.
+      return (
+        <div data-inset-block={element.component || 'unknown'}>
+          {renderAll(element.children, block, components)}
+        </div>
+      )
+    }
+
+    case 'concept_block': {
+      // A tagged prose fence (```md:faq). Same rule one layer over: the tag
+      // names CONTENT, and the set of concepts belongs to whoever edits or
+      // renders it. The tag rides on a data attribute where a foundation's CSS
+      // can reach it — or it passes `components={{ concept_block: … }}` and
+      // renders the concept itself.
+      return (
+        <div data-concept={element.tag || 'unknown'}>
+          {renderAll(element.children, block, components)}
+        </div>
+      )
+    }
+
+    case 'inset': {
+      if (!block || !element.refId) return null
+      const insetBlock = block.getInset?.(element.refId)
+      if (!insetBlock) return null
+      const InsetRenderer = getChildBlockRenderer()
+      if (!InsetRenderer) return null
+      return <InsetRenderer blocks={[insetBlock]} />
+    }
+
+    // A link promoted out of a paragraph — it stood alone on its line, which is
+    // how an author writes a call to action.
+    case 'link': {
+      const { href, label } = element.attrs || {}
+      return (
+        <p>
+          <Link to={href}>{label}</Link>
+        </p>
+      )
+    }
+
+    case 'button':
+      return (
+        <p>
+          <Link to={element.attrs?.href}>{element.text}</Link>
+        </p>
+      )
+
+    // `type` is content — `---{type=dots}` is a different divider, not a
+    // differently-styled one — so this resolves it rather than emitting <hr>.
+    case 'divider':
+      return <Divider type={element.attrs?.type} />
+
+    default:
+      return null
+  }
+}
+
+/**
+ * Render — walk a content sequence and emit React.
+ *
+ * Returns a FRAGMENT. No wrapper, no classes: spacing and typography are the
+ * caller's, which is what makes this usable as an engine. `<Prose>` supplies a
+ * typography container; a foundation with its own type system supplies nothing
+ * and lays the elements out itself.
+ *
+ * @param {Object} props
+ * @param {Object|Array} [props.content] - Parsed content (`.sequence`), a
+ *   ProseMirror doc, or an array of ProseMirror nodes
+ * @param {Object} [props.block] - Block instance; supplies content when none is
+ *   passed, and resolves insets
+ * @param {Object} [props.components] - Per-element-type renderer overrides
+ */
+export function Render({ content, block, components }) {
+  const sequence = toSequence(content, block)
+  if (!sequence?.length) return null
+  return <>{renderAll(sequence, block, components)}</>
+}
+
+export default Render

package/src/styled/Section/Section.jsx

@@ -10,7 +10,7 @@
 import React from 'react'
 import { cn } from '../../utils/index.js'
 import { useWebsite } from '../../hooks/useWebsite.js'
-import { Render } from './Render.jsx'
+import { Prose } from '../Prose/index.jsx'
 
 /**
  * Width presets
@@ -115,11 +115,17 @@ export function Section({
             columns !== '1' && 'grid gap-8',
             columns !== '1' && columnClass
           )}>
-            {children || (
-              <div className="prose prose-gray max-w-none">
-                <Render content={resolvedContent} />
-              </div>
-            )}
+            {/*
+              `prose-gray` was here until 2026-07-30, and prose-tokens.css
+              forbids it in as many words: a palette modifier "re-declares every
+              variable below", so it overrode the bridge that makes a prose
+              container answer to the site's theme.yml — the one thing that file
+              exists to do. Every Section rendering its own content styled its
+              prose with fixed Tailwind greys instead of the site's palette.
+              no-fixed-palettes did not catch it because it matches colour
+              UTILITIES (bg-, text-, border-), and this is a Typography modifier.
+            */}
+            {children || <Prose content={resolvedContent} />}
           </div>
         )}
       </div>

package/src/styled/Section/index.js

@@ -5,5 +5,4 @@
  */
 
 export { Section, default } from './Section.jsx'
-export { Render } from './Render.jsx'
 export * from './renderers/index.js'

package/src/styled/index.js

@@ -20,7 +20,8 @@
 // ============================================================================
 
 // Section - Rich content section layout container
-export { Section, Render } from './Section/index.js'
+export { Section } from './Section/index.js'
+export { Render, SequenceElement } from './Render/index.jsx'
 
 // Prose - Typography wrapper for long-form content
 export { Prose } from './Prose/index.jsx'

package/src/styled/Section/Render.jsx

@@ -1,367 +0,0 @@
-/**
- * Render Component
- *
- * Orchestrates rendering of content blocks within a Section.
- * Dispatches to appropriate renderers based on content type.
- *
- * @module @uniweb/kit/Section/Render
- */
-
-import React from 'react'
-import { cn, getChildBlockRenderer, headingId } from '../../utils/index.js'
-import { SafeHtml } from '../../components/SafeHtml/index.js'
-import { Image } from '../../components/Image/index.js'
-import { Media } from '../../components/Media/index.js'
-import { Icon } from '../../components/Icon/index.js'
-import { Link } from '../../components/Link/index.js'
-import { Code } from './renderers/Code.jsx'
-import { Alert } from './renderers/Alert.jsx'
-import { Table } from './renderers/Table.jsx'
-import { Details } from './renderers/Details.jsx'
-import { Divider } from './renderers/Divider.jsx'
-
-/**
- * Extract text content from a node
- */
-function extractText(node) {
-  if (!node) return ''
-  if (typeof node === 'string') return node
-  if (node.text) return node.text
-  if (node.content) {
-    return node.content.map(extractText).join('')
-  }
-  return ''
-}
-
-
-/**
- * Render a list (ordered or unordered)
- */
-function renderList(items, ordered = false) {
-  const Tag = ordered ? 'ol' : 'ul'
-  const listClass = ordered ? 'list-decimal' : 'list-disc'
-
-  return (
-    <Tag className={cn('pl-6 space-y-1', listClass)}>
-      {items?.map((item, i) => (
-        <li key={i}>
-          {item.content?.map((child, j) => (
-            <RenderNode key={j} node={child} />
-          ))}
-        </li>
-      ))}
-    </Tag>
-  )
-}
-
-/**
- * Render a single content node
- */
-function RenderNode({ node, block, ...props }) {
-  if (!node) return null
-
-  const { type, attrs, content } = node
-
-  switch (type) {
-    case 'paragraph': {
-      const html = extractText(node)
-      if (!html) return null
-      return <p><SafeHtml value={html} as="span" /></p>
-    }
-
-    case 'heading': {
-      const level = attrs?.level || 1
-      const text = extractText(node)
-      const id = headingId(text)
-      const Tag = `h${Math.min(level, 6)}`
-
-      return (
-        <Tag id={id} className="scroll-mt-20">
-          {text}
-        </Tag>
-      )
-    }
-
-    case 'image': {
-      const src = attrs?.src || ''
-      const alt = attrs?.alt || ''
-      const caption = attrs?.caption || ''
-      const role = attrs?.role
-
-      // Dispatch based on role attribute
-      if (role === 'video') {
-        // Video content - use Media component
-        return (
-          <Media
-            src={src}
-            autoplay={attrs?.autoplay}
-            muted={attrs?.muted}
-            loop={attrs?.loop}
-            controls={attrs?.controls}
-            className="my-4 rounded-lg overflow-hidden"
-          />
-        )
-      }
-
-      if (role === 'document') {
-        // Document/file link with optional preview
-        const poster = attrs?.poster
-        const preview = attrs?.preview
-        const filename = alt || src.split('/').pop() || 'Document'
-
-        return (
-          <figure className="my-4">
-            <Link
-              to={src}
-              className="block group border rounded-lg overflow-hidden hover:shadow-md transition-shadow"
-              target="_blank"
-            >
-              {(poster || preview) ? (
-                <Image
-                  src={poster || preview}
-                  alt={filename}
-                  className="w-full"
-                />
-              ) : (
-                <div className="flex items-center gap-3 p-4 bg-muted">
-                  <Icon name="download" size="24" className="text-subtle" />
-                  <span className="text-link group-hover:underline">
-                    {filename}
-                  </span>
-                </div>
-              )}
-            </Link>
-            {caption && (
-              <figcaption className="mt-2 text-sm text-subtle text-center">
-                {caption}
-              </figcaption>
-            )}
-          </figure>
-        )
-      }
-
-      if (role === 'icon') {
-        // Icon - use Icon component
-        // Supports: ![alt](lucide:icon-name){size=24 color=blue}
-        //           ![alt](icon:/path/to/icon.svg){size=32}
-        const size = attrs?.size || '24'
-        const iconName = attrs?.name || alt
-        const iconColor = attrs?.color
-
-        return (
-          <Icon
-            url={src}
-            name={iconName}
-            size={size}
-            color={iconColor}
-            className="inline-block"
-          />
-        )
-      }
-
-      // Default: image or banner - use Image component
-      return (
-        <figure className="my-4">
-          <Image src={src} alt={alt} className="rounded-lg" />
-          {caption && (
-            <figcaption className="mt-2 text-sm text-subtle text-center">
-              {caption}
-            </figcaption>
-          )}
-        </figure>
-      )
-    }
-
-    case 'video': {
-      const src = attrs?.src || ''
-      return <Media src={src} className="my-4 rounded-lg overflow-hidden" />
-    }
-
-    case 'codeBlock': {
-      const language = attrs?.language || 'plaintext'
-      const code = extractText(node)
-      return <Code content={code} language={language} className="my-4" />
-    }
-
-    case 'warning':
-    case 'alert': {
-      const alertType = attrs?.type || 'info'
-      const alertContent = content?.map(extractText).join('') || ''
-      return <Alert type={alertType} content={alertContent} className="my-4" />
-    }
-
-    case 'blockquote': {
-      return (
-        <blockquote className="border-l-4 border-border pl-4 italic text-subtle my-4">
-          {content?.map((child, i) => (
-            <RenderNode key={i} node={child} block={block} />
-          ))}
-        </blockquote>
-      )
-    }
-
-    case 'bulletList': {
-      return renderList(content, false)
-    }
-
-    case 'orderedList': {
-      return renderList(content, true)
-    }
-
-    case 'table': {
-      return <Table content={content} className="my-4" />
-    }
-
-    case 'details': {
-      const summary = attrs?.summary || 'Details'
-      const detailsContent = content?.map(extractText).join('') || ''
-      return (
-        <Details
-          summary={summary}
-          content={detailsContent}
-          open={attrs?.open}
-          className="my-4"
-        />
-      )
-    }
-
-    case 'inset_block': {
-      // The block form of an inset: a fenced `@Component{params}` container
-      // whose body is real block content, recursed like a blockquote's rather
-      // than flattened to a string.
-      //
-      // NOTE: a container reaching this case means it was NOT lifted.
-      // `@uniweb/core`'s Block rewrites every `inset_block` to an
-      // `inset_placeholder` when it builds the render graph, so the normal
-      // path is the `inset_placeholder` case below — which resolves the
-      // component against the FOUNDATION. This branch is what is left for a
-      // document rendered without a Block behind it.
-      //
-      // `@Component` names foundation vocabulary, so kit must not answer for
-      // it. kit's own Details and Alert are not reachable through
-      // `getInset()` and must not become reachable here, or a foundation
-      // shipping its own Alert would be shadowed by ours. (kit still renders
-      // `details` / `alert` above — those are the editor's DOCUMENT node
-      // types, a different mechanism that happens to share a name.)
-      //
-      // So: no name dispatch. A VISIBLE generic box that keeps its body.
-      // Never a drop — an unmapped node taking its subtree with it is the
-      // failure this container exists to fix.
-      const component = attrs?.component
-      const body = content?.map((child, i) => (
-        <RenderNode key={i} node={child} block={block} />
-      ))
-
-      return (
-        <div
-          data-inset-block={component || 'unknown'}
-          className="border border-border rounded-md p-4 my-4"
-        >
-          {body}
-        </div>
-      )
-    }
-
-    case 'horizontalRule':
-    case 'divider': {
-      return <Divider type={attrs?.type} className="my-6" />
-    }
-
-    case 'inset_placeholder': {
-      const refId = attrs?.refId
-      if (!block || !refId) return null
-
-      const insetBlock = block.getInset(refId)
-      if (!insetBlock) return null
-
-      const InsetRenderer = getChildBlockRenderer()
-      return <InsetRenderer blocks={[insetBlock]} />
-    }
-
-    case 'button': {
-      const href = attrs?.href || '#'
-      const label = extractText(node) || attrs?.label || 'Button'
-      return (
-        <Link
-          to={href}
-          className="inline-block px-4 py-2 bg-primary text-primary-foreground rounded-md hover:bg-primary-hover transition-colors my-2"
-        >
-          {label}
-        </Link>
-      )
-    }
-
-    case 'text': {
-      // Handle inline marks (bold, italic, etc.)
-      let text = node.text || ''
-
-      if (node.marks) {
-        node.marks.forEach((mark) => {
-          switch (mark.type) {
-            case 'bold':
-            case 'strong':
-              text = `<strong>${text}</strong>`
-              break
-            case 'italic':
-            case 'em':
-              text = `<em>${text}</em>`
-              break
-            case 'code':
-              text = `<code class="px-1 py-0.5 bg-muted rounded text-sm">${text}</code>`
-              break
-            case 'link':
-              text = `<a href="${mark.attrs?.href || '#'}" class="text-link hover:underline">${text}</a>`
-              break
-          }
-        })
-      }
-
-      return <SafeHtml value={text} as="span" />
-    }
-
-    default:
-      // Try to render children if they exist
-      if (content && Array.isArray(content)) {
-        return (
-          <>
-            {content.map((child, i) => (
-              <RenderNode key={i} node={child} block={block} />
-            ))}
-          </>
-        )
-      }
-      return null
-  }
-}
-
-/**
- * Render - Content block renderer
- *
- * @param {Object} props
- * @param {Array|Object} props.content - Content to render (array of nodes or single node)
- * @param {string} [props.className] - Additional CSS classes
- */
-export function Render({ content, block, className, ...props }) {
-  // Get content from block if not provided directly
-  let resolvedContent = content
-  if (!resolvedContent && block) {
-    resolvedContent = block.rawContent
-    if (resolvedContent?.type === 'doc') {
-      resolvedContent = resolvedContent.content
-    }
-  }
-
-  if (!resolvedContent) return null
-
-  const nodes = Array.isArray(resolvedContent) ? resolvedContent : [resolvedContent]
-
-  return (
-    <div className={cn('space-y-4', className)} {...props}>
-      {nodes.map((node, i) => (
-        <RenderNode key={i} node={node} block={block} />
-      ))}
-    </div>
-  )
-}
-
-export default Render