@flamingo-stack/openframe-frontend-core 0.0.488 → 0.0.490-1506.3944.1

package/src/utils/markdown-heading-id.ts

@@ -0,0 +1,348 @@
+/**
+ * Markdown heading-id slug SSOT (server-safe: no React, no DOM).
+ *
+ * This algorithm previously existed in THREE byte-identical copies:
+ *   - `components/ui/simple-markdown-renderer.tsx` (generateHeadingId)
+ *   - `components/ui/rich-markdown-renderer.tsx` (generateHeadingId)
+ *   - `utils/markdown-section-extractor.ts` (extractSections)
+ *
+ * The extractor is the PRODUCER of `sectionIds` and the renderers are the
+ * CONSUMERS — if the two ever drift, deep-link anchors and scroll-spy
+ * targets silently diverge. All three now call these helpers; the parity
+ * test `components/ui/__tests__/markdown-parity.test.tsx` asserts
+ * extractor-vs-renderer ID agreement over the fixture corpus.
+ */
+
+/** Emoji ranges stripped from heading text before slugification. */
+export const HEADING_EMOJI_RE =
+  /[\u{1F300}-\u{1F9FF}]|[\u{2600}-\u{26FF}]|[\u{2700}-\u{27BF}]/gu
+
+/** Remove emoji characters and trim. */
+export function stripHeadingEmojis(text: string): string {
+  return text.replace(HEADING_EMOJI_RE, '').trim()
+}
+
+/**
+ * Core slug chain WITHOUT the emoji strip (the extractor exposes emoji
+ * stripping as an option, so the two steps are kept separable):
+ * lowercase → drop non-word/space/hyphen chars → spaces to hyphens →
+ * trim leading/trailing hyphens. May return `''` for symbol-only input —
+ * callers apply their own fallback (`section-N`).
+ */
+export function slugifyHeadingBase(text: string): string {
+  return text
+    .trim()
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+/** The full default chain used by the renderers: emoji strip + slugify. */
+export function slugifyHeadingText(text: string): string {
+  return slugifyHeadingBase(stripHeadingEmojis(text))
+}
+
+// ---------------------------------------------------------------------------
+// Heading SCANNER + DEDUPER (the other half of the producer/consumer contract)
+// ---------------------------------------------------------------------------
+/**
+ * Sharing the slug chain alone was not enough. The PRODUCER
+ * (`utils/markdown-section-extractor`) and the CONSUMER
+ * (`components/ui/markdown/heading-ids`) each carried their own copy of
+ * "which lines are headings" and "how do duplicates get suffixed", and the
+ * copies drifted:
+ *   - the extractor toggled its code-block state on a bare
+ *     `line.startsWith('```')`, so a `~~~`-fenced (or wider-backtick, or
+ *     indented) block containing `## Setup` produced a SECTION from the
+ *     extractor and NO id from the renderer — `sectionIdMap` then missed
+ *     silently and the deep-link anchor pointed nowhere;
+ *   - the extractor anchored ATX at column 0 while the renderer allowed the
+ *     CommonMark 0..3-space indent;
+ *   - the dedupe counter was hand-copied in both files, each with a comment
+ *     saying "the two must agree".
+ * Both now call `scanHeadings` + `createHeadingIdDeduper`. Server-safe: no
+ * React, no DOM.
+ */
+
+// The CommonMark fence machine used to live in THIS file, which meant a
+// streaming renderer imported its fence state from a module named after
+// heading slugs. It now lives in `./markdown-fences`; re-exported here so the
+// public `utils` surface (and every existing import) is unchanged.
+export {
+  createFenceTracker,
+  isBlankLine,
+  type FenceTracker,
+  type FenceLineRole,
+} from './markdown-fences'
+import { createFenceTracker, isBlankLine } from './markdown-fences'
+
+/** A heading the renderer will emit, located in the source. */
+export interface ScannedHeading {
+  /** 1-based line of the heading's FIRST line (setext: the title line). */
+  line: number
+  level: number
+  /** Raw title text, before `stripInlineMarkdown` / slugification. */
+  text: string
+}
+
+export interface ScanHeadingsOptions {
+  /**
+   * Skip a leading YAML frontmatter block (`---` on line 1 through the next
+   * `---`). Only a DOCUMENT-LEADING block counts: a bare `---` mid-document
+   * is a thematic break or a setext underline, and treating it as a
+   * frontmatter toggle (what the extractor used to do) silently swallowed
+   * every heading until the next one.
+   */
+  skipFrontmatter?: boolean
+  /** Include raw-HTML headings (`<h2>Title</h2>`). Default true. */
+  includeRawHtml?: boolean
+  /**
+   * Skip fenced-code blocks. Default true — a `##` inside a code fence is
+   * code, not a heading, and the renderer emits no id for it.
+   */
+  skipFences?: boolean
+}
+
+/**
+ * EVERY line-anchored regex in this module ends `\r?$`, not `$`.
+ *
+ * Lines here come from `content.split('\n')`, so on a CRLF document each one
+ * carries a trailing `\r`. `$` (no `m` flag) anchors at end of string and `\r`
+ * is not in `[ \t]`, so a `$`-anchored pattern matches NOTHING on such a
+ * document. That was a live REGRESSION: `main`'s looser `^(#{1,6})\s+(.+)`
+ * had no end anchor at all and tolerated the `\r` (the title was `.trim()`ed
+ * afterwards), so `'# Real\r\n\r\nbody\r\n\r\n## Second\r\n'` yielded
+ * `["Real","Second"]` on `main` and `[]` here — every CRLF-stored doc / blog /
+ * release body silently lost its TOC, its in-page anchors and its doc-SEO
+ * heading links.
+ *
+ * The `\r` is ABSORBED, not normalized away: `scanHeadings` reports 1-based
+ * LINE numbers that the renderer's id map is keyed by, and the sanitizer's mask
+ * (which shares `markdown-fences`) is length-preserving — neither may be fed a
+ * rewritten source.
+ */
+/** CommonMark ATX heading (closing `#` run is not part of the title). */
+const ATX_HEADING_RE = /^ {0,3}(#{1,6})[ \t]+(.*?)(?:[ \t]+#+)?[ \t]*\r?$/
+/** ATX with no title at all (`###`, `## ###`) — still a heading, empty text. */
+const ATX_EMPTY_RE = /^ {0,3}(#{1,6})[ \t]*#*[ \t]*\r?$/
+/**
+ * Raw-HTML heading (`<h2 id="x">Title</h2>`) — rehype-raw renders these too.
+ * GLOBAL: two `<h3>`s on one line are two headings, and a non-global scan
+ * silently dropped the second (it then fell through to the renderer's
+ * suffix-free fallback and emitted a DUPLICATE DOM id).
+ */
+const RAW_HEADING_RE = /<h([1-6])\b[^>]*>([\s\S]*?)(?:<\/h\1>|$)/gi
+/**
+ * Blockquote markers and list-item markers preceding an ATX heading
+ * (`> ## Setup`, `- ## Setup`, `1. ## Setup`). mdast emits a REAL `<h2>` for
+ * these; scanning only column-0..3 missed them entirely, so two identical
+ * `> ## Setup` headings both hit the suffix-free fallback and emitted the
+ * duplicate DOM ids this whole module exists to prevent.
+ */
+const CONTAINER_PREFIX_RE = /^ {0,3}(?:(?:>[ \t]?)+|(?:[-+*]|\d{1,9}[.)])[ \t]+)+/
+/** Setext underline (`===` → h1, `---` → h2), AFTER container-prefix strip. */
+const SETEXT_UNDERLINE_RE = /^ {0,3}(=+|-+)[ \t]*\r?$/
+/** Thematic break — ends a paragraph run, never underlines it. */
+const THEMATIC_BREAK_RE = /^ {0,3}(\*|_){3,}[ \t]*\r?$/
+/**
+ * CommonMark HTML-block type 6 tag names — these open a raw HTML block no
+ * matter what follows them on the line.
+ */
+const HTML_BLOCK_TAGS =
+  'address|article|aside|base|basefont|blockquote|body|caption|center|col|colgroup|dd|details|dialog|dir|div|dl|dt|fieldset|figcaption|figure|footer|form|frame|frameset|h1|h2|h3|h4|h5|h6|head|header|hr|html|iframe|legend|li|link|main|menu|menuitem|nav|noframes|ol|optgroup|option|p|param|search|section|summary|table|tbody|td|tfoot|th|thead|title|tr|track|ul'
+
+/**
+ * A line that OPENS a raw HTML block. mdast hands the whole block to the HTML
+ * parser, so a `---` inside it is not a setext underline and the lines above
+ * it are not a paragraph: `<div>\nText\n---\n</div>` emits NO heading. The
+ * scanner used to publish a phantom `Text` h2 there.
+ *
+ * The naive `^ {0,3}<` this replaced disqualified any run whose first line
+ * merely STARTED with a tag, so `<span>x</span> more text` + `---` (a plain
+ * paragraph in mdast, yielding an h2) was missed. The alternatives are spelled
+ * out per CommonMark:
+ *   - types 1-5: `<script|pre|style|textarea`, `<!--`, `<?`, `<!X`, `<![CDATA[`
+ *   - type 6:    a `HTML_BLOCK_TAGS` name, whatever follows it
+ *   - type 7:    ANY complete open/closing tag ALONE on the line (trailing
+ *                whitespace only) — this is the clause the old regex got wrong
+ * Attribute soup inside a type-7 tag is approximated with `[^>]*` rather than
+ * a full attribute grammar; the error bias is unchanged (a missed run costs a
+ * TOC entry, never a wrong id — the same direction as the documented
+ * list-item-indent gap in `SetextRun.prefix`).
+ */
+const HTML_BLOCK_OPENER_RE = new RegExp(
+  '^ {0,3}(?:' +
+    // types 1-5
+    '<(?:script|pre|style|textarea)(?:[\\s>]|$)|<!--|<\\?|<![a-zA-Z]|<!\\[CDATA\\[' +
+    // type 6
+    `|</?(?:${HTML_BLOCK_TAGS})(?:[\\s/>]|$)` +
+    // type 7 — a complete tag standing alone on the line
+    '|<[a-zA-Z][a-zA-Z0-9-]*(?:\\s[^>]*)?/?>[ \\t]*\\r?$' +
+    '|</[a-zA-Z][a-zA-Z0-9-]*[ \\t]*>[ \\t]*\\r?$' +
+    ')',
+  'i',
+)
+
+/**
+ * The paragraph RUN that a setext underline would convert into a heading.
+ *
+ * mdast positions a setext heading at the FIRST line of the paragraph and its
+ * text is the WHOLE run (`Foo\nbar\n===` → `{line:1, text:"Foo\nbar"}`). The
+ * scanner used to remember only the LAST line, so the renderer's line-keyed
+ * lookup missed the heading entirely (falling back to a slug of the rendered
+ * children, `foo-bar`) while the extractor published `bar` — a dead deep
+ * link, plus a phantom TOC entry at the wrong line.
+ */
+interface SetextRun {
+  /** 1-based line of the run's FIRST line — where mdast puts the heading. */
+  line: number
+  /**
+   * Container prefix (`> `, `- `, …) every line of the run shares. The
+   * underline must carry the IDENTICAL prefix, which is why `> Quote` +
+   * `> ---` scans as an h2 while `> Quote` + a bare `---` does not.
+   *
+   * KNOWN, DELIBERATE GAP: a setext underline indented to a LIST ITEM's
+   * content column (`- item` / `  ---`) is a heading in mdast but has no
+   * container prefix at all, so this equality test misses it. Closing that
+   * would mean re-deriving list-item content columns here — the scanner
+   * simply emits nothing (the pre-existing behavior), which costs a TOC entry
+   * and never produces a WRONG id.
+   */
+  prefix: string
+  /** Run lines with the container prefix stripped, in order. */
+  lines: string[]
+  /** Run opened with a raw-HTML block line — mdast emits no heading for it. */
+  disqualified: boolean
+}
+
+/**
+ * Collect every heading the markdown renderer will emit, in document order.
+ * THE single definition of "which lines are headings" for both the extractor
+ * and the renderer's id map.
+ */
+export function scanHeadings(
+  content: string,
+  options: ScanHeadingsOptions = {},
+): ScannedHeading[] {
+  const { skipFrontmatter = true, includeRawHtml = true, skipFences = true } = options
+  const out: ScannedHeading[] = []
+  const lines = content.split('\n')
+  // ONE fenced-code state machine (utils/markdown-fences), shared with
+  // markdown/streaming.ts.
+  const fences = skipFences ? createFenceTracker() : null
+
+  let start = 0
+  if (skipFrontmatter && lines[0]?.trim() === '---') {
+    for (let i = 1; i < lines.length; i++) {
+      if (lines[i].trim() === '---' || lines[i].trim() === '...') {
+        start = i + 1
+        break
+      }
+    }
+  }
+
+  // The paragraph run a setext underline would convert (see SetextRun).
+  let setextRun: SetextRun | null = null
+
+  for (let i = start; i < lines.length; i++) {
+    const line = lines[i]
+    if (fences) {
+      const role = fences.push(line)
+      if (role !== 'text') {
+        setextRun = null
+        continue
+      }
+    }
+
+    // Container prefix (`> `, `- `, `1. `) is stripped from EVERY construct
+    // below, so a blockquote/list-nested heading is scanned in both its ATX
+    // (`> ## Setup`) and setext (`> Quote title` / `> ---`) spellings.
+    const prefix = CONTAINER_PREFIX_RE.exec(line)?.[0] ?? ''
+    const body = prefix ? line.slice(prefix.length) : line
+
+    // --- setext (`Title` / `===`): a REAL h1/h2 in mdast, positioned at the
+    // run's FIRST line — which is the line the heading-id map is keyed by.
+    // The underline must carry the SAME container prefix as the run it
+    // closes; `> Quote` followed by a bare `---` is a quote and a thematic
+    // break, not a heading.
+    const setext = SETEXT_UNDERLINE_RE.exec(body)
+    if (setext) {
+      if (setextRun && !setextRun.disqualified && setextRun.prefix === prefix) {
+        out.push({
+          line: setextRun.line,
+          level: setext[1][0] === '=' ? 1 : 2,
+          text: setextRun.lines.join('\n'),
+        })
+      }
+      setextRun = null
+      continue
+    }
+
+    // --- ATX, including inside a blockquote / list item.
+    const atx = ATX_HEADING_RE.exec(body) ?? ATX_EMPTY_RE.exec(body)
+    if (atx) {
+      out.push({ line: i + 1, level: atx[1].length, text: (atx[2] ?? '').trim() })
+      setextRun = null
+      continue
+    }
+
+    if (includeRawHtml && line.indexOf('<') !== -1) {
+      RAW_HEADING_RE.lastIndex = 0
+      let raw: RegExpExecArray | null
+      let matched = false
+      while ((raw = RAW_HEADING_RE.exec(line)) !== null) {
+        matched = true
+        out.push({
+          line: i + 1,
+          level: Number(raw[1]),
+          text: raw[2].replace(/<[^>]*>/g, '').trim(),
+        })
+      }
+      if (matched) {
+        setextRun = null
+        continue
+      }
+    }
+
+    // Paragraph accumulation. A blank line or a thematic break ends the run;
+    // a change of container prefix starts a new block (a list or blockquote
+    // interrupts a paragraph in CommonMark).
+    // CommonMark's blank line (spaces/tabs), NOT `trim()` — an NBSP-only line
+    // is paragraph CONTENT to remark, so ending the run there would move a
+    // setext heading's reported line off the run's first line.
+    if (isBlankLine(body) || THEMATIC_BREAK_RE.test(body)) {
+      setextRun = null
+      continue
+    }
+    if (setextRun && setextRun.prefix === prefix) {
+      setextRun.lines.push(body.trim())
+    } else {
+      setextRun = {
+        line: i + 1,
+        prefix,
+        lines: [body.trim()],
+        disqualified: HTML_BLOCK_OPENER_RE.test(body),
+      }
+    }
+  }
+
+  return out
+}
+
+/**
+ * The duplicate-id suffix counter, as ONE closure both sides instantiate.
+ * First occurrence keeps the bare slug; the Nth gets `-N`. Extractor and
+ * renderer MUST use the same counter or `#anchor` deep links diverge.
+ */
+export function createHeadingIdDeduper(): (cleanId: string) => string {
+  const counts: Record<string, number> = {}
+  return (cleanId: string): string => {
+    if (counts[cleanId]) {
+      counts[cleanId]++
+      return `${cleanId}-${counts[cleanId]}`
+    }
+    counts[cleanId] = 1
+    return cleanId
+  }
+}

package/src/utils/markdown-section-extractor.ts

@@ -4,6 +4,12 @@
  */
 
 import { stripInlineMarkdown } from './markdown-to-plain'
+import {
+  createHeadingIdDeduper,
+  scanHeadings,
+  slugifyHeadingBase,
+  stripHeadingEmojis,
+} from './markdown-heading-id'
 
 export interface MarkdownSection {
   id: string
@@ -38,68 +44,47 @@ export function extractSections(
 ): MarkdownSection[] {
   const opts = { ...DEFAULT_OPTIONS, ...options }
   const sections: MarkdownSection[] = []
-  const lines = markdown.split('\n')
-  const idCounts: Record<string, number> = {}
-
-  let inCodeBlock = false
-  let inYamlBlock = false
-
-  for (const line of lines) {
-    if (opts.skipCodeAndYamlBlocks) {
-      if (line.startsWith('```')) {
-        inCodeBlock = !inCodeBlock
-        continue
-      }
-      if (line === '---') {
-        inYamlBlock = !inYamlBlock
-        continue
-      }
-      if (inCodeBlock || inYamlBlock) continue
-    }
-
-    const pattern = new RegExp(`^(#{1,${opts.maxLevel}})\\s+(.+)`)
-    const match = line.match(pattern)
-    if (!match) continue
-
-    const level = match[1].length
-    if (level > opts.maxLevel) continue
-
-    let title = match[2].trim()
-
+  const dedupe = createHeadingIdDeduper()
+
+  // ONE scanner, shared with the renderer's heading-id map
+  // (utils/markdown-heading-id.ts). This file used to carry its own
+  // line loop — `line.startsWith('```')` for fences (blind to `~~~`, to
+  // longer backtick runs and to the CommonMark 0..3-space indent) and a
+  // bare `line === '---'` YAML toggle (which a mid-document thematic break
+  // or setext underline tripped, swallowing every heading after it). Both
+  // produced sections the renderer emitted no id for.
+  const scanned = scanHeadings(markdown, {
+    skipFrontmatter: opts.skipCodeAndYamlBlocks,
+    skipFences: opts.skipCodeAndYamlBlocks,
+  })
+
+  for (const heading of scanned) {
+    if (heading.level > opts.maxLevel) continue
+
+    let title = heading.text
     if (opts.stripFormattingMarkers) {
       title = stripInlineMarkdown(title).trim()
     }
 
-    let baseId = title
-
-    if (opts.removeEmojis) {
-      baseId = baseId
-        .replace(
-          /[\u{1F300}-\u{1F9FF}]|[\u{2600}-\u{26FF}]|[\u{2700}-\u{27BF}]/gu,
-          '',
-        )
-        .trim()
-    }
-
-    baseId = baseId
-      .toLowerCase()
-      .replace(/[^\w\s-]/g, '')
-      .replace(/\s+/g, '-')
-      .replace(/^-+|-+$/g, '')
-
+    // Slug chain SSOT — shared with the renderers' heading-id generator
+    // (see utils/markdown-heading-id.ts). Extractor and renderers MUST
+    // agree or deep-link anchors silently diverge.
+    const baseId = slugifyHeadingBase(
+      opts.removeEmojis ? stripHeadingEmojis(title) : title,
+    )
+
+    // Symbol-only heading fallback: the 1-based ordinal among the headings
+    // this extractor EMITS (levels ≤ maxLevel). The renderer's heading-id
+    // generator mirrors this exact counter for levels ≤ 2
+    // (components/ui/markdown/heading-ids.ts) — the two must agree or
+    // deep-link anchors diverge for symbol-only headings.
     const cleanId = baseId || `section-${sections.length + 1}`
 
-    let id = cleanId
-    if (opts.handleDuplicateIds) {
-      if (idCounts[cleanId]) {
-        idCounts[cleanId]++
-        id = `${cleanId}-${idCounts[cleanId]}`
-      } else {
-        idCounts[cleanId] = 1
-      }
-    }
-
-    sections.push({ id, title, level })
+    sections.push({
+      id: opts.handleDuplicateIds ? dedupe(cleanId) : cleanId,
+      title,
+      level: heading.level,
+    })
   }
 
   return sections

package/dist/chunk-2B6773QM.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["/home/runner/work/openframe-oss-lib/openframe-oss-lib/openframe-frontend-core/dist/chunk-2B6773QM.cjs","../src/contexts/endpoints-runtime-context.tsx","../src/contexts/chat-runtime-context.tsx"],"names":["createContext","useContext"],"mappings":"AAAA,qFAAY;AACZ;AACA;ACqBA,8BAA0C;AAenC,IAAM,wBAAA,EAA0B,kCAAA,IAA2C,CAAA;AAO3E,SAAS,mBAAA,CAAA,EAA+C;AAC7D,EAAA,OAAO,+BAAA,uBAAkC,CAAA;AAC3C;AASO,SAAS,2BAAA,CAAA,EAAgD;AAC9D,EAAA,MAAM,EAAA,EAAI,+BAAA,uBAAkC,CAAA;AAC5C,EAAA,GAAA,CAAI,CAAC,CAAA,EAAG;AACN,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,IAIF,CAAA;AAAA,EACF;AACA,EAAA,OAAO,CAAA;AACT;ADlDA;AACA;AEiBA;AA0MO,IAAM,mBAAA,EAAqBA,kCAAAA,IAAsC,CAAA;AAQjE,SAAS,cAAA,CAAA,EAAqC;AACnD,EAAA,OAAOC,+BAAAA,kBAA6B,CAAA;AACtC;AAUO,SAAS,sBAAA,CAAA,EAAsC;AACpD,EAAA,MAAM,EAAA,EAAIA,+BAAAA,kBAA6B,CAAA;AACvC,EAAA,GAAA,CAAI,CAAC,CAAA,EAAG;AACN,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,IAMF,CAAA;AAAA,EACF;AACA,EAAA,OAAO,CAAA;AACT;AF7OA;AACA;AACE;AACA;AACA;AACA;AACA;AACA;AACF,mUAAC","file":"/home/runner/work/openframe-oss-lib/openframe-oss-lib/openframe-frontend-core/dist/chunk-2B6773QM.cjs","sourcesContent":[null,"'use client'\n\n/**\n * Endpoints runtime — sibling of ChatRuntime. Carries the API path\n * literals consumed by oss-lib components/hooks/utils so a host\n * application can override them (e.g. when running behind a reverse\n * proxy as `user1.openframe.ai` → `/api/mingo-guide/*`).\n *\n * The hub mounts `<HubRuntimeProvider>` at root with the\n * canonical hub paths; an embedded app mounts its own provider with\n * remapped paths. The pattern mirrors ChatRuntimeContext exactly:\n *\n *   - `useEndpointsRuntime()` returns null when no provider is mounted.\n *     For optional consumers that should gracefully no-op without one.\n *   - `useRequiredEndpointsRuntime()` throws on missing provider — for\n *     hooks/components that cannot function without endpoints.\n *\n * IMPORTANT for embedders: memoize the value passed to\n * `<EndpointsRuntimeContext.Provider value={...}>` (e.g. React.useMemo).\n * Reference changes invalidate downstream effect dependency arrays and\n * trigger unnecessary re-fetches.\n */\n\nimport { createContext, useContext } from 'react'\n\nexport interface EndpointsRuntime {\n  /** GET active announcement (used by `<AnnouncementBar>` mount fetch + refocus revalidation). */\n  announcementsUrl: string\n  accessCode: {\n    /** POST validate access code. */\n    validateUrl: string\n    /** POST consume / redeem access code after registration. */\n    consumeUrl: string\n  }\n  /** POST contact-form submission. */\n  contactUrl: string\n}\n\nexport const EndpointsRuntimeContext = createContext<EndpointsRuntime | null>(null)\n\n/**\n * Optional read — returns null when no provider is mounted. Use for\n * surfaces that should silently skip the fetch (e.g. announcement\n * polling on a page rendered outside the provider tree).\n */\nexport function useEndpointsRuntime(): EndpointsRuntime | null {\n  return useContext(EndpointsRuntimeContext)\n}\n\n/**\n * Strict variant — throws on missing provider. Use for consumers that\n * cannot function without an endpoint (form submission, code\n * validation). In tests/Storybook, wrap with the hub's\n * `<HubRuntimeProvider>` or a stub\n * `<EndpointsRuntimeContext.Provider value={mockedEndpoints}>`.\n */\nexport function useRequiredEndpointsRuntime(): EndpointsRuntime {\n  const v = useContext(EndpointsRuntimeContext)\n  if (!v) {\n    throw new Error(\n      '[endpoints-runtime] hook called outside an <EndpointsRuntimeContext.Provider>. ' +\n        'Hub: mount <HubRuntimeProvider> in your providers tree. ' +\n        'Embedded app: mount your own provider with proxied URLs at the tree root. ' +\n        'Tests/Storybook: wrap render() in <EndpointsRuntimeContext.Provider value={mocked}>.',\n    )\n  }\n  return v\n}\n","'use client'\n\n/**\n * Chat runtime context — single seam for embedding the chat panel in a\n * different host (e.g. user1.openframe.ai reverse-proxying API calls\n * under /api/mingo-guide/* to hub.openframe.ai/api/*).\n *\n * Three concerns, one context:\n *   1. API endpoints: chatStreamUrl / approvalToolUrl / commandsUrl /\n *      buildListUrl + attachment endpoints + chat-identity. The chat\n *      reads them from runtime; hub vs embedded app supply different\n *      strings via different providers.\n *   2. Navigation mode + callbacks: 'host' or 'embed' mode. Host wires\n *      its own router/docNav via the optional `navigate` callback\n *      (plain function, NOT a hook); embed forces new-tab via\n *      `defaultContentOrigin` + lib's `resolveExternalNavigation`.\n *   3. Identity context: only `source` (required for localStorage\n *      namespacing). The display identity (greeting first-name etc.)\n *      comes from the server via `useChatIdentity()` — never injected\n *      client-side, so it always matches the server-resolved auth.\n *\n * Sibling of EndpointsRuntimeContext (announcement bar, contact form,\n * access codes). Each runtime stays an independent React context so\n * embedders can opt into either feature without forcing the other.\n *\n * IMPORTANT for embedders: memoize the value passed to\n * `<ChatRuntimeContext.Provider value={...}>` (e.g. via React.useMemo).\n * Every change to its reference identity invalidates downstream\n * `useMemo` consumers (the chat input's slash-commands binding,\n * useNavLink's embed-resolution memo, useDocChat's streamFn factory).\n * The hub's `<HubRuntimeProvider>` already memoizes correctly with\n * stable deps. Embedded apps that build the value inline on each render\n * will pay an avoidable re-render cost across the entire chat tree.\n */\n\nimport { createContext, useContext, type ReactNode } from 'react'\n\nimport type { ComposeContentUrl } from '../utils/content-href'\n\n/**\n * Runtime config consumed by the chat panel.\n */\nexport interface ChatRuntime {\n  endpoints: {\n    /** POST streaming chat. Hub: '/api/docs/chat'. */\n    chatStreamUrl: string\n    /** POST agent approve/reject. Hub: '/api/chat/agent/confirm-tool'. */\n    approvalToolUrl: string\n    /** Customer-ticket agent endpoints (Help Center). OPTIONAL — when unset,\n     *  the ticket hooks fall back to the bare hub paths\n     *  (`/api/chat/agent/{find-ticket,ticket-action,list-engagements}`).\n     *  Embedders behind a reverse proxy set these to their proxied paths\n     *  (e.g. `/content/api/chat/agent/...`) so tickets route through the SAME\n     *  endpoint config + proxy as every other endpoint. */\n    findTicketUrl?: string\n    ticketActionUrl?: string\n    listEngagementsUrl?: string\n    /** GET slash-command catalog. Hub: '/api/docs/commands'. */\n    commandsUrl: string\n    /** GET RAG-search endpoint behind `<DocSearchBar>` (the in-source search\n     *  bar mounted by `<DocViewer>` / `<DocsHubPage>` when `showAIChat` is on).\n     *  Hub: '/api/docs/search'. OPTIONAL — falls back to the hub path so\n     *  same-origin Next.js hosts don't need to set it. Cross-origin embedders\n     *  set their proxied path so the search bar routes through the same\n     *  reverse proxy as everything else. Same pattern as `findTicketUrl`. */\n    docsSearchUrl?: string\n    /** POST internal-link resolver. The in-source markdown renderer (lib or\n     *  custom) calls `<DocViewer>`'s `handlers.onResolveLink(href, currentPath)`\n     *  for relative hrefs like `./getting-started/intro.md` — that callback\n     *  posts to this URL with `{ link, currentPath, source }` and expects a\n     *  `ResolveLinkResult` back. Hub: '/api/docs/resolve-link'. OPTIONAL — same\n     *  fall-back chain as `docsSearchUrl`: prop override → runtime → default. */\n    docsResolveLinkUrl?: string\n    /** GET per-platform empty-state config (admin-edited in\n     *  `/admin/chat-config`): `{ greeting, enabledRagTableIds, suggestedQueries }`.\n     *  Hub: '/api/docs/empty-state'. OPTIONAL — the in-app (host-mode) chat\n     *  injects these values as SSR props instead, so it leaves this unset.\n     *  Cross-origin EMBEDDERS (no server hop) set it to their proxied path\n     *  (e.g. '/content/api/docs/empty-state') so `<EmbeddableChat>` can fetch\n     *  the greeting / quick-action chips / RAG-source filter at runtime. When\n     *  unset, the chat falls back to the explicit `emptyStateGreeting` /\n     *  `suggestedQueries` / `enabledRagTableIds` props (or in-code defaults). */\n    emptyStateUrl?: string\n    /** Build the per-agent display-config URL for an OpenFrame AI agent\n     *  (Fae/Mingo). OPTIONAL. The returned endpoint MUST be byte-compatible\n     *  with the empty-state wire shape ({ greeting, suggestedQueries,\n     *  enabledRagTableIds }). When set AND `EmbeddableChat` receives an\n     *  `activeAgentSlug` in embed mode, the chat fetches THIS url instead of\n     *  `emptyStateUrl` to render the selected agent's greeting + suggested\n     *  prompts (the \"agent mode\" URL override). Hub: `(slug) =>\n     *  '/api/ai-agents/' + encodeURIComponent(slug)`. */\n    aiAgentConfigUrl?: (slug: string) => string\n    /** Build entity-card list URL for a content type + ids. Hub delegates\n     *  to the rag-table-config registry; embedded app provides its own\n     *  per-type URL builder against the reverse proxy. Returns null when\n     *  the type has no list endpoint (caller skips rendering). */\n    buildListUrl: (type: string, ids: string[]) => string | null\n    /** Chat-attachment endpoints — added for the v2 attachment feature.\n     *\n     *  Three concerns:\n     *    - `attachmentUploadUrl` — POSTed by the chat-attachment hook\n     *      to mint a Supabase signed-upload-URL + HMAC view token.\n     *    - `attachmentViewUrlPrefix` — embedded in markdown URLs the\n     *      chat hosts in user message bubbles (`![]()` / `[Attached]`).\n     *      Stored in chat history; chosen at SEND time. In host mode the\n     *      relative `/api/storage/view/chat-attachments/` is sufficient\n     *      (same-origin); embedders supply an absolute hub URL so the\n     *      browser can fetch cross-origin.\n     *    - `identityUrl` — GET endpoint the `useChatIdentity` hook\n     *      hits to learn the `{authTier, source, attachmentsEnabled}`\n     *      capability bag for the current session. Used beyond chat\n     *      (tickets / contact form / any embedded surface that needs\n     *      to identify the proxied customer), so the name has no\n     *      \"chat\" prefix even though the consuming hook still does. */\n    attachmentUploadUrl: string\n    attachmentViewUrlPrefix: string\n    identityUrl: string\n    /** Optional URL prefix for the image proxy (`<prefix>?url=<external>`).\n     *  When unset, lib's `getProxiedImageUrl` returns the original URL\n     *  unchanged. Hub default: '/api/image-proxy'. Embedders that don't\n     *  host an image-proxy route leave this undefined → images load\n     *  directly cross-origin (CORS-permitting). */\n    imageProxyUrlPrefix?: string\n    /** Optional list of hostnames that should bypass the image proxy\n     *  (rendered direct). Hub uses ['openmsp.ai']; embedders typically\n     *  leave it unset. Matches the `skipDomains` parameter of\n     *  `getProxiedImageUrl`. */\n    imageProxySkipDomains?: string[]\n    /** Optional base URL for the branded og-placeholder image route — the\n     *  DEFAULT cover-image fallback for entity cards with no image. The lib\n     *  appends `?title=…` (+ `w`/`h` for square slots) itself, so this is\n     *  the base, NOT a full URL: relative (`/api/og-placeholder`) for same-\n     *  origin hosts, or the proxied path (`/content/api/og-placeholder`) for\n     *  cross-origin embedders. May carry baked-in query params (preserved when\n     *  the lib layers `title`/dimensions on top) — but per-platform brand\n     *  colors are NO LONGER baked here; the `/api/og-placeholder` route\n     *  resolves them server-side from the platform. Most hosts leave this unset\n     *  and let the lib derive the base from `imageProxyUrlPrefix`.\n     *\n     *  OPTIONAL — when unset the lib derives the base from the sibling\n     *  `imageProxyUrlPrefix` (same API base, route name swapped), then falls\n     *  back to the relative `/api/og-placeholder`. So an embedder that already\n     *  proxies images needs NO og-placeholder wiring. See\n     *  `resolveOgPlaceholderBase` / `buildOgPlaceholderUrl` in `../utils`. */\n    ogPlaceholderUrl?: string\n    /** Supabase storage origin (e.g. `https://xyz.supabase.co`) — used\n     *  by `useVideoWarmup` to scope the `<link rel=\"preload\" as=\"video\">`\n     *  hint to MP4s the deployment actually hosts. Hub wires it via\n     *  `getSupabaseStorageOrigin()`; embedders without a Supabase\n     *  storage origin leave it unset (preload is then skipped; Mux/\n     *  YouTube preconnect still fires). */\n    supabaseStorageOrigin?: string\n  }\n  navigation: {\n    /** ONE knob, two behaviors:\n     *  - 'host' = use the host page's existing click-routing untouched.\n     *    The chat panel calls `navigate?.()` for in-app routing.\n     *  - 'embed' = guest inside another app: short-circuit at the top\n     *    of click handlers to force new-tab + absolutize via\n     *    resolveExternalNavigation. */\n    mode: 'host' | 'embed'\n    /** Embed-only fallback origin for relative URLs whose target platform\n     *  can't be inferred. Used by resolveExternalNavigation when\n     *  `targetPlatform` is null — without this, a relative `/foo` href would\n     *  window.open against the embedder's origin, which is WRONG.\n     *  Set to your content host (e.g. 'https://hub.openframe.ai').\n     *  Required by the embedded app whenever mode='embed'. */\n    defaultContentOrigin?: string\n    /** Override for opening external URLs. MUST BE SYNCHRONOUS —\n     *  Safari/Firefox block popups opened outside a direct user gesture.\n     *  Default: window.open(href, '_blank', 'noopener,noreferrer'). */\n    openExternal?: (href: string) => void\n    /** Optional in-app navigation callback (host-mode only).\n     *  Returns `true` if the host handled the click in-app\n     *  (router.push + docNav.navigate); returns `false`, `undefined`,\n     *  or `void` → lib falls back to window.location.assign(href).\n     *  Hub wires this via HubRuntimeProvider's HubNavigationWiring;\n     *  embedders not in Next.js leave it undefined. */\n    navigate?: (input: { href: string; path?: string | null; targetPlatform?: string | null }) => boolean | void\n    /** Optional new-tab decision callback. Returns true → lib opens in\n     *  new tab; false → same tab via `navigate`. Hub wires the existing\n     *  `decideNewTab` logic from use-nav-link.tsx (re-imports the pure\n     *  helper from lib). Embedders may omit; lib defaults to:\n     *  same-origin/same-platform → same tab, else new tab. */\n    decideNewTab?: (args: { href: string; targetPlatform?: string | null }) => boolean\n  }\n  /** Optional content-URL composer. Returns the platform-aware href +\n   *  target-platform tuple for a content entity. Hub wires this to its\n   *  `buildContentURL(type, slug, extractPrimaryPlatform(platforms))`\n   *  pipeline so the lib catalog/detail views can derive cross-\n   *  platform hrefs without knowing the hub's platform topology\n   *  (openmsp.ai / openframe.app / flamingo.run / tmcg).\n   *\n   *  THE single content-href authority for every embeddable surface — page\n   *  views (onboarding catalog/detail, releases) AND chat cards / chips /\n   *  search results all resolve content links through this one seam, so a\n   *  given type lands in the SAME place regardless of where it's rendered.\n   *  Embedders wire `makeComposeContentUrl({ hostedTypes, contentOrigin })`;\n   *  omit it and lib views fall back to a same-origin relative path\n   *  (`buildDefaultHref`).\n   *\n   *  Takes a single `ComposeContentUrlInput`: `type` + `identifier` (page\n   *  views pass the slug; chat rows pass the id + `externalUrl`, whose path\n   *  yields the slug for in-app routing) + optional `platforms` /\n   *  `externalUrl` / `targetPlatform`. */\n  composeContentUrl?: ComposeContentUrl\n  /** Per-`documentType` doc-viewer targets — the UNIFIED, DYNAMIC replacement for\n   *  the single `chipBasePlatform` prop. Maps a doc-table documentType\n   *  (`'markdown'`, `'data_room_doc'`, …) → `{ platform, basePath }` for the PUBLIC\n   *  doc viewer that hosts it. Doc chips with no `externalUrl` resolve PER ROW to\n   *  `getBaseUrl(platform)/<basePath>/<path>`, so a chat mixing several doc sources\n   *  sends EACH to its own home (markdown→flamingo/knowledge-base,\n   *  data_room_doc→company-hub/data-room) instead of one static fallback. The hub\n   *  may keep using `chipBasePlatform` (one doc source per platform); embedders that\n   *  surface multiple doc sources wire this. Threaded into `resolveSourceRowCTA`. */\n  docPlatformTargets?: Record<string, { platform: string; basePath: string }>\n  /** Chat source / platform identifier — OPTIONAL. The hub sets it from\n   *  `currentPlatform()`; EMBEDDERS leave it unset and stay platform-agnostic.\n   *\n   *  It is NOT required for chat to work. The wire resolves source server-side\n   *  (`/docs/chat|search|commands` reject any client `source`); the\n   *  same-tab-vs-new-tab link decision falls back to an origin comparison when\n   *  it's absent (`decideNewTab` → `isCrossOriginUrl`); and the localStorage\n   *  history namespace falls back to a stable constant. Set it only where the\n   *  client legitimately needs to know its platform a priori — i.e. the hub,\n   *  where several platforms share related origins so \"same platform\" can't be\n   *  inferred from a URL alone. */\n  source?: string\n  // NOTE: No `user` field. The chat's display identity (greeting\n  // first-name, etc.) comes from the SERVER-resolved auth via\n  // `useChatIdentity()` — the same identity the server uses to\n  // authorize requests. Letting embedders pass a client-side `user`\n  // would let it desync from the actual auth tier, causing greetings\n  // like \"Hey Bob\" while the server treats the session as\n  // alice@example.com. Single source of truth: the server.\n}\n\nexport const ChatRuntimeContext = createContext<ChatRuntime | null>(null)\n\n/**\n * Returns the active runtime, or null when no provider is mounted.\n * NULL is a first-class value — it signals \"no chat runtime configured.\"\n * Optional consumers fall back to no-op behavior; strict consumers\n * use `useRequiredChatRuntime` (below).\n */\nexport function useChatRuntime(): ChatRuntime | null {\n  return useContext(ChatRuntimeContext)\n}\n\n/**\n * Strict variant used INSIDE the chat panel. Throws if no provider.\n * The hub guarantees one exists by mounting `<HubRuntimeProvider>` at\n * root; the embedded app mounts its own `<ChatRuntimeContext.Provider>`\n * at the tree root. In Jest / Storybook tests that render chat\n * internals directly, wrap with `<HubRuntimeProvider>` (hub defaults)\n * or supply `<ChatRuntimeContext.Provider value={mockedRuntime}>`.\n */\nexport function useRequiredChatRuntime(): ChatRuntime {\n  const v = useContext(ChatRuntimeContext)\n  if (!v) {\n    throw new Error(\n      '[chat-runtime] hook called outside a <ChatRuntimeContext.Provider>. ' +\n        'The hub mounts <HubRuntimeProvider> at root — this only fires when ' +\n        'chat internals are rendered above the provider tree. ' +\n        'Fix: ensure the rendering subtree descends from the runtime provider. ' +\n        'In tests/Storybook: wrap with <HubRuntimeProvider> or supply ' +\n        'a <ChatRuntimeContext.Provider value={mockedRuntime}>.',\n    )\n  }\n  return v\n}\n"]}