@tokenoftrust/storefront-runner 2.0.41 → 2.0.43

package/packages/public-runtime/src/image-dependencies.ts

@@ -0,0 +1,1438 @@
+import { transform, transformStyleAttribute, type CustomAtRules, type Declaration, type Image, type TokenOrValue, type Url, type Visitor } from "lightningcss";
+import { parseFragment, type DefaultTreeAdapterMap } from "parse5";
+
+/**
+ * Provider-neutral image dependency discovery and classification.
+ *
+ * This module is deliberately pure: it turns already-read artifact text into a
+ * capture plan plus a sanitized finding batch. Network capture, persistence,
+ * and lifecycle state belong to control-plane adapters. Keeping one extractor
+ * here prevents HTML, CSS, catalog, and migrated-blog paths from silently
+ * disagreeing about which image references exist.
+ *
+ * Raw locators are present only in `dependencies`/`captureCandidates`, which are
+ * effect inputs. `findings` and `warningBatch` are the operator-visible contract
+ * and never include locators, tenant ids, artifact paths, query strings, or
+ * content digests.
+ */
+
+export type ImageArtifactKind = "html" | "css" | "catalog";
+export type ImageReferenceSurface =
+  | "html-src"
+  | "html-srcset"
+  | "html-metadata"
+  | "css-url"
+  | "catalog";
+
+export interface ImageDependencyArtifact {
+  /** Used only for relative-path containment; never copied into a finding. */
+  path: string;
+  content: string;
+  kind?: ImageArtifactKind;
+}
+
+export interface PlatformHostedImageConfig {
+  /** Exact already-hosted references. Query/fragment spelling is ignored. */
+  references?: readonly string[];
+  /** Absolute origins whose image bytes are platform-hosted. */
+  origins?: readonly string[];
+  /** Root-absolute platform namespaces in addition to the built-in ones. */
+  pathPrefixes?: readonly string[];
+}
+
+export interface ImageDependencyScanOptions {
+  tenantId: string;
+  platformHosted?: PlatformHostedImageConfig;
+}
+
+export type ImageDependencyDisposition =
+  | "platform-hosted"
+  | "tenant-hosted"
+  | "inline"
+  | "capture-required"
+  | "security-error"
+  | "deferred";
+
+export type ImageDependencyReason =
+  | "third-party"
+  | "local"
+  | "cross-tenant"
+  | "tenant-escape"
+  | "unsafe-scheme"
+  | "malformed"
+  | "unsupported";
+
+/** Internal/effect-facing dependency. Its locator must never be rendered. */
+export interface ImageDependency {
+  locator: string;
+  canonicalLocator: string;
+  artifactIndex: number;
+  occurrence: number;
+  surface: ImageReferenceSurface;
+  disposition: ImageDependencyDisposition;
+  reason?: ImageDependencyReason;
+}
+
+export interface ImageDependencyFinding {
+  /** Stable within an exact ordered artifact revision; contains no content-derived data. */
+  id: string;
+  code: "image-capture-required" | "image-reference-security" | "image-reference-deferred";
+  reason: ImageDependencyReason;
+  occurrences: number;
+  authoring: "warning" | "non-overridable-security-error";
+  /** Hosted preview is the capture verb and therefore the enforcement point. */
+  hostedPreview: "overridable-quality-error" | "non-overridable-security-error";
+  overridable: boolean;
+  message: string;
+}
+
+export interface ImageDependencyWarningBatch {
+  code: "image-dependency-batch";
+  total: number;
+  captureRequired: number;
+  securityErrors: number;
+  /** CSS image forms skipped whole. Not part of captureRequired or securityErrors. */
+  deferred: number;
+  representedFindings: number;
+  omittedFindings: number;
+  /** Bounded, sanitized copy; never one line per reference. */
+  messages: string[];
+}
+
+export interface ImageDependencyScan {
+  census: {
+    references: number;
+    platformHosted: number;
+    tenantHosted: number;
+    inline: number;
+    captureRequired: number;
+    securityErrors: number;
+    deferred: number;
+  };
+  dependencies: ImageDependency[];
+  /** De-duplicated raw effect inputs. URL provenance is not byte identity. */
+  captureCandidates: Array<{
+    locator: string;
+    canonicalLocator: string;
+    reason: "third-party" | "local";
+    /** A locator is provenance only; capture must derive identity from fetched original bytes. */
+    identityAuthority: "original-image-bytes";
+  }>;
+  findings: ImageDependencyFinding[];
+  warningBatch: ImageDependencyWarningBatch | null;
+}
+
+interface ExtractedReference {
+  locator: string;
+  surface: ImageReferenceSurface;
+  classificationLocator?: string;
+  /** Set only for HTML references that appear after the document's first base href. */
+  afterBase?: boolean;
+  /** Set when the reference is a skipped CSS image function, not an authored URL. */
+  deferredFunction?: "var" | "env" | "cross-fade";
+}
+
+/** Properties whose value includes an image. Unparsed var()/env()/cross-fade() anywhere in them is deferred. */
+const IMAGE_VALUE_PROPERTIES = new Set([
+  "background",
+  "background-image",
+  "border-image",
+  "border-image-source",
+  "content",
+  "cursor",
+  "list-style",
+  "list-style-image",
+  "mask",
+  "mask-border",
+  "mask-border-source",
+  "mask-box-image",
+  "mask-box-image-source",
+  "mask-image",
+  "shape-outside",
+]);
+
+const DEFERRED_IMAGE_MESSAGE = "A CSS image form was skipped because hosted preview does not resolve it yet.";
+
+const BUILTIN_PLATFORM_PREFIXES = ["/_astro/", "/shared/"] as const;
+const DIRECT_IMAGE_KEY_RE = /^(?:image|images|featuredimage|featured_image|thumbnail|thumbnailurl|imageurl|image_url)$/i;
+const SCALAR_IMAGE_KEY_RE = /^(?:thumbnailurl|imageurl|image_url)$/i;
+const HTML_VALUE_KEYS = new Set(["contenthtml", "content_html", "descriptionhtml", "description_html", "html"]);
+const NON_IMAGE_ASSET_RE = /\.(?:css|m?js|woff2?|ttf|otf|eot|map|json|xml|txt|pdf|mp4|webm|mov)$/i;
+const CONTROL_RE = /[\u0000-\u001f\u007f]/;
+const URL_TAB_OR_NEWLINE_RE = /[\t\n\r]/g;
+const ASCII_WHITESPACE_RE = /[\t\n\f\r ]/;
+const ASCII_WHITESPACE_RUN_RE = /[\t\n\f\r ]+/;
+const MAX_VISIBLE_FINDINGS = 100;
+const MAX_PERCENT_DECODE_PASSES = 8;
+const MAX_CATALOG_WALK_ITEMS = 1_000_000;
+const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
+const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+const CSS_FILENAME = "artifact.css";
+const textEncoder = new TextEncoder();
+
+type HtmlNode = DefaultTreeAdapterMap["node"];
+type HtmlElement = DefaultTreeAdapterMap["element"];
+type HtmlChild = DefaultTreeAdapterMap["childNode"];
+
+function inferKind(artifact: ImageDependencyArtifact): ImageArtifactKind {
+  if (artifact.kind) return artifact.kind;
+  const path = artifact.path.toLowerCase().split(/[?#]/, 1)[0] ?? "";
+  if (path.endsWith(".css")) return "css";
+  if (path.endsWith(".html") || path.endsWith(".htm")) return "html";
+  return "catalog";
+}
+
+function isAsciiWhitespace(value: string | undefined): boolean {
+  return value != null && ASCII_WHITESPACE_RE.test(value);
+}
+
+function trimAsciiWhitespace(value: string): string {
+  return value.replace(/^[\t\n\f\r ]+|[\t\n\f\r ]+$/g, "");
+}
+
+function isC0ControlOrSpace(code: number): boolean {
+  return code <= 0x1f || code === 0x20;
+}
+
+/** WHATWG basic URL parser: drop leading and trailing C0 controls and spaces, then ASCII tab and newline anywhere. An interior form feed stays. */
+function normalizeUrlInput(value: string): string {
+  let start = 0;
+  let end = value.length;
+  while (start < end && isC0ControlOrSpace(value.charCodeAt(start))) start += 1;
+  while (end > start && isC0ControlOrSpace(value.charCodeAt(end - 1))) end -= 1;
+  return value.slice(start, end).replace(URL_TAB_OR_NEWLINE_RE, "");
+}
+
+function isHtmlText(node: HtmlNode): node is DefaultTreeAdapterMap["textNode"] {
+  return node.nodeName === "#text";
+}
+
+function isHtmlElement(node: HtmlNode): node is HtmlElement {
+  return node.nodeName !== "#text"
+    && node.nodeName !== "#comment"
+    && node.nodeName !== "#documentType"
+    && node.nodeName !== "#document"
+    && node.nodeName !== "#document-fragment";
+}
+
+function htmlAttribute(element: HtmlElement, name: string): string | null {
+  for (const candidate of element.attrs) {
+    if (candidate.name === name || candidate.name.toLowerCase() === name) return candidate.value;
+  }
+  return null;
+}
+
+const SRCSET_FLOAT_RE = /^-?(?:(?:[0-9]+|[0-9]*\.[0-9]+)(?:[eE][+-]?[0-9]+)?|[0-9]*\.[eE][+-]?[0-9]+)$/;
+const SRCSET_MAX_INTEGER = 0x7fffffff;
+
+function srcsetDensityValue(value: string): number {
+  if (value.startsWith("-.")) return Number(`-0${value.slice(1)}`);
+  if (value.startsWith(".")) return Number(`0${value}`);
+  return Number(value);
+}
+
+function validSrcsetDescriptors(descriptors: readonly string[]): boolean {
+  let width = false;
+  let density = false;
+  let height = false;
+  for (const descriptor of descriptors) {
+    const suffix = descriptor.at(-1);
+    const number = descriptor.slice(0, -1);
+    if (suffix === "w" && /^\d+$/.test(number)) {
+      const value = Number(number);
+      if (width || density || value === 0 || value > SRCSET_MAX_INTEGER) return false;
+      width = true;
+    } else if (suffix === "x" && SRCSET_FLOAT_RE.test(number)) {
+      const value = srcsetDensityValue(number);
+      if (width || density || height || value < 0 || !Number.isFinite(value)) return false;
+      density = true;
+    } else if (suffix === "h" && /^\d+$/.test(number)) {
+      const value = Number(number);
+      if (height || density || value === 0 || value > SRCSET_MAX_INTEGER) return false;
+      height = true;
+    } else {
+      return false;
+    }
+  }
+  return !height || width;
+}
+
+interface SrcsetEntry {
+  locator: string;
+  descriptors: string[];
+}
+
+function srcsetEntries(value: string): SrcsetEntry[] {
+  const entries: SrcsetEntry[] = [];
+  let cursor = 0;
+  while (cursor < value.length) {
+    while (cursor < value.length && (isAsciiWhitespace(value[cursor]) || value[cursor] === ",")) cursor++;
+    if (cursor >= value.length) break;
+    const start = cursor;
+    while (cursor < value.length && !isAsciiWhitespace(value[cursor])) cursor++;
+    let locator = value.slice(start, cursor);
+    const trailingCommas = locator.match(/,+$/)?.[0].length ?? 0;
+    if (trailingCommas) locator = locator.slice(0, -trailingCommas);
+    if (trailingCommas) {
+      if (locator) entries.push({ locator, descriptors: [] });
+      continue;
+    }
+    const descriptors: string[] = [];
+    let descriptor = "";
+    let inParens = false;
+    while (cursor < value.length) {
+      const char = value[cursor]!;
+      if (char === "(" && !inParens) inParens = true;
+      else if (char === ")" && inParens) inParens = false;
+      if ((isAsciiWhitespace(char) || char === ",") && !inParens) {
+        if (descriptor) {
+          descriptors.push(descriptor);
+          descriptor = "";
+        }
+        if (char === ",") { cursor++; break; }
+        cursor++;
+        continue;
+      }
+      descriptor += char;
+      cursor++;
+    }
+    if (descriptor) descriptors.push(descriptor);
+    if (locator && validSrcsetDescriptors(descriptors)) entries.push({ locator, descriptors });
+  }
+  return entries;
+}
+
+function srcsetLocators(value: string): string[] {
+  return srcsetEntries(value).map((entry) => entry.locator);
+}
+
+function srcsetDensity(descriptors: readonly string[]): number | null {
+  if (descriptors.length === 0) return 1;
+  for (const descriptor of descriptors) {
+    if (descriptor.endsWith("x")) return srcsetDensityValue(descriptor.slice(0, -1));
+  }
+  return null;
+}
+
+function srcsetWidth(descriptors: readonly string[]): number | null {
+  for (const descriptor of descriptors) {
+    if (descriptor.endsWith("w")) return Number(descriptor.slice(0, -1));
+  }
+  return null;
+}
+
+type PreloadChoice =
+  | { kind: "href" }
+  | { kind: "none" }
+  | { kind: "urls"; locators: string[] };
+
+function choosePreloadImage(imagesrcset: string, href: string | null, _imagesizes: string | null): PreloadChoice {
+  const entries = srcsetEntries(imagesrcset).map((entry, index) => ({
+    locator: entry.locator,
+    density: srcsetDensity(entry.descriptors),
+    width: srcsetWidth(entry.descriptors),
+    index,
+  }));
+  if (entries.length === 0) return { kind: "href" };
+  if (entries.some((entry) => entry.width != null)) {
+    const locators = entries
+      .filter((entry) => !isFragmentOnlyLocator(entry.locator))
+      .map((entry) => entry.locator);
+    return locators.length === 0 ? { kind: "none" } : { kind: "urls", locators };
+  }
+  const densities = entries.filter((entry) => entry.density != null).map((entry) => ({
+    locator: entry.locator,
+    density: entry.density!,
+    index: entry.index,
+  }));
+  if (!densities.some((entry) => entry.density === 1) && href != null) {
+    densities.push({ locator: href, density: 1, index: entries.length });
+  }
+  if (densities.length === 0) return { kind: "href" };
+  const atLeastOne = densities.filter((entry) => entry.density >= 1);
+  const pool = atLeastOne.length > 0 ? atLeastOne : densities;
+  pool.sort((left, right) => atLeastOne.length > 0
+    ? left.density - right.density || left.index - right.index
+    : right.density - left.density || left.index - right.index);
+  const selected = pool[0]!.locator;
+  return isFragmentOnlyLocator(selected) ? { kind: "none" } : { kind: "urls", locators: [selected] };
+}
+
+function isBlankLocator(locator: string): boolean {
+  return trimAsciiWhitespace(locator).length === 0;
+}
+
+function isFragmentOnlyLocator(locator: string): boolean {
+  return trimAsciiWhitespace(locator).startsWith("#");
+}
+
+function isNonImageDataUrl(locator: string): boolean {
+  return /^data:(?!image\/)/i.test(trimAsciiWhitespace(locator));
+}
+
+function isNonImageAsset(locator: string): boolean {
+  return NON_IMAGE_ASSET_RE.test(stripQueryHash(trimAsciiWhitespace(locator)));
+}
+
+function rememberImageLocator(
+  refs: ExtractedReference[],
+  locator: string,
+  surface: ImageReferenceSurface,
+  afterBase = false,
+): void {
+  const normalized = normalizeUrlInput(locator);
+  if (isBlankLocator(normalized) || isFragmentOnlyLocator(normalized)) return;
+  refs.push(afterBase ? { locator: normalized, surface, afterBase: true } : { locator: normalized, surface });
+}
+
+function rememberCssLocator(refs: ExtractedReference[], locator: string): boolean {
+  // WHATWG drops leading and trailing C0 controls, then tab and newline anywhere.
+  // CSS \9, \A, and \D arrive as those characters; normalize before the data-URL and extension filters.
+  const normalized = normalizeUrlInput(locator);
+  if (isBlankLocator(normalized) || isFragmentOnlyLocator(normalized) || isNonImageDataUrl(normalized) || isNonImageAsset(normalized)) return false;
+  refs.push({ locator: normalized, surface: "css-url" });
+  return true;
+}
+
+function urlLocationKey(url: Url): string {
+  return `${url.loc.line}:${url.loc.column}`;
+}
+
+function cssFunctionName(name: string): string {
+  return name.toLowerCase();
+}
+
+function declarationPropertyName(declaration: Declaration): string {
+  // Custom properties keep author case. Image properties match case-insensitively.
+  const name = declaration.property === "unparsed"
+    ? declaration.value.propertyId.property
+    : declaration.property === "custom"
+      ? String(declaration.value.name)
+      : declaration.property;
+  return name.toLowerCase();
+}
+
+/** Quoted URL() / uRl() inside an unparsed image() is a nested function. Its source is the first string. */
+function quotedUrlFunctionLocator(nodes: readonly TokenOrValue[]): string | null {
+  for (const argument of nodes) {
+    if (argument.type === "token" && argument.value.type === "string") return String(argument.value.value);
+  }
+  return null;
+}
+
+function suppressImageFunctionUrls(
+  nodes: readonly TokenOrValue[],
+  locations: Set<string>,
+  walkVariableFallbacks = false,
+): void {
+  for (const argument of nodes) {
+    if (argument.type === "url") {
+      locations.add(urlLocationKey(argument.value));
+      continue;
+    }
+    if (argument.type === "function") {
+      suppressImageFunctionUrls(argument.value.arguments, locations, walkVariableFallbacks);
+      continue;
+    }
+    // image-set suppression stays on nested functions. image() also suppresses var()/env() fallback urls.
+    if (!walkVariableFallbacks || (argument.type !== "var" && argument.type !== "env")) continue;
+    const fallback = argument.value.fallback;
+    if (fallback) suppressImageFunctionUrls(fallback, locations, true);
+  }
+}
+
+/** url() nodes nested in an unparsed image-set option are not that option. Direct url() arguments stay visible. */
+function suppressNestedFunctionUrls(nodes: readonly TokenOrValue[], locations: Set<string>): void {
+  for (const argument of nodes) {
+    if (argument.type === "function") suppressImageFunctionUrls(argument.value.arguments, locations);
+  }
+}
+
+function deferredFunctionName(name: string): "var" | "env" | "cross-fade" | null {
+  const normalized = cssFunctionName(name);
+  if (normalized === "var" || normalized === "env") return normalized;
+  // -webkit-cross-fade is cross-fade. Any vendor prefix stays unresolved.
+  if (normalized === "cross-fade" || /^-[a-z]+-cross-fade$/.test(normalized)) return "cross-fade";
+  return null;
+}
+
+function rememberDeferred(refs: ExtractedReference[], name: "var" | "env" | "cross-fade"): void {
+  refs.push({ locator: `css-function:${name}`, surface: "css-url", deferredFunction: name });
+}
+
+/** One kept locator. type(), format(), and a discarded non-image do not consume it. var(), env(), and cross-fade() consume it without walking children. Nested image() keeps its own one source. */
+function recordImageFunctionSource(refs: ExtractedReference[], nodes: readonly TokenOrValue[]): boolean {
+  for (const argument of nodes) {
+    if (argument.type === "url") {
+      if (rememberCssLocator(refs, argument.value.url)) return true;
+      continue;
+    }
+    if (argument.type === "token" && argument.value.type === "string") {
+      if (rememberCssLocator(refs, String(argument.value.value))) return true;
+      continue;
+    }
+    // The visitor records the deferred dependency. Children are not a source.
+    if (argument.type === "var" || argument.type === "env") return true;
+    if (argument.type !== "function") continue;
+    const name = cssFunctionName(argument.value.name);
+    if (name === "url") {
+      const locator = quotedUrlFunctionLocator(argument.value.arguments);
+      if (locator != null && rememberCssLocator(refs, locator)) return true;
+      continue;
+    }
+    // MIME tags, not image sources. Recursing would keep "image/png" and consume the one slot.
+    if (name === "type" || name === "format") continue;
+    if (deferredFunctionName(name)) return true;
+    if (recordImageFunctionSource(refs, argument.value.arguments)) return true;
+  }
+  return false;
+}
+
+function adoptCssReferences(refs: ExtractedReference[], cssRefs: readonly ExtractedReference[], afterBase: boolean): void {
+  for (const ref of cssRefs) refs.push(afterBase ? { ...ref, afterBase: true } : ref);
+}
+
+function rememberCssImage(refs: ExtractedReference[], image: Image): void {
+  if (image.type === "url") {
+    rememberCssLocator(refs, image.value.url);
+    return;
+  }
+  if (image.type !== "image-set") return;
+  for (const option of image.value.options) rememberCssImage(refs, option.image);
+}
+
+function cssReferences(css: string, kind: "stylesheet" | "declaration"): ExtractedReference[] {
+  if (!css) return [];
+  const refs: ExtractedReference[] = [];
+  const fontFaceUrls: string[] = [];
+  // url() nodes anywhere inside image() are still walked by the Url visitor after Function.
+  // The visitor rebuilds a fresh object per callback, so identity can't dedupe — key on source
+  // position, which is stable for the same node. One image() keeps one source; the rest stay suppressed.
+  const imageFunctionUrlLocations = new Set<string>();
+  // Function enter runs before children. "image" means this image() recorded its one source;
+  // a nested image() visit must not record again. "image-set" means a direct string token is an option.
+  // "deferred" is var(), env(), or cross-fade(): their children are not resolved.
+  const frames: Array<"image" | "image-set" | "deferred" | "skip"> = [];
+  let valueDeferDepth = 0;
+  const propertyStack: string[] = [];
+  const deferredOpen = (): boolean => valueDeferDepth > 0 || frames.includes("deferred");
+  const inImageValue = (): boolean => {
+    if (frames.includes("image") || frames.includes("image-set")) return true;
+    const property = propertyStack.at(-1);
+    return property != null && IMAGE_VALUE_PROPERTIES.has(property);
+  };
+  const noteDeferred = (name: "var" | "env" | "cross-fade"): void => {
+    if (!deferredOpen() && inImageValue()) rememberDeferred(refs, name);
+  };
+  const visitor: Visitor<CustomAtRules> = {
+    Declaration(declaration) {
+      propertyStack.push(declarationPropertyName(declaration));
+    },
+    DeclarationExit() {
+      propertyStack.pop();
+    },
+    Rule: {
+      "font-face"(rule) {
+        for (const property of rule.value.properties) {
+          if (property.type !== "source") continue;
+          for (const source of property.value) {
+            if (source.type === "url") fontFaceUrls.push(source.value.url.url);
+          }
+        }
+      },
+    },
+    Url(url) {
+      if (imageFunctionUrlLocations.has(urlLocationKey(url))) return;
+      if (fontFaceUrls[0] === url.url) {
+        fontFaceUrls.shift();
+        return;
+      }
+      if (deferredOpen()) return;
+      rememberCssLocator(refs, url.url);
+    },
+    Image(image) {
+      if (deferredOpen()) return;
+      if (image.type === "image-set") rememberCssImage(refs, image);
+    },
+    Token: {
+      string(token) {
+        if (deferredOpen()) return;
+        if (frames.at(-1) !== "image-set") return;
+        rememberCssLocator(refs, String(token.value));
+      },
+    },
+    Variable() {
+      noteDeferred("var");
+      valueDeferDepth++;
+    },
+    VariableExit() {
+      valueDeferDepth--;
+    },
+    EnvironmentVariable() {
+      noteDeferred("env");
+      valueDeferDepth++;
+    },
+    EnvironmentVariableExit() {
+      valueDeferDepth--;
+    },
+    // image() stays unparsed. Quoted URL()/uRl() is a nested function, not argument type "url".
+    // image-set() with a string or image() option stays unparsed too; its string options are tokens.
+    // Lowercase var() and env() are not functions; VAR()/ENV() are. cross-fade(), including a vendor prefix, is always a function.
+    Function(fn) {
+      const deferred = deferredFunctionName(fn.name);
+      if (deferred) {
+        noteDeferred(deferred);
+        frames.push("deferred");
+        return;
+      }
+      if (deferredOpen()) {
+        frames.push("skip");
+        return;
+      }
+      const name = cssFunctionName(fn.name);
+      if (name === "image") {
+        if (frames.includes("image")) {
+          frames.push("skip");
+          return;
+        }
+        frames.push("image");
+        suppressImageFunctionUrls(fn.arguments, imageFunctionUrlLocations, true);
+        recordImageFunctionSource(refs, fn.arguments);
+        return;
+      }
+      if ((name === "image-set" || name === "-webkit-image-set") && !frames.includes("image")) {
+        frames.push("image-set");
+        suppressNestedFunctionUrls(fn.arguments, imageFunctionUrlLocations);
+        return;
+      }
+      if (name === "url" && frames.at(-1) === "image-set") {
+        const locator = quotedUrlFunctionLocator(fn.arguments);
+        if (locator != null) rememberCssLocator(refs, locator);
+      }
+      frames.push("skip");
+    },
+    FunctionExit() {
+      frames.pop();
+    },
+  };
+  const code = textEncoder.encode(css);
+  try {
+    if (kind === "declaration") {
+      transformStyleAttribute({ filename: CSS_FILENAME, code, errorRecovery: true, visitor });
+    } else {
+      transform({ filename: CSS_FILENAME, code, errorRecovery: true, visitor });
+    }
+  } catch {
+    return refs;
+  }
+  return refs;
+}
+
+const LOCAL_REFERENCE_ORIGIN = "https://local.invalid";
+const ALTERNATE_LOCAL_REFERENCE_ORIGIN = "https://alternate-local.invalid";
+
+function localArtifactUrl(artifactPath: string, origin = LOCAL_REFERENCE_ORIGIN): URL | null {
+  try {
+    const safeArtifactPath = artifactPath.replace(/\\/g, "/").replace(/[?#]/g, (character) => encodeURIComponent(character));
+    return new URL(safeArtifactPath, `${origin}/`);
+  } catch {
+    return null;
+  }
+}
+
+type ResolvedBase = { base: URL; alternateBase: URL | null };
+
+type HtmlBaseResolution =
+  | { kind: "none" }
+  | { kind: "resolved"; base: URL; alternateBase: URL | null }
+  | { kind: "invalid" };
+
+function effectiveHtmlBase(baseHref: string | null, artifactPath: string, inherited: ResolvedBase | null = null): HtmlBaseResolution {
+  const fallback = inherited?.base ?? localArtifactUrl(artifactPath);
+  const alternateFallback = inherited ? inherited.alternateBase : localArtifactUrl(artifactPath, ALTERNATE_LOCAL_REFERENCE_ORIGIN);
+  if (!fallback || (!inherited && !alternateFallback)) return { kind: "invalid" };
+  if (baseHref == null) return { kind: "none" };
+  const href = normalizeUrlInput(baseHref);
+  if (CONTROL_RE.test(href)) return { kind: "invalid" };
+  try {
+    const base = new URL(href, fallback);
+    const alternateBase = alternateFallback ? new URL(href, alternateFallback) : null;
+    new URL("x", base);
+    if (alternateBase) new URL("x", alternateBase);
+    return { kind: "resolved", base, alternateBase: alternateBase && base.href !== alternateBase.href ? alternateBase : null };
+  } catch {
+    return { kind: "invalid" };
+  }
+}
+
+function resolveHtmlReference(locator: string, base: URL, alternateBase: URL | null): string {
+  const href = normalizeUrlInput(locator);
+  if (!href || CONTROL_RE.test(href)) return locator;
+  try {
+    const resolved = new URL(href, base);
+    const alternateResolved = alternateBase ? new URL(href, alternateBase) : null;
+    if (resolved.origin === LOCAL_REFERENCE_ORIGIN && alternateResolved && alternateResolved.href !== resolved.href) {
+      return `${resolved.pathname}${resolved.search}${resolved.hash}`;
+    }
+    return resolved.toString();
+  } catch {
+    return locator;
+  }
+}
+
+function resolvedBase(baseHref: string | null, sawBase: boolean, artifactPath: string, inherited: ResolvedBase | null): ResolvedBase | null {
+  if (!sawBase || baseHref == null) return inherited;
+  const own = effectiveHtmlBase(baseHref, artifactPath, inherited);
+  if (own.kind === "resolved") return { base: own.base, alternateBase: own.alternateBase };
+  return inherited;
+}
+
+function applyHtmlBase(
+  refs: ExtractedReference[],
+  baseHref: string | null,
+  artifactPath: string,
+  inherited: ResolvedBase | null,
+): ExtractedReference[] {
+  const own = baseHref == null ? null : effectiveHtmlBase(baseHref, artifactPath, inherited);
+  const ownBase = own?.kind === "resolved" ? own : null;
+  return refs.map((reference) => {
+    if (reference.deferredFunction) return reference;
+    if (reference.afterBase && ownBase) {
+      return { ...reference, locator: resolveHtmlReference(reference.locator, ownBase.base, ownBase.alternateBase) };
+    }
+    if (inherited && (!reference.afterBase || !ownBase)) {
+      return { ...reference, locator: resolveHtmlReference(reference.locator, inherited.base, inherited.alternateBase) };
+    }
+    return reference;
+  });
+}
+
+type HtmlSourceContext = "picture" | null;
+
+interface HtmlWalkFrame {
+  node: HtmlNode;
+  inTemplate: boolean;
+  cssText: boolean;
+  sourceContext: HtmlSourceContext;
+}
+
+function pushHtmlChildren(
+  stack: HtmlWalkFrame[],
+  children: readonly HtmlChild[],
+  inTemplate: boolean,
+  cssText: boolean,
+  sourceContext: HtmlSourceContext,
+): void {
+  for (let index = children.length - 1; index >= 0; index--) {
+    const child = children[index]!;
+    stack.push({ node: child, inTemplate, cssText: cssText && child.nodeName === "#text", sourceContext });
+  }
+}
+
+function childSourceContext(tag: string, namespace: string): HtmlSourceContext {
+  if (namespace === HTML_NAMESPACE && tag === "picture") return "picture";
+  return null;
+}
+
+function collectHtmlElement(
+  element: HtmlElement,
+  refs: ExtractedReference[],
+  inTemplate: boolean,
+  noteBase: (href: string) => void,
+  afterBase: boolean,
+  sourceContext: HtmlSourceContext,
+  artifactPath: string,
+  inheritedBase: ResolvedBase | null,
+): void {
+  const tag = element.tagName;
+  const html = element.namespaceURI === HTML_NAMESPACE;
+  if (html && !inTemplate && tag === "base") {
+    const href = htmlAttribute(element, "href");
+    if (href != null) noteBase(href);
+    afterBase = true;
+  }
+  if (tag === "style") return;
+  const styleValue = htmlAttribute(element, "style");
+  const emitStyle = (): void => {
+    if (styleValue != null) adoptCssReferences(refs, cssReferences(styleValue, "declaration"), afterBase);
+  };
+  if (!html) {
+    if (element.namespaceURI === SVG_NAMESPACE && (tag === "image" || tag.toLowerCase() === "feimage")) {
+      for (const candidate of element.attrs) {
+        const name = candidate.name.toLowerCase();
+        if (name === "href" || name === "xlink:href") rememberImageLocator(refs, candidate.value, "html-src", afterBase);
+      }
+    }
+    emitStyle();
+    return;
+  }
+  if (tag === "iframe") {
+    const srcdoc = htmlAttribute(element, "srcdoc");
+    if (srcdoc != null && !isBlankLocator(srcdoc)) {
+      for (const nested of htmlReferences(srcdoc, artifactPath, inheritedBase)) {
+        refs.push({
+          locator: nested.locator,
+          surface: nested.surface,
+          classificationLocator: nested.classificationLocator,
+          // Dropping this treats css-function:* as an unsafe scheme and loses the warning.
+          deferredFunction: nested.deferredFunction,
+        });
+      }
+    }
+    emitStyle();
+    return;
+  }
+  if (tag === "img") {
+    const src = htmlAttribute(element, "src");
+    if (src != null) rememberImageLocator(refs, src, "html-src", afterBase);
+    const srcset = htmlAttribute(element, "srcset");
+    if (srcset != null) {
+      for (const locator of srcsetLocators(srcset)) rememberImageLocator(refs, locator, "html-srcset", afterBase);
+    }
+    emitStyle();
+    return;
+  }
+  if (tag === "source") {
+    if (sourceContext === "picture") {
+      const srcset = htmlAttribute(element, "srcset");
+      if (srcset != null) {
+        for (const locator of srcsetLocators(srcset)) rememberImageLocator(refs, locator, "html-srcset", afterBase);
+      }
+    }
+    emitStyle();
+    return;
+  }
+  if (tag === "video") {
+    const poster = htmlAttribute(element, "poster");
+    if (poster != null) rememberImageLocator(refs, poster, "html-src", afterBase);
+    emitStyle();
+    return;
+  }
+  if (tag === "meta") {
+    const property = (htmlAttribute(element, "property") ?? "").toLowerCase();
+    const name = (htmlAttribute(element, "name") ?? "").toLowerCase();
+    if (property === "og:image" || property === "twitter:image" || name === "og:image" || name === "twitter:image") {
+      const content = htmlAttribute(element, "content");
+      if (content != null) rememberImageLocator(refs, content, "html-metadata", afterBase);
+    }
+    emitStyle();
+    return;
+  }
+  if (tag === "input" && (htmlAttribute(element, "type") ?? "").toLowerCase() === "image") {
+    const src = htmlAttribute(element, "src");
+    if (src != null) rememberImageLocator(refs, src, "html-src", afterBase);
+  }
+  const rel = (htmlAttribute(element, "rel") ?? "").toLowerCase().split(ASCII_WHITESPACE_RUN_RE);
+  const preloadsImage = rel.includes("preload") && (htmlAttribute(element, "as") ?? "").toLowerCase() === "image";
+  const linkHref = htmlAttribute(element, "href");
+  if (tag === "link" && preloadsImage && htmlAttribute(element, "imagesrcset") != null) {
+    const choice = choosePreloadImage(htmlAttribute(element, "imagesrcset") ?? "", linkHref, htmlAttribute(element, "imagesizes"));
+    if (choice.kind === "href" && linkHref != null) rememberImageLocator(refs, linkHref, "html-metadata", afterBase);
+    else if (choice.kind === "urls") {
+      for (const locator of choice.locators) rememberImageLocator(refs, locator, "html-srcset", afterBase);
+    }
+  } else if (tag === "link" && (rel.includes("icon") || rel.includes("apple-touch-icon") || preloadsImage)) {
+    if (linkHref != null) rememberImageLocator(refs, linkHref, "html-metadata", afterBase);
+  }
+  emitStyle();
+}
+
+function htmlReferences(html: string, artifactPath: string, inherited: ResolvedBase | null = null): ExtractedReference[] {
+  const refs: ExtractedReference[] = [];
+  let baseHref: string | null = null;
+  let sawBase = false;
+  const noteBase = (href: string): void => {
+    if (sawBase) return;
+    sawBase = true;
+    baseHref = href;
+  };
+  const enclosingBase = (): ResolvedBase | null => resolvedBase(baseHref, sawBase, artifactPath, inherited);
+  const stack: HtmlWalkFrame[] = [{ node: parseFragment(html), inTemplate: false, cssText: false, sourceContext: null }];
+  while (stack.length > 0) {
+    const frame = stack.pop()!;
+    const { node, inTemplate, sourceContext } = frame;
+    if (isHtmlText(node)) {
+      if (frame.cssText) adoptCssReferences(refs, cssReferences(node.value, "stylesheet"), sawBase);
+      continue;
+    }
+    if (node.nodeName === "#document" || node.nodeName === "#document-fragment") {
+      pushHtmlChildren(stack, node.childNodes, inTemplate, false, sourceContext);
+      continue;
+    }
+    if (!isHtmlElement(node)) continue;
+    collectHtmlElement(node, refs, inTemplate, noteBase, sawBase, sourceContext, artifactPath, enclosingBase());
+    const childContext = childSourceContext(node.tagName, node.namespaceURI);
+    if (node.tagName === "template" && node.namespaceURI === HTML_NAMESPACE && "content" in node) {
+      pushHtmlChildren(stack, node.content.childNodes, true, false, childContext);
+      continue;
+    }
+    if (node.tagName === "style") {
+      pushHtmlChildren(stack, node.childNodes, inTemplate, true, childContext);
+      continue;
+    }
+    pushHtmlChildren(stack, node.childNodes, inTemplate, false, childContext);
+  }
+  return applyHtmlBase(refs, baseHref, artifactPath, inherited);
+}
+
+function catalogReferences(content: string, artifactPath: string): ExtractedReference[] | null {
+  let root: unknown;
+  try {
+    root = JSON.parse(content);
+  } catch {
+    return null;
+  }
+  const refs: ExtractedReference[] = [];
+  const malformed = (): void => { refs.push({ locator: "", surface: "catalog" }); };
+  type WalkItem =
+    | { kind: "visit"; value: unknown; key: string; imageContext: boolean }
+    | { kind: "reference"; locator: string }
+    | { kind: "malformed" };
+  const stack: WalkItem[] = [{ kind: "visit", value: root, key: "", imageContext: false }];
+  let processed = 0;
+  while (stack.length > 0) {
+    if (++processed > MAX_CATALOG_WALK_ITEMS) {
+      malformed();
+      break;
+    }
+    const item = stack.pop()!;
+    if (item.kind === "reference") {
+      refs.push({ locator: item.locator, surface: "catalog" });
+      continue;
+    }
+    if (item.kind === "malformed") {
+      malformed();
+      continue;
+    }
+    const { value, key, imageContext } = item;
+    if (SCALAR_IMAGE_KEY_RE.test(key) && typeof value !== "string") {
+      malformed();
+      continue;
+    }
+    if (typeof value === "string") {
+      if (HTML_VALUE_KEYS.has(key.toLowerCase())) refs.push(...htmlReferences(value, artifactPath));
+      else if (DIRECT_IMAGE_KEY_RE.test(key) || (imageContext && /^(?:src|url)$/i.test(key))) {
+        if (trimAsciiWhitespace(value)) refs.push({ locator: value, surface: "catalog" });
+        else malformed();
+      }
+      continue;
+    }
+    if (Array.isArray(value)) {
+      const images = /^(?:image|images)$/i.test(key);
+      if (stack.length + value.length > MAX_CATALOG_WALK_ITEMS - processed) {
+        malformed();
+        break;
+      }
+      for (let index = value.length - 1; index >= 0; index--) {
+        const child = value[index];
+        if (images && (child == null || (typeof child !== "string" && typeof child !== "object"))) {
+          stack.push({ kind: "malformed" });
+        } else {
+          stack.push({ kind: "visit", value: child, key, imageContext: imageContext || images });
+        }
+      }
+      continue;
+    }
+    if (!value || typeof value !== "object") {
+      if (DIRECT_IMAGE_KEY_RE.test(key) || (imageContext && /^(?:src|url)$/i.test(key))) malformed();
+      continue;
+    }
+    const record = value as Record<string, unknown>;
+    const entries = Object.entries(record);
+    if (stack.length + entries.length > MAX_CATALOG_WALK_ITEMS - processed) {
+      malformed();
+      break;
+    }
+    if (imageContext && !entries.some(([childKey, child]) => /^(?:src|url)$/i.test(childKey) && typeof child === "string" && trimAsciiWhitespace(child))) {
+      malformed();
+    }
+    for (let index = entries.length - 1; index >= 0; index--) {
+      const [childKey, child] = entries[index]!;
+      if (imageContext && /^(?:src|url)$/i.test(childKey)) {
+        if (typeof child === "string" && trimAsciiWhitespace(child)) stack.push({ kind: "reference", locator: child });
+        continue;
+      }
+      const nextImageContext = /^(?:image|images|featuredImage|featured_image|thumbnail)$/i.test(childKey);
+      stack.push({ kind: "visit", value: child, key: childKey, imageContext: nextImageContext });
+    }
+  }
+  return refs;
+}
+
+function structuralPath(path: string): string {
+  return stripQueryHash(path).replace(/\\/g, "/");
+}
+
+function literalPathSegments(path: string): string[] {
+  return stripQueryHash(path).replace(/\\/g, "/").split("/");
+}
+
+function decodePathSegment(segment: string): string | null {
+  let decoded = segment;
+  for (let pass = 0; pass < MAX_PERCENT_DECODE_PASSES; pass++) {
+    let next: string;
+    try {
+      next = decodeURIComponent(decoded);
+    } catch {
+      return decoded;
+    }
+    if (next === decoded) return decoded;
+    decoded = next;
+  }
+  try {
+    return decodeURIComponent(decoded) === decoded ? decoded : null;
+  } catch {
+    return decoded;
+  }
+}
+
+function hasEscape(path: string): boolean {
+  let depth = 0;
+  for (const segment of literalPathSegments(path)) {
+    if (!segment) continue;
+    const decoded = decodePathSegment(segment);
+    if (decoded == null) return true;
+    if (decoded === ".") continue;
+    if (decoded === "..") {
+      if (depth === 0) return true;
+      depth--;
+    } else {
+      depth++;
+    }
+  }
+  return false;
+}
+
+function hasDotDotSegment(path: string): boolean {
+  return literalPathSegments(path).some((segment) => {
+    const decoded = decodePathSegment(segment);
+    return decoded == null || decoded === "..";
+  });
+}
+
+function segmentDecodesToDotDot(segment: string): boolean {
+  const decoded = decodePathSegment(segment);
+  return decoded == null || decoded === "..";
+}
+
+function absolutePathEscapes(pathname: string): boolean {
+  return pathname.split("/").some((segment) => segmentDecodesToDotDot(segment));
+}
+
+function resolveLocalPath(artifactPath: string, locatorPath: string): string | null {
+  if (artifactPath.startsWith("/") || hasEscape(artifactPath)) return null;
+  const base = literalPathSegments(artifactPath).slice(0, -1);
+  const absolute = locatorPath.replace(/\\/g, "/").startsWith("/");
+  const parts = absolute ? [] : base;
+  for (const segment of literalPathSegments(locatorPath)) {
+    if (!segment) continue;
+    const decoded = decodePathSegment(segment);
+    if (decoded == null) return null;
+    if (decoded === ".") continue;
+    if (decoded === "..") {
+      if (parts.length === 0) return null;
+      parts.pop();
+    } else {
+      parts.push(segment);
+    }
+  }
+  return `/${parts.join("/")}`;
+}
+
+function normalizePathPercentEncoding(path: string): string {
+  return path.replace(/%([0-9a-f]{2})/gi, (encoded, hex: string) => {
+    const character = String.fromCharCode(Number.parseInt(hex, 16));
+    return /[a-z0-9_.~-]/i.test(character) ? character : encoded.toUpperCase();
+  });
+}
+
+function canonicalLocalPath(artifactPath: string, locatorPath: string): string | null {
+  try {
+    const artifactUrl = localArtifactUrl(artifactPath);
+    if (!artifactUrl) return null;
+    const resolved = new URL(locatorPath.replace(/\\/g, "/"), artifactUrl);
+    return resolved.origin === LOCAL_REFERENCE_ORIGIN ? normalizePathPercentEncoding(resolved.pathname) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** A literal backslash the URL parser resolves off-origin is a scheme-relative network path. `%5C` is not. */
+function backslashNetworkUrl(locator: string, artifactPath: string): URL | null {
+  if (!locator.includes("\\")) return null;
+  const artifactUrl = localArtifactUrl(artifactPath);
+  if (!artifactUrl) return null;
+  try {
+    const parsed = new URL(locator, artifactUrl);
+    if (parsed.origin === LOCAL_REFERENCE_ORIGIN) return null;
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function stripQueryHash(value: string): string {
+  return value.replace(/[?#].*$/, "");
+}
+
+function stripHash(value: string): string {
+  return value.replace(/#.*$/, "");
+}
+
+function normalizedOrigin(value: string): string | null {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:" ? url.origin : null;
+  } catch {
+    return null;
+  }
+}
+
+function canonicalPlatformReference(value: string): string {
+  const reference = trimAsciiWhitespace(value);
+  if (reference.startsWith("//") || /^https?:/i.test(reference)) {
+    try {
+      const url = reference.startsWith("//") ? new URL(`https:${reference}`) : new URL(reference);
+      if ((url.protocol === "http:" || url.protocol === "https:") && url.hostname) {
+        url.search = "";
+        url.hash = "";
+        return url.toString();
+      }
+    } catch {
+      // Fall through to exact path/reference handling.
+    }
+  }
+  return stripQueryHash(reference);
+}
+
+interface PreparedPlatformHostedImageConfig {
+  references: Set<string>;
+  origins: Set<string>;
+  prefixRoot: PlatformPathPrefixNode;
+}
+
+interface PlatformPathPrefixNode {
+  terminal: boolean;
+  children: Map<string, PlatformPathPrefixNode>;
+}
+
+function platformPrefixTree(prefixes: readonly string[]): PlatformPathPrefixNode {
+  const root: PlatformPathPrefixNode = { terminal: false, children: new Map() };
+  for (const configured of prefixes) {
+    const normalized = (configured.startsWith("/") ? configured : `/${configured}`).replace(/\/$/, "");
+    let node = root;
+    for (const character of normalized) {
+      let child = node.children.get(character);
+      if (!child) {
+        child = { terminal: false, children: new Map() };
+        node.children.set(character, child);
+      }
+      node = child;
+    }
+    node.terminal = true;
+  }
+  return root;
+}
+
+function hasPlatformPrefix(path: string, root: PlatformPathPrefixNode): boolean {
+  if (root.terminal && path.startsWith("/")) return true;
+  let node = root;
+  let offset = 0;
+  for (const character of path) {
+    const child = node.children.get(character);
+    if (!child) return false;
+    node = child;
+    offset += character.length;
+    if (node.terminal && (offset === path.length || path[offset] === "/")) return true;
+  }
+  return false;
+}
+
+function preparePlatformHostedConfig(config: PlatformHostedImageConfig | undefined): PreparedPlatformHostedImageConfig {
+  return {
+    references: new Set((config?.references ?? []).map(canonicalPlatformReference)),
+    origins: new Set((config?.origins ?? []).map(normalizedOrigin).filter((origin): origin is string => origin != null)),
+    prefixRoot: platformPrefixTree([...BUILTIN_PLATFORM_PREFIXES, ...(config?.pathPrefixes ?? [])]),
+  };
+}
+
+function tenantPathOwner(path: string): string | null {
+  return path.match(/^\/tenants\/([^/]+)(?:\/.*)?$/)?.[1] ?? null;
+}
+
+/**
+ * Classify one extracted locator. The returned locator fields are effect inputs,
+ * not user-facing copy; callers render only findings/batches from `scanImageDependencies`.
+ */
+export function classifyImageDependency(
+  locator: string,
+  context: {
+    tenantId: string;
+    artifactPath: string;
+    platformHosted?: PlatformHostedImageConfig;
+  },
+): Pick<ImageDependency, "canonicalLocator" | "disposition" | "reason"> {
+  return classifyImageDependencyWithPrepared(locator, context, preparePlatformHostedConfig(context.platformHosted));
+}
+
+function classifyParsedHttpUrl(
+  absolute: URL,
+  context: { tenantId: string },
+  platformHosted: PreparedPlatformHostedImageConfig,
+): Pick<ImageDependency, "canonicalLocator" | "disposition" | "reason"> {
+  if (!absolute.hostname || absolute.username || absolute.password) {
+    return { canonicalLocator: "invalid:", disposition: "security-error", reason: "malformed" };
+  }
+  if (absolutePathEscapes(absolute.pathname)) {
+    return { canonicalLocator: "escape:", disposition: "security-error", reason: "tenant-escape" };
+  }
+  absolute.hash = "";
+  const canonical = absolute.toString();
+  if (platformHosted.origins.has(absolute.origin) || platformHosted.references.has(stripQueryHash(canonical))) {
+    const absoluteTenant = tenantPathOwner(absolute.pathname);
+    if (absoluteTenant != null && absoluteTenant !== context.tenantId) {
+      return { canonicalLocator: "cross-tenant:", disposition: "security-error", reason: "cross-tenant" };
+    }
+    return { canonicalLocator: canonical, disposition: "platform-hosted" };
+  }
+  return { canonicalLocator: canonical, disposition: "capture-required", reason: "third-party" };
+}
+
+function classifyImageDependencyWithPrepared(
+  locator: string,
+  context: { tenantId: string; artifactPath: string },
+  platformHosted: PreparedPlatformHostedImageConfig,
+): Pick<ImageDependency, "canonicalLocator" | "disposition" | "reason"> {
+  const raw = normalizeUrlInput(locator);
+  if (!raw || CONTROL_RE.test(raw)) {
+    return { canonicalLocator: "invalid:", disposition: "security-error", reason: "malformed" };
+  }
+  if (/^data:image\//i.test(raw)) {
+    return { canonicalLocator: "inline:", disposition: "inline" };
+  }
+  if (/^(?:javascript|file|blob|ftp|vbscript):/i.test(raw)) {
+    return { canonicalLocator: "unsafe:", disposition: "security-error", reason: "unsafe-scheme" };
+  }
+  if (raw.startsWith("//") || /^https?:/i.test(raw)) {
+    let absolute: URL;
+    try {
+      absolute = raw.startsWith("//") ? new URL(`https:${raw}`) : new URL(raw);
+    } catch {
+      return { canonicalLocator: "invalid:", disposition: "security-error", reason: "malformed" };
+    }
+    return classifyParsedHttpUrl(absolute, context, platformHosted);
+  }
+
+  if (/^[a-z][a-z0-9+.-]*:/i.test(raw)) {
+    return { canonicalLocator: "unsafe:", disposition: "security-error", reason: "unsafe-scheme" };
+  }
+  const networkUrl = backslashNetworkUrl(raw, context.artifactPath);
+  if (networkUrl) return classifyParsedHttpUrl(networkUrl, context, platformHosted);
+  const pathOnly = stripQueryHash(raw);
+  const structural = structuralPath(pathOnly);
+  if (structural.startsWith("/") && hasDotDotSegment(pathOnly)) {
+    return { canonicalLocator: "escape:", disposition: "security-error", reason: "tenant-escape" };
+  }
+  const tenant = tenantPathOwner(structural);
+  if (tenant != null) {
+    if (tenant !== context.tenantId) {
+      return { canonicalLocator: "cross-tenant:", disposition: "security-error", reason: "cross-tenant" };
+    }
+    return { canonicalLocator: stripHash(raw), disposition: "tenant-hosted" };
+  }
+  if (
+    (!hasDotDotSegment(pathOnly) && platformHosted.references.has(pathOnly)) ||
+    hasPlatformPrefix(structural, platformHosted.prefixRoot)
+  ) {
+    return { canonicalLocator: stripHash(raw), disposition: "platform-hosted" };
+  }
+  if (/^\/_a\/[0-9a-f]{64}(?:\.[a-z0-9]+)?$/i.test(structural)) {
+    return { canonicalLocator: stripHash(raw), disposition: "platform-hosted" };
+  }
+  const resolved = resolveLocalPath(context.artifactPath, pathOnly);
+  const canonicalPath = canonicalLocalPath(context.artifactPath, pathOnly);
+  if (resolved == null || canonicalPath == null) {
+    return { canonicalLocator: "escape:", disposition: "security-error", reason: "tenant-escape" };
+  }
+  const canonical = `${canonicalPath}${stripHash(raw.slice(pathOnly.length))}`;
+  const resolvedTenant = tenantPathOwner(resolved);
+  if (resolvedTenant != null) {
+    if (resolvedTenant !== context.tenantId) {
+      return { canonicalLocator: "cross-tenant:", disposition: "security-error", reason: "cross-tenant" };
+    }
+    return { canonicalLocator: canonical, disposition: "tenant-hosted" };
+  }
+  if (
+    platformHosted.references.has(canonicalPath) ||
+    hasPlatformPrefix(resolved, platformHosted.prefixRoot) ||
+    /^\/_a\/[0-9a-f]{64}(?:\.[a-z0-9]+)?$/i.test(resolved)
+  ) {
+    return { canonicalLocator: canonical, disposition: "platform-hosted" };
+  }
+  return { canonicalLocator: canonical, disposition: "capture-required", reason: "local" };
+}
+
+function findingMessage(reason: ImageDependencyReason): string {
+  switch (reason) {
+    case "third-party": return "Third-party image content must be captured before hosted preview.";
+    case "local": return "Local image content must be captured before hosted preview.";
+    case "cross-tenant": return "An image reference crosses the current tenant boundary.";
+    case "tenant-escape": return "An image reference escapes the current tenant boundary.";
+    case "unsafe-scheme": return "An image reference uses a scheme that hosted preview cannot accept.";
+    case "malformed": return "An image reference is malformed.";
+    case "unsupported": return DEFERRED_IMAGE_MESSAGE;
+  }
+}
+
+export function buildImageDependencyWarningBatch(
+  findings: readonly ImageDependencyFinding[],
+): ImageDependencyWarningBatch | null {
+  if (findings.length === 0) return null;
+  const captureRequired = findings
+    .filter((finding) => finding.code === "image-capture-required")
+    .reduce((sum, finding) => sum + finding.occurrences, 0);
+  const securityErrors = findings
+    .filter((finding) => finding.code === "image-reference-security")
+    .reduce((sum, finding) => sum + finding.occurrences, 0);
+  const deferred = findings
+    .filter((finding) => finding.code === "image-reference-deferred")
+    .reduce((sum, finding) => sum + finding.occurrences, 0);
+  const unresolved = captureRequired + securityErrors;
+  const messages: string[] = [];
+  if (unresolved > 0) messages.push(`Image hosting found ${unresolved} unresolved reference(s) in one batch.`);
+  if (captureRequired > 0) messages.push(`${captureRequired} reference(s) require capture before hosted preview.`);
+  if (securityErrors > 0) messages.push(`${securityErrors} reference(s) require a security fix before hosted preview.`);
+  if (deferred > 0) messages.push(`${deferred} reference(s) were skipped because hosted preview does not resolve them yet.`);
+  return {
+    code: "image-dependency-batch",
+    total: unresolved + deferred,
+    captureRequired,
+    securityErrors,
+    deferred,
+    representedFindings: findings.length,
+    omittedFindings: 0,
+    messages,
+  };
+}
+
+/** Scan a revision's already-read artifacts with no network or filesystem I/O. */
+export function scanImageDependencies(
+  artifacts: readonly ImageDependencyArtifact[],
+  options: ImageDependencyScanOptions,
+): ImageDependencyScan {
+  const dependencies: ImageDependency[] = [];
+  const platformHosted = preparePlatformHostedConfig(options.platformHosted);
+  let occurrence = 0;
+  for (const [artifactIndex, artifact] of artifacts.entries()) {
+    const kind = inferKind(artifact);
+    let refs: ExtractedReference[];
+    if (kind === "html") refs = htmlReferences(artifact.content, artifact.path);
+    else if (kind === "css") refs = cssReferences(artifact.content, "stylesheet");
+    else {
+      const parsed = catalogReferences(artifact.content, artifact.path);
+      if (parsed == null) {
+        refs = [{ locator: "", surface: "catalog" }];
+      } else {
+        refs = parsed;
+      }
+    }
+    for (const ref of refs) {
+      occurrence++;
+      if (ref.deferredFunction) {
+        dependencies.push({
+          locator: `css-function:${ref.deferredFunction}`,
+          canonicalLocator: "deferred:",
+          artifactIndex,
+          occurrence,
+          surface: ref.surface,
+          disposition: "deferred",
+          reason: "unsupported",
+        });
+        continue;
+      }
+      const classified = classifyImageDependencyWithPrepared(ref.classificationLocator ?? ref.locator, {
+        tenantId: options.tenantId,
+        artifactPath: artifact.path,
+      }, platformHosted);
+      dependencies.push({
+        locator: ref.locator,
+        artifactIndex,
+        occurrence,
+        surface: ref.surface,
+        ...classified,
+      });
+    }
+  }
+
+  const unresolved = new Map<string, { dependency: ImageDependency; occurrences: number; groupOrdinal: number }>();
+  const artifactGroupCounts = new Map<number, number>();
+  for (const dependency of dependencies) {
+    if (dependency.disposition !== "capture-required" && dependency.disposition !== "security-error" && dependency.disposition !== "deferred") continue;
+    const key = `${dependency.artifactIndex}\0${dependency.surface}\0${dependency.disposition}\0${dependency.reason}\0${dependency.canonicalLocator}`;
+    const current = unresolved.get(key);
+    if (current) current.occurrences++;
+    else {
+      const groupOrdinal = (artifactGroupCounts.get(dependency.artifactIndex) ?? 0) + 1;
+      artifactGroupCounts.set(dependency.artifactIndex, groupOrdinal);
+      unresolved.set(key, { dependency, occurrences: 1, groupOrdinal });
+    }
+  }
+
+  const findings: ImageDependencyFinding[] = [];
+  for (const { dependency, occurrences, groupOrdinal } of unresolved.values()) {
+    const reason = dependency.reason!;
+    const security = dependency.disposition === "security-error";
+    const deferred = dependency.disposition === "deferred";
+    findings.push({
+      id: `image-dependency-${String(dependency.artifactIndex + 1).padStart(6, "0")}-${String(groupOrdinal).padStart(6, "0")}`,
+      code: security ? "image-reference-security" : deferred ? "image-reference-deferred" : "image-capture-required",
+      reason,
+      occurrences,
+      authoring: security ? "non-overridable-security-error" : "warning",
+      hostedPreview: security ? "non-overridable-security-error" : "overridable-quality-error",
+      overridable: !security,
+      message: findingMessage(reason),
+    });
+  }
+  const visibleFindings = findings.slice(0, MAX_VISIBLE_FINDINGS);
+
+  const captureByCanonicalLocator = new Map<string, ImageDependency & { reason: "third-party" | "local" }>();
+  for (const dependency of dependencies) {
+    if (dependency.disposition !== "capture-required" || (dependency.reason !== "third-party" && dependency.reason !== "local")) continue;
+    const current = captureByCanonicalLocator.get(dependency.canonicalLocator);
+    if (!current || dependency.locator < current.locator) captureByCanonicalLocator.set(dependency.canonicalLocator, dependency as ImageDependency & { reason: "third-party" | "local" });
+  }
+  const captureCandidates = [...captureByCanonicalLocator.values()]
+    .sort((left, right) => left.canonicalLocator < right.canonicalLocator ? -1 : left.canonicalLocator > right.canonicalLocator ? 1 : 0)
+    .map(({ locator, canonicalLocator, reason }) => ({
+      locator,
+      canonicalLocator,
+      reason,
+      identityAuthority: "original-image-bytes" as const,
+    }));
+
+  const count = (disposition: ImageDependencyDisposition): number =>
+    dependencies.filter((dependency) => dependency.disposition === disposition).length;
+  return {
+    census: {
+      references: dependencies.length,
+      platformHosted: count("platform-hosted"),
+      tenantHosted: count("tenant-hosted"),
+      inline: count("inline"),
+      captureRequired: count("capture-required"),
+      securityErrors: count("security-error"),
+      deferred: count("deferred"),
+    },
+    dependencies,
+    captureCandidates,
+    findings: visibleFindings,
+    warningBatch: (() => {
+      const batch = buildImageDependencyWarningBatch(findings);
+      if (!batch) return null;
+      batch.representedFindings = visibleFindings.length;
+      batch.omittedFindings = findings.length - visibleFindings.length;
+      return batch;
+    })(),
+  };
+}