@uniweb/kit 0.9.33 → 0.9.35

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.9.33",
+  "version": "0.9.35",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
     "./xref": "./src/xref/index.js",
-    "./theme-tokens.css": "./src/theme-tokens.css"
+    "./theme-tokens.css": "./src/theme-tokens.css",
+    "./prose-tokens.css": "./src/prose-tokens.css"
   },
   "files": [
     "src",
@@ -39,8 +40,8 @@
     "fuse.js": "^7.0.0",
     "shiki": "^3.0.0",
     "tailwind-merge": "^3.6.0",
-    "@uniweb/core": "0.7.26",
-    "@uniweb/scene": "0.1.2"
+    "@uniweb/scene": "0.1.2",
+    "@uniweb/core": "0.7.27"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/hooks/index.js

@@ -9,6 +9,7 @@ export { useVersion } from './useVersion.js'
 export { useScrolled } from './useScrolled.js'
 export { useMobileMenu } from './useMobileMenu.js'
 export { useAccordion } from './useAccordion.js'
+export { useHeadings } from './useHeadings.js'
 export { useGridLayout, getGridClasses } from './useGridLayout.js'
 export { useTheme, getThemeClasses, THEMES, THEME_NAMES } from './useTheme.js'
 export { useInView, useIsInView } from './useInView.js'

package/src/hooks/useHeadings.js

@@ -0,0 +1,218 @@
+/**
+ * useHeadings Hook
+ *
+ * The headings of the page being read, plus which one the reader is level with.
+ * What a table of contents needs, without any opinion about how it looks.
+ *
+ * Every documentation shell on this framework has hand-written this, and each
+ * one wrote it the only way a foundation can: scan the DOM for `h2, h3` after
+ * the body renders. That works, but it costs a frame of timing guesswork and it
+ * cannot run during prerender, so the rail is missing from every served page
+ * until hydration.
+ *
+ * The framework can do better because it owns both ends. It renders the
+ * headings and stamps their ids (`headingId`), and it holds the page content
+ * that produced them — so the list can come from the content, before anything
+ * is painted, and be guaranteed to match the anchors. Only the highlight needs
+ * the DOM, because only scrolling does.
+ *
+ * @example
+ * function PageContents() {
+ *   const { headings, activeId, scrollTo } = useHeadings()
+ *   if (!headings.length) return null
+ *
+ *   return (
+ *     <nav aria-label="On this page">
+ *       {headings.map(h => (
+ *         <button key={h.id} onClick={() => scrollTo(h.id)}
+ *                 className={h.id === activeId ? 'text-primary' : 'text-subtle'}>
+ *           {h.text}
+ *         </button>
+ *       ))}
+ *     </nav>
+ *   )
+ * }
+ */
+
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { headingId, nodeText } from '../utils/index.js'
+import { useWebsite } from './useWebsite.js'
+import { useActiveRoute } from './useActiveRoute.js'
+
+/**
+ * Pull headings out of the page's own content — available during prerender.
+ *
+ * Skips the headings the semantic parser claimed as the section's own
+ * title/pretitle/subtitle. In this framework a leading `###` is a pretitle and
+ * the `##` after the title is a subtitle — structure, not body headings — so a
+ * typed section would otherwise open every contents rail with two entries no
+ * reader recognises as sections of the article. An untyped document has none of
+ * those fields set, and everything in it counts.
+ */
+export function headingsFromContent(page, levels = [2, 3]) {
+  const blocks = page?.getBodyBlocks?.() ?? []
+  const found = []
+
+  for (const block of blocks) {
+    const nodes = block?.rawContent?.content
+    if (!Array.isArray(nodes)) continue
+
+    const parsed = block.parsedContent || {}
+    const claimed = new Set(
+      [parsed.title, parsed.pretitle, parsed.subtitle]
+        .flat()
+        .filter(Boolean)
+        .map(value => String(value).trim())
+    )
+
+    for (const node of nodes) {
+      if (node?.type !== 'heading') continue
+      const level = node.attrs?.level ?? 1
+      if (!levels.includes(level)) continue
+
+      const text = nodeText(node).trim()
+      if (!text || claimed.has(text)) continue
+
+      found.push({ id: headingId(text), text, level })
+    }
+  }
+
+  return found
+}
+
+/**
+ * Fall back to the rendered document, for content this hook cannot see — a
+ * foundation rendering its own markup, or anything not built from page blocks.
+ */
+function headingsFromDom(root, levels) {
+  if (typeof document === 'undefined') return []
+
+  const scope = document.querySelector(root)
+  if (!scope) return []
+
+  const selector = levels.map(level => `h${level}`).join(', ')
+
+  return [...scope.querySelectorAll(selector)]
+    .map(el => {
+      const text = el.textContent?.trim() || ''
+      if (!text) return null
+      // Adopt the id that is there; stamp the shared one when it is missing, so
+      // scrollTo has something to find either way.
+      if (!el.id) el.id = headingId(text)
+      return { id: el.id, text, level: Number(el.tagName[1]) }
+    })
+    .filter(Boolean)
+}
+
+/**
+ * Nest a flat, ordered heading list by level. A heading deeper than the one
+ * before it becomes its child; anything at or above the top level starts a new
+ * branch. Headings that skip a level still land somewhere sensible.
+ */
+function nest(flat) {
+  if (!flat.length) return []
+
+  const topLevel = Math.min(...flat.map(h => h.level))
+  const tree = []
+  let current = null
+
+  for (const heading of flat) {
+    const node = { ...heading, children: [] }
+    if (heading.level === topLevel || !current) {
+      tree.push(node)
+      current = node
+    } else {
+      current.children.push(node)
+    }
+  }
+
+  return tree
+}
+
+/**
+ * Height of the fixed site header, so anchors are not scrolled under it.
+ */
+function headerOffset(explicit) {
+  if (typeof explicit === 'number') return explicit
+  if (typeof document === 'undefined') return 0
+
+  const declared = getComputedStyle(document.documentElement).getPropertyValue('--header-height')
+  return (parseInt(declared, 10) || 0) + 16
+}
+
+/**
+ * @param {Object} [options]
+ * @param {number[]} [options.levels=[2,3]] - Heading levels to collect
+ * @param {string} [options.root='main'] - Selector to scan, for the DOM fallback
+ * @param {number} [options.offset] - Scroll offset in px; defaults to the site
+ *   header's height read from `--header-height`, plus a little breathing room
+ * @returns {{ headings: Array, activeId: string, scrollTo: (id: string) => void }}
+ *   `headings` is nested — each entry carries `{ id, text, level, children }`
+ */
+export function useHeadings({ levels = [2, 3], root = 'main', offset } = {}) {
+  const { website } = useWebsite()
+  const { route } = useActiveRoute()
+  const [domHeadings, setDomHeadings] = useState(null)
+  const [activeId, setActiveId] = useState('')
+
+  // The content path runs during render, so it is available server-side.
+  const contentHeadings = useMemo(
+    () => headingsFromContent(website?.activePage, levels),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [website?.activePage, route, levels.join()]
+  )
+
+  // Only reached when the content path found nothing.
+  useEffect(() => {
+    setActiveId('')
+    if (contentHeadings.length) {
+      setDomHeadings(null)
+      return
+    }
+    const id = requestAnimationFrame(() => setDomHeadings(headingsFromDom(root, levels)))
+    return () => cancelAnimationFrame(id)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [route, contentHeadings.length, root, levels.join()])
+
+  const flat = contentHeadings.length ? contentHeadings : domHeadings ?? []
+  const headings = useMemo(() => nest(flat), [flat])
+
+  // Which heading the reader is level with. Scroll position is the one thing
+  // here that only the DOM knows.
+  useEffect(() => {
+    if (!flat.length || typeof window === 'undefined') return
+
+    const gap = headerOffset(offset)
+
+    function onScroll() {
+      const line = window.scrollY + gap + 4
+      let current = ''
+      for (const { id } of flat) {
+        const el = document.getElementById(id)
+        if (el && el.getBoundingClientRect().top + window.scrollY <= line) current = id
+      }
+      setActiveId(current || flat[0].id)
+    }
+
+    window.addEventListener('scroll', onScroll, { passive: true })
+    onScroll()
+    return () => window.removeEventListener('scroll', onScroll)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [flat.map(h => h.id).join(), offset])
+
+  const scrollTo = useCallback(
+    id => {
+      const el = typeof document !== 'undefined' && document.getElementById(id)
+      if (!el) return
+      window.scrollTo({
+        top: el.getBoundingClientRect().top + window.scrollY - headerOffset(offset),
+        behavior: 'smooth',
+      })
+    },
+    [offset]
+  )
+
+  return { headings, activeId, scrollTo }
+}
+
+export default useHeadings

package/src/index.js

@@ -62,6 +62,7 @@ export {
   useScrolled,
   useMobileMenu,
   useAccordion,
+  useHeadings,
   useGridLayout,
   getGridClasses,
   useTheme,
@@ -99,6 +100,10 @@ export {
   parseIconRef,
   // Content utilities
   splitContent,
+  // Heading anchors — one generator, shared by the renderers that stamp them
+  // and by anything that links to one (see useHeadings).
+  headingId,
+  nodeText,
   // Href resolution (for foundations rendering their own links or prose HTML)
   applyBasePath,
   resolveRoute,
@@ -119,7 +124,6 @@ export {
 // Styled Components (Tailwind-based)
 // ============================================================================
 
-export { SidebarLayout } from './styled/SidebarLayout/index.js'
 export { Section, Render } from './styled/Section/index.js'
 export { Prose } from './styled/Prose/index.jsx'
 export { Article } from './styled/Article/index.jsx'

package/src/prose-tokens.css

@@ -0,0 +1,73 @@
+/*
+ * Tailwind Typography, wired to the theme.
+ *
+ * Usage — after the plugin, so these win on equal specificity:
+ *
+ *   @plugin "@tailwindcss/typography";
+ *   @import "@uniweb/kit/prose-tokens.css";
+ *
+ * `prose` ships its own greys, which means long-form body copy is the one part
+ * of a foundation that ignores the site's theme.yml unless someone bridges it
+ * by hand. Everyone does bridge it by hand, identically, and the bridge is easy
+ * to get subtly wrong — so it lives here.
+ *
+ * After this import, a prose container answers to the site like everything else
+ * and flips with the visitor's scheme on its own. Do not add a `prose-invert`
+ * or a `dark:` variant: the tokens have already changed by the time the dark
+ * scheme is active, and `prose-invert` would override this with fixed greys.
+ *
+ * For the same reason, do not add a palette modifier — `prose-gray`,
+ * `prose-slate`, `prose-neutral`. Those re-declare every variable below.
+ *
+ * ── One container ──
+ *
+ * These variables are inherited, so a `prose` container nested inside another
+ * silently resets the lot for its subtree. Two containers is always a bug, and
+ * a quiet one: the outer looks right and everything inside it does not. Decide
+ * who owns prose — the section that renders the document is usually the better
+ * owner, since it then renders correctly under any layout — and make sure the
+ * other one only supplies column width and padding.
+ */
+
+.prose {
+  --tw-prose-body: var(--body);
+  --tw-prose-headings: var(--heading);
+  --tw-prose-lead: var(--subtle);
+  --tw-prose-links: var(--link, var(--primary));
+  --tw-prose-bold: var(--heading);
+  --tw-prose-counters: var(--subtle);
+  --tw-prose-bullets: var(--border);
+  --tw-prose-hr: var(--border);
+  --tw-prose-quotes: var(--subtle);
+  --tw-prose-quote-borders: var(--primary);
+  --tw-prose-captions: var(--subtle);
+  --tw-prose-kbd: var(--heading);
+  --tw-prose-code: var(--heading);
+  --tw-prose-th-borders: var(--border);
+  --tw-prose-td-borders: var(--border);
+
+  /* Fenced code keeps whatever the highlighter paints — a site retunes that
+     through `code:` in theme.yml, not here. */
+  --tw-prose-pre-code: var(--code-text, var(--body));
+  --tw-prose-pre-bg: var(--code-surface, var(--muted));
+}
+
+/* Inline code reads as a chip on whatever surface it sits on, rather than the
+   plugin's fixed grey. Scoped to `:not(pre)` so fenced blocks are untouched. */
+.prose :not(pre) > code {
+  background-color: color-mix(in oklch, var(--section), var(--heading) 6%);
+  border-radius: 0.25rem;
+  padding: 0.125rem 0.375rem;
+  font-weight: 500;
+  font-size: 0.875em;
+}
+.prose :not(pre) > code::before,
+.prose :not(pre) > code::after {
+  content: none;
+}
+
+/* Anchors land clear of a fixed site header when something scrolls to them —
+   a contents rail, or a link with a #fragment. */
+.prose :is(h1, h2, h3, h4) {
+  scroll-margin-top: calc(var(--header-height, 4rem) + 1rem);
+}

package/src/styled/Prose/index.jsx

@@ -11,7 +11,7 @@
  */
 
 import React from 'react'
-import { cn, getChildBlockRenderer } from '../../utils/index.js'
+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'
@@ -30,13 +30,6 @@ const SIZE_CLASSES = {
   '2xl': 'prose-2xl'
 }
 
-function generateId(text) {
-  return text
-    .replace(/<[^>]*>/g, '')
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-|-$/g, '')
-}
 
 const INLINE_INSET_RE = /<uniweb-inset data-ref-id="([^"]+)"><\/uniweb-inset>/g
 
@@ -92,7 +85,7 @@ function SequenceElement({ element, block }) {
     case 'heading': {
       const level = Math.min(element.level || 1, 6)
       const Tag = `h${level}`
-      const id = generateId(element.text || '')
+      const id = headingId(element.text || '')
       return <Tag id={id}><SafeHtml value={element.text} as="span" /></Tag>
     }
 

package/src/styled/Section/Render.jsx

@@ -8,7 +8,7 @@
  */
 
 import React from 'react'
-import { cn, getChildBlockRenderer } from '../../utils/index.js'
+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'
@@ -33,15 +33,6 @@ function extractText(node) {
   return ''
 }
 
-/**
- * Generate ID from heading text
- */
-function generateId(text) {
-  return text
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-|-$/g, '')
-}
 
 /**
  * Render a list (ordered or unordered)
@@ -81,7 +72,7 @@ function RenderNode({ node, block, ...props }) {
     case 'heading': {
       const level = attrs?.level || 1
       const text = extractText(node)
-      const id = generateId(text)
+      const id = headingId(text)
       const Tag = `h${Math.min(level, 6)}`
 
       return (

package/src/styled/Section/renderers/Code.jsx

@@ -1,9 +1,10 @@
 /**
  * Code Block Renderer
  *
- * Renders syntax-highlighted code blocks using Shiki.
- * Shiki is lazy-loaded only when code blocks are actually used,
- * and CSS variables are injected at runtime from theme.code.
+ * Renders syntax-highlighted code blocks using Shiki, lazy-loaded only when a
+ * page actually has one. A site's `theme.yml` `code:` block becomes a Shiki
+ * theme layered over the default, so the colours a site declares are the
+ * colours Shiki writes.
  *
  * @module @uniweb/kit/Section/renderers/Code
  */
@@ -16,37 +17,90 @@ import { getUniweb } from '@uniweb/core'
 let cssInjected = false
 let shikiInstance = null
 let shikiLoadPromise = null
+let siteThemeLoaded = false
+
+// What a site gets when it declares no `code:` block of its own, and the base
+// every declaration layers over.
+const DEFAULT_THEME = 'github-dark'
 
 /**
- * Map theme.code keys to Shiki CSS variable names
+ * Where each documented `theme.code` key lands in TextMate scope terms.
+ *
+ * Shiki colours by scope, so a declaration only reaches the output by becoming
+ * a scope rule. This used to map the same keys onto `--shiki-*` CSS variables,
+ * which could never take effect: Shiki writes its theme as an inline style on
+ * the <pre> and on every token span, and an inline style outranks any
+ * stylesheet. The `code:` block was documented, parsed, and inert.
+ *
+ * `lineNumber` and `selection` are deliberately absent. They are editor chrome,
+ * not token scopes, and Shiki's HTML has neither.
+ */
+const SCOPE_MAP = {
+  comment: ['comment', 'punctuation.definition.comment'],
+  string: ['string', 'string.quoted', 'constant.other.symbol'],
+  keyword: ['keyword', 'storage', 'storage.type', 'keyword.control'],
+  operator: ['keyword.operator'],
+  function: ['entity.name.function', 'support.function', 'meta.function-call'],
+  variable: ['variable', 'variable.other.readwrite'],
+  number: ['constant.numeric'],
+  constant: ['constant.language', 'constant.character', 'support.constant'],
+  type: ['entity.name.type', 'entity.name.class', 'support.type', 'support.class'],
+  property: ['variable.other.property', 'support.type.property-name', 'meta.object-literal.key'],
+  tag: ['entity.name.tag'],
+  attribute: ['entity.other.attribute-name'],
+  punctuation: ['punctuation'],
+}
+
+export const SITE_CODE_THEME = 'uniweb-site-code'
+
+/**
+ * Build a Shiki theme from a site's `theme.yml` `code:` block, layered over a
+ * base theme.
+ *
+ * Layering rather than replacing is the point. Most sites declare `background:`
+ * alone — "the same highlighting, on my surface" — and building a theme from
+ * only the declared keys would strip every syntax colour to answer that. So the
+ * base supplies everything, and each declared key overrides its own scopes.
+ *
+ * @param {Object} base - A resolved Shiki theme to layer over
+ * @param {Object} code - The site's `theme.code` declaration
+ * @returns {Object} A Shiki theme registration
  */
-const CSS_VAR_MAP = {
-  background: '--shiki-background',
-  foreground: '--shiki-foreground',
-  keyword: '--shiki-token-keyword',
-  string: '--shiki-token-string',
-  number: '--shiki-token-constant',
-  comment: '--shiki-token-comment',
-  function: '--shiki-token-function',
-  variable: '--shiki-token-variable',
-  operator: '--shiki-token-operator',
-  punctuation: '--shiki-token-punctuation',
-  type: '--shiki-token-type',
-  constant: '--shiki-token-constant',
-  property: '--shiki-token-property',
-  tag: '--shiki-token-tag',
-  attribute: '--shiki-token-attribute',
-  lineNumber: '--shiki-line-number',
-  selection: '--shiki-selection',
+export function buildCodeTheme(base, code) {
+  const theme = {
+    ...base,
+    name: SITE_CODE_THEME,
+    colors: { ...base?.colors },
+    // Declared scopes go last so they win over the base's own rules.
+    settings: [...(base?.settings ?? [])],
+  }
+
+  if (code?.background) {
+    theme.bg = code.background
+    theme.colors['editor.background'] = code.background
+  }
+  if (code?.foreground) {
+    theme.fg = code.foreground
+    theme.colors['editor.foreground'] = code.foreground
+  }
+
+  for (const [key, scope] of Object.entries(SCOPE_MAP)) {
+    if (code?.[key]) theme.settings.push({ scope, settings: { foreground: code[key] } })
+  }
+
+  return theme
 }
 
 /**
- * Inject CSS variables from theme.code into the document
+ * Layout for the highlighted block. Colour is not set here — Shiki writes the
+ * theme's own inline, and the theme is now the site's (see buildCodeTheme).
+ * What is left is spacing and the code face, so a listing is legible before a
+ * foundation styles it, without kit deciding what colour anything is.
  */
-function injectCodeThemeCSS(codeTheme) {
+function injectCodeLayoutCSS() {
   if (cssInjected || typeof document === 'undefined') return
 
-  const styleId = 'uniweb-code-theme'
+  const styleId = 'uniweb-code-layout'
 
   // Check if already injected (e.g., by another component instance)
   if (document.getElementById(styleId)) {
@@ -54,38 +108,15 @@ function injectCodeThemeCSS(codeTheme) {
     return
   }
 
-  // Build CSS variables
-  const cssVars = []
-  for (const [key, value] of Object.entries(codeTheme || {})) {
-    const varName = CSS_VAR_MAP[key]
-    if (varName && value) {
-      cssVars.push(`${varName}: ${value};`)
-    }
-  }
-
-  // Create and inject style element
   const style = document.createElement('style')
   style.id = styleId
   style.textContent = `
-:root {
-  ${cssVars.join('\n  ')}
-}
-
-/* Code block base styles */
 .shiki {
-  background-color: var(--shiki-background, #1e1e2e);
-  color: var(--shiki-foreground, #cdd6f4);
   padding: 1rem;
   border-radius: 0.5rem;
   overflow-x: auto;
 }
 
-/* Ensure proper token colors */
-.shiki span {
-  color: var(--shiki-token-foreground, inherit);
-}
-
-/* Code element inside shiki */
 .shiki code {
   display: block;
   font-family: var(--font-code, ui-monospace, SFMono-Regular, "SF Mono", Menlo, Monaco, Consolas, monospace);
@@ -138,13 +169,33 @@ async function loadShiki() {
   return shikiLoadPromise
 }
 
+/**
+ * Register the site's `code:` declaration as a theme, once, and answer with the
+ * theme name to highlight against. Sites that declare nothing get the default.
+ */
+async function resolveThemeName(highlighter, codeTheme) {
+  if (!codeTheme || Object.keys(codeTheme).length === 0) return DEFAULT_THEME
+  if (siteThemeLoaded) return SITE_CODE_THEME
+
+  try {
+    await highlighter.loadTheme(buildCodeTheme(highlighter.getTheme(DEFAULT_THEME), codeTheme))
+    siteThemeLoaded = true
+    return SITE_CODE_THEME
+  } catch (error) {
+    console.warn('[Code] Could not apply theme.code, using the default:', error)
+    return DEFAULT_THEME
+  }
+}
+
 /**
  * Highlight code using Shiki
  */
-async function highlightCode(code, language, highlighter) {
+async function highlightCode(code, language, highlighter, codeTheme) {
   if (!highlighter) return null
 
   try {
+    const theme = await resolveThemeName(highlighter, codeTheme)
+
     // Load language if not already loaded
     const loadedLangs = highlighter.getLoadedLanguages()
     const lang = language?.toLowerCase() || 'plaintext'
@@ -154,16 +205,13 @@ async function highlightCode(code, language, highlighter) {
         await highlighter.loadLanguage(lang)
       } catch {
         // Language not available, fall back to plaintext
-        return highlighter.codeToHtml(code, {
-          lang: 'plaintext',
-          theme: 'github-dark',
-        })
+        return highlighter.codeToHtml(code, { lang: 'plaintext', theme })
       }
     }
 
     return highlighter.codeToHtml(code, {
       lang: lang === 'plaintext' ? 'text' : lang,
-      theme: 'github-dark',
+      theme,
     })
   } catch (error) {
     console.warn('[Code] Highlighting failed:', error)
@@ -207,12 +255,11 @@ export function Code({ content, language = 'plaintext', className, ...props }) {
     return aliases[l] || l
   }, [language])
 
-  // Inject CSS on first render (if in browser)
+  // Inject layout CSS on first render (if in browser). Unlike the colours, this
+  // is wanted whether or not the site declared a `code:` block.
   useEffect(() => {
-    if (typeof document !== 'undefined' && codeTheme) {
-      injectCodeThemeCSS(codeTheme)
-    }
-  }, [codeTheme])
+    injectCodeLayoutCSS()
+  }, [])
 
   // Load Shiki and highlight code
   useEffect(() => {
@@ -223,7 +270,7 @@ export function Code({ content, language = 'plaintext', className, ...props }) {
       if (cancelled) return
 
       if (highlighter && content) {
-        const html = await highlightCode(content, lang, highlighter)
+        const html = await highlightCode(content, lang, highlighter, codeTheme)
         if (!cancelled) {
           setHighlightedHtml(html)
         }
@@ -235,7 +282,7 @@ export function Code({ content, language = 'plaintext', className, ...props }) {
     return () => {
       cancelled = true
     }
-  }, [content, lang])
+  }, [content, lang, codeTheme])
 
   // Render highlighted code or fallback
   if (highlightedHtml) {
@@ -248,18 +295,19 @@ export function Code({ content, language = 'plaintext', className, ...props }) {
     )
   }
 
-  // Fallback: plain code block (shown before Shiki loads or if it fails)
-  // No loading indicator - the code content is already visible and readable.
-  // When Shiki loads, syntax colors will appear smoothly.
+  // Fallback: plain code block (shown before Shiki loads or if it fails).
+  // No loading indicator — the code is already readable, and the syntax colours
+  // arrive when Shiki does. Semantic tokens, so the wait looks like the site
+  // rather than like a fixed grey no theme asked for.
   return (
     <pre
       className={cn(
-        'overflow-x-auto rounded-lg bg-gray-900 p-4 text-sm',
+        'overflow-x-auto rounded-lg bg-muted p-4 text-sm text-body',
         className
       )}
       {...props}
     >
-      <code className={`language-${lang} text-gray-100`}>
+      <code className={`language-${lang}`}>
         {content}
       </code>
     </pre>

package/src/styled/index.js

@@ -7,14 +7,13 @@
  * For unstyled primitives, use the main '@uniweb/kit' export.
  *
  * @example
- * import { SidebarLayout, Section, Media } from '@uniweb/kit (styled)'
+ * import { Section, Prose, Media } from '@uniweb/kit (styled)'
  */
 
 // ============================================================================
 // Layout
 // ============================================================================
 
-export { SidebarLayout } from './SidebarLayout/index.js'
 
 // ============================================================================
 // Content Rendering

package/src/utils/index.js

@@ -248,3 +248,37 @@ export function detectMediaType(url) {
 // ─────────────────────────────────────────────────────────────────
 
 export { submitForm, derivePreviewFromFormData } from './submitForm.js'
+
+/**
+ * The text of a ProseMirror node, flattened.
+ *
+ * @param {Object|string} node - A ProseMirror node
+ * @returns {string}
+ */
+export function nodeText(node) {
+  if (!node) return ''
+  if (typeof node === 'string') return node
+  if (node.text) return node.text
+  if (node.content) return node.content.map(nodeText).join('')
+  return ''
+}
+
+/**
+ * The anchor id for a heading.
+ *
+ * One generator, used by every renderer that stamps a heading and by anything
+ * that links to one. That agreement is the whole point: a table of contents
+ * scrolls to an id some other module produced, so a second implementation is a
+ * drift waiting to happen — and there were two, differing in whether they
+ * stripped markup first, which decided whether a heading containing a link got
+ * a usable anchor.
+ *
+ * @param {string} text - Heading text, plain or containing markup
+ * @returns {string}
+ */
+export function headingId(text) {
+  return stripTags(String(text ?? ''))
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+}

package/src/styled/SidebarLayout/SidebarLayout.jsx

@@ -1,310 +0,0 @@
-import React, { useEffect } from 'react'
-import { cn } from '../../utils/index.js'
-import { useMobileMenu } from '../../hooks/useMobileMenu.js'
-
-/**
- * SidebarLayout Component
- *
- * A flexible layout with optional left and/or right sidebars.
- * On desktop, sidebars appear inline at their configured breakpoints.
- * On mobile, the left panel is accessible via a slide-out drawer with FAB toggle.
- * The right panel is hidden on mobile (common pattern: nav essential, TOC optional).
- *
- * The layout is "sandwiched" - header and footer span the full width,
- * with the sidebars and content area between them.
- *
- * @example
- * // In foundation's src/foundation.js
- * import { SidebarLayout } from '@uniweb/kit'
- *
- * export default {
- *   Layout: SidebarLayout,
- * }
- *
- * @example
- * // With custom configuration
- * import { SidebarLayout } from '@uniweb/kit'
- *
- * function CustomLayout(props) {
- *   return (
- *     <SidebarLayout
- *       {...props}
- *       leftBreakpoint="lg"
- *       rightBreakpoint="xl"
- *       leftWidth="w-72"
- *     />
- *   )
- * }
- *
- * export default { Layout: CustomLayout }
- */
-
-/**
- * Hamburger menu icon
- */
-function MenuIcon({ className }) {
-  return (
-    <svg className={className} fill="none" viewBox="0 0 24 24" stroke="currentColor">
-      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 6h16M4 12h16M4 18h16" />
-    </svg>
-  )
-}
-
-/**
- * Close (X) icon
- */
-function CloseIcon({ className }) {
-  return (
-    <svg className={className} fill="none" viewBox="0 0 24 24" stroke="currentColor">
-      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-    </svg>
-  )
-}
-
-/**
- * Mobile drawer component (always slides from left)
- */
-function MobileDrawer({ isOpen, onClose, width, stickyHeader, children }) {
-  // Prevent body scroll when drawer is open
-  useEffect(() => {
-    if (isOpen) {
-      document.body.style.overflow = 'hidden'
-      return () => {
-        document.body.style.overflow = ''
-      }
-    }
-  }, [isOpen])
-
-  // Position below header if sticky, otherwise from top
-  const topOffset = stickyHeader ? 'top-16' : 'top-0'
-  const height = stickyHeader ? 'h-[calc(100vh-4rem)]' : 'h-screen'
-
-  return (
-    <>
-      {/* Backdrop */}
-      <div
-        className={cn(
-          'fixed inset-0 bg-black/50 z-40 transition-opacity duration-300',
-          isOpen ? 'opacity-100' : 'opacity-0 pointer-events-none'
-        )}
-        onClick={onClose}
-        aria-hidden="true"
-      />
-
-      {/* Drawer (always from left) */}
-      <div
-        className={cn(
-          'fixed left-0 bg-white z-50 shadow-xl',
-          topOffset,
-          height,
-          width,
-          'transform transition-transform duration-300 ease-in-out',
-          isOpen ? 'translate-x-0' : '-translate-x-full'
-        )}
-        role="dialog"
-        aria-modal="true"
-        aria-label="Sidebar navigation"
-      >
-        {/* Close button */}
-        <button
-          onClick={onClose}
-          className="absolute top-4 right-4 p-1.5 rounded-md hover:bg-gray-100 transition-colors"
-          aria-label="Close sidebar"
-        >
-          <CloseIcon className="w-5 h-5 text-gray-500" />
-        </button>
-
-        {/* Drawer content */}
-        <div className="h-full overflow-y-auto overscroll-contain">
-          {children}
-        </div>
-      </div>
-    </>
-  )
-}
-
-/**
- * Floating action button for mobile menu (always bottom-left)
- */
-function FloatingMenuButton({ onClick }) {
-  return (
-    <button
-      onClick={onClick}
-      className={cn(
-        'fixed bottom-4 left-4 z-30',
-        'p-3 bg-primary text-white rounded-full shadow-lg',
-        'hover:bg-primary/90 active:scale-95 transition-all',
-        'focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2'
-      )}
-      aria-label="Open navigation menu"
-    >
-      <MenuIcon className="w-6 h-6" />
-    </button>
-  )
-}
-
-/**
- * Get responsive classes for showing/hiding at breakpoint
- */
-function getBreakpointClasses(breakpoint) {
-  const showClass = {
-    sm: 'sm:block',
-    md: 'md:block',
-    lg: 'lg:block',
-    xl: 'xl:block',
-  }[breakpoint] || 'md:block'
-
-  const hideClass = {
-    sm: 'sm:hidden',
-    md: 'md:hidden',
-    lg: 'lg:hidden',
-    xl: 'xl:hidden',
-  }[breakpoint] || 'md:hidden'
-
-  return { showClass, hideClass }
-}
-
-/**
- * SidebarLayout main component
- *
- * @param {Object} props
- * @param {React.ReactNode} props.header - Header content (from layout/header.md)
- * @param {React.ReactNode} props.body - Main body content (page sections)
- * @param {React.ReactNode} props.footer - Footer content (from layout/footer.md)
- * @param {React.ReactNode} props.left - Left panel content (from layout/left.md)
- * @param {React.ReactNode} props.right - Right panel content (from layout/right.md)
- * @param {React.ReactNode} props.leftPanel - Alias for left (backwards compatibility)
- * @param {React.ReactNode} props.rightPanel - Alias for right (backwards compatibility)
- * @param {string} [props.leftWidth='w-64'] - Tailwind width class for left sidebar
- * @param {string} [props.rightWidth='w-64'] - Tailwind width class for right sidebar
- * @param {string} [props.drawerWidth='w-72'] - Tailwind width class for mobile drawer
- * @param {string} [props.leftBreakpoint='md'] - Breakpoint for showing left sidebar inline
- * @param {string} [props.rightBreakpoint='xl'] - Breakpoint for showing right sidebar inline
- * @param {boolean} [props.stickyHeader=true] - Whether header sticks to top
- * @param {boolean} [props.stickySidebar=true] - Whether sidebars stick below header
- * @param {string} [props.maxWidth='max-w-7xl'] - Max width of content area
- * @param {string} [props.contentPadding='px-4 py-8 sm:px-6 lg:px-8'] - Padding for main content
- * @param {string} [props.className] - Additional classes for the root element
- */
-export function SidebarLayout({
-  // Pre-rendered layout areas from runtime
-  header,
-  body,
-  footer,
-  left,
-  right,
-  leftPanel,
-  rightPanel,
-  // Configuration
-  leftWidth = 'w-64',
-  rightWidth = 'w-64',
-  drawerWidth = 'w-72',
-  leftBreakpoint = 'md',
-  rightBreakpoint = 'xl',
-  stickyHeader = true,
-  stickySidebar = true,
-  maxWidth = 'max-w-7xl',
-  contentPadding = 'px-4 py-8 sm:px-6 lg:px-8',
-  className,
-}) {
-  const { isOpen, open, close } = useMobileMenu()
-
-  // Resolve panel content (support both naming conventions)
-  const leftContent = left || leftPanel
-  const rightContent = right || rightPanel
-
-  // Get breakpoint classes for each panel
-  const leftClasses = getBreakpointClasses(leftBreakpoint)
-  const rightClasses = getBreakpointClasses(rightBreakpoint)
-
-  // Sticky positioning
-  const headerClasses = stickyHeader
-    ? 'sticky top-0 z-30'
-    : ''
-
-  const sidebarClasses = stickySidebar && stickyHeader
-    ? 'sticky top-16 h-[calc(100vh-4rem)]'
-    : stickySidebar
-      ? 'sticky top-0 h-screen'
-      : ''
-
-  return (
-    <div className={cn('min-h-screen flex flex-col bg-white', className)}>
-      {/* Header */}
-      {header && (
-        <header className={cn(
-          'w-full border-b border-gray-200 bg-white/95 backdrop-blur supports-[backdrop-filter]:bg-white/80',
-          headerClasses
-        )}>
-          {header}
-        </header>
-      )}
-
-      {/* Mobile Drawer (left panel only) */}
-      {leftContent && (
-        <div className={leftClasses.hideClass}>
-          <MobileDrawer
-            isOpen={isOpen}
-            onClose={close}
-            width={drawerWidth}
-            stickyHeader={stickyHeader}
-          >
-            {leftContent}
-          </MobileDrawer>
-        </div>
-      )}
-
-      {/* Main Content Area */}
-      <div className={cn('flex-1 w-full mx-auto', maxWidth)}>
-        <div className="flex">
-          {/* Left Sidebar (desktop) */}
-          {leftContent && (
-            <aside className={cn(
-              'hidden flex-shrink-0 overflow-y-auto border-r border-gray-200',
-              leftClasses.showClass,
-              leftWidth,
-              sidebarClasses
-            )}>
-              {leftContent}
-            </aside>
-          )}
-
-          {/* Main Content */}
-          <main className="flex-1 min-w-0">
-            <div className={contentPadding}>
-              {body}
-            </div>
-          </main>
-
-          {/* Right Sidebar (desktop only, hidden on mobile) */}
-          {rightContent && (
-            <aside className={cn(
-              'hidden flex-shrink-0 overflow-y-auto border-l border-gray-200',
-              rightClasses.showClass,
-              rightWidth,
-              sidebarClasses
-            )}>
-              {rightContent}
-            </aside>
-          )}
-        </div>
-      </div>
-
-      {/* Footer */}
-      {footer && (
-        <footer className="w-full border-t border-gray-200">
-          {footer}
-        </footer>
-      )}
-
-      {/* Mobile FAB (only if left panel exists) */}
-      {leftContent && (
-        <div className={leftClasses.hideClass}>
-          <FloatingMenuButton onClick={open} />
-        </div>
-      )}
-    </div>
-  )
-}
-
-export default SidebarLayout

package/src/styled/SidebarLayout/index.js

@@ -1 +0,0 @@
-export { SidebarLayout, default } from './SidebarLayout.jsx'