@flamingo-stack/openframe-frontend-core 0.0.510 → 0.0.511

package/src/utils/__tests__/anchor-id.test.ts

@@ -0,0 +1,139 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it } from 'vitest'
+import { extractSections } from '../markdown-section-extractor'
+import { findAnchorElementByNormalizedId, normalizeAnchorId } from '../anchor-id'
+import { getHashTargetElement } from '../same-page-hash-nav'
+
+describe('normalizeAnchorId', () => {
+  it('drops the hyphen GitHub leaves behind a stripped emoji', () => {
+    expect(normalizeAnchorId('-getting-started')).toBe('getting-started')
+    expect(normalizeAnchorId('-architecture-diagrams')).toBe('architecture-diagrams')
+  })
+
+  it('collapses the hyphen run GitHub emits around a dropped "&"', () => {
+    expect(normalizeAnchorId('-community--support')).toBe('community-support')
+  })
+
+  it('is a no-op for an already-clean id', () => {
+    expect(normalizeAnchorId('table-of-contents')).toBe('table-of-contents')
+  })
+
+  it('normalizes raw heading text too', () => {
+    expect(normalizeAnchorId('🚀 Getting Started')).toBe('getting-started')
+  })
+})
+
+describe('findAnchorElementByNormalizedId', () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <h1 id="openframe-cli-documentation">OpenFrame CLI — Documentation</h1>
+      <h2 id="table-of-contents">📚 Table of Contents</h2>
+      <h2 id="getting-started">🚀 Getting Started</h2>
+      <h2 id="community-support">💬 Community &amp; Support</h2>
+      <h3 id="a---b">A - B</h3>
+    `
+  })
+
+  it('resolves a GitHub-style anchor onto our heading id', () => {
+    expect(findAnchorElementByNormalizedId('-getting-started', document)?.id).toBe('getting-started')
+    expect(findAnchorElementByNormalizedId('-table-of-contents', document)?.id).toBe(
+      'table-of-contents',
+    )
+  })
+
+  it('resolves the double-hyphen "&" form', () => {
+    expect(findAnchorElementByNormalizedId('-community--support', document)?.id).toBe(
+      'community-support',
+    )
+  })
+
+  it('matches an id whose own raw form normalizes differently', () => {
+    // `a---b` is not reachable by normalized lookup — only the heading scan finds it.
+    expect(findAnchorElementByNormalizedId('a-b', document)?.id).toBe('a---b')
+  })
+
+  it('returns null for an anchor with no heading behind it', () => {
+    expect(findAnchorElementByNormalizedId('nope', document)).toBeNull()
+    expect(findAnchorElementByNormalizedId('', document)).toBeNull()
+  })
+})
+
+describe('duplicate headings — GitHub numbers from -1, our deduper from -2', () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <h2 id="setup">Setup</h2>
+      <h2 id="setup-2">Setup</h2>
+      <h2 id="setup-3">Setup</h2>
+      <h2 id="step-2">Step 2</h2>
+    `
+  })
+
+  it('shifts a GitHub duplicate fragment onto our id', () => {
+    expect(getHashTargetElement('setup-1')?.id).toBe('setup-2')
+    expect(getHashTargetElement('setup-2')?.id).toBe('setup-2')
+  })
+
+  it('an id that genuinely ends in a number is matched exactly, never shifted', () => {
+    // `step-2` exists, so the exact lookup wins and `step-3` is never consulted.
+    expect(getHashTargetElement('step-2')?.id).toBe('step-2')
+  })
+
+  it('does not invent a match when the shifted id is absent too', () => {
+    expect(getHashTargetElement('missing-1')).toBeNull()
+  })
+})
+
+describe('getHashTargetElement — the fuzzy pass is wired into THE resolver', () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <h2 id="getting-started">🚀 Getting Started</h2>
+      <div id="ticket-a/b">encoded-id row</div>
+    `
+  })
+
+  it('exact ids still win, unchanged', () => {
+    expect(getHashTargetElement('getting-started')?.id).toBe('getting-started')
+  })
+
+  it('percent-decoding still runs before the fuzzy pass', () => {
+    expect(getHashTargetElement('ticket-a%2Fb')?.id).toBe('ticket-a/b')
+  })
+
+  it('falls back to a normalized match — the TOC bug, through the public entry point', () => {
+    expect(getHashTargetElement('-getting-started')?.id).toBe('getting-started')
+  })
+
+  it('still returns null when nothing matches', () => {
+    expect(getHashTargetElement('nope')).toBeNull()
+    expect(getHashTargetElement('')).toBeNull()
+  })
+})
+
+describe('the openframe-cli doc that reported the bug', () => {
+  // Verbatim shapes from
+  // GET /api/docs/sources/openframe-docs/content?path=openframe-cli
+  const headings = [
+    '# OpenFrame CLI — Documentation',
+    '## 📚 Table of Contents',
+    '## 🚀 Getting Started',
+    '## 🛠️ Development',
+    '## 💬 Community & Support',
+  ].join('\n\n')
+  const tocHrefs = ['#-getting-started', '#-development', '#-community--support']
+
+  it('every TOC href resolves to the id the section extractor emits', () => {
+    const sections = extractSections(headings)
+    document.body.innerHTML = sections
+      .map((s) => `<h2 id="${s.id}">${s.title}</h2>`)
+      .join('')
+
+    const resolved = tocHrefs.map((href) => getHashTargetElement(href.slice(1))?.id ?? null)
+    expect(resolved).toEqual(['getting-started', 'development', 'community-support'])
+    // …and none of them resolved before this helper existed:
+    expect(tocHrefs.map((href) => document.getElementById(href.slice(1)))).toEqual([
+      null,
+      null,
+      null,
+    ])
+  })
+})

package/src/utils/__tests__/content-href.test.ts

@@ -32,6 +32,80 @@ describe('makeComposeContentUrl (unified single-object seam)', () => {
     })
   })
 
+  it('canonicalizes rail-vocab aliases before matching suffixes', () => {
+    // `blog_post_existing` is the legacy ContentRef spelling `buildListUrl`
+    // accepts. Without canonicalization here it missed `suffixes` entirely and
+    // emitted `<hub>/blog_post_existing/<slug>` — the same post reachable at
+    // two different urls depending on which call site produced the link.
+    expect(compose({ type: 'blog_post_existing', identifier: 'hello' })).toEqual(
+      compose({ type: 'blog_post', identifier: 'hello' }),
+    )
+    expect(compose({ type: 'blog_post_existing', identifier: 'hello' })).toEqual({
+      href: `${HUB}/blog/hello`,
+      targetPlatform: null,
+    })
+  })
+
+  it('non-hosted row resolves to the OWNING platform, not to contentOrigin', () => {
+    // The reported bug: an OpenMSP-owned blog post linked to flamingo.run.
+    expect(
+      compose({ type: 'blog_post', identifier: 'why-mdr', platforms: [{ name: 'openmsp' }] }),
+    ).toEqual({ href: 'https://www.openmsp.ai/blog/why-mdr', targetPlatform: 'openmsp' })
+  })
+
+  it('reads all three junction shapes the DALs produce', () => {
+    const shapes = [
+      [{ name: 'openmsp' }],
+      [{ platform_name: 'openmsp' } as unknown as { name?: string }],
+      [{ platforms: { name: 'openmsp' } } as unknown as { name?: string }],
+    ]
+    for (const platforms of shapes) {
+      expect(compose({ type: 'blog_post', identifier: 'x', platforms }).href).toBe(
+        'https://www.openmsp.ai/blog/x',
+      )
+    }
+  })
+
+  it('explicit targetPlatform wins over the junction', () => {
+    expect(
+      compose({
+        type: 'blog_post',
+        identifier: 'x',
+        targetPlatform: 'tmcg',
+        platforms: [{ name: 'openmsp' }],
+      }),
+    ).toEqual({ href: 'https://www.tmcg.miami/blog/x', targetPlatform: 'tmcg' })
+  })
+
+  it('falls back to contentOrigin for an unknown or absent platform', () => {
+    expect(compose({ type: 'blog_post', identifier: 'x' })).toEqual({
+      href: `${HUB}/blog/x`,
+      targetPlatform: null,
+    })
+    // An unresolvable owner reports `null`, NOT its own name: the href came
+    // from `contentOrigin`, and `decideNewTab` prefers `targetPlatform` over
+    // its origin check — so claiming a platform here forced a same-host link
+    // into a new tab.
+    expect(
+      compose({ type: 'blog_post', identifier: 'x', platforms: [{ name: 'not-a-platform' }] }),
+    ).toEqual({ href: `${HUB}/blog/x`, targetPlatform: null })
+    expect(
+      compose({ type: 'blog_post', identifier: 'x', targetPlatform: 'not-a-platform' }),
+    ).toEqual({ href: `${HUB}/blog/x`, targetPlatform: null })
+  })
+
+  it('externalUrl still wins — the RAG url is authoritative', () => {
+    expect(
+      compose({
+        type: 'blog_post',
+        identifier: 'x',
+        externalUrl: 'https://www.openmsp.ai/blog/x',
+        targetPlatform: 'openmsp',
+        platforms: [{ name: 'flamingo' }],
+      }),
+    ).toEqual({ href: 'https://www.openmsp.ai/blog/x', targetPlatform: 'openmsp' })
+  })
+
   it('always returns a tuple (never null) — even for an unknown type', () => {
     expect(compose({ type: 'totally_unknown', identifier: 'x' })).toEqual({
       href: `${HUB}/totally_unknown/x`,

package/src/utils/__tests__/list-url.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { buildListUrl } from '../list-url'
+import { buildListUrl, canonicalContentRefType } from '../list-url'
 
 /**
  * Byte-parity gate for the shared `buildListUrl`.
@@ -33,6 +33,16 @@ describe('buildListUrl — byte parity with the hub mappers', () => {
     expect(buildListUrl(type, ['a', 'b'])).toBe(expected)
   })
 
+  it('canonicalContentRefType: aliases resolve, prototype keys do not', () => {
+    expect(canonicalContentRefType('blog_post_existing')).toBe('blog_post')
+    expect(canonicalContentRefType('roadmap_item')).toBe('roadmap_item')
+    // A bare `ALIASES[key]` read returned `Object` here, which downstream
+    // interpolated into a URL path.
+    expect(canonicalContentRefType('constructor')).toBe('constructor')
+    expect(canonicalContentRefType('__proto__')).toBe('__proto__')
+    expect(canonicalContentRefType('toString')).toBe('toString')
+  })
+
   it('un-aliases blog_post_existing → blog_post (mirrors hub LEGACY_TYPE_ALIASES)', () => {
     expect(buildListUrl('blog_post_existing', ['a', 'b'])).toBe(BASELINE.blog_post)
   })

package/src/utils/anchor-id.ts

@@ -0,0 +1,106 @@
+/**
+ * GitHub-compatible anchor resolution for in-page `#hash` links.
+ *
+ * ## The mismatch this exists to bridge
+ *
+ * Doc authors write their table of contents against GitHub's slugger, which
+ * keeps the separator left behind by a stripped emoji:
+ *
+ *   `## 📚 Table of Contents`  →  GitHub anchor `#-table-of-contents`
+ *
+ * Our heading ids come from the shared slug SSOT (`markdown-heading-id`),
+ * whose `slugifyHeadingBase` trims leading and trailing hyphens — so the same
+ * heading renders as `id="table-of-contents"`. The "On this page" rail
+ * navigates by those ids and works; the in-body TOC link points at an id that
+ * does not exist and the browser silently does nothing.
+ *
+ * Rather than change the id shape (it is already baked into shared URLs and
+ * the rail), resolution is made tolerant: compare a *normalized* form of both
+ * sides. This module owns ONLY that tolerance — the slug chain itself is
+ * imported, never re-implemented, so a change to the id shape lands in one
+ * place and both sides move together.
+ *
+ * Callers do not reach for this directly: `getHashTargetElement`
+ * (`utils/same-page-hash-nav`) is the ONE resolver every hash consumer goes
+ * through, and it applies this as its last pass.
+ */
+import { slugifyHeadingText } from './markdown-heading-id'
+
+/**
+ * Reduce an anchor id (ours or GitHub's) to a comparable form.
+ *
+ * Everything but the final hyphen-run collapse is the shared heading-slug
+ * chain: emoji strip → lowercase → drop non-word chars → spaces to hyphens →
+ * trim edge hyphens. The collapse is this module's own addition, covering
+ * GitHub's *interior* divergence — `## 💬 Community & Support` slugs to
+ * `#-community--support` (a double hyphen around the dropped `&`) against our
+ * `community-support`.
+ *
+ *   `'-getting-started'`     → `'getting-started'`
+ *   `'-community--support'`  → `'community-support'`
+ *   `'Getting Started'`      → `'getting-started'`
+ */
+export function normalizeAnchorId(raw: string): string {
+  return slugifyHeadingText(raw).replace(/-+/g, '-').replace(/^-+|-+$/g, '')
+}
+
+/** Heading elements carrying an id — the candidate set for the fuzzy pass. */
+const HEADING_SELECTOR = 'h1[id], h2[id], h3[id], h4[id], h5[id], h6[id]'
+
+/** A `base-N` id, split into its base and ordinal. */
+const DUPLICATE_SUFFIX_RE = /^(.+)-(\d+)$/
+
+/**
+ * The two sides also disagree on where duplicate-heading numbering STARTS.
+ * For a document with two `## Setup` headings GitHub emits `setup` and
+ * `setup-1`, while `createHeadingIdDeduper` emits `setup` and `setup-2` (its
+ * suffix is the occurrence COUNT, not the offset). So a GitHub `#setup-1`
+ * needs our `setup-2` — every duplicate is off by exactly one.
+ *
+ * Runs LAST, after the exact lookup and the heading scan have both missed: a
+ * heading that genuinely slugs to `step-2` is resolved long before this, and
+ * the shift is the one pass that can match an id it was not asked for.
+ */
+function findDuplicateShifted(normalized: string, doc: Document): HTMLElement | null {
+  const parts = DUPLICATE_SUFFIX_RE.exec(normalized)
+  if (!parts) return null
+  const ordinal = Number(parts[2])
+  if (!Number.isSafeInteger(ordinal)) return null
+  return doc.getElementById(`${parts[1]}-${ordinal + 1}`)
+}
+
+/**
+ * Resolve a `#hash` id that no exact lookup matched, by comparing normalized
+ * forms. Returns `null` when nothing in the document matches, so the caller
+ * can leave the browser's default behavior alone rather than hijacking a
+ * click that was never ours to handle.
+ *
+ * Three passes, in order of how much they assume:
+ *   1. a single `getElementById` on the normalized id — catches the whole
+ *      emoji-hyphen family without walking the DOM;
+ *   2. a heading scan — catches ids whose own raw form normalizes differently
+ *      (e.g. `a---b`, from a title containing a literal ` - `);
+ *   3. the duplicate-heading shift (see `findDuplicateShifted`) — last,
+ *      because it is the only pass that resolves to an id the fragment did
+ *      not name.
+ */
+export function findAnchorElementByNormalizedId(
+  rawId: string,
+  doc: Document,
+): HTMLElement | null {
+  const normalized = normalizeAnchorId(rawId)
+  if (!normalized) return null
+
+  if (normalized !== rawId) {
+    const direct = doc.getElementById(normalized)
+    if (direct) return direct
+  }
+
+  for (const heading of Array.from(doc.querySelectorAll<HTMLElement>(HEADING_SELECTOR))) {
+    if (normalizeAnchorId(heading.id) === normalized) return heading
+  }
+
+  // Last: the shift would happily match an unrelated `x-3` for a `x-2` that
+  // has no heading at all, so it runs only once the scan has come up empty.
+  return findDuplicateShifted(normalized, doc)
+}

package/src/utils/content-href.ts

@@ -26,6 +26,9 @@
  *   })
  */
 
+import { canonicalContentRefType } from './list-url'
+import { byKey, getPlatformProductionUrl } from '../platform-domains'
+
 /**
  * Type → in-app route suffix. The public-hostable subset of the hub's
  * `PUBLIC_URL_PATHS` (`lib/utils/content-url-builder.ts`); the hub keeps
@@ -56,14 +59,32 @@ export const DEFAULT_CONTENT_SUFFIXES: Record<string, string> = {
  *  `identifier` (the primary-key id) + `externalUrl` (the canonical hub URL,
  *  from which the slug is recovered for in-app routing). */
 export interface ComposeContentUrlInput {
-  /** The content's documentType (e.g. `'product_release'`, `'blog_post'`). */
+  /** The content's CANONICAL documentType (e.g. `'product_release'`,
+   *  `'blog_post'`).
+   *
+   *  Rail-vocab aliases (`'blog_post_existing'`) must be canonicalized by the
+   *  caller via `canonicalContentRefType` BEFORE they reach the seam: a host
+   *  writes its `hostedTypes` / `suffixes` / `overrides` against the canonical
+   *  vocabulary, so an alias silently misses every one of them and falls
+   *  through to the default `<contentOrigin>/<type>/<id>` branch — which is how
+   *  the same blog post reached `/blog/<slug>` from one path and
+   *  `/blog_post_existing/<slug>` from another. */
   type: string
   /** Content identifier. Page views pass the slug; chat rows pass the
    *  primary-key id (the slug is recovered from `externalUrl` when hosted). */
   identifier: string
-  /** Hydrated platform junction (page views). Unused by the embedder default
-   *  — `hostedTypes` membership decides in-vs-out — but threaded for the hub
-   *  composer's cross-platform topology. */
+  /** Preferred path segment for HOSTED types when there is no `externalUrl`
+   *  to recover the slug from — the Mingo/NATS transport ships bare
+   *  `[card://type:id]` markers with no ref metadata, so a fetch-mode card
+   *  knows the row's slug only AFTER it loads the row. `identifier` must stay
+   *  the primary key (that is what `overrides` deep-link on), hence a separate
+   *  field rather than overloading it. Ignored for non-hosted types. */
+  slug?: string | null
+  /** Hydrated platform junction from the list APIs. `hostedTypes` membership
+   *  still decides in-app vs out; this decides WHICH origin an out-link points
+   *  at — an OpenMSP-owned row resolves to openmsp.ai, not to the embedder's
+   *  `contentOrigin`. Read only when `targetPlatform` is absent. Accepts the
+   *  three junction shapes the DALs produce (see `primaryPlatformOf`). */
   platforms?: Array<{ name?: string }>
   /** The canonical hub URL when the caller already has it (chat entity rows
    *  carry it from the RAG mapper). Hosted types relativize it to an in-app
@@ -78,8 +99,11 @@ export interface ContentHrefOptions {
   /** Types THIS host serves in-app → relative href (soft-nav). Everything
    *  else resolves to the row's `externalUrl` / `contentOrigin` (opens out). */
   hostedTypes: ReadonlySet<string>
-  /** Hub origin for non-hosted types with no `externalUrl` (e.g.
-   *  `https://openframe.app`). */
+  /** Fallback origin for non-hosted types with no `externalUrl` AND no
+   *  resolvable owning platform (e.g. `https://openframe.app`). When the row
+   *  DOES name its platform, that platform's canonical origin wins — otherwise
+   *  cross-platform content (an OpenMSP blog post) would be linked to the
+   *  wrong site. */
   contentOrigin: string
   /** Per-type route suffix. Defaults to {@link DEFAULT_CONTENT_SUFFIXES}. */
   suffixes?: Record<string, string>
@@ -95,6 +119,35 @@ export type ComposeContentUrl = (
   input: ComposeContentUrlInput,
 ) => { href: string; targetPlatform: string | null }
 
+/**
+ * Owning platform of a content row, from the hydrated junction the list APIs
+ * return. Mirrors the hub's `extractPrimaryPlatform` (`lib/utils/content-url-
+ * builder.ts`): the same junction arrives in three shapes depending on which
+ * DAL produced it, so all three are read.
+ *
+ *   1. `{ platforms: { name } }`  — raw Supabase row (rag-mappers)
+ *   2. `{ platform_name }`        — legacy pre-flattened admin endpoints
+ *   3. `{ name }`                 — modern flattened shape (blog / case-study utils)
+ *
+ * Returns the FIRST resolvable name; `null` when the junction is absent or
+ * carries no usable platform (caller then falls back to `contentOrigin`).
+ */
+function primaryPlatformOf(
+  platforms: ComposeContentUrlInput['platforms'],
+): string | null {
+  if (!Array.isArray(platforms)) return null
+  for (const entry of platforms) {
+    const row = entry as {
+      name?: unknown
+      platform_name?: unknown
+      platforms?: { name?: unknown }
+    }
+    const name = row?.platforms?.name ?? row?.platform_name ?? row?.name
+    if (typeof name === 'string' && name.trim()) return name.trim()
+  }
+  return null
+}
+
 /** Last non-empty path segment of a URL (relative or absolute) — the content
  *  slug of a canonical detail URL like `https://hub/releases/my-release`.
  *  Returns `null` on a malformed URL or empty path. */
@@ -127,7 +180,19 @@ function lastPathSegment(url: string): string | null {
  */
 export function makeComposeContentUrl(opts: ContentHrefOptions): ComposeContentUrl {
   const suffixes = opts.suffixes ?? DEFAULT_CONTENT_SUFFIXES
-  return ({ type, identifier, externalUrl, targetPlatform }) => {
+  return ({
+    type: rawType,
+    identifier,
+    slug: slugHint,
+    externalUrl,
+    targetPlatform,
+    platforms,
+  }) => {
+    // Defence in depth: callers are expected to hand over a canonical
+    // documentType (see `ComposeContentUrlInput.type`), but a stray alias must
+    // not silently produce a `<origin>/blog_post_existing/<slug>` URL. Same
+    // canonicalizer `buildListUrl` uses — one alias table, both paths.
+    const type = canonicalContentRefType(rawType)
     const override =
       opts.overrides && Object.prototype.hasOwnProperty.call(opts.overrides, type)
         ? opts.overrides[type]
@@ -143,15 +208,50 @@ export function makeComposeContentUrl(opts: ContentHrefOptions): ComposeContentU
       // segment is the type's OWN suffix (e.g. a malformed/list externalUrl like
       // `https://hub/releases/` → `'releases'`), fall back to `identifier` instead
       // of emitting a nonsensical `/releases/releases`.
+      //
+      // `slug` (the explicit hint) sits between the two: a Mingo fetch-mode card
+      // has NO externalUrl to recover from but DOES know the row's slug once it
+      // loads, and its `identifier` must stay the primary key so `overrides`
+      // still deep-link correctly.
       const recovered = externalUrl ? lastPathSegment(externalUrl) : null
-      const slug = recovered && recovered !== seg ? recovered : identifier
+      const slug =
+        recovered && recovered !== seg ? recovered : (slugHint?.trim() || identifier)
       return { href: `/${seg}/${slug}`, targetPlatform: null }
     }
-    // Not hosted → opens out. Prefer the RAG-authoritative `externalUrl` (chat);
-    // else compose against the hub origin (page views with no externalUrl).
-    return externalUrl
-      ? { href: externalUrl, targetPlatform: targetPlatform ?? null }
-      : { href: `${opts.contentOrigin}/${seg}/${identifier}`, targetPlatform: null }
+    // Not hosted → opens out. Prefer the RAG-authoritative `externalUrl` (chat).
+    if (externalUrl) return { href: externalUrl, targetPlatform: targetPlatform ?? null }
+
+    // No externalUrl → compose it. The destination is the origin of the
+    // platform that OWNS the row, not a fixed hub: an OpenMSP blog post lives
+    // on openmsp.ai, and pinning every non-hosted type to `contentOrigin` sent
+    // it to flamingo.run (a 404 / wrong site). Owner comes from the explicit
+    // `targetPlatform`, else the hydrated platforms junction — mirroring the
+    // hub's `composeContentUrlFromPlatforms` + `extractPrimaryPlatform`.
+    // Origins resolve through the platform-domain SSOT (env override → default
+    // production URL), so a per-deploy `NEXT_PUBLIC_*_URL` is honoured here too.
+    //
+    // `contentOrigin` stays the fallback for rows with no resolvable owner and
+    // for platform names the registry doesn't know — an embedder's explicit
+    // configuration must win over the registry's flamingo default.
+    // Only a REGISTRY-RESOLVED owner counts. An unknown name (a platform the
+    // registry doesn't carry) falls back to `contentOrigin` for the href, and
+    // reporting it as the `targetPlatform` anyway made the two disagree:
+    // `decideNewTab` prefers `targetPlatform` over its origin check, so a link
+    // pointing at the CURRENT host opened in a new tab.
+    const claimedOwner = targetPlatform ?? primaryPlatformOf(platforms)
+    const owner = claimedOwner && byKey(claimedOwner) ? claimedOwner : null
+    const origin = owner ? getPlatformProductionUrl(owner) : opts.contentOrigin
+    // The hub's public detail routes are SLUG-based, so the `slug` hint wins
+    // over `identifier` here too — a Mingo fetch-mode card knows the row's slug
+    // but its `identifier` is the marker's primary key, which would 404.
+    return {
+      href: `${origin.replace(/\/+$/, '')}/${seg}/${slugHint?.trim() || identifier}`,
+      // Report the owner so `decideNewTab` can compare it against the current
+      // app instead of falling back to an origin guess (which is unreliable in
+      // dev, where every platform shares localhost). `null` whenever the href
+      // came from `contentOrigin`, so the two never disagree.
+      targetPlatform: owner,
+    }
   }
 }
 

package/src/utils/index.ts

@@ -299,6 +299,14 @@ export {
   type NavigateSamePageHashOptions,
 } from './same-page-hash-nav'
 
+// GitHub-compatible anchor resolution. Doc TOCs are authored against
+// GitHub's slugger (`## 📚 Table of Contents` → `#-table-of-contents`)
+// while our heading ids trim the emoji's leftover hyphen — this bridges
+// that without changing the id shape the "On this page" rail and every
+// shared URL already depend on. Consumers resolving a hash want
+// `getHashTargetElement` (above), which applies this as its last pass.
+export { findAnchorElementByNormalizedId, normalizeAnchorId } from './anchor-id'
+
 // Shared list-API URL builder — the single source for the per-type chat
 // entity-card fetch shapes. The hub's 12 RAG mapper `listApi` closures
 // delegate here (byte-parity test guards the migration); embedders wire

package/src/utils/list-url.ts

@@ -43,7 +43,12 @@ const ALIASES: Record<string, string> = { blog_post_existing: 'blog_post' }
  *  registry entityTypes (e.g. the related-content rail's same-type-first
  *  ordering) share THIS alias map instead of re-declaring it. */
 export function canonicalContentRefType(contentRefType: string): string {
-  return ALIASES[contentRefType] ?? contentRefType
+  // `hasOwnProperty` guard, same as `buildListUrl` below: a bare index read
+  // resolves prototype keys, so `canonicalContentRefType('constructor')`
+  // returned `Object` itself — which then got interpolated into a URL path.
+  return Object.prototype.hasOwnProperty.call(ALIASES, contentRefType)
+    ? ALIASES[contentRefType]
+    : contentRefType
 }
 
 /**

package/src/utils/same-page-hash-nav.ts

@@ -1,4 +1,5 @@
 import { scrollElementIntoView } from './scroll-into-view'
+import { findAnchorElementByNormalizedId } from './anchor-id'
 
 /** Pages with a section-nav STRIP on top of the global hub header
  *  (dev-center roadmap/delivery/tickets, FAQ category-pill nav).
@@ -24,24 +25,42 @@ export function normalizeHashFragment(hash: string): string {
 }
 
 /**
- * Resolve the DOM element a hash fragment id points at. Tries the raw
- * id first (ordinary anchors), then the percent-decoded form — href
- * composers like `buildTicketOpenHref` encode the id into the fragment
- * while rows render the raw id, so `#ticket-a%2Fb` must still find
- * `id="ticket-a/b"`. A malformed escape sequence falls back to the
- * raw lookup result.
+ * Resolve the DOM element a hash fragment id points at — THE hash resolver;
+ * `navigateSamePageHash`, `useScrollToHash` and the markdown link renderer
+ * all go through this one, so a fragment that resolves for a deep link
+ * resolves for an in-body click too.
+ *
+ * Three passes, cheapest first:
+ *   1. the raw id (ordinary anchors — the overwhelming common case);
+ *   2. the percent-decoded form — href composers like `buildTicketOpenHref`
+ *      encode the id into the fragment while rows render the raw id, so
+ *      `#ticket-a%2Fb` must still find `id="ticket-a/b"`. A malformed escape
+ *      sequence just falls through;
+ *   3. a NORMALIZED match against the document's headings — doc bodies are
+ *      authored on GitHub, whose slugger keeps the hyphen left behind by a
+ *      stripped emoji (`## 📚 Table of Contents` → `#-table-of-contents`)
+ *      while our ids trim it. Without this every in-body TOC link in every
+ *      GitHub-authored doc resolves to nothing and clicking one does nothing.
+ *      See `utils/anchor-id`.
  */
 export function getHashTargetElement(id: string): HTMLElement | null {
   if (!id) return null
   const direct = document.getElementById(id)
   if (direct) return direct
+
+  let decoded = id
   try {
-    const decoded = decodeURIComponent(id)
-    if (decoded !== id) return document.getElementById(decoded)
+    decoded = decodeURIComponent(id)
+    if (decoded !== id) {
+      const decodedEl = document.getElementById(decoded)
+      if (decodedEl) return decodedEl
+    }
   } catch {
     // malformed escape — the raw lookup above already covered it
+    decoded = id
   }
-  return null
+
+  return findAnchorElementByNormalizedId(decoded, document)
 }
 
 export interface NavigateSamePageHashOptions {