@obvi/blueprint 1.0.10 → 1.1.0

package/dist/blueprint.js

@@ -1,3 +1,936 @@
+// Document chrome — site nav, reading progress, contents rail, and footer
+// metadata are injected at runtime so authored pages stay semantic (<main> only).
+// Chrome glyphs are Iconoir (MIT) line icons, stored as raw path data and
+// drawn at runtime so the framework ships zero icon-pack dependencies. Each
+// stroke inherits currentColor, so the ink-scale tokens theme them for free.
+const SIDEBAR_COLLAPSE_ICON = [
+  'M19 21L5 21C3.89543 21 3 20.1046 3 19L3 5C3 3.89543 3.89543 3 5 3L19 3C20.1046 3 21 3.89543 21 5L21 19C21 20.1046 20.1046 21 19 21Z',
+  'M7.25 10L5.5 12L7.25 14',
+  'M9.5 21V3',
+]
+const SIDEBAR_EXPAND_ICON = [
+  'M19 21L5 21C3.89543 21 3 20.1046 3 19L3 5C3 3.89543 3.89543 3 5 3L19 3C20.1046 3 21 3.89543 21 5L21 19C21 20.1046 20.1046 21 19 21Z',
+  'M9.5 21V3',
+  'M5.5 10L7.25 12L5.5 14',
+]
+const SEARCH_ICON = [
+  'M3 11C3 15.4183 6.58172 19 11 19C13.213 19 15.2161 18.1015 16.6644 16.6493C18.1077 15.2022 19 13.2053 19 11C19 6.58172 15.4183 3 11 3C6.58172 3 3 6.58172 3 11Z',
+  'M17 17L21 21',
+]
+const DOC_CHEVRON_ICON = 'M6 9L12 15L18 9'
+const THEME_MOON_ICON =
+  'M3 11.5066C3 16.7497 7.25034 21 12.4934 21C16.2209 21 19.4466 18.8518 21 15.7259C12.4934 15.7259 8.27411 11.5066 8.27411 3C5.14821 4.55344 3 7.77915 3 11.5066Z'
+const THEME_BULB_ICON = [
+  'M9 18H15',
+  'M10 21H14',
+  'M9.00082 15C9.00098 13 8.50098 12.5 7.50082 11.5C6.50067 10.5 6.02422 9.48689 6.00082 8C5.95284 4.95029 8.00067 3 12.0008 3C16.001 3 18.0488 4.95029 18.0008 8C17.9774 9.48689 17.5007 10.5 16.5008 11.5C15.501 12.5 15.001 13 15.0008 15',
+]
+
+function metaSelector({ name, property } = {}) {
+  if (property) return `meta[property="${property}"]`
+  if (name) return `meta[name="${name}"]`
+  return null
+}
+
+function readMetaContent(doc, target) {
+  const selector = metaSelector(target)
+  return selector ? doc.querySelector(selector)?.content?.trim() ?? '' : ''
+}
+
+function readMetaContentAll(doc, target) {
+  const selector = metaSelector(target)
+  if (!selector) return []
+  return [...doc.querySelectorAll(selector)]
+    .map((meta) => meta.content?.trim())
+    .filter(Boolean)
+}
+
+function readMetaJson(doc, name) {
+  const raw = readMetaContent(doc, { name })
+  if (!raw) return null
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return null
+  }
+}
+
+function formatPublishedDate(iso) {
+  if (!iso) return null
+  const day = iso.includes('T') ? iso.split('T')[0] : iso
+  const date = new Date(day.includes('T') ? day : `${day}T12:00:00`)
+  if (Number.isNaN(date.getTime())) return null
+  return {
+    iso: day,
+    label: date.toLocaleDateString(undefined, {
+      day: 'numeric',
+      month: 'long',
+      year: 'numeric',
+      timeZone: 'UTC',
+    }),
+  }
+}
+
+function pageBasename(href, win) {
+  try {
+    return new URL(href, win.location.href).pathname.split('/').pop() || 'index.html'
+  } catch {
+    return href.split('/').pop() || 'index.html'
+  }
+}
+
+function isCurrentHref(href, win) {
+  const current = win.location.pathname.split('/').pop() || 'index.html'
+  return pageBasename(href, win) === current
+}
+
+function createChromeSvg(doc, pathD, size = 16) {
+  const svg = doc.createElementNS('http://www.w3.org/2000/svg', 'svg')
+  svg.setAttribute('viewBox', '0 0 24 24')
+  svg.setAttribute('fill', 'none')
+  svg.setAttribute('stroke', 'currentColor')
+  svg.setAttribute('stroke-width', '1.5')
+  svg.setAttribute('stroke-linecap', 'round')
+  svg.setAttribute('stroke-linejoin', 'round')
+  svg.setAttribute('width', String(size))
+  svg.setAttribute('height', String(size))
+  svg.setAttribute('aria-hidden', 'true')
+  for (const d of Array.isArray(pathD) ? pathD : [pathD]) {
+    const path = doc.createElementNS('http://www.w3.org/2000/svg', 'path')
+    path.setAttribute('d', d)
+    svg.append(path)
+  }
+  return svg
+}
+
+function injectScrollProgress(doc) {
+  if (doc.querySelector('.scroll-progress')) return null
+  const bar = doc.createElement('div')
+  bar.className = 'scroll-progress'
+  bar.setAttribute('aria-hidden', 'true')
+  return bar
+}
+
+function injectSiteNav(doc, win) {
+  if (doc.querySelector('.site-nav')) return null
+  const links = readMetaJson(doc, 'bp:site-nav')
+  if (!links?.length) return null
+
+  const nav = doc.createElement('nav')
+  nav.className = 'site-nav'
+  nav.setAttribute('aria-label', 'Site')
+
+  const brandLabel =
+    readMetaContent(doc, { property: 'og:site_name' }) ||
+    doc.title.split('—')[0]?.trim() ||
+    'Home'
+  const brandHref = readMetaContent(doc, { name: 'bp:site-home' }) || 'index.html'
+
+  const brand = doc.createElement('a')
+  brand.className = 'site-nav__brand'
+  brand.href = brandHref
+  brand.setAttribute('aria-label', `${brandLabel} home`)
+
+  const logo = doc.createElement('span')
+  logo.className = 'site-nav__logo'
+  logo.setAttribute('aria-hidden', 'true')
+
+  const wordmark = doc.createElement('span')
+  wordmark.className = 'site-nav__wordmark'
+  wordmark.textContent = brandLabel
+
+  brand.append(logo, wordmark)
+
+  const list = doc.createElement('ul')
+  list.className = 'site-nav__links'
+
+  for (const item of links) {
+    const li = doc.createElement('li')
+    const link = doc.createElement('a')
+    link.href = item.href
+    link.textContent = item.label
+    if (item.current || isCurrentHref(item.href, win)) {
+      link.setAttribute('aria-current', 'page')
+    }
+    li.append(link)
+    list.append(li)
+  }
+
+  nav.append(brand, list)
+
+  if (readMetaContent(doc, { name: 'bp:site-theme' }) === 'nav') {
+    const theme = doc.createElement('button')
+    theme.className = 'toggle site-nav__theme'
+    theme.type = 'button'
+    theme.id = 'themeToggle'
+    theme.setAttribute('aria-label', 'Toggle light and dark theme')
+    theme.textContent = 'Theme'
+    nav.append(theme)
+  }
+
+  return nav
+}
+
+function injectSidebarToggle(doc) {
+  if (doc.querySelector('.sidebar-toggle')) return null
+  const toggle = doc.createElement('button')
+  toggle.className = 'sidebar-toggle'
+  toggle.type = 'button'
+  toggle.setAttribute('aria-controls', 'bp-contents-rail')
+  toggle.setAttribute('aria-expanded', 'true')
+  toggle.setAttribute('aria-label', 'Hide contents sidebar')
+
+  const icons = doc.createElement('span')
+  icons.className = 'sidebar-toggle__icons'
+  icons.setAttribute('aria-hidden', 'true')
+
+  const collapse = doc.createElement('span')
+  collapse.className =
+    'sidebar-toggle__icon sidebar-toggle__icon--collapse bp-transition-opacity bp-duration-slow bp-ease-in-out'
+  collapse.append(createChromeSvg(doc, SIDEBAR_COLLAPSE_ICON))
+
+  const expand = doc.createElement('span')
+  expand.className =
+    'sidebar-toggle__icon sidebar-toggle__icon--expand bp-transition-opacity bp-duration-slow bp-ease-in-out'
+  expand.append(createChromeSvg(doc, SIDEBAR_EXPAND_ICON))
+
+  icons.append(collapse, expand)
+  toggle.append(icons)
+  return toggle
+}
+
+function buildDocSwitcher(doc, win) {
+  const collections = readMetaJson(doc, 'bp:collections')
+  if (!collections?.length) return null
+
+  const details = doc.createElement('details')
+  details.className = 'doc-switcher'
+
+  const summary = doc.createElement('summary')
+  summary.className = 'doc-switcher__current sidebar-field'
+  summary.setAttribute('aria-label', 'Switch blueprint collection')
+
+  const current =
+    collections.find((item) => item.current || isCurrentHref(item.href, win)) ??
+    collections[0]
+  const collectionMeta = readMetaContent(doc, { name: 'bp:collection-meta' })
+
+  const label = doc.createElement('span')
+  label.className = 'doc-switcher__label'
+
+  const title = doc.createElement('span')
+  title.className = 'doc-switcher__title'
+  title.textContent = current.title
+
+  const meta = doc.createElement('span')
+  meta.className = 'doc-switcher__meta'
+  meta.textContent = collectionMeta || current.desc || ''
+
+  label.append(title)
+  if (meta.textContent) label.append(meta)
+
+  const chevron = doc.createElement('span')
+  chevron.className =
+    'doc-switcher__chevron bp-transition-transform bp-duration-normal bp-ease-in-out'
+  chevron.setAttribute('aria-hidden', 'true')
+  chevron.append(createChromeSvg(doc, DOC_CHEVRON_ICON))
+
+  summary.append(label, chevron)
+
+  const menu = doc.createElement('div')
+  menu.className = 'doc-switcher__menu'
+  menu.setAttribute('role', 'menu')
+
+  for (const item of collections) {
+    const link = doc.createElement('a')
+    link.href = item.href
+    link.setAttribute('role', 'menuitem')
+    if (item.current || isCurrentHref(item.href, win)) {
+      link.className = 'is-current'
+      link.setAttribute('aria-current', 'page')
+    }
+
+    const option = doc.createElement('span')
+    option.className = 'doc-switcher__option'
+
+    const name = doc.createElement('span')
+    name.className = 'doc-switcher__name'
+    name.textContent = item.title
+
+    option.append(name)
+    if (item.desc) {
+      const desc = doc.createElement('span')
+      desc.className = 'doc-switcher__desc'
+      desc.textContent = item.desc
+      option.append(desc)
+    }
+
+    const go = doc.createElement('span')
+    go.className = 'doc-switcher__go bp-transition-opacity'
+    go.setAttribute('aria-hidden', 'true')
+    go.append(createChromeSvg(doc, DOC_CHEVRON_ICON, 14))
+
+    link.append(option, go)
+    menu.append(link)
+  }
+
+  details.append(summary, menu)
+  return details
+}
+
+function buildSidebarFooter(doc) {
+  const footer = doc.createElement('div')
+  footer.className = 'sidebar-footer'
+
+  const theme = doc.createElement('button')
+  theme.className = 'theme-toggle'
+  theme.type = 'button'
+  theme.setAttribute('role', 'switch')
+  theme.setAttribute('aria-checked', 'false')
+  theme.setAttribute('aria-label', 'Switch to dark theme')
+
+  const thumb = doc.createElement('span')
+  thumb.className =
+    'theme-toggle__thumb bp-transition-transform bp-duration-normal bp-ease-in-out'
+  thumb.setAttribute('aria-hidden', 'true')
+
+  const moon = doc.createElement('span')
+  moon.className = 'theme-toggle__icon theme-toggle__icon--moon'
+  moon.setAttribute('aria-hidden', 'true')
+  moon.append(createChromeSvg(doc, THEME_MOON_ICON, 14))
+
+  const bulb = doc.createElement('span')
+  bulb.className = 'theme-toggle__icon theme-toggle__icon--bulb'
+  bulb.setAttribute('aria-hidden', 'true')
+  bulb.append(createChromeSvg(doc, THEME_BULB_ICON, 14))
+
+  theme.append(thumb, moon, bulb)
+
+  const meta = doc.createElement('div')
+  meta.className = 'sidebar-meta'
+
+  const authors = readMetaContentAll(doc, { property: 'article:author' })
+  const published = formatPublishedDate(
+    readMetaContent(doc, { property: 'article:published_time' })
+  )
+
+  if (authors.length) {
+    const item = doc.createElement('div')
+    item.className = 'sidebar-meta__item'
+    const label = doc.createElement('p')
+    label.className = 'bp-meta'
+    label.textContent = authors.length > 1 ? 'Authors' : 'Author'
+    const value = doc.createElement('p')
+    value.className = 'bp-note'
+    value.textContent = authors.join(', ')
+    item.append(label, value)
+    meta.append(item)
+  }
+
+  if (published) {
+    const item = doc.createElement('div')
+    item.className = 'sidebar-meta__item'
+    const label = doc.createElement('p')
+    label.className = 'bp-meta'
+    label.textContent = 'Date'
+    const value = doc.createElement('p')
+    value.className = 'bp-note'
+    const time = doc.createElement('time')
+    time.dateTime = published.iso
+    time.textContent = published.label
+    value.append(time)
+    item.append(label, value)
+    meta.append(item)
+  }
+
+  footer.append(theme)
+  if (meta.childNodes.length) footer.append(meta)
+  return footer
+}
+
+function injectSidebar(doc, win) {
+  if (doc.querySelector('.bp-sidebar')) return null
+
+  const nav = doc.createElement('nav')
+  nav.className = 'bp-sidebar'
+  nav.id = 'bp-contents-rail'
+  nav.setAttribute('aria-label', 'Contents')
+
+  const panel = doc.createElement('div')
+  panel.className = 'bp-sidebar__panel'
+
+  const search = doc.createElement('div')
+  search.className = 'sidebar-search'
+  // The trigger is a button (it opens a dialog, it is not a text field): the
+  // field carries the chrome (border/radius/surface) and the magnifier + ⌘K
+  // hint sit inside it beside the label. Pressing it — or ⌘K / Ctrl+K — opens
+  // the command palette; see wireSearchPalette().
+  const searchField = doc.createElement('button')
+  searchField.type = 'button'
+  searchField.className =
+    'sidebar-search__field sidebar-field bp-transition-colors bp-ease'
+  searchField.setAttribute('aria-haspopup', 'dialog')
+  searchField.setAttribute('aria-keyshortcuts', 'Meta+K Control+K')
+  searchField.setAttribute('aria-label', 'Search (⌘K)')
+  const searchIcon = createChromeSvg(doc, SEARCH_ICON, 14)
+  searchIcon.classList.add('sidebar-search__icon')
+  const searchLabel = doc.createElement('span')
+  searchLabel.className = 'sidebar-search__label'
+  searchLabel.textContent = 'Search'
+  const searchHint = doc.createElement('span')
+  searchHint.className = 'sidebar-search__hint'
+  searchHint.setAttribute('aria-hidden', 'true')
+  const searchHintCmd = doc.createElement('kbd')
+  searchHintCmd.textContent = '⌘'
+  const searchHintKey = doc.createElement('kbd')
+  searchHintKey.textContent = 'K'
+  searchHint.append(searchHintCmd, searchHintKey)
+  searchField.append(searchIcon, searchLabel, searchHint)
+  search.append(searchField)
+
+  panel.append(search)
+
+  const switcher = buildDocSwitcher(doc, win)
+  if (switcher) panel.append(switcher)
+
+  const list = doc.createElement('ul')
+  panel.append(list)
+
+  nav.append(panel, buildSidebarFooter(doc))
+  return nav
+}
+
+function syncThemeSwitch(doc, button) {
+  const dark = doc.documentElement.dataset.obviousTheme === 'dark'
+  button.setAttribute('aria-checked', String(dark))
+  button.setAttribute(
+    'aria-label',
+    dark ? 'Switch to light theme' : 'Switch to dark theme'
+  )
+}
+
+// A reader's explicit pick is persisted here so the page reopens in their
+// theme — mirrors the bp-sidebar collapse key.
+const THEME_KEY = 'bp-theme'
+
+function readStoredTheme(win) {
+  try {
+    const value = win.localStorage.getItem(THEME_KEY)
+    return value === 'dark' || value === 'light' ? value : null
+  } catch {
+    return null
+  }
+}
+
+function writeStoredTheme(win, value) {
+  try {
+    win.localStorage.setItem(THEME_KEY, value)
+  } catch {}
+}
+
+function systemPrefersDark(win) {
+  try {
+    return win.matchMedia?.('(prefers-color-scheme: dark)').matches ?? false
+  } catch {
+    return false
+  }
+}
+
+// Opt-in (head meta `bp:theme` = "auto"): when no explicit pick exists the page
+// follows the OS color scheme. Off by default, so an author/bridge-set
+// data-obvious-theme is left untouched.
+function followsSystemTheme(doc) {
+  return readMetaContent(doc, { name: 'bp:theme' }).toLowerCase() === 'auto'
+}
+
+function themePrefersReducedMotion(win) {
+  try {
+    return win.matchMedia('(prefers-reduced-motion: reduce)').matches
+  } catch {
+    return false
+  }
+}
+
+function setTheme(doc, theme) {
+  doc.documentElement.dataset.obviousTheme = theme
+  for (const button of doc.querySelectorAll('.theme-toggle')) {
+    syncThemeSwitch(doc, button)
+  }
+}
+
+// Flip with a single compositor crossfade (View Transitions API). Timing is
+// owned by ::view-transition-* rules in blueprint.css. If the update callback
+// is deferred (some embedded hosts), apply immediately so the toggle never
+// desyncs from persistence; instant when reduced motion is on or VT is missing.
+function setThemeAnimated(doc, win, theme) {
+  const apply = () => setTheme(doc, theme)
+  if (themePrefersReducedMotion(win) || typeof doc.startViewTransition !== 'function') {
+    apply()
+    return
+  }
+  const root = doc.documentElement
+  let applied = false
+  const clearSwitching = () => {
+    delete root.dataset.bpThemeSwitching
+  }
+  const runUpdate = () => {
+    applied = true
+    apply()
+  }
+  root.dataset.bpThemeSwitching = ''
+  try {
+    let transition
+    try {
+      transition = doc.startViewTransition({ update: runUpdate, types: ['bp-theme'] })
+    } catch {
+      transition = doc.startViewTransition(runUpdate)
+    }
+    if (!applied) runUpdate()
+    if (transition?.finished) {
+      transition.finished.finally(clearSwitching).catch(clearSwitching)
+    } else {
+      clearSwitching()
+    }
+  } catch {
+    clearSwitching()
+    apply()
+  }
+}
+
+// Resolve the theme at load: a persisted pick always wins; otherwise, when the
+// page opts into bp:theme=auto, follow the OS scheme. No animation on load.
+function resolveInitialTheme(doc, win) {
+  const stored = readStoredTheme(win)
+  if (stored) {
+    setTheme(doc, stored)
+    return
+  }
+  if (followsSystemTheme(doc)) {
+    setTheme(doc, systemPrefersDark(win) ? 'dark' : 'light')
+  }
+}
+
+function wireThemeToggle(doc, win) {
+  const root = doc.documentElement
+  const toggleTheme = () => {
+    const next = root.dataset.obviousTheme === 'dark' ? 'light' : 'dark'
+    setThemeAnimated(doc, win, next)
+    writeStoredTheme(win, next)
+  }
+
+  for (const button of doc.querySelectorAll('.theme-toggle')) {
+    if (button.dataset.bpThemeWired) continue
+    button.dataset.bpThemeWired = 'true'
+    syncThemeSwitch(doc, button)
+    button.addEventListener('click', toggleTheme)
+  }
+
+  const navTheme = doc.getElementById('themeToggle')
+  if (navTheme && !navTheme.dataset.bpThemeWired) {
+    navTheme.dataset.bpThemeWired = 'true'
+    navTheme.addEventListener('click', toggleTheme)
+  }
+
+  // Track the OS scheme live, but only until the reader makes an explicit pick
+  // (a persisted value), which wins thereafter.
+  if (followsSystemTheme(doc) && win.matchMedia) {
+    const query = win.matchMedia('(prefers-color-scheme: dark)')
+    query.addEventListener?.('change', (event) => {
+      if (readStoredTheme(win)) return
+      setThemeAnimated(doc, win, event.matches ? 'dark' : 'light')
+    })
+  }
+}
+
+function wireSidebarCollapse(doc, win) {
+  const root = doc.documentElement
+  const toggle = doc.querySelector('.sidebar-toggle')
+  if (!toggle || toggle.dataset.bpSidebarWired) return
+  toggle.dataset.bpSidebarWired = 'true'
+
+  const KEY = 'bp-sidebar'
+  const read = () => {
+    try {
+      return win.localStorage.getItem(KEY)
+    } catch {
+      return null
+    }
+  }
+  const write = (value) => {
+    try {
+      win.localStorage.setItem(KEY, value)
+    } catch {}
+  }
+  const apply = (collapsed) => {
+    root.dataset.sidebar = collapsed ? 'collapsed' : 'open'
+    toggle.setAttribute('aria-expanded', String(!collapsed))
+    toggle.setAttribute(
+      'aria-label',
+      collapsed ? 'Show contents sidebar' : 'Hide contents sidebar'
+    )
+  }
+
+  apply(read() === 'collapsed')
+  win.requestAnimationFrame(() => {
+    root.classList.add('bp-sidebar-animate')
+  })
+
+  toggle.addEventListener('click', () => {
+    const collapsed = root.dataset.sidebar !== 'collapsed'
+    apply(collapsed)
+    write(collapsed ? 'collapsed' : 'open')
+  })
+}
+
+// Search command palette. The sidebar trigger — and ⌘K / Ctrl+K from anywhere —
+// opens a centered dialog over a scrim. It is wired to the document's own
+// headings: the rail's section links populate the list, the input filters them
+// by a case-insensitive substring, ↑/↓ move the selection, and Enter / click
+// jump to the section and close. Richer search (snippets, ranking, a built
+// index, cross-document scope) is deferred to the search-logic owner; this is
+// the open/close + jump-to-section surface.
+function wireSearchPalette(doc, win) {
+  const trigger = doc.querySelector('.sidebar-search__field')
+  if (!trigger || trigger.dataset.bpSearchWired) return
+  trigger.dataset.bpSearchWired = 'true'
+
+  const isMacLike = /Mac|iPhone|iPad/.test(win.navigator?.platform || '')
+  if (!isMacLike) {
+    const cmd = trigger.querySelector('.sidebar-search__hint kbd')
+    if (cmd) cmd.textContent = 'Ctrl'
+    trigger.setAttribute('aria-label', 'Search (Ctrl+K)')
+  }
+
+  let overlay = null
+  let panel = null
+  let input = null
+  let results = null
+  let footStatus = null
+  let entries = []
+  let visible = []
+  let selected = 0
+  let returnFocus = null
+  let prevOverflow = ''
+
+  // Mirror the document's own structure from the rendered rail, so the palette
+  // stays portable (no per-document hardcoding). Each top-level entry carries
+  // its group eyebrow as the breadcrumb; nested entries fold the parent in too.
+  const collectEntries = () => {
+    const list =
+      doc.querySelector('.bp-sidebar .bp-sidebar__panel > ul') ??
+      doc.querySelector('.bp-toc > ul')
+    if (!list) return []
+    const out = []
+    let group = ''
+    for (const li of list.children) {
+      if (li.classList.contains('bp-nav-group')) {
+        group = (li.textContent || '').trim()
+        continue
+      }
+      const link = li.querySelector(':scope > a[href^="#"]')
+      if (!link) continue
+      const title = (link.textContent || '').trim()
+      out.push({ href: link.getAttribute('href') || '', title, crumb: group })
+      for (const sub of li.querySelectorAll(':scope > ul > li > a[href^="#"]')) {
+        out.push({
+          href: sub.getAttribute('href') || '',
+          title: (sub.textContent || '').trim(),
+          crumb: [group, title].filter(Boolean).join(' › '),
+        })
+      }
+    }
+    return out
+  }
+
+  const keyHint = (caps, labelText) => {
+    const span = doc.createElement('span')
+    span.className = 'docs-search__key'
+    for (const cap of caps) {
+      const kbd = doc.createElement('kbd')
+      kbd.textContent = cap
+      span.append(kbd)
+    }
+    span.append(doc.createTextNode(` ${labelText}`))
+    return span
+  }
+
+  const highlight = (text, q) => {
+    if (!q) return [doc.createTextNode(text)]
+    const idx = text.toLowerCase().indexOf(q)
+    if (idx < 0) return [doc.createTextNode(text)]
+    const mark = doc.createElement('mark')
+    mark.textContent = text.slice(idx, idx + q.length)
+    return [
+      doc.createTextNode(text.slice(0, idx)),
+      mark,
+      doc.createTextNode(text.slice(idx + q.length)),
+    ]
+  }
+
+  const buildRow = (entry, index, q) => {
+    const row = doc.createElement('a')
+    row.className = 'docs-search__row'
+    row.id = `docs-search-row-${index}`
+    row.setAttribute('role', 'option')
+    row.href = entry.href
+    row.dataset.index = String(index)
+    row.addEventListener('click', () => close())
+    row.addEventListener('mousemove', () => {
+      if (selected !== index) {
+        selected = index
+        applySelection()
+      }
+    })
+
+    const mainCol = doc.createElement('span')
+    mainCol.className = 'docs-search__row-main'
+    if (entry.crumb) {
+      const crumb = doc.createElement('span')
+      crumb.className = 'docs-search__crumb'
+      crumb.textContent = entry.crumb
+      mainCol.append(crumb)
+    }
+    const title = doc.createElement('span')
+    title.className = 'docs-search__title'
+    const hash = doc.createElement('span')
+    hash.className = 'docs-search__hash'
+    hash.setAttribute('aria-hidden', 'true')
+    hash.textContent = '#'
+    title.append(hash, ...highlight(entry.title, q))
+    mainCol.append(title)
+
+    const enter = doc.createElement('kbd')
+    enter.className = 'docs-search__enter'
+    enter.textContent = '↵'
+
+    row.append(mainCol, enter)
+    return row
+  }
+
+  const buildEmpty = (query) => {
+    const wrap = doc.createElement('div')
+    wrap.className = 'docs-search__empty'
+    const iconWrap = doc.createElement('span')
+    iconWrap.className = 'docs-search__empty-icon'
+    iconWrap.append(createChromeSvg(doc, SEARCH_ICON, 28))
+    const title = doc.createElement('span')
+    title.className = 'docs-search__empty-title'
+    title.textContent = `No results for “${(query || '').trim()}”`
+    const note = doc.createElement('span')
+    note.className = 'docs-search__empty-note'
+    note.textContent = 'Try a different term, or check your spelling.'
+    wrap.append(iconWrap, title, note)
+    return wrap
+  }
+
+  const applySelection = () => {
+    const rows = results.querySelectorAll('.docs-search__row[role="option"]')
+    let activeId = ''
+    rows.forEach((row, index) => {
+      const isSel = index === selected
+      row.setAttribute('aria-selected', String(isSel))
+      if (isSel) {
+        activeId = row.id
+        row.scrollIntoView({ block: 'nearest' })
+      }
+    })
+    if (activeId) input.setAttribute('aria-activedescendant', activeId)
+    else input.removeAttribute('aria-activedescendant')
+  }
+
+  const move = (delta) => {
+    if (!visible.length) return
+    selected = (selected + delta + visible.length) % visible.length
+    applySelection()
+  }
+
+  const render = (query) => {
+    const q = (query || '').trim().toLowerCase()
+    visible = q
+      ? entries.filter((entry) => entry.title.toLowerCase().includes(q))
+      : entries
+    selected = 0
+    results.replaceChildren()
+
+    if (visible.length === 0) {
+      results.append(buildEmpty(query))
+      footStatus.textContent = '0 results'
+      input.removeAttribute('aria-activedescendant')
+      return
+    }
+
+    const group = doc.createElement('div')
+    group.className = 'docs-search__group'
+    group.append(doc.createTextNode(q ? 'Results' : 'On this page'))
+    const count = doc.createElement('span')
+    count.className = 'docs-search__group-count'
+    count.textContent = String(visible.length)
+    group.append(count)
+    results.append(group)
+
+    visible.forEach((entry, index) => results.append(buildRow(entry, index, q)))
+    applySelection()
+    footStatus.textContent = q
+      ? `${visible.length} result${visible.length === 1 ? '' : 's'}`
+      : 'Jump to a section'
+  }
+
+  const onKeydown = (event) => {
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      close()
+    } else if (event.key === 'ArrowDown') {
+      event.preventDefault()
+      move(1)
+    } else if (event.key === 'ArrowUp') {
+      event.preventDefault()
+      move(-1)
+    } else if (event.key === 'Enter') {
+      const row = results.querySelector(
+        `.docs-search__row[data-index="${selected}"]`
+      )
+      if (row) {
+        event.preventDefault()
+        row.click()
+      }
+    } else if (event.key === 'Tab') {
+      const focusable = panel.querySelectorAll(
+        'a[href], button, input, [tabindex]:not([tabindex="-1"])'
+      )
+      const first = focusable[0]
+      const last = focusable[focusable.length - 1]
+      if (
+        first &&
+        last &&
+        (event.shiftKey ? doc.activeElement === first : doc.activeElement === last)
+      ) {
+        event.preventDefault()
+        ;(event.shiftKey ? last : first).focus()
+      }
+    }
+  }
+
+  const build = () => {
+    overlay = doc.createElement('div')
+    overlay.className = 'docs-search-overlay'
+    overlay.addEventListener('click', (event) => {
+      if (event.target === overlay) close()
+    })
+
+    panel = doc.createElement('div')
+    panel.className = 'docs-search'
+    panel.setAttribute('role', 'dialog')
+    panel.setAttribute('aria-modal', 'true')
+    panel.setAttribute('aria-label', 'Search')
+
+    const field = doc.createElement('div')
+    field.className = 'docs-search__field'
+    const icon = createChromeSvg(doc, SEARCH_ICON, 16)
+    icon.classList.add('docs-search__icon')
+    input = doc.createElement('input')
+    input.className = 'docs-search__input'
+    input.type = 'search'
+    input.placeholder = 'Search the docs…'
+    input.setAttribute('role', 'combobox')
+    input.setAttribute('aria-autocomplete', 'list')
+    input.setAttribute('aria-controls', 'docs-search-listbox')
+    input.setAttribute('aria-expanded', 'false')
+    input.setAttribute('aria-label', 'Search the docs')
+    input.autocomplete = 'off'
+    input.spellcheck = false
+    const esc = doc.createElement('span')
+    esc.className = 'docs-search__esc'
+    esc.textContent = 'esc'
+    field.append(icon, input, esc)
+
+    results = doc.createElement('div')
+    results.className = 'docs-search__results'
+    results.id = 'docs-search-listbox'
+    results.setAttribute('role', 'listbox')
+    results.setAttribute('aria-label', 'Search results')
+
+    const foot = doc.createElement('div')
+    foot.className = 'docs-search__foot'
+    footStatus = doc.createElement('span')
+    const keys = doc.createElement('span')
+    keys.className = 'docs-search__keys'
+    keys.append(
+      keyHint(['↑', '↓'], 'navigate'),
+      keyHint(['↵'], 'open'),
+      keyHint(['esc'], 'close')
+    )
+    foot.append(footStatus, keys)
+
+    panel.append(field, results, foot)
+    overlay.append(panel)
+    ;(doc.body || doc.documentElement).append(overlay)
+
+    input.addEventListener('input', () => render(input.value))
+  }
+
+  const open = () => {
+    if (!overlay) build()
+    if (overlay.classList.contains('is-open')) return
+    entries = collectEntries()
+    returnFocus = doc.activeElement
+    prevOverflow = doc.documentElement.style.overflow
+    doc.documentElement.style.overflow = 'hidden'
+    input.value = ''
+    render('')
+    overlay.classList.add('is-open')
+    input.setAttribute('aria-expanded', 'true')
+    doc.addEventListener('keydown', onKeydown)
+    input.focus({ preventScroll: true })
+    win.requestAnimationFrame(() => input.focus({ preventScroll: true }))
+  }
+
+  function close() {
+    if (!overlay || !overlay.classList.contains('is-open')) return
+    overlay.classList.remove('is-open')
+    input.setAttribute('aria-expanded', 'false')
+    input.removeAttribute('aria-activedescendant')
+    doc.documentElement.style.overflow = prevOverflow ?? ''
+    doc.removeEventListener('keydown', onKeydown)
+    if (returnFocus && typeof returnFocus.focus === 'function') returnFocus.focus()
+  }
+
+  trigger.addEventListener('click', open)
+
+  doc.addEventListener('keydown', (event) => {
+    if ((event.metaKey || event.ctrlKey) && (event.key === 'k' || event.key === 'K')) {
+      event.preventDefault()
+      if (overlay && overlay.classList.contains('is-open')) close()
+      else open()
+    }
+  })
+}
+
+function injectDocumentChrome(doc, win = doc.defaultView) {
+  if (doc.body?.dataset.bpChromeReady === 'true') return
+  const main = doc.querySelector('main')
+  if (!main) return
+
+  const sidebar = injectSidebar(doc, win)
+  const chrome = [
+    injectSiteNav(doc, win),
+    injectScrollProgress(doc),
+    sidebar ? injectSidebarToggle(doc) : null,
+    sidebar,
+  ].filter(Boolean)
+
+  if (chrome.length > 0) {
+    main.before(...chrome)
+  }
+
+  if (sidebar) {
+    doc.documentElement.dataset.bpDocument = ''
+  }
+
+  wireThemeToggle(doc, win)
+  wireSidebarCollapse(doc, win)
+  doc.body.dataset.bpChromeReady = 'true'
+}
+
 // Optional behavior for TOC current state and reading progress.
 import { registerBlueprintChoiceElements } from './blueprint-choices.js'
 
@@ -8,17 +941,27 @@ export function initializeBlueprintRuntime(doc = document, win = window) {
   if (root.dataset.blueprintRuntime === 'ready') return
   root.dataset.blueprintRuntime = 'ready'
 
-  wireSectionHeadingLinks(doc)
+  // Resolve the theme before chrome is injected so the toggle renders in the
+  // correct state and the page doesn't repaint a second time.
+  resolveInitialTheme(doc, win)
+  injectDocumentChrome(doc, win)
+  generateNavigationFromHeadings(doc)
+  wireSectionHeadingLinks(doc, win)
+  wireSearchPalette(doc, win)
   wireFigureDiagramSize(doc)
 
-  // The shell becomes the scroll container only while it is fixed (wide
+  // <main> becomes the scroll container only while it is fixed (wide
   // layout). At ≤700px the CSS reverts it to static and the window scrolls, so
   // resolve the scroller live rather than caching it — a wide→narrow resize
   // otherwise leaves the scroll listener bound to an element that no longer
   // scrolls, silently freezing reading-progress and TOC highlighting.
-  const shell = doc.querySelector('.bp-shell')
+  const main = doc.querySelector('main')
   const resolveScroller = () =>
-    shell && win.getComputedStyle(shell).position === 'fixed' ? shell : null
+    main &&
+    root.dataset.bpDocument !== undefined &&
+    win.getComputedStyle(main).position === 'fixed'
+      ? main
+      : null
   let shellScroller = resolveScroller()
   const scrollTop = () => (shellScroller ? shellScroller.scrollTop : win.scrollY)
   const scrollHeight = () =>
@@ -27,10 +970,23 @@ export function initializeBlueprintRuntime(doc = document, win = window) {
     shellScroller ? shellScroller.clientHeight : win.innerHeight
 
   const progress = doc.querySelector('.scroll-progress')
+  const isPrimaryNavLink = (link) => {
+    const listItem = link.closest('li')
+    const list = listItem?.parentElement
+    if (!list || !listItem) return true
+    const container = link.closest('.bp-sidebar, .bp-toc, .sidebar')
+    if (!container) return true
+    const topList =
+      container.querySelector(':scope > .bp-sidebar__panel > ul') ??
+      container.querySelector(':scope > ul')
+    return list === topList
+  }
   // Only the fixed rails track an active entry. A full-width .bp-contents
   // index (typically parked at the top of a document) has no "current" entry,
-  // so it stays a static index and is intentionally excluded here.
+  // so it stays a static index and is intentionally excluded here. Sub-nav
+  // links nest one level beneath a primary entry and are click targets only.
   const entries = [...doc.querySelectorAll('.bp-sidebar a[href^="#"], .bp-toc a[href^="#"], .sidebar a[href^="#"]')]
+    .filter(isPrimaryNavLink)
     .map((link) => ({
       link,
       section: doc.getElementById(decodeURIComponent(link.hash.slice(1))),
@@ -76,19 +1032,24 @@ export function initializeBlueprintRuntime(doc = document, win = window) {
       progress.style.transform = `scaleX(${max > 0 ? scrollTop() / max : 0})`
     }
     if (sections.length === 0) return
+    const threshold = win.innerHeight * 0.35
     if (scrollingTo) {
-      const top = scrollingTo.getBoundingClientRect().top
-      if (top <= win.innerHeight * 0.35 && top >= -8) scrollingTo = null
-      else {
+      const rect = scrollingTo.getBoundingClientRect()
+      const top = rect.top
+      const visible = rect.bottom > 0 && top < win.innerHeight
+      if (top <= threshold && top >= -8) {
+        scrollingTo = null
+      } else if (visible) {
         setCurrent(scrollingTo)
         return
+      } else {
+        scrollingTo = null
       }
     }
     if (scrollTop() + clientHeight() >= scrollHeight() - 2) {
       setCurrent(sections.at(-1))
       return
     }
-    const threshold = win.innerHeight * 0.35
     setCurrent(
       sections.reduce(
         (current, section) => (section.getBoundingClientRect().top <= threshold ? section : current),
@@ -101,11 +1062,18 @@ export function initializeBlueprintRuntime(doc = document, win = window) {
     scheduled = true
     win.requestAnimationFrame(update)
   }
+  const prefersReducedMotion = () => themePrefersReducedMotion(win)
   const updateFromHash = () => {
     const match = entries.find(({ link }) => link.hash === win.location.hash)
     if (match) {
       scrollingTo = match.section
       setCurrent(match.section)
+      const top = match.section.getBoundingClientRect().top
+      const threshold = win.innerHeight * 0.35
+      if (top > threshold || top < -8) {
+        match.section.scrollIntoView({ block: 'start' })
+      }
+      scheduleUpdate()
       return
     }
     scrollingTo = null
@@ -114,7 +1082,6 @@ export function initializeBlueprintRuntime(doc = document, win = window) {
 
   const navLinkSelector =
     '.bp-sidebar a[href^="#"], .bp-toc a[href^="#"], .sidebar a[href^="#"], .bp-contents a[href^="#"]'
-  const prefersReducedMotion = () => win.matchMedia('(prefers-reduced-motion: reduce)').matches
 
   const scrollToSection = (section) => {
     scrollingTo = section
@@ -178,14 +1145,17 @@ export function initializeBlueprintRuntime(doc = document, win = window) {
   updateFromHash()
 }
 
-// Section heading permalink — pixelarticons in the main-column gutter; link on
-// heading hover, copy on icon hover, check after a successful copy.
-const HEADING_LINK_ICON =
-  'M4 6h7v2H4zm0 10h7v2H4zM2 8h2v8H2zm18-2h-7v2h7zm0 10h-7v2h7zm2-8h-2v8h2zM7 11h10v2H7z'
-const HEADING_COPY_ICON =
-  'M8 6h12v2H8zM4 2h12v2H4zm2 6h2v12H6zM2 4h2v12H2zm6 16h12v2H8zM20 8h2v12h-2zm-4-4h2v2h-2zM4 16h2v2H4z'
-const HEADING_CHECK_ICON =
-  'M10 18H8v-2h2v2Zm-2-2H6v-2h2v2Zm4-2v2h-2v-2h2Zm-6 0H4v-2h2v2Zm8 0h-2v-2h2v2Zm2-2h-2v-2h2v2Zm2-2h-2V8h2v2Zm2-2h-2V6h2v2Z'
+// Section heading permalink — Iconoir line glyphs in the main-column gutter;
+// link on heading hover, copy on icon hover, check after a successful copy.
+const HEADING_LINK_ICON = [
+  'M14 11.9976C14 9.5059 11.683 7 8.85714 7C8.52241 7 7.41904 7.00001 7.14286 7.00001C4.30254 7.00001 2 9.23752 2 11.9976C2 14.376 3.70973 16.3664 6 16.8714C6.36756 16.9525 6.75006 16.9952 7.14286 16.9952',
+  'M10 11.9976C10 14.4893 12.317 16.9952 15.1429 16.9952C15.4776 16.9952 16.581 16.9952 16.8571 16.9952C19.6975 16.9952 22 14.7577 22 11.9976C22 9.6192 20.2903 7.62884 18 7.12383C17.6324 7.04278 17.2499 6.99999 16.8571 6.99999',
+]
+const HEADING_COPY_ICON = [
+  'M19.4 20H9.6C9.26863 20 9 19.7314 9 19.4V9.6C9 9.26863 9.26863 9 9.6 9H19.4C19.7314 9 20 9.26863 20 9.6V19.4C20 19.7314 19.7314 20 19.4 20Z',
+  'M15 9V4.6C15 4.26863 14.7314 4 14.4 4H4.6C4.26863 4 4 4.26863 4 4.6V14.4C4 14.7314 4.26863 15 4.6 15H9',
+]
+const HEADING_CHECK_ICON = 'M5 13L9 17L19 7'
 const headingLinkTimers = new WeakMap()
 
 function createHeadingPixelIcon(doc, name, pathD) {
@@ -193,12 +1163,18 @@ function createHeadingPixelIcon(doc, name, pathD) {
   svg.setAttribute('viewBox', '0 0 24 24')
   svg.setAttribute('width', '16')
   svg.setAttribute('height', '16')
-  svg.setAttribute('fill', 'currentColor')
+  svg.setAttribute('fill', 'none')
+  svg.setAttribute('stroke', 'currentColor')
+  svg.setAttribute('stroke-width', '1.5')
+  svg.setAttribute('stroke-linecap', 'round')
+  svg.setAttribute('stroke-linejoin', 'round')
   svg.setAttribute('aria-hidden', 'true')
   svg.classList.add('bp-heading-link__icon', `bp-heading-link__icon--${name}`)
-  const path = doc.createElementNS('http://www.w3.org/2000/svg', 'path')
-  path.setAttribute('d', pathD)
-  svg.append(path)
+  for (const d of Array.isArray(pathD) ? pathD : [pathD]) {
+    const path = doc.createElementNS('http://www.w3.org/2000/svg', 'path')
+    path.setAttribute('d', d)
+    svg.append(path)
+  }
   return svg
 }
 
@@ -230,7 +1206,7 @@ function showHeadingLinkState(button, state, label) {
   const previousTimer = headingLinkTimers.get(button)
   if (previousTimer) clearTimeout(previousTimer)
 
-  const heading = button.closest('h2')
+  const heading = button.closest('h1, h2, h3, h4, h5, h6')
 
   if (state === 'idle') {
     delete button.dataset.bpCopyState
@@ -262,24 +1238,322 @@ function wireFigureDiagramSize(doc) {
   }
 }
 
-function wireSectionHeadingLinks(doc, win = doc.defaultView) {
-  for (const section of doc.querySelectorAll('section[id]')) {
-    const heading =
-      section.querySelector(':scope > h2:first-child') ??
-      section.querySelector(':scope > hgroup:first-child > h2')
-    if (!heading || heading.querySelector(':scope > .bp-heading-row')) continue
+const SIDEBAR_HEADING_SELECTOR =
+  'h2[data-sidebar], h3[data-sidebar], h4[data-sidebar], h5[data-sidebar], h6[data-sidebar]'
+const NAV_CONTENT_ROOT = 'main, [data-bp-nav-root]'
 
-    const label = heading.textContent.trim()
-    heading.replaceChildren()
+function slugifyHeadingId(value) {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/['']/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
 
-    const row = doc.createElement('span')
-    row.className = 'bp-heading-row'
+function isSectionLeadHeading(heading) {
+  const section = heading.closest('section')
+  if (!section) return false
+  return (
+    heading === section.querySelector(':scope > h2:first-child') ||
+    heading === section.querySelector(':scope > hgroup:first-child > h2')
+  )
+}
 
-    const button = createHeadingLinkButton(doc, label)
+function ensureUniqueHeadingId(doc, base, heading) {
+  let candidate = base || 'section'
+  let suffix = 2
+  while (doc.getElementById(candidate) && doc.getElementById(candidate) !== heading) {
+    candidate = `${base}-${suffix}`
+    suffix += 1
+  }
+  return candidate
+}
+
+function resolveHeadingId(doc, heading) {
+  if (heading.id) return heading.id
+
+  const section = heading.closest('section[id]')
+  if (section && isSectionLeadHeading(heading)) {
+    // `<section id>` is the single anchoring contract: leave the id on the
+    // section and point navigation, permalinks, and scroll-spy at it.
+    return section.id
+  }
+
+  const base = slugifyHeadingId(
+    heading.getAttribute('data-sidebar') || heading.textContent || 'section'
+  )
+  heading.id = ensureUniqueHeadingId(doc, base, heading)
+  return heading.id
+}
+
+function getSidebarLabel(heading) {
+  return heading.getAttribute('data-sidebar')?.trim() || heading.textContent.trim()
+}
+
+// A repeated <header> in the nav root (every one after the masthead) is a
+// navigation GROUP divider: it reuses the masthead structure (eyebrow + h1 +
+// optional <bp-subheader>) and its title becomes a quiet eyebrow above the
+// sections that follow, in both the fixed rail and the inline contents.
+function findNavMasthead(root) {
+  return root.querySelector(':scope > header')
+}
+
+function getGroupLabel(header) {
+  const explicit = header.getAttribute('data-sidebar')?.trim()
+  if (explicit) return explicit
+  const heading = header.querySelector('h1, h2, h3, h4, h5, h6')
+  if (heading?.textContent.trim()) return heading.textContent.trim()
+  const eyebrow = header.querySelector('bp-eyebrow')
+  if (eyebrow?.textContent.trim()) return eyebrow.textContent.trim()
+  return header.textContent.trim() || 'Section'
+}
+
+function resolveGroupId(doc, header) {
+  if (header.id) return header.id
+  const base = slugifyHeadingId(getGroupLabel(header))
+  header.id = ensureUniqueHeadingId(doc, base, header)
+  return header.id
+}
+
+// Collect group dividers (nav-root <header>s after the masthead) and every
+// data-sidebar heading in a single document-ordered pass.
+function collectNavNodes(doc) {
+  const root = doc.querySelector(NAV_CONTENT_ROOT) ?? doc.body
+  const masthead = findNavMasthead(root)
+  const selector = `:scope > header, ${SIDEBAR_HEADING_SELECTOR}`
+  return [...root.querySelectorAll(selector)].filter((node) => node !== masthead)
+}
+
+function buildSidebarTree(nodes, doc) {
+  const tree = []
+  let currentGroup = null
+  let currentPrimary = null
+
+  for (const node of nodes) {
+    if (node.tagName === 'HEADER') {
+      currentGroup = {
+        type: 'group',
+        label: getGroupLabel(node),
+        id: resolveGroupId(doc, node),
+        children: [],
+      }
+      currentPrimary = null
+      tree.push(currentGroup)
+      continue
+    }
+
+    const level = Number(node.tagName.slice(1))
+    const item = {
+      type: 'section',
+      heading: node,
+      label: getSidebarLabel(node),
+      id: node.id || resolveHeadingId(doc, node),
+      children: [],
+    }
+
+    if (level === 2) {
+      currentPrimary = item
+      ;(currentGroup ? currentGroup.children : tree).push(item)
+      continue
+    }
+
+    if (currentPrimary) {
+      currentPrimary.children.push(item)
+      continue
+    }
+
+    ;(currentGroup ? currentGroup.children : tree).push(item)
+  }
+
+  return tree
+}
+
+function createNavLink(doc, { id, label }) {
+  const link = doc.createElement('a')
+  link.href = `#${id}`
+  link.textContent = label
+  return link
+}
+
+// Group eyebrow + its section entries stay siblings in one flat list so the
+// gliding pill, auto-numbering, scroll-spy, and search keep working unchanged;
+// the group row carries no link and is skipped by the numbering counter.
+function createNavGroupRow(doc, group, labelClass) {
+  const li = doc.createElement('li')
+  li.className = 'bp-nav-group'
+  const label = doc.createElement('span')
+  label.className = labelClass
+  label.textContent = group.label
+  li.append(label)
+  return li
+}
+
+function renderNavTree(doc, tree) {
+  const fragment = doc.createDocumentFragment()
+
+  const appendSection = (section) => {
+    const li = doc.createElement('li')
+    li.append(createNavLink(doc, section))
+
+    if (section.children?.length > 0) {
+      const subList = doc.createElement('ul')
+      for (const child of section.children) {
+        const subItem = doc.createElement('li')
+        subItem.append(createNavLink(doc, child))
+        subList.append(subItem)
+      }
+      li.append(subList)
+    }
+
+    fragment.append(li)
+  }
+
+  for (const item of tree) {
+    if (item.type === 'group') {
+      fragment.append(createNavGroupRow(doc, item, 'bp-nav-group__label'))
+      item.children.forEach(appendSection)
+      continue
+    }
+    appendSection(item)
+  }
+
+  return fragment
+}
+
+function renderContentsTree(doc, tree) {
+  const fragment = doc.createDocumentFragment()
+
+  const appendSection = (section) => {
+    const li = doc.createElement('li')
+    li.append(createNavLink(doc, section))
+    fragment.append(li)
+  }
+
+  for (const item of tree) {
+    if (item.type === 'group') {
+      const li = createNavGroupRow(doc, item, 'bp-contents-group__label')
+      li.className = 'bp-contents-group'
+      fragment.append(li)
+      item.children.forEach(appendSection)
+      continue
+    }
+    appendSection(item)
+  }
+
+  return fragment
+}
+
+function findSidebarNavLists(doc) {
+  const lists = []
+
+  for (const nav of doc.querySelectorAll('.bp-sidebar:not([data-bp-nav-manual])')) {
+    const list =
+      nav.querySelector(':scope > .bp-sidebar__panel > ul') ??
+      nav.querySelector(':scope > ul')
+    if (list) lists.push(list)
+  }
+
+  for (const nav of doc.querySelectorAll('.bp-toc:not([data-bp-nav-manual])')) {
+    const list = nav.querySelector(':scope > ul')
+    if (list) lists.push(list)
+  }
+
+  return lists
+}
+
+function ensureDocumentNavTree(doc) {
+  const nodes = collectNavNodes(doc)
+  if (nodes.length === 0) return []
+
+  for (const node of nodes) {
+    if (node.tagName === 'HEADER') resolveGroupId(doc, node)
+    else resolveHeadingId(doc, node)
+  }
+
+  return buildSidebarTree(nodes, doc)
+}
+
+function populateBpTocElement(element, doc, tree) {
+  if (element.dataset.bpTocReady === 'true') return
+  if (!tree?.length) return
+
+  element.dataset.bpTocReady = 'true'
+
+  const label =
+    element.getAttribute('label')?.trim() ||
+    element.textContent.trim() ||
+    'Contents'
+  const ariaLabel = element.getAttribute('aria-label')?.trim() || label
+
+  const nav = doc.createElement('nav')
+  nav.className = 'bp-contents'
+  nav.setAttribute('aria-label', ariaLabel)
+
+  const eyebrow = doc.createElement('p')
+  eyebrow.className = 'bp-eyebrow'
+  eyebrow.textContent = label
+
+  const list = doc.createElement('ol')
+  list.append(renderContentsTree(doc, tree))
+
+  nav.append(eyebrow, list)
+  element.replaceChildren(nav)
+}
+
+function populateAllBpToc(doc, tree) {
+  for (const element of doc.querySelectorAll('bp-toc')) {
+    populateBpTocElement(element, doc, tree)
+  }
+}
+
+function generateNavigationFromHeadings(doc) {
+  const tree = ensureDocumentNavTree(doc)
+  if (tree.length === 0) return
+
+  const navFragment = renderNavTree(doc, tree)
+
+  for (const list of findSidebarNavLists(doc)) {
+    list.replaceChildren(navFragment.cloneNode(true))
+  }
+
+  populateAllBpToc(doc, tree)
+}
+
+function formatHeadingEyebrow(number) {
+  return String(number).padStart(2, '0')
+}
+
+function wireSectionHeadingLinks(doc, win = doc.defaultView) {
+  const root = doc.querySelector(NAV_CONTENT_ROOT) ?? doc.body
+  let primaryNumber = 0
+
+  for (const heading of root.querySelectorAll(SIDEBAR_HEADING_SELECTOR)) {
+    if (heading.querySelector(':scope > .bp-heading-row')) continue
+
+    const level = Number(heading.tagName.slice(1))
+    const label = getSidebarLabel(heading)
+    const titleNodes = [...heading.childNodes]
+    const id = resolveHeadingId(doc, heading)
+
+    heading.replaceChildren()
+
+    if (level === 2) {
+      primaryNumber += 1
+      const eyebrow = doc.createElement('span')
+      eyebrow.className = 'bp-heading-eyebrow'
+      eyebrow.textContent = formatHeadingEyebrow(primaryNumber)
+      heading.append(eyebrow)
+    }
+
+    const row = doc.createElement('span')
+    row.className = 'bp-heading-row'
+
+    const button = createHeadingLinkButton(doc, label)
 
     const title = doc.createElement('span')
     title.className = 'bp-heading-title'
-    title.textContent = label
+    title.append(...titleNodes)
 
     row.append(button, title)
     heading.append(row)
@@ -312,7 +1586,7 @@ function wireSectionHeadingLinks(doc, win = doc.defaultView) {
 
     button.addEventListener('click', (event) => {
       event.preventDefault()
-      const url = new URL(`#${section.id}`, win?.location.href ?? '').href
+      const url = new URL(`#${id}`, win?.location.href ?? '').href
       copySectionUrl(url)
         .then(() => showHeadingLinkState(button, 'copied', label))
         .catch(() => showHeadingLinkState(button, 'error', label))
@@ -367,6 +1641,25 @@ function createCalloutIcon(doc, pathD) {
   return svg
 }
 
+// ---------------------------------------------------------------------
+// <bp-toc> — inline table of contents (full-width .bp-contents family).
+//
+// Place the element wherever the index should appear; it expands to a
+// numbered, multi-column nav on load from h2 headings marked data-sidebar.
+// Sub-sections appear in the fixed rail only; the inline block stays flat.
+//
+//   <bp-toc label="Contents"></bp-toc>
+//
+// label: eyebrow text (default: Contents). aria-label overrides the nav label.
+// ---------------------------------------------------------------------
+class BlueprintTocElement extends HTMLElement {
+  connectedCallback() {
+    const doc = this.ownerDocument
+    if (doc.documentElement.dataset.blueprintRuntime !== 'ready') return
+    populateBpTocElement(this, doc, ensureDocumentNavTree(doc))
+  }
+}
+
 class BlueprintCalloutElement extends HTMLElement {
   #rendered = false
 
@@ -407,10 +1700,1141 @@ class BlueprintCalloutElement extends HTMLElement {
   }
 }
 
+// ---------------------------------------------------------------------
+// <bp-mock> — a drafting "browser frame" for UX mockups.
+//
+// Wraps a low-fidelity component sketch in an ink chrome frame (window
+// ticks + a mono URL/title). The frame is light-DOM and the authored
+// children are moved into a scalable canvas, so the mock is contained by
+// construction — no shadow DOM. Two optional behaviours:
+//   • viewport="1280"  draws the canvas at that pixel width and scales it
+//     to fit the frame (crisp 1:1 when the frame is wide enough or when
+//     expanded), so a desktop layout can be mocked inside a narrow column.
+//   • expandable        an expand control lifts the frame into a near-
+//     fullscreen overlay (Esc / the control dismiss; focus is restored).
+//
+//   <bp-mock label="app.example.com" viewport="1280"> … </bp-mock>
+//
+// label: mono caption in the chrome bar. viewport: canvas width in px.
+// expandable="false" drops the expand control.
+// ---------------------------------------------------------------------
+const MOCK_EXPAND_ICON = [
+  'M9 9L4 4M4 4V8M4 4H8',
+  'M15 9L20 4M20 4V8M20 4H16',
+  'M9 15L4 20M4 20V16M4 20H8',
+  'M15 15L20 20M20 20V16M20 20H16',
+]
+const MOCK_COLLAPSE_ICON = [
+  'M20 20L15 15M15 15V19M15 15H19',
+  'M4 20L9 15M9 15V19M9 15H5',
+  'M20 4L15 9M15 9V5M15 9H19',
+  'M4 4L9 9M9 9V5M9 9H5',
+]
+
+class BlueprintMockElement extends HTMLElement {
+  #rendered = false
+  #ro = null
+  #wrap = null
+  #stage = null
+  #canvas = null
+  #btn = null
+  #naturalWidth = 0
+  #onKeydown = null
+  #returnFocus = null
+  #prevOverflow = ''
+
+  connectedCallback() {
+    if (this.#rendered) return
+    this.#rendered = true
+
+    const doc = this.ownerDocument
+    const label = this.getAttribute('label') || ''
+    const vw = Number.parseInt(this.getAttribute('viewport') || '', 10)
+    this.#naturalWidth = Number.isFinite(vw) && vw > 0 ? vw : 0
+    const expandable = this.getAttribute('expandable') !== 'false'
+
+    const wrap = doc.createElement('div')
+    wrap.className = 'bp-mock'
+    wrap.setAttribute('role', 'group')
+    if (label) wrap.setAttribute('aria-label', `Mockup: ${label}`)
+
+    const frame = doc.createElement('div')
+    frame.className = 'bp-mock__frame'
+
+    const bar = doc.createElement('div')
+    bar.className = 'bp-mock__bar'
+
+    const ticks = doc.createElement('span')
+    ticks.className = 'bp-mock__ticks'
+    ticks.setAttribute('aria-hidden', 'true')
+    ticks.append(doc.createElement('i'), doc.createElement('i'), doc.createElement('i'))
+    bar.append(ticks)
+
+    const cap = doc.createElement('span')
+    cap.className = 'bp-mock__label'
+    cap.textContent = label
+    bar.append(cap)
+
+    if (expandable) {
+      const btn = doc.createElement('button')
+      btn.type = 'button'
+      btn.className = 'bp-mock__btn'
+      btn.setAttribute('aria-expanded', 'false')
+      btn.setAttribute('aria-label', 'Expand mockup')
+      btn.append(createChromeSvg(doc, MOCK_EXPAND_ICON, 14))
+      btn.addEventListener('click', () => this.#toggle())
+      bar.append(btn)
+      this.#btn = btn
+    }
+
+    const stage = doc.createElement('div')
+    stage.className = 'bp-mock__stage'
+
+    const canvas = doc.createElement('div')
+    canvas.className = 'bp-mock__canvas'
+    if (this.#naturalWidth) canvas.style.width = `${this.#naturalWidth}px`
+    canvas.append(...this.childNodes)
+    stage.append(canvas)
+
+    frame.append(bar, stage)
+    wrap.append(frame)
+    this.replaceChildren(wrap)
+
+    this.#wrap = wrap
+    this.#stage = stage
+    this.#canvas = canvas
+
+    if (this.#naturalWidth && typeof ResizeObserver !== 'undefined') {
+      this.#ro = new ResizeObserver(() => this.#relayout())
+      this.#ro.observe(stage)
+      this.#ro.observe(canvas)
+      this.#relayout()
+    }
+  }
+
+  disconnectedCallback() {
+    this.#ro?.disconnect()
+    if (this.#onKeydown) this.ownerDocument.removeEventListener('keydown', this.#onKeydown)
+  }
+
+  // Scale the fixed-width canvas down to whatever width the stage offers,
+  // then collapse the stage to the scaled height so there is no dead space.
+  #relayout() {
+    if (!this.#naturalWidth || !this.#stage) return
+    const avail = this.#stage.clientWidth
+    if (!avail) return
+    const scale = Math.min(1, avail / this.#naturalWidth)
+    this.#canvas.style.setProperty('--bp-mock-scale', String(scale))
+    this.#stage.style.height = `${Math.round(this.#canvas.offsetHeight * scale)}px`
+  }
+
+  #toggle() {
+    const doc = this.ownerDocument
+    const expanded = this.#wrap.classList.toggle('is-expanded')
+    if (this.#btn) {
+      this.#btn.setAttribute('aria-expanded', String(expanded))
+      this.#btn.setAttribute('aria-label', expanded ? 'Collapse mockup' : 'Expand mockup')
+      this.#btn.replaceChildren(
+        createChromeSvg(doc, expanded ? MOCK_COLLAPSE_ICON : MOCK_EXPAND_ICON, 14)
+      )
+    }
+    if (expanded) {
+      this.#returnFocus = doc.activeElement
+      // The page scrolls, so freeze the background behind the overlay.
+      this.#prevOverflow = doc.documentElement.style.overflow
+      doc.documentElement.style.overflow = 'hidden'
+      this.#onKeydown = (event) => {
+        if (event.key === 'Escape') this.#toggle()
+      }
+      doc.addEventListener('keydown', this.#onKeydown)
+      this.#btn?.focus()
+    } else {
+      doc.documentElement.style.overflow = this.#prevOverflow ?? ''
+      if (this.#onKeydown) {
+        doc.removeEventListener('keydown', this.#onKeydown)
+        this.#onKeydown = null
+      }
+      if (this.#returnFocus && typeof this.#returnFocus.focus === 'function') {
+        this.#returnFocus.focus()
+      }
+    }
+    // The stage width changes with the overlay; rescale on the next frame.
+    if (typeof requestAnimationFrame === 'function') {
+      requestAnimationFrame(() => this.#relayout())
+    } else {
+      this.#relayout()
+    }
+  }
+}
+
+// ---------------------------------------------------------------------
+// <bp-gallery> — an elegant grid of images that expands to a lightbox.
+//
+// Wraps author-provided images (screenshots, generated mockups, or user
+// uploads) in a tidy responsive grid. Each thumbnail wears a bluescale
+// treatment — desaturated and washed in the illustration ramp — until it
+// is hovered or focused, when its true color is revealed. Activating a
+// thumbnail lifts the full-color image into a near-fullscreen lightbox
+// over a drafting scrim (Esc / the close control dismiss; arrow keys and
+// the prev/next controls page between images; focus is restored).
+//
+//   <bp-gallery label="Concept explorations">
+//     <figure>
+//       <img src="hero.png" alt="Landing hero" />
+//       <figcaption>Landing hero</figcaption>
+//     </figure>
+//     <img src="settings.png" alt="Settings panel" />
+//   </bp-gallery>
+//
+// label: optional mono caption for the gallery as a whole (accessible
+// name + lightbox kicker). Captions come from a child <figcaption> when
+// present, otherwise the image's alt text. The component is light-DOM and
+// expands to documented .bp-gallery* markup styled by blueprint.css.
+// ---------------------------------------------------------------------
+const GALLERY_ZOOM_ICON = [
+  'M8 11H11M14 11H11M11 11V8M11 11V14',
+  'M17 17L21 21',
+  'M3 11C3 15.4183 6.58172 19 11 19C13.213 19 15.2161 18.1015 16.6644 16.6493C18.1077 15.2022 19 13.2053 19 11C19 6.58172 15.4183 3 11 3C6.58172 3 3 6.58172 3 11Z',
+]
+const GALLERY_CLOSE_ICON =
+  'M6.75827 17.2426L12.0009 12M17.2435 6.75736L12.0009 12M12.0009 12L6.75827 6.75736M12.0009 12L17.2435 17.2426'
+const GALLERY_PREV_ICON = 'M15 6L9 12L15 18'
+const GALLERY_NEXT_ICON = 'M9 6L15 12L9 18'
+
+class BlueprintGalleryElement extends HTMLElement {
+  #rendered = false
+  /** @type {{ src: string, alt: string, caption: string }[]} */
+  #slides = []
+  #label = ''
+  #box = null
+  #boxImg = null
+  #boxCaption = null
+  #boxCounter = null
+  #boxKicker = null
+  #index = 0
+  #onKeydown = null
+  #returnFocus = null
+  #prevOverflow = ''
+
+  connectedCallback() {
+    if (this.#rendered) return
+    this.#rendered = true
+
+    const doc = this.ownerDocument
+    this.#label = this.getAttribute('label') || ''
+
+    // Collect the authored images and their captions before replacing the
+    // light-DOM children. A <figcaption> wins; otherwise fall back to alt.
+    for (const img of this.querySelectorAll('img')) {
+      const figure = img.closest('figure')
+      const cap = figure?.querySelector('figcaption')
+      const caption = (cap?.textContent || img.getAttribute('alt') || '').trim()
+      this.#slides.push({
+        src: img.getAttribute('src') || '',
+        alt: (img.getAttribute('alt') || caption || '').trim(),
+        caption,
+      })
+    }
+
+    const wrap = doc.createElement('div')
+    wrap.className = 'bp-gallery'
+    wrap.setAttribute('role', 'group')
+    if (this.#label) wrap.setAttribute('aria-label', `Gallery: ${this.#label}`)
+
+    const grid = doc.createElement('div')
+    grid.className = 'bp-gallery__grid'
+
+    this.#slides.forEach((slide, index) => {
+      const item = doc.createElement('button')
+      item.type = 'button'
+      item.className = 'bp-gallery__item'
+      item.setAttribute(
+        'aria-label',
+        slide.caption ? `View image: ${slide.caption}` : `View image ${index + 1}`
+      )
+      item.addEventListener('click', () => this.#open(index))
+
+      const thumb = doc.createElement('span')
+      thumb.className = 'bp-gallery__thumb'
+
+      const img = doc.createElement('img')
+      img.className = 'bp-gallery__img'
+      img.src = slide.src
+      img.alt = slide.alt
+      img.loading = 'lazy'
+      img.decoding = 'async'
+
+      // The bluescale wash: a blue veil that color-blends the grayscale
+      // thumbnail, faded away on hover/focus to reveal true color.
+      const wash = doc.createElement('span')
+      wash.className = 'bp-gallery__wash'
+      wash.setAttribute('aria-hidden', 'true')
+
+      const zoom = doc.createElement('span')
+      zoom.className = 'bp-gallery__zoom'
+      zoom.setAttribute('aria-hidden', 'true')
+      zoom.append(createChromeSvg(doc, GALLERY_ZOOM_ICON, 16))
+
+      thumb.append(img, wash, zoom)
+      item.append(thumb)
+
+      if (slide.caption) {
+        const cap = doc.createElement('span')
+        cap.className = 'bp-gallery__caption'
+        cap.textContent = slide.caption
+        item.append(cap)
+      }
+
+      grid.append(item)
+    })
+
+    wrap.append(grid)
+    this.replaceChildren(wrap)
+  }
+
+  disconnectedCallback() {
+    if (this.#onKeydown) this.ownerDocument.removeEventListener('keydown', this.#onKeydown)
+    this.#box?.remove()
+    this.#box = null
+  }
+
+  #ensureBox() {
+    if (this.#box) return
+    const doc = this.ownerDocument
+
+    const box = doc.createElement('div')
+    box.className = 'bp-lightbox'
+    box.setAttribute('role', 'dialog')
+    box.setAttribute('aria-modal', 'true')
+    box.setAttribute('aria-label', this.#label ? `${this.#label} — image viewer` : 'Image viewer')
+    box.addEventListener('click', (event) => {
+      if (event.target === box) this.#close()
+    })
+
+    const close = doc.createElement('button')
+    close.type = 'button'
+    close.className = 'bp-lightbox__close'
+    close.setAttribute('aria-label', 'Close image viewer')
+    close.append(createChromeSvg(doc, GALLERY_CLOSE_ICON, 18))
+    close.addEventListener('click', () => this.#close())
+
+    const prev = doc.createElement('button')
+    prev.type = 'button'
+    prev.className = 'bp-lightbox__nav bp-lightbox__nav--prev'
+    prev.setAttribute('aria-label', 'Previous image')
+    prev.append(createChromeSvg(doc, GALLERY_PREV_ICON, 22))
+    prev.addEventListener('click', () => this.#step(-1))
+
+    const next = doc.createElement('button')
+    next.type = 'button'
+    next.className = 'bp-lightbox__nav bp-lightbox__nav--next'
+    next.setAttribute('aria-label', 'Next image')
+    next.append(createChromeSvg(doc, GALLERY_NEXT_ICON, 22))
+    next.addEventListener('click', () => this.#step(1))
+
+    const figure = doc.createElement('figure')
+    figure.className = 'bp-lightbox__figure'
+
+    const img = doc.createElement('img')
+    img.className = 'bp-lightbox__img'
+    img.alt = ''
+
+    const meta = doc.createElement('figcaption')
+    meta.className = 'bp-lightbox__meta'
+
+    const kicker = doc.createElement('span')
+    kicker.className = 'bp-lightbox__kicker'
+    kicker.textContent = this.#label
+
+    const counter = doc.createElement('span')
+    counter.className = 'bp-lightbox__counter'
+
+    const caption = doc.createElement('span')
+    caption.className = 'bp-lightbox__caption'
+
+    meta.append(kicker, counter, caption)
+    figure.append(img, meta)
+    box.append(close, prev, figure, next)
+
+    const host = doc.body || doc.documentElement
+    host.append(box)
+
+    this.#box = box
+    this.#boxImg = img
+    this.#boxCaption = caption
+    this.#boxCounter = counter
+    this.#boxKicker = kicker
+  }
+
+  #render() {
+    const slide = this.#slides[this.#index]
+    if (!slide) return
+    this.#boxImg.src = slide.src
+    this.#boxImg.alt = slide.alt
+    this.#boxCaption.textContent = slide.caption
+    this.#boxCaption.hidden = !slide.caption
+    this.#boxKicker.hidden = !this.#label
+    const many = this.#slides.length > 1
+    this.#boxCounter.textContent = many ? `${this.#index + 1} / ${this.#slides.length}` : ''
+    this.#boxCounter.hidden = !many
+    this.#box.classList.toggle('is-single', !many)
+  }
+
+  #open(index) {
+    if (!this.#slides.length) return
+    this.#ensureBox()
+    this.#index = index
+    this.#render()
+
+    const doc = this.ownerDocument
+    this.#returnFocus = doc.activeElement
+    this.#prevOverflow = doc.documentElement.style.overflow
+    doc.documentElement.style.overflow = 'hidden'
+    this.#box.classList.add('is-open')
+
+    this.#onKeydown = (event) => {
+      if (event.key === 'Escape') this.#close()
+      else if (event.key === 'ArrowRight') this.#step(1)
+      else if (event.key === 'ArrowLeft') this.#step(-1)
+    }
+    doc.addEventListener('keydown', this.#onKeydown)
+    this.#box.querySelector('.bp-lightbox__close')?.focus()
+  }
+
+  #step(delta) {
+    if (this.#slides.length < 2) return
+    const count = this.#slides.length
+    this.#index = (this.#index + delta + count) % count
+    this.#render()
+  }
+
+  #close() {
+    if (!this.#box) return
+    const doc = this.ownerDocument
+    this.#box.classList.remove('is-open')
+    doc.documentElement.style.overflow = this.#prevOverflow ?? ''
+    if (this.#onKeydown) {
+      doc.removeEventListener('keydown', this.#onKeydown)
+      this.#onKeydown = null
+    }
+    if (this.#returnFocus && typeof this.#returnFocus.focus === 'function') {
+      this.#returnFocus.focus()
+    }
+  }
+}
+
+// Presentational text-role elements. No behavior — styled by tag name in
+// blueprint.css (lede paragraph, quiet aside, muted mono micro-label). They
+// exist as elements so authors compose with markup instead of utility classes.
+class BlueprintSubheaderElement extends HTMLElement {}
+class BlueprintNoteElement extends HTMLElement {}
+class BlueprintEyebrowElement extends HTMLElement {}
+
+// ---------------------------------------------------------------------
+// <bp-table> — an opt-in enhanced data table.
+//
+// A light-DOM wrapper around a plain author <table>; the <table> keeps its
+// base styling and the expanded form stays a valid stored document. On
+// upgrade the runtime wraps the table in a .bp-table-x scroll shell so
+// horizontal overflow is contained without making <bp-table> the sticky
+// header's scroll ancestor; wide / hover / sticky / compact are pure CSS
+// (attribute selectors in blueprint.css). The runtime's other job is the
+// value-specific work CSS cannot do: scan each column's <tbody> data cells
+// and, when they all read as numbers, end-align that column's <td> AND its
+// <th scope="col"> by stamping a .bp-col-num class.
+//
+//   <bp-table sticky density="compact" wide><table>…</table></bp-table>
+//
+// numeric: omit to auto-detect; `off` disables alignment; an explicit
+// 1-based list ("2,3") forces those columns. sticky pins the header + key
+// column; density="compact" tightens cells; wide breaks past the measure.
+// ---------------------------------------------------------------------
+
+// A cell reads as numeric: optional sign / currency, digits with optional
+// grouping and decimals, optional percent.
+const TABLE_NUMERIC = /^[+-]?[$€£¥]?\s?\d[\d,]*(\.\d+)?\s?%?$/
+// Dash / "n/a" placeholders count as empty (not as text), so a numeric
+// column with a few gaps still resolves as numeric.
+const TABLE_BLANK = /^(—|–|-|n\/?a)$/i
+
+class BlueprintTableElement extends HTMLElement {
+  static get observedAttributes() {
+    return ['numeric']
+  }
+
+  #observer = null
+  #applying = false
+
+  connectedCallback() {
+    this.#ensureScrollShell()
+    this.#apply()
+    if (typeof MutationObserver !== 'undefined' && !this.#observer) {
+      // Re-detect when the author's table content changes. Our own class
+      // edits are attribute mutations, which this observer ignores, so it
+      // cannot loop; the flag is belt-and-suspenders.
+      this.#observer = new MutationObserver(() => {
+        if (!this.#applying) this.#apply()
+      })
+      this.#observer.observe(this, { childList: true, subtree: true, characterData: true })
+    }
+  }
+
+  disconnectedCallback() {
+    this.#observer?.disconnect()
+    this.#observer = null
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected) {
+      this.#ensureScrollShell()
+      this.#apply()
+    }
+  }
+
+  // Wrap the author's <table> in a horizontal scroll shell. Sticky header
+  // cells must stick to the page scrollport, not to <bp-table> — so overflow-x
+  // lives here, on .bp-table-x, instead of on the host.
+  #ensureScrollShell() {
+    const table = this.querySelector(':scope > table')
+    if (!table) return
+    let shell = this.querySelector(':scope > .bp-table-x')
+    if (!shell) {
+      shell = document.createElement('div')
+      shell.className = 'bp-table-x'
+      this.insertBefore(shell, table)
+    }
+    if (table.parentElement !== shell) shell.append(table)
+  }
+
+  // Resolve which 1-based columns end-align, then stamp .bp-col-num on the
+  // matching cells across thead / tbody / tfoot.
+  #apply() {
+    const table = this.querySelector('table')
+    if (!table) return
+    this.#applying = true
+    try {
+      for (const el of this.querySelectorAll('.bp-col-num')) {
+        el.classList.remove('bp-col-num')
+      }
+      const attr = (this.getAttribute('numeric') || '').trim().toLowerCase()
+      if (attr === 'off') return
+      let columns
+      if (attr) {
+        columns = new Set(
+          attr.split(',').map((n) => Number.parseInt(n, 10)).filter((n) => n > 0)
+        )
+        if (!columns.size) columns = this.#detect(table)
+      } else {
+        columns = this.#detect(table)
+      }
+      if (columns.size) this.#mark(table, columns)
+    } finally {
+      this.#applying = false
+    }
+  }
+
+  // A column is numeric when every non-blank <td> in it parses as a number.
+  // <th> cells (the key column) are skipped but still advance the column
+  // index so it stays aligned with the header row.
+  #detect(table) {
+    const tally = new Map()
+    for (const body of table.tBodies) {
+      for (const row of body.rows) {
+        let col = 0
+        for (const cell of row.cells) {
+          const span = cell.colSpan || 1
+          col += 1
+          if (cell.tagName === 'TH') {
+            col += span - 1
+            continue
+          }
+          const text = cell.textContent.trim()
+          if (!text || TABLE_BLANK.test(text)) continue
+          const rec = tally.get(col) || { total: 0, numeric: 0 }
+          rec.total += 1
+          if (TABLE_NUMERIC.test(text)) rec.numeric += 1
+          tally.set(col, rec)
+          col += span - 1
+        }
+      }
+    }
+    const columns = new Set()
+    for (const [col, rec] of tally) {
+      if (rec.total > 0 && rec.numeric === rec.total) columns.add(col)
+    }
+    return columns
+  }
+
+  // Stamp .bp-col-num on every cell whose 1-based column index is numeric.
+  #mark(table, columns) {
+    const stamp = (rows) => {
+      for (const row of rows) {
+        let col = 0
+        for (const cell of row.cells) {
+          const span = cell.colSpan || 1
+          col += 1
+          for (let i = 0; i < span; i += 1) {
+            if (columns.has(col + i)) {
+              cell.classList.add('bp-col-num')
+              break
+            }
+          }
+          col += span - 1
+        }
+      }
+    }
+    if (table.tHead) stamp(table.tHead.rows)
+    for (const body of table.tBodies) stamp(body.rows)
+    if (table.tFoot) stamp(table.tFoot.rows)
+  }
+}
+
+if (typeof customElements !== 'undefined' && !customElements.get('bp-toc')) {
+  customElements.define('bp-toc', BlueprintTocElement)
+}
+
 if (typeof customElements !== 'undefined' && !customElements.get('bp-callout')) {
   customElements.define('bp-callout', BlueprintCalloutElement)
 }
 
+if (typeof customElements !== 'undefined' && !customElements.get('bp-mock')) {
+  customElements.define('bp-mock', BlueprintMockElement)
+}
+
+if (typeof customElements !== 'undefined' && !customElements.get('bp-gallery')) {
+  customElements.define('bp-gallery', BlueprintGalleryElement)
+}
+
+if (typeof customElements !== 'undefined' && !customElements.get('bp-table')) {
+  customElements.define('bp-table', BlueprintTableElement)
+}
+
+if (typeof customElements !== 'undefined') {
+  for (const [name, ctor] of [
+    ['bp-subheader', BlueprintSubheaderElement],
+    ['bp-note', BlueprintNoteElement],
+    ['bp-eyebrow', BlueprintEyebrowElement],
+  ]) {
+    if (!customElements.get(name)) customElements.define(name, ctor)
+  }
+}
+
+// ---------------------------------------------------------------------
+// <bp-workplan> — a live "work plan" surface.
+//
+// Visualizes a set of typed, dependent tasks that resolve into waves of
+// work, rendered four ways (list · gantt · kanban · swimlanes). It is a
+// frame client: it reads its plan from a `.plan` property, the global
+// `window.__WORKPLAN__`, or a `{ type: 'workplan:update', plan }`
+// postMessage — so a host frame drives it and the author writes no task
+// data. With no plan it paints a "waiting for a plan" state.
+//
+//   <bp-workplan mode="gantt" header="…" subheader="…"></bp-workplan>
+//
+// mode: list|gantt|kanban|swimlanes pins a layout; omit it for the
+// built-in view selector. header/subheader override the plan's titles.
+// unit: hours|days sets the gantt axis. ignore-global opts out of the
+// window.__WORKPLAN__ source (postMessage only).
+// ---------------------------------------------------------------------
+;(() => {
+  const VIEW_OPTIONS = [
+    ['list', 'List'],
+    ['gantt', 'Gantt'],
+    ['kanban', 'Kanban'],
+    ['swimlanes', 'Swimlanes'],
+  ]
+
+  // Waves + readiness + a longest-path schedule, all derived (not authored).
+  function derive(plan) {
+    const byId = new Map(plan.tasks.map((t) => [t.id, t]))
+    const waveMemo = new Map()
+    const startMemo = new Map()
+
+    const wave = (id, trail = new Set()) => {
+      if (waveMemo.has(id)) return waveMemo.get(id)
+      const deps = byId.get(id)?.dependsOn ?? []
+      let w = 0
+      for (const d of deps) {
+        if (!byId.has(d) || trail.has(d)) continue
+        w = Math.max(w, wave(d, new Set([...trail, id])) + 1)
+      }
+      waveMemo.set(id, w)
+      return w
+    }
+
+    const start = (id, trail = new Set()) => {
+      if (startMemo.has(id)) return startMemo.get(id)
+      const deps = byId.get(id)?.dependsOn ?? []
+      let s = 0
+      for (const d of deps) {
+        const dep = byId.get(d)
+        if (!dep || trail.has(d)) continue
+        s = Math.max(s, start(d, new Set([...trail, id])) + (dep.effort ?? 1))
+      }
+      startMemo.set(id, s)
+      return s
+    }
+
+    return plan.tasks.map((t) => {
+      const deps = t.dependsOn ?? []
+      const blockedBy = deps.filter((d) => byId.get(d)?.status !== 'done')
+      const ready = blockedBy.length === 0
+      const s = start(t.id)
+      return {
+        ...t,
+        wave: wave(t.id),
+        ready,
+        locked: !ready && t.status !== 'done',
+        start: s,
+        finish: s + (t.effort ?? 1),
+        blockedBy,
+      }
+    })
+  }
+
+  function phase(t) {
+    if (t.status === 'done') return 'done'
+    if (t.locked) return 'blocked'
+    if (t.status === 'active') return 'active'
+    return 'ready'
+  }
+
+  const esc = (s) =>
+    String(s ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]))
+
+  const TYPE_LABEL = {
+    research: 'Research',
+    write: 'Write',
+    review: 'Review',
+    design: 'Design',
+    code: 'Code',
+  }
+
+  const CI_LABEL = {
+    running: 'Tests running',
+    failed: 'CI failed',
+    passed: 'CI passed',
+    approved: 'Approved',
+  }
+
+  const UNIT_SUFFIX = { hours: 'h', days: 'd' }
+  const UNIT_AXIS = { hours: 'Hours', days: 'Days' }
+
+  // 16×16 glyphs, drawn in currentColor; UI chrome stays on the ink scale.
+  const TYPE_ICON = {
+    research: '<circle cx="7" cy="7" r="4.2"/><path d="M10 10l4 4"/>',
+    write: '<path d="M3 13l8.5-8.5 2.5 2.5L5.5 15.5 2.5 16z"/><path d="M11 5l2.5 2.5"/>',
+    review: '<path d="M2 8s2.4-4 6-4 6 4 6 4-2.4 4-6 4-6-4-6-4z"/><circle cx="8" cy="8" r="1.8"/>',
+    design: '<path d="M8 2v12"/><path d="M8 2l4.5 10.5a5 5 0 01-9 0z"/>',
+    code: '<path d="M6 4L2 8l4 4"/><path d="M10 4l4 4-4 4"/>',
+  }
+
+  const CI_ICON = {
+    running: '<circle cx="8" cy="8" r="5.4" stroke-dasharray="3 3"/>',
+    failed: '<circle cx="8" cy="8" r="6"/><path d="M5.5 5.5l5 5M10.5 5.5l-5 5"/>',
+    passed: '<circle cx="8" cy="8" r="6"/><path d="M5 8.2l2 2 4-4.4"/>',
+    approved: '<path d="M3 8.4l2.2 2.2 4.4-4.8"/><path d="M7 8.4l2.2 2.2 4.4-4.8"/>',
+  }
+
+  // 8-point spark — the mark for automated (agent) work.
+  const AGENT_ICON = '<path d="M8 1.5v13M1.5 8h13M3.7 3.7l8.6 8.6M12.3 3.7l-8.6 8.6"/>'
+
+  const svgMark = (paths, cls) =>
+    `<svg class="${cls}" viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${paths}</svg>`
+
+  const typeBadge = (t) =>
+    `<span class="wp-type wp-type--${t}">${svgMark(TYPE_ICON[t], 'wp-type__glyph')}<span class="wp-type__label">${TYPE_LABEL[t]}</span></span>`
+
+  const phaseDot = (p) => `<span class="wp-dot wp-dot--${p}" role="img" aria-label="${p}"></span>`
+
+  // Inline (no pill) PR status: glyph for running/failed, positive ink for
+  // passed/approved, mono throughout. `compact` drops the diff stat.
+  function prStatus(pr, compact = false) {
+    const needsGlyph = pr.ci === 'running' || pr.ci === 'failed'
+    const diff =
+      !compact && pr.additions != null
+        ? `<span class="wp-pr__diff"><span class="wp-pr__add">+${pr.additions}</span> <span class="wp-pr__del">\u2212${pr.deletions ?? 0}</span></span>`
+        : ''
+    return (
+      `<span class="wp-pr wp-pr--${pr.ci}" title="${esc(`PR #${pr.number} — ${CI_LABEL[pr.ci]}`)}">` +
+      (needsGlyph ? svgMark(CI_ICON[pr.ci], 'wp-pr__glyph') : '') +
+      `<span class="wp-pr__num">#${pr.number}</span>` +
+      `<span class="wp-pr__ci">${esc(CI_LABEL[pr.ci])}</span>` +
+      diff +
+      `</span>`
+    )
+  }
+
+  function initials(name) {
+    const parts = name.trim().split(/\s+/)
+    if (parts.length === 1) return parts[0].slice(0, 2).toUpperCase()
+    return (parts[0][0] + parts[parts.length - 1][0]).toUpperCase()
+  }
+
+  // Agent → spark mark (square); human → initials monogram (circle).
+  function ownerMark(owner) {
+    if (!owner) return ''
+    if (owner.kind === 'agent') {
+      return `<span class="wp-owner wp-owner--agent" title="${esc(owner.name)} (agent)">${svgMark(AGENT_ICON, 'wp-owner__glyph')}</span>`
+    }
+    return `<span class="wp-owner wp-owner--human" title="${esc(owner.name)}">${esc(initials(owner.name))}</span>`
+  }
+
+  function waitLabel(t, byId) {
+    const names = t.blockedBy.map((d) => byId.get(d)?.name ?? d)
+    return `Waiting on ${names.join(', ')}`
+  }
+
+  function waitNote(t, byId) {
+    if (!t.locked) return ''
+    const label = waitLabel(t, byId)
+    return `<span class="wp-wait" title="${esc(label)}">${esc(label)}</span>`
+  }
+
+  function groupByWave(tasks) {
+    const map = new Map()
+    for (const t of tasks) {
+      const arr = map.get(t.wave) ?? []
+      arr.push(t)
+      map.set(t.wave, arr)
+    }
+    return [...map.entries()].sort((a, b) => a[0] - b[0])
+  }
+
+  function renderList(tasks, byId) {
+    const blocks = groupByWave(tasks)
+      .map(
+        ([w, items]) => `
+        <div class="wp-wave">
+          <div class="wp-wave__head">
+            <span class="wp-wave__no">Wave ${w + 1}</span>
+            <span class="wp-wave__count">${items.length} task${items.length === 1 ? '' : 's'}</span>
+          </div>
+          <div class="wp-list">
+            ${items
+              .map((t) => {
+                const p = phase(t)
+                return `
+                <div class="wp-row wp-row--${p}" data-locked="${t.locked}">
+                  ${phaseDot(p)}
+                  ${typeBadge(t.type)}
+                  <span class="wp-row__main">
+                    <span class="wp-row__name">${esc(t.name)}</span>
+                    ${waitNote(t, byId)}
+                  </span>
+                  <span class="wp-row__pr">${t.pr ? prStatus(t.pr) : ''}</span>
+                  ${ownerMark(t.owner)}
+                </div>`
+              })
+              .join('')}
+          </div>
+        </div>`
+      )
+      .join('')
+    return `<div class="wp-view wp-view--list">${blocks}</div>`
+  }
+
+  function renderKanban(tasks, byId) {
+    const cols = [
+      { key: 'blocked', title: 'Blocked' },
+      { key: 'ready', title: 'Ready' },
+      { key: 'active', title: 'In progress' },
+      { key: 'done', title: 'Done' },
+    ]
+    const columns = cols
+      .map(({ key, title }) => {
+        const items = tasks.filter((t) => phase(t) === key)
+        return `
+        <div class="wp-col wp-col--${key}">
+          <div class="wp-col__head">
+            <span class="wp-col__title">${title}</span>
+            <span class="wp-col__count">${items.length}</span>
+          </div>
+          <div class="wp-col__body">
+            ${
+              items.length === 0
+                ? '<div class="wp-col__empty">No tasks</div>'
+                : items
+                    .map(
+                      (t) => `
+              <div class="wp-card wp-card--${key}" data-locked="${t.locked}"${t.locked ? ` title="${esc(waitLabel(t, byId))}"` : ''}>
+                <div class="wp-card__top">
+                  ${typeBadge(t.type)}
+                  ${phaseDot(phase(t))}
+                </div>
+                <div class="wp-card__name">${esc(t.name)}</div>
+                ${t.pr ? `<div class="wp-card__pr">${prStatus(t.pr, true)}</div>` : ''}
+                <div class="wp-card__foot">
+                  <span class="wp-card__wave">Wave ${t.wave + 1}</span>
+                  ${ownerMark(t.owner)}
+                </div>
+              </div>`
+                    )
+                    .join('')
+            }
+          </div>
+        </div>`
+      })
+      .join('')
+    return `<div class="wp-view wp-view--kanban">${columns}</div>`
+  }
+
+  function renderSwimlanes(tasks) {
+    const order = ['research', 'design', 'write', 'code', 'review']
+    const maxWave = Math.max(0, ...tasks.map((t) => t.wave))
+    const header =
+      `<div class="wp-swim__corner">Type \u00d7 wave</div>` +
+      Array.from({ length: maxWave + 1 }, (_, w) => `<div class="wp-swim__whead">Wave ${w + 1}</div>`).join('')
+    const lanes = order
+      .filter((type) => tasks.some((t) => t.type === type))
+      .map((type) => {
+        const cells = Array.from({ length: maxWave + 1 }, (_, w) => {
+          const items = tasks.filter((t) => t.type === type && t.wave === w)
+          return `<div class="wp-swim__cell">${items
+            .map((t) => {
+              const p = phase(t)
+              return `<div class="wp-chip wp-chip--${p}" data-locked="${t.locked}" title="${esc(t.name)}">
+                <div class="wp-chip__head">
+                  ${phaseDot(p)}
+                  <span class="wp-chip__name">${esc(t.name)}</span>
+                  ${ownerMark(t.owner)}
+                </div>
+                ${t.pr ? `<div class="wp-chip__pr">${prStatus(t.pr, true)}</div>` : ''}
+              </div>`
+            })
+            .join('')}</div>`
+        }).join('')
+        return `<div class="wp-swim__lanehead">${typeBadge(type)}</div>${cells}`
+      })
+      .join('')
+    return `<div class="wp-view wp-view--swim" style="--wp-waves:${maxWave + 1}">${header}${lanes}</div>`
+  }
+
+  function renderGantt(tasks, unit) {
+    const span = Math.max(1, ...tasks.map((t) => t.finish))
+    const suffix = UNIT_SUFFIX[unit]
+    const axis = Array.from(
+      { length: span + 1 },
+      (_, d) => `<span class="wp-gantt__tick" style="--at:${d}">${d}</span>`
+    ).join('')
+    const rows = [...tasks]
+      .sort((a, b) => a.start - b.start || a.wave - b.wave)
+      .map((t) => {
+        const p = phase(t)
+        const pct = (n) => (n / span) * 100
+        return `
+        <div class="wp-gantt__row wp-gantt__row--${p}" data-locked="${t.locked}">
+          <div class="wp-gantt__label">
+            ${typeBadge(t.type)}
+            <span class="wp-gantt__name">${esc(t.name)}</span>
+            ${ownerMark(t.owner)}
+          </div>
+          <div class="wp-gantt__track">
+            <div class="wp-gantt__bar wp-gantt__bar--${p}" style="left:${pct(t.start)}%;width:${pct(t.finish - t.start)}%">
+              ${phaseDot(p)}
+              <span class="wp-gantt__bar-label">${t.pr ? `#${t.pr.number}` : `${t.effort ?? 1}${suffix}`}</span>
+            </div>
+          </div>
+        </div>`
+      })
+      .join('')
+    return `<div class="wp-view wp-view--gantt">
+      <div class="wp-gantt__row wp-gantt__row--axis">
+        <div class="wp-gantt__label wp-gantt__label--axis">${UNIT_AXIS[unit]} \u2192</div>
+        <div class="wp-gantt__track wp-gantt__track--axis" style="--span:${span}">${axis}</div>
+      </div>
+      ${rows}
+    </div>`
+  }
+
+  function summarize(tasks) {
+    return {
+      total: tasks.length,
+      done: tasks.filter((t) => t.status === 'done').length,
+      active: tasks.filter((t) => phase(t) === 'active').length,
+      blocked: tasks.filter((t) => t.locked).length,
+      waves: new Set(tasks.map((t) => t.wave)).size,
+    }
+  }
+
+  function renderEmpty() {
+    return `<div class="wp-empty" role="status">
+      <svg viewBox="0 0 48 48" width="48" height="48" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" class="wp-empty__art">
+        <rect x="7" y="9" width="34" height="30" rx="2"/>
+        <path d="M7 17h34"/>
+        <path d="M13 24h10M13 30h16" stroke-dasharray="2 3"/>
+        <circle cx="33" cy="29" r="6"/>
+        <path d="M33 26v3l2 2"/>
+      </svg>
+      <div class="wp-empty__title">Waiting for a plan</div>
+      <div class="wp-empty__hint">No work plan has been received yet. The host frame will post one over <span class="wp-mono">postMessage</span>.</div>
+    </div>`
+  }
+
+  const MESSAGE_TYPE = 'workplan:update'
+  const GLOBAL_KEY = '__WORKPLAN__'
+  const MODES = new Set(['list', 'gantt', 'kanban', 'swimlanes'])
+
+  class BlueprintWorkplanElement extends HTMLElement {
+    static get observedAttributes() {
+      return ['mode', 'unit', 'header', 'subheader']
+    }
+
+    #plan = null
+    #root = null
+    #activeView = 'list'
+    #onMessage = (e) => this.#handleMessage(e)
+    #onClick = (e) => this.#handleClick(e)
+
+    set plan(value) {
+      this.#plan = value
+      this.#render()
+    }
+    get plan() {
+      return this.#plan
+    }
+
+    get mode() {
+      const m = this.getAttribute('mode')
+      return MODES.has(m) ? m : null
+    }
+
+    get unit() {
+      return this.getAttribute('unit') === 'days' ? 'days' : 'hours'
+    }
+
+    connectedCallback() {
+      if (!this.#root) {
+        this.#root = this.ownerDocument.createElement('div')
+        this.#root.className = 'bp-workplan'
+        this.#root.addEventListener('click', this.#onClick)
+        this.replaceChildren(this.#root)
+      }
+      if (!this.#plan && !this.hasAttribute('ignore-global')) {
+        const fromGlobal = this.ownerDocument.defaultView?.[GLOBAL_KEY]
+        if (fromGlobal) this.#plan = fromGlobal
+      }
+      this.ownerDocument.defaultView?.addEventListener('message', this.#onMessage)
+      this.#render()
+    }
+
+    disconnectedCallback() {
+      this.ownerDocument.defaultView?.removeEventListener('message', this.#onMessage)
+    }
+
+    attributeChangedCallback() {
+      this.#render()
+    }
+
+    #handleMessage(e) {
+      const data = e.data
+      if (!data || data.type !== MESSAGE_TYPE || !data.plan) return
+      this.#plan = data.plan
+      this.#render()
+    }
+
+    // Delegated: the toolbar's buttons live in re-rendered markup, so we
+    // listen on the persistent root and read intent off data-attributes.
+    #handleClick(e) {
+      const target = e.target
+      const btn = target instanceof Element ? target.closest('[data-wp-view],[data-wp-unit]') : null
+      if (!btn || !this.#root?.contains(btn)) return
+      const view = btn.getAttribute('data-wp-view')
+      if (view) {
+        this.#activeView = view
+        this.#render()
+        return
+      }
+      const unit = btn.getAttribute('data-wp-unit')
+      if (unit) this.setAttribute('unit', unit)
+    }
+
+    get #view() {
+      return this.mode ?? this.#activeView
+    }
+
+    #toolbar(view, showModes) {
+      const modes = showModes
+        ? `<div class="wp-modes" role="tablist" aria-label="Choose a view">` +
+          VIEW_OPTIONS.map(
+            ([v, label]) =>
+              `<button class="wp-modes__btn" type="button" role="tab" aria-selected="${v === view}" data-wp-view="${v}">${label}</button>`
+          ).join('') +
+          `</div>`
+        : ''
+      const unit =
+        view === 'gantt'
+          ? `<div class="wp-modes wp-modes--unit" role="group" aria-label="Time unit">` +
+            ['hours', 'days']
+              .map(
+                (u) =>
+                  `<button class="wp-modes__btn" type="button" aria-selected="${u === this.unit}" data-wp-unit="${u}">${UNIT_AXIS[u]}</button>`
+              )
+              .join('') +
+            `</div>`
+          : ''
+      return modes || unit ? `<div class="wp-toolbar">${modes}${unit}</div>` : ''
+    }
+
+    #render() {
+      if (!this.#root) return
+      const plan = this.#plan
+      const hasData = !!plan && Array.isArray(plan.tasks) && plan.tasks.length > 0
+      const view = this.#view
+      const showModes = this.mode === null
+
+      const title = this.getAttribute('header') ?? plan?.title ?? ''
+      const subtitle = this.getAttribute('subheader') ?? plan?.subtitle ?? ''
+
+      let stats = ''
+      let body = ''
+      if (hasData) {
+        this.#root.dataset.state = 'ready'
+        const derived = derive(plan)
+        const byId = new Map(plan.tasks.map((t) => [t.id, t]))
+        const counts = summarize(derived)
+        stats =
+          `<div class="wp-stats">` +
+          `<div class="wp-stat"><span class="wp-stat__k">Done</span><span class="wp-stat__v">${counts.done}/${counts.total}</span></div>` +
+          `<div class="wp-stat"><span class="wp-stat__k">Active</span><span class="wp-stat__v">${counts.active}</span></div>` +
+          `<div class="wp-stat"><span class="wp-stat__k">Blocked</span><span class="wp-stat__v">${counts.blocked}</span></div>` +
+          `<div class="wp-stat"><span class="wp-stat__k">Waves</span><span class="wp-stat__v">${counts.waves}</span></div>` +
+          `</div>`
+        body =
+          view === 'gantt'
+            ? renderGantt(derived, this.unit)
+            : view === 'kanban'
+              ? renderKanban(derived, byId)
+              : view === 'swimlanes'
+                ? renderSwimlanes(derived)
+                : renderList(derived, byId)
+      } else {
+        this.#root.dataset.state = 'empty'
+        body = renderEmpty()
+      }
+
+      const head =
+        title || subtitle || stats
+          ? `<div class="wp-head">` +
+            `<div class="wp-head__title">` +
+            (title ? `<div class="wp-head__name">${esc(title)}</div>` : '') +
+            (subtitle ? `<div class="wp-head__sub">${esc(subtitle)}</div>` : '') +
+            `</div>` +
+            stats +
+            `</div>`
+          : ''
+
+      const toolbar = hasData ? this.#toolbar(view, showModes) : ''
+
+      this.#root.innerHTML = head + toolbar + `<div class="wp-canvas">${body}</div>`
+    }
+  }
+
+  if (typeof customElements !== 'undefined' && !customElements.get('bp-workplan')) {
+    customElements.define('bp-workplan', BlueprintWorkplanElement)
+  }
+})()
+
 if (typeof document !== 'undefined') {
   if (document.readyState === 'loading') {
     document.addEventListener('DOMContentLoaded', () => initializeBlueprintRuntime(), { once: true })