@kolkrabbi/kol-framework 0.57.0 → 0.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.57.0",
+  "version": "0.59.0",
   "description": "Site shell and page layout",
   "license": "MIT",
   "type": "module",
@@ -16,14 +16,16 @@
   "peerDependencies": {
     "@kolkrabbi/kol-component": ">=0.298.0",
     "@kolkrabbi/kol-icons": ">=0.18.0",
+    "@kolkrabbi/kol-markdown": ">=0.2.0",
     "@kolkrabbi/kol-theme": ">=0.186.0",
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0",
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.303.0",
-    "@kolkrabbi/kol-icons": "^0.46.0"
+    "@kolkrabbi/kol-markdown": "0.2.0",
+    "@kolkrabbi/kol-component": "^0.307.0",
+    "@kolkrabbi/kol-icons": "^0.49.0"
   },
   "files": [
     "src",

package/src/LinkPreview.jsx

@@ -0,0 +1,90 @@
+import { useEffect, useRef, useState } from 'react'
+
+/* LINK PREVIEW — kol-atlas's hover card (apps/workspace/src/components/LinkPreview.jsx + previews.js), carried for the
+ * document space: hover a link in the sheet and, after a short pause, a card opens under it — an image on top, a short
+ * text below, Wikipedia-style. `#page` previews the page's title, intro and thumbnail; `#page--section` the section's
+ * heading, first paragraph and first image (its page's thumbnail when it has none). Moving into the card keeps it open;
+ * leaving both closes it; the card follows the link. Touch: a long press opens the card, a tap follows the link.
+ * Not inside the note list — a link's note is its constant source, the card already showed in the text.
+ *
+ *   cardFor(a)  (anchor element) => { title, text, image, graphic, site, href } | null — the app's, from its corpus */
+const W = 320
+const PAUSE = 400
+const PRESS = 400
+const isGraphic = (file = '') => /\.(svg|png)$/i.test(file)
+
+export default function LinkPreview({ root, cardFor }) {
+  const [card, setCard] = useState(null)
+  const timer = useRef(null)
+  const over = useRef(false)
+
+  useEffect(() => {
+    const el = root?.current ?? document
+    const clear = () => { clearTimeout(timer.current); timer.current = null }
+    const close = () => { clear(); setCard(null) }
+    const linkOf = (t) => t.closest?.('.kol-sheet a[href]')
+    const inNotes = (a) => a.closest('ol.fns')
+    const open = (a) => {
+      const data = cardFor(a)
+      if (!data) return
+      const r = a.getBoundingClientRect()
+      /* under the link; above it near the bottom of the window; kept inside the viewport's width */
+      const below = window.innerHeight - r.bottom > 260
+      setCard({ ...data, left: Math.min(Math.max(8, r.left), window.innerWidth - W - 8), top: below ? r.bottom + 8 : null, bottom: below ? null : window.innerHeight - r.top + 8 })
+    }
+    const onOver = (e) => {
+      const a = linkOf(e.target)
+      if (!a || inNotes(a) || e.pointerType === 'touch') return
+      clear()
+      timer.current = setTimeout(() => open(a), PAUSE)
+    }
+    const onOut = (e) => {
+      const a = linkOf(e.target)
+      if (!a) return
+      clear()
+      setTimeout(() => { if (!over.current) setCard(null) }, 120)
+    }
+    let press = null
+    const onDown = (e) => { const a = linkOf(e.target); if (!a || e.pointerType !== 'touch' || inNotes(a)) return; press = setTimeout(() => { open(a); a.dataset.held = '1' }, PRESS) }
+    const onUp = () => { clearTimeout(press); press = null }
+    const onClick = (e) => { const a = linkOf(e.target); if (a?.dataset.held) { delete a.dataset.held; e.preventDefault() } else if (!e.target.closest('[data-link-card]')) setCard(null) }
+    const onKey = (e) => { if (e.key === 'Escape') close() }
+    el.addEventListener('pointerover', onOver)
+    el.addEventListener('pointerout', onOut)
+    el.addEventListener('pointerdown', onDown)
+    el.addEventListener('pointerup', onUp)
+    document.addEventListener('click', onClick, true)
+    window.addEventListener('keydown', onKey)
+    window.addEventListener('scroll', close, true)
+    return () => {
+      el.removeEventListener('pointerover', onOver); el.removeEventListener('pointerout', onOut)
+      el.removeEventListener('pointerdown', onDown); el.removeEventListener('pointerup', onUp)
+      document.removeEventListener('click', onClick, true); window.removeEventListener('keydown', onKey); window.removeEventListener('scroll', close, true)
+      clear()
+    }
+  }, [root, cardFor])
+
+  if (!card) return null
+  return (
+    <a
+      href={card.href}
+      data-link-card
+      onPointerEnter={() => { over.current = true }}
+      onPointerLeave={() => { over.current = false; setCard(null) }}
+      className="fixed z-[var(--kol-z-tooltip,60)] block overflow-hidden rounded border border-fg-12 bg-surface-primary no-underline shadow-[0_8px_24px_rgba(0,0,0,.18)]"
+      style={{ width: W, left: card.left, top: card.top ?? undefined, bottom: card.bottom ?? undefined }}
+    >
+      {card.image && (
+        /* the image keeps its own aspect between 1:1 and 2:1; a graphic is shown whole in a 16:9 frame on the soft ground */
+        <div className={`w-full overflow-hidden ${card.graphic ? 'aspect-video bg-fg-04' : 'max-h-80'}`}>
+          <img src={card.image} alt="" className={`block w-full ${card.graphic ? 'h-full object-contain p-[6%]' : 'h-auto min-h-40 max-h-80 object-cover'}`} />
+        </div>
+      )}
+      <div className="flex flex-col gap-1 p-3">
+        <span className="kol-mono-12 text-emphasis">{card.title}</span>
+        {card.text && <span className="kol-mono-12 text-body line-clamp-3">{card.text}</span>}
+        {card.site && <span className="kol-helper-10 text-meta uppercase tracking-wider mt-1">{card.site}</span>}
+      </div>
+    </a>
+  )
+}

package/src/MarkdownPage.jsx

@@ -0,0 +1,264 @@
+import { useContext, useLayoutEffect, useMemo } from 'react'
+import { CodeBlock, DocsToc, Table } from '@kolkrabbi/kol-component'
+import { ShellTocContext } from './SiteLayout.jsx'
+import { parseDocsMarkdown, splitFrontmatter } from '@kolkrabbi/kol-markdown'
+
+/* MARKDOWN PAGE — a markdown file as a document page (plan-2026-10-28-document W3.2, born in apps/document, home here
+ * since W5.2 after his review, 2026-10-28; kol-website's MarkdownPage ticket). kol-markdown's blocks written as the
+ * markup `.kol-sheet` already styles (kol-theme's port of kol-atlas's workspace.css, class for
+ * class): the head, `.proj` with the `num` gutter when the document is numbered, `p.when` meta lines with their `k`,
+ * `.mk` marks and `.why` reasons, `sup.fn` + `ol.fns` notes under the passage that cites them (kol-atlas's rule: a
+ * note sits at the end of its phase, not the page), `ol.fns.src` for Sources, tables on the DS `Table` inside
+ * `.tablewrap` (a key–value table plain), `CodeBlock` for fences, the `.media` figure grid, blockquote with `cite`,
+ * `.tb` item text. No class of its own.
+ *
+ *   source       the file's text, frontmatter included
+ *   numbered     a numbered document (kol-atlas's `proj`): `.proj`, the number gutter, `data-ms` levels, `.tb` items
+ *   toc          'frame' (default): the headings go to the frame's TOC rail through ShellTocContext, nothing drawn here;
+ *                without a frame, or with 'rail', the DS rail (DocsToc variant="rail"); false: none
+ *   linkNotes    every external link becomes a numbered note too (kol-atlas's `footnotes` tabs: Project, SEO + GEO)
+ *   fit          'cover' (default): a figure fills its frame; 'contain': the whole image on the plate
+ *   ratio        the figure frame's aspect ratio ('4/3' by default, from the theme)
+ *   resolveLink  (url) => href — the app maps `#page`, `#page--section` and `.md` links to its routes
+ *   assetUrl     (file) => url for `![[file]]` embeds; null draws the file's name on a plate */
+const jumpTo = (e) => {
+  e.preventDefault()
+  const id = e.currentTarget.getAttribute('href')?.slice(1)
+  if (id) document.getElementById(id)?.scrollIntoView({ block: 'start' })
+}
+const MARK = { hand: '✋', park: '🅿️', pin: '📍', done: '✓' }
+const isGraphic = (file) => /\.(svg|png)$/i.test(file)
+const isExternal = (url) => /^https?:\/\//.test(url)
+const shortUrl = (url) => { const s = url.replace(/^https?:\/\/(www\.)?/, '').replace(/\/$/, ''); try { return decodeURIComponent(s) } catch { return s } }
+
+/* THE NOTES — kol-atlas's engine rule (apps/workspace/src/engine/render.js, 2026-10-20): one sequence through the page in
+ * reading order, headings included. A `[^key]` takes its number at its first reference, or when its definition line is
+ * listed; with linkNotes every external link takes a new number where it stands (the same address twice in one passage
+ * shares one). The pending notes are listed before the next ## or ### and at the end, under the passage they belong to;
+ * a note's own text can carry links, which join that list. Every link and footnote token is given its number (`t.note`)
+ * so the text and the list agree. */
+function collectNotes(parsed, linkNotes) {
+  const at = {}                 // passage id → [{ key, n, def }]
+  const defs = {}               // key → { tokens } (a footnote's text) | { text, url } (a link's)
+  const num = {}                // key → number
+  let n = 0, pend = [], passage = 'intro'
+  const scan = (tokens = []) => tokens.forEach((t) => {
+    if (t.type === 'footnote') { if (!(t.key in num)) num[t.key] = ++n; t.note = num[t.key] }
+    else if (linkNotes && t.type === 'link' && isExternal(t.url)) {
+      let k = pend.find((x) => defs[x]?.url === t.url)
+      if (!k) { k = `u${++n}`; num[k] = n; defs[k] = { text: t.text, url: t.url }; pend.push(k) }
+      t.note = num[k]
+    } else if (t.type === 'link') t.note = undefined
+  })
+  const scanBlock = (b) => {
+    scan(b.tokens); scan(b.citeTokens)
+    b.rows?.forEach((r) => (Array.isArray(r) ? r.forEach((c) => scan(c?.tokens)) : scan(r.tokens)))
+    b.header?.forEach((c) => scan(c?.tokens))
+    b.items?.forEach((it) => scan(it.tokens ?? it.captionTokens))
+  }
+  const flush = () => {
+    if (!pend.length) return
+    const list = []
+    while (pend.length) {
+      const ks = pend.sort((a, b) => (num[a] ?? 1e9) - (num[b] ?? 1e9)); pend = []
+      ks.forEach((k) => { if (!(k in num)) num[k] = ++n; list.push({ key: k, n: num[k], def: defs[k] ?? {} }); if (defs[k]?.tokens) scan(defs[k].tokens) })
+    }
+    at[passage] = list
+  }
+  const walk = (blocks, sectionId) => {
+    blocks.forEach((b) => {
+      if (b.type === 'heading3') { flush(); passage = `${sectionId}/${b.id}`; scan(b.tokens); return }
+      if (b.type === 'footnote-def') { defs[b.key] = { tokens: b.tokens }; pend.push(b.key); return }
+      scanBlock(b)
+    })
+  }
+  walk(parsed.introBlocks, 'intro')
+  parsed.sections.forEach((s) => { flush(); passage = s.id; scan(s.tokens); walk(s.blocks, s.id) })
+  flush()
+  return { at, defs }
+}
+
+/* inline tokens → elements */
+function Inline({ tokens = [], ctx }) {
+  return tokens.map((t, i) => {
+    switch (t.type) {
+      case 'text': return t.content
+      case 'bold': return <strong key={i}>{t.tokens ? <Inline tokens={t.tokens} ctx={ctx} /> : t.content}</strong>
+      case 'italic': return <em key={i}>{t.tokens ? <Inline tokens={t.tokens} ctx={ctx} /> : t.content}</em>
+      case 'code': return <code key={i}>{t.content}</code>
+      case 'link': {
+        const ext = isExternal(t.url)
+        return <span key={i}><a href={ctx.resolveLink(t.url)} target={ext ? '_blank' : undefined} rel={ext ? 'noopener' : undefined}>{t.text}</a>{t.note && <sup className="fn"><a href={`#fn-${t.note}`}>{t.note}</a></sup>}</span>
+      }
+      case 'image': {
+        /* a markdown image names a file beside the document (`_assets/x.png`, `./x.png`) — the fixture's url for it; a web image as written */
+        const local = !/^(https?:|data:|\/)/.test(t.src)
+        return <img key={i} src={(local && ctx.assetUrl(t.src.split('/').pop())) || t.src} alt={t.alt} loading="lazy" />
+      }
+      case 'colorswatch': return <span key={i} className="inline-block size-3 align-middle rounded-sm border border-fg-12" style={{ background: t.color }} />
+      case 'hashtag': return `#${t.tag}`
+      case 'footnote': return <sup key={i} className="fn"><a href={`#fn-${t.note}`}>{t.note}</a></sup>
+      default: return null
+    }
+  })
+}
+
+/* a mark with a reason follows the title (`.mk` + `.why`); a bare mark (📍 Sync) leads it, as kol-atlas prints it */
+const Marks = ({ marks = [], lead }) => marks.filter((m) => m.kind !== 'done' && Boolean(m.reason) !== Boolean(lead)).map((m, i) => (
+  lead ? <span key={i}>{MARK[m.kind]} </span> : <span key={i}><span className="mk">{MARK[m.kind]}</span>{m.reason && <span className="why">{m.reason}</span>}</span>
+))
+
+function Heading({ as: Tag, block, ctx }) {
+  const done = block.marks?.some((m) => m.kind === 'done')
+  return (
+    <Tag id={`a-${block.id}`} className={done ? 'done' : undefined}>
+      {block.num && <span className="num">{block.num}</span>}
+      <Marks marks={block.marks} lead />
+      <Inline tokens={block.tokens ?? [{ type: 'text', content: block.content }]} ctx={ctx} />
+      <Marks marks={block.marks} />
+    </Tag>
+  )
+}
+
+/* the notes of one passage: a footnote's text, or a link's text and short address */
+function Notes({ list = [], ms, ctx }) {
+  if (!list.length) return null
+  return (
+    <ol className="fns" data-ms={ms ? '' : undefined} start={list[0].n}>
+      {list.map(({ key, n, def: d }) => (
+        <li key={key} id={`fn-${n}`}>
+          <span className="fnn">{n}.</span>
+          {d.url ? <><a href={d.url} target="_blank" rel="noopener">{d.text}</a> <span className="url">{shortUrl(d.url)}</span></> : <Inline tokens={d.tokens ?? []} ctx={ctx} />}
+        </li>
+      ))}
+    </ol>
+  )
+}
+
+/* the figure grid: a workspace image by its file, or a web link card (`![caption](https://…)`) — its stored screenshot,
+ * the figure a link to the site, the site's name on the plate when there is no shot. A figure fills its frame (`fit`
+ * 'cover', the theme's default); `fit="contain"` shows the whole image on the plate; `ratio` sets the frame ('4/3') */
+function MediaGrid({ items, ctx }) {
+  const cols = items.length <= 2 ? 2 : items.length === 3 ? 3 : 4
+  return (
+    <div className="media" data-fit={ctx.fit === 'contain' ? 'contain' : undefined} style={{ '--cols': cols, ...(ctx.ratio ? { '--media-ratio': ctx.ratio } : {}) }}>
+      {items.map((it, i) => {
+        const web = isExternal(it.file)
+        const url = ctx.assetUrl(it.file)
+        const fig = (
+          <figure key={i} className={!web && isGraphic(it.file) ? 'g' : undefined}>
+            {url ? <img src={url} alt={it.caption || it.file} loading="lazy" /> : <div className="doc">{web ? shortUrl(it.file) : it.file}</div>}
+            <figcaption>{it.captionTokens ? <Inline tokens={it.captionTokens} ctx={ctx} /> : it.caption || it.file.split('/').pop()}</figcaption>
+          </figure>
+        )
+        return web ? <a key={i} href={it.file} className="no-underline">{fig}</a> : fig
+      })}
+    </div>
+  )
+}
+
+function TableBlock({ block, ms, ctx }) {
+  const cell = (c, key) => <Inline key={key} tokens={c.tokens} ctx={ctx} />
+  if (block.kv) {
+    return (
+      <div className="tablewrap kv" data-ms={ms ? '' : undefined}>
+        <table><tbody>{block.rows.map((r, i) => <tr key={i}>{r.map((c, j) => <td key={j} className={block.align?.[j] === 'right' ? 'num' : undefined}>{cell(c, j)}</td>)}</tr>)}</tbody></table>
+      </div>
+    )
+  }
+  const columns = block.headers.map((h, j) => ({ accessor: `c${j}`, header: h, wrap: true, align: block.align?.[j] }))
+  const rows = block.rows.map((r, i) => Object.fromEntries([['id', i], ...r.map((c, j) => [`c${j}`, cell(c, `${i}-${j}`)])]))
+  return <div className="tablewrap" data-ms={ms ? '' : undefined}><Table variant="simple" columns={columns} rows={rows} /></div>
+}
+
+/* a section's blocks in order; each passage's notes close it. In a numbered document (`.proj`) the text has three
+ * levels, kol-atlas's: MILESTONE text (the intro, and under a ## before any ###) hangs back into the gutter with
+ * `data-ms`; PHASE text (under a ###) sits at the padded edge; ITEM text (under a ####) is `.tb`, one gutter further. */
+function Blocks({ blocks, sectionId, sources, ctx }) {
+  const out = []
+  let passage = sectionId
+  let level = 'ms'      // 'ms' · 'phase' · 'item'
+  let skipList = false  // the list under a pop-out definition is the pop-out's, not the page's
+  const ms = () => (ctx.proj && level === 'ms' ? '' : undefined)
+  const tb = () => (ctx.proj && level === 'item' ? 'tb' : undefined)
+  const close = (key) => out.push(<Notes key={`notes-${key}`} list={ctx.notes.at[passage]} ms={ms() !== undefined} ctx={ctx} />)
+  blocks.forEach((b, i) => {
+    switch (b.type) {
+      case 'heading3': close(i); passage = `${sectionId}/${b.id}`; level = 'phase'; out.push(<Heading key={i} as="h3" block={b} ctx={ctx} />); break
+      case 'heading4': level = 'item'; out.push(<Heading key={i} as="h4" block={b} ctx={ctx} />); break
+      case 'meta': {
+        /* one `p.when` per run of meta lines, the lines on <br>; an Acceptance line is its own `p.dw` (the engine's rule) */
+        const runs = []
+        b.rows.forEach((r) => { const dw = r.key === 'Acceptance'; const last = runs[runs.length - 1]; if (!dw && last && !last.dw) last.rows.push(r); else runs.push({ dw, rows: [r] }) })
+        runs.forEach((run, j) => out.push(
+          <p key={`${i}-${j}`} className={run.dw ? 'dw' : 'when'} data-ms={ms()}>
+            {run.rows.map((r, k) => <span key={k}>{k > 0 && <br />}<span className="k">{r.key}:</span> <Inline tokens={r.tokens} ctx={ctx} /></span>)}
+          </p>,
+        ))
+        break
+      }
+      case 'paragraph': out.push(<p key={i} className={b.tokens.length === 1 && b.tokens[0].type === 'italic' ? 'note' : tb()} data-ms={ms()}><Inline tokens={b.tokens} ctx={ctx} /></p>); break
+      case 'list': {
+        if (skipList) { skipList = false; break }
+        /* a Sources list is numbered notes whatever its bullet (kol-atlas's rule) */
+        const L = b.ordered || sources ? 'ol' : 'ul'
+        out.push(<L key={i} className={sources ? 'fns src' : tb()} data-ms={ms()}>{b.items.map((it, j) => {
+          /* a Sources item: number, text, and the short address of its first link (the engine's rule) */
+          const u = sources && it.tokens.find((t) => t.type === 'link' && isExternal(t.url))?.url
+          return <li key={j}>{sources && <span className="fnn">{j + 1}.</span>}<Inline tokens={it.tokens} ctx={ctx} />{u && <> <span className="url">{shortUrl(u)}</span></>}</li>
+        })}</L>)
+        break
+      }
+      case 'blockquote': out.push(<blockquote key={i} data-ms={ms()}><p><Inline tokens={b.tokens} ctx={ctx} /></p>{b.cite && <cite><Inline tokens={b.citeTokens} ctx={ctx} /></cite>}</blockquote>); break
+      case 'code': out.push(<CodeBlock key={i} language={b.lang || 'text'} code={b.lines.join('\n')} />); break
+      case 'divider': out.push(<hr key={i} />); break
+      case 'table': out.push(<TableBlock key={i} block={b} ms={ms() !== undefined} ctx={ctx} />); break
+      case 'media': out.push(<MediaGrid key={i} items={b.items} ctx={ctx} />); break
+      case 'popout-def': skipList = true; break
+      default: break   // footnote-def: its text is read by the notes
+    }
+  })
+  close('end')
+  return out
+}
+
+export default function MarkdownPage({ source = '', numbered = false, toc = 'frame', linkNotes = false, fit = 'cover', ratio, resolveLink = (u) => u, assetUrl = () => null }) {
+  const { fields, body } = useMemo(() => splitFrontmatter(source), [source])
+  const fm = Object.fromEntries(fields)
+  const parsed = useMemo(() => parseDocsMarkdown(body, { numbered }), [body, numbered])
+  const h1 = parsed.introBlocks.find((b) => b.type === 'heading1')
+  const title = h1?.content ?? fm.title ?? ''
+  const proj = numbered
+  const notes = useMemo(() => collectNotes(parsed, linkNotes), [parsed, linkNotes])
+  const ctx = { notes, proj, linkNotes, fit, ratio, resolveLink, assetUrl }
+
+  /* two sections with one heading (a research paper repeats its brand names) get one anchor each */
+  const seen = {}
+  const sections = parsed.sections.map((s) => { seen[s.id] = (seen[s.id] ?? 0) + 1; return seen[s.id] > 1 ? { ...s, id: `${s.id}-${seen[s.id]}` } : s })
+  const tocItems = sections.map((s) => ({ id: `a-${s.id}`, label: s.heading }))
+  const setToc = useContext(ShellTocContext)
+  const onFrame = toc === 'frame' && typeof setToc === 'function'
+  useLayoutEffect(() => {
+    if (!onFrame) return undefined
+    setToc(tocItems.length ? <DocsToc toc={tocItems} onNavigate={jumpTo} /> : null)
+    return () => setToc(null)
+  }, [onFrame, setToc, body]) // eslint-disable-line react-hooks/exhaustive-deps
+  const rail = toc === 'rail' || (toc === 'frame' && !onFrame)
+
+  return (
+    /* the page's inset is `.kol-page`, as site-hub's Sheet wears it — the frame paints the plane, the page its margins */
+    <div className={`kol-page${rail ? ' xl:pr-32' : ''}`}>
+      <article className={`kol-sheet${proj ? ' proj' : ''}`} style={{ maxWidth: 980 }}>
+        <h1>{title}</h1>
+        <Blocks blocks={parsed.introBlocks.filter((b) => b.type !== 'heading1')} sectionId="intro" ctx={ctx} />
+        {sections.map((s, i) => (
+          <section key={`${i}-${s.id}`} id={`a-${s.id}`}>
+            <h2>{s.num && <span className="num">{s.num}</span>}<Marks marks={s.marks} lead /><Inline tokens={s.tokens ?? [{ type: 'text', content: s.heading }]} ctx={ctx} /><Marks marks={s.marks} /></h2>
+            <Blocks blocks={s.blocks} sectionId={parsed.sections[i].id} sources={s.sources} ctx={ctx} />
+          </section>
+        ))}
+      </article>
+      {rail && tocItems.length > 1 && <DocsToc variant="rail" toc={tocItems} onNavigate={jumpTo} className="hidden xl:flex" />}
+    </div>
+  )
+}

package/src/documentFiles.js

@@ -0,0 +1,27 @@
+import { kindOf, extOf } from '@kolkrabbi/kol-component'
+
+/* DOCUMENT FILES — the files beside a folder's markdown (DocumentIndexFilesAndIcons049, kol-website 2026-10-28, a point
+ * of the MarkdownPage ticket: *"a folder may also hold PDFs and images; the contents index lists them beside the md
+ * pages and opens them in the DS QuickLook, not as pages"*). The consumer globs them as URLs and hands the modules over:
+ *
+ *   documentFiles(import.meta.glob('./brand/business/**\/*.{pdf,png,jpg,jpeg,webp,svg}', { query: '?url', import: 'default', eager: true }))
+ *   → [{ id, title, group, file, ext, kind }]   in the glob's (path) order
+ *
+ *   id      the file's stem without a `NN-` prefix (`02-business-plan.pdf` → `business-plan`)
+ *   title   the stem, unprefixed and titlecased (`Business Plan`)
+ *   group   the file's parent folder, titlecased and unprefixed (`frumkvaedi-2024/` → `Frumkvaedi 2024`); '' at the root
+ *   file    the served URL; ext its extension; kind the DS's (`kindOf`: pdf · image · video · audio · …)
+ *
+ * A row is what `DocumentIndex` draws as a card in its part and opens in Quick Look. `documentTabs` is the markdown half. */
+const unprefix = (s) => s.replace(/^\d+[-_.]\s*/, '')
+const titleCase = (s) => s.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase())
+
+export default function documentFiles(modules = {}, { root = '' } = {}) {
+  return Object.entries(modules).map(([path, url]) => {
+    const rel = root && path.startsWith(root) ? path.slice(root.length) : path
+    const parts = rel.replace(/^\.?\//, '').split('/')
+    const name = parts.pop()
+    const stem = name.replace(/\.[a-z0-9]+$/i, '')
+    return { id: unprefix(stem), title: titleCase(unprefix(stem)), group: parts.length ? titleCase(unprefix(parts[parts.length - 1])) : '', file: typeof url === 'string' ? url : '', ext: extOf(name), kind: kindOf({ key: name }) }
+  })
+}

package/src/documentTabs.js

@@ -0,0 +1,29 @@
+import { splitFrontmatter } from '@kolkrabbi/kol-markdown'
+
+/* DOCUMENT TABS — a folder of markdown files as page rows (plan-2026-10-28-document W5.2; kol-website's MarkdownPage
+ * ticket: *"a folder of .md files rendered as pages"*). The consumer globs its folder and hands the modules over:
+ *
+ *   documentTabs(import.meta.glob('./brand/foundation/**\/*.md', { query: '?raw', import: 'default', eager: true }))
+ *   → [{ id, title, group, file, source }]   in the glob's (path) order
+ *
+ *   id      the file's stem without a `NN-` prefix (`01-strategy.md` → `strategy`)
+ *   title   the frontmatter `title`, else the first `# heading`, else the stem
+ *   group   the file's parent folder, titlecased and unprefixed (`02-identity/` → `Identity`); '' at the root
+ *   file    the path as globbed; source the markdown
+ *
+ * A row is what `MarkdownPage` takes (`source`) and what a rail row or a `DocumentIndex` card is made from; `numbered`,
+ * `notes` and the rest are the consumer's to add per row, as kol-atlas's tab table does. */
+const unprefix = (s) => s.replace(/^\d+[-_.]\s*/, '')
+const titleCase = (s) => s.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase())
+
+export default function documentTabs(modules = {}, { root = '' } = {}) {
+  return Object.entries(modules).map(([file, source]) => {
+    const rel = root && file.startsWith(root) ? file.slice(root.length) : file
+    const parts = rel.replace(/^\.?\//, '').split('/')
+    const stem = parts.pop().replace(/\.md$/i, '')
+    const { fields, body } = splitFrontmatter(typeof source === 'string' ? source : '')
+    const fm = Object.fromEntries(fields)
+    const h1 = /^#\s+(.+)$/m.exec(body)?.[1]?.trim()
+    return { id: unprefix(stem), title: fm.title || h1 || titleCase(unprefix(stem)), group: parts.length ? titleCase(unprefix(parts[parts.length - 1])) : '', file, source: typeof source === 'string' ? source : '' }
+  })
+}

package/src/index.js

@@ -27,3 +27,9 @@ export { default as PortalFooter } from './PortalFooter.jsx'
 export { default as ScrollToTop } from './ScrollToTop.jsx'
 export { default as PageHero, default as BrandHero, default as SubPageHero } from './PageHero.jsx'
 export { default as CategoryPage } from './CategoryPage.jsx'
+/* the document page (plan-2026-10-28-document W5.2): a markdown file as `.kol-sheet`, the hover card for its links,
+ * a folder of files as page rows */
+export { default as MarkdownPage } from './MarkdownPage.jsx'
+export { default as LinkPreview } from './LinkPreview.jsx'
+export { default as documentTabs } from './documentTabs.js'
+export { default as documentFiles } from './documentFiles.js'