From db5e3f5d78ce72b044b3ab7705ccf6c11961a9cd Mon Sep 17 00:00:00 2001
From: Noel Tock <hello@noeltock.com>
Date: Thu, 3 Sep 2026 10:48:07 +0700
Subject: [PATCH 1/4] Translate Tailwind/CSS into destination-native styles and
 assets

Closes #5
---
 README.md               |   25 +-
 src/author/assets.ts    |  706 +++++++++++++++++++++
 src/author/index.ts     |  723 +++++++++++++++++++++
 src/author/styles.ts    | 1324 +++++++++++++++++++++++++++++++++++++++
 src/cli.ts              |   46 +-
 src/config/schema.ts    |    6 +
 src/convert/assemble.ts |   29 +-
 src/convert/dom.ts      |   32 +-
 src/convert/walk.ts     |   11 +
 src/index.ts            |   24 +
 src/styles/apply.ts     |   51 +-
 src/types.ts            |  113 +++-
 test/author.test.ts     |  247 ++++++++
 13 files changed, 3319 insertions(+), 18 deletions(-)
 create mode 100644 src/author/assets.ts
 create mode 100644 src/author/index.ts
 create mode 100644 src/author/styles.ts
 create mode 100644 test/author.test.ts

diff --git a/README.md b/README.md
index 6ec5167..fd9cfb7 100644
--- a/README.md
+++ b/README.md
@@ -154,7 +154,8 @@ Gutenberg before it reaches the editor.
 
 | Command | What it does |
 | --- | --- |
-| `convert` | Authored HTML to native blocks. The only path that carries CSS. |
+| `convert` | Authored HTML to native post-content blocks, including the legacy styling path. |
+| `author` | One authored design to a static, registered block package with scoped parity CSS and assets. |
 | `assemble` | An intent tree — JSON describing which blocks and how they nest — to native blocks, built with `createBlock` so the result cannot be invalid. |
 | `author preview <plan\|->` | Validate and render a versioned registered-block AuthoringPlan without writing files. |
 | `author write <plan\|-> --confirm <hash> --output-dir <dir>` | Write only the reviewed plan bound to its SHA-256 confirmation and destination. |
@@ -165,6 +166,7 @@ Gutenberg before it reaches the editor.
 
 ```sh
 block-runner convert hero.html                    # blocks to stdout
+block-runner author hero.html --name acme/hero --out-dir blocks/hero
 block-runner assemble intent.json                 # structure in, blocks out
 block-runner validate "content/**/*.html" --json
 block-runner fix post-content.html --out post-content.fixed.html
@@ -242,6 +244,11 @@ All commands:
 | `--wp-user <user>` | WordPress username for `rest` resolution. |
 | `--wp-app-password-env <name>` | Env var holding a WordPress application password. |
 
+`author` generates exactly one block package. It requires `--name <namespace/slug>` and writes
+to `--out-dir <path>` (or use `--json` to inspect the package without writing). Its `style.css`
+is registered with `block.json`'s `style` field, so parity-critical CSS loads in both editor and
+frontend; `editorStyle` is used only for explicitly supplied editor affordances.
+
 `skill --install` adds installation flags:
 
 | Flag | Description |
@@ -382,6 +389,22 @@ than not offering it.
 Custom JavaScript is never inlined. A behavior maps to a native interactive block,
 comes from a block plugin, or is dropped, and every drop or escalation is reported.
 
+### Registered-block CSS and assets
+
+`author` accepts compiled CSS through `author.styles.css` (or `<style>` content in the design).
+It does not infer Tailwind output from class names or ship Tailwind at runtime. When Tailwind is
+detected, supply its complete `author.styles.tailwind` graph: CSS entries, resolved imports and
+directives, sources, safelist, plugins, environment, and browser target. Missing inputs are
+reported field by field and generation stops; the supplied CSS must be compiler output, with every
+referenced `--tw-*` variable defined in that output.
+
+Non-native selectors are preserved only when they can be rooted beneath the generated block's
+deterministic `.wp-block-<namespace>-<slug>` class. Responsive, container-query, and pseudo-state
+rules retain their conditions. Preflight/global rules, escaping selectors, imports, keyframes, and
+font faces are ledgered and blocked rather than silently scoped. Local static asset references are
+copied into `assets/` and rewritten; remote URLs remain external by default, while font files
+remain unresolved pending an external licensing decision.
+
 > Status: `strict`, `relaxed` and `open` are implemented. `source` is not built yet and is
 > rejected rather than silently downgraded — though the converter already falls back to a
 > Custom HTML block for structure it cannot convert.
diff --git a/src/author/assets.ts b/src/author/assets.ts
new file mode 100644
index 0000000..41acc52
--- /dev/null
+++ b/src/author/assets.ts
@@ -0,0 +1,706 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/** The only outcomes an authored CSS asset can have in a generated bundle. */
+export type AssetOutcome = 'copied' | 'external' | 'unresolved' | 'blocked';
+
+/** The use is deliberately descriptive; it never implies a WordPress attachment ID. */
+export type CssAssetKind = 'asset' | 'font';
+
+export interface CssAssetLocation {
+  /** The supplied CSS source path, when one was available. */
+  path?: string;
+  /** Zero-based offset in `sourceCss`. */
+  offset: number;
+  /** One-based line and column, useful for a conversion report. */
+  line: number;
+  column: number;
+}
+
+/**
+ * A literal `url(...)` reference found in CSS. `start`/`end` delimit the complete function,
+ * whereas `url` is the unquoted, CSS-unescaped reference inside it.
+ */
+export interface CssUrlReference {
+  raw: string;
+  url: string;
+  start: number;
+  end: number;
+  location: CssAssetLocation;
+  kind: CssAssetKind;
+  /** `url` is a CSS url() function; `string` is a direct image-set() source string. */
+  syntax?: 'url' | 'string';
+}
+
+/** One explicit ledger entry for one authored `url(...)` reference. */
+export interface CssAssetLedgerEntry extends CssUrlReference {
+  outcome: AssetOutcome;
+  reason: string;
+  /** The filesystem source used for a copied asset. Never set for a remote asset. */
+  sourceAssetPath?: string;
+  /** The copied destination. Never set for an unresolved, external, or blocked asset. */
+  destinationAssetPath?: string;
+  /** The URL substituted into the returned CSS. Omitted when the source CSS is left untouched. */
+  rewrittenUrl?: string;
+}
+
+/**
+ * Inputs for CSS asset processing. `sourcePath` names the authored stylesheet (or the HTML file
+ * containing an inline stylesheet); relative URLs are resolved from its directory. The result CSS
+ * is intended to live beside `destinationAssetDir`, so the default rewritten URLs are
+ * `./<assets-dir-name>/<hashed-file>`.
+ */
+export interface RewriteCssAssetsOptions {
+  sourcePath?: string;
+  /**
+   * Boundary for relative local URLs. Defaults to the directory containing `sourcePath`; a CSS
+   * reference may name a file below this directory, but never a parent or sibling. Supplying an
+   * asset root is useful when a stylesheet lives in a nested `css/` directory beside `assets/`.
+   */
+  assetRoot?: string;
+  sourceCss: string;
+  destinationAssetDir: string;
+  /**
+   * Public URL prefix for copied files, for example `/wp-content/blocks/acme/assets/`.
+   * Defaults to `./<basename(destinationAssetDir)>/`.
+   */
+  assetUrlPrefix?: string;
+  /**
+   * A caller must make this affirmative licensing decision before a local or remote font URL is
+   * carried forward. This module deliberately does not infer font redistribution rights.
+   */
+  allowFontLicense?: boolean;
+}
+
+export interface RewriteCssAssetsResult {
+  /** CSS with only successfully copied local references rewritten. */
+  css: string;
+  /** Alias for consumers that prefer an explicit result name. */
+  rewrittenCss: string;
+  /** A complete, one-entry-per-`url()` asset ledger. */
+  assets: CssAssetLedgerEntry[];
+  /** Alias for `assets`, to make the accounting purpose clear at call sites. */
+  ledger: CssAssetLedgerEntry[];
+}
+
+interface AssetClassification {
+  outcome: Exclude<AssetOutcome, 'copied'>;
+  reason: string;
+  localPath?: string;
+  suffix?: string;
+}
+
+const FONT_EXTENSIONS = new Set(['.eot', '.otf', '.ttf', '.woff', '.woff2']);
+const DANGEROUS_SCHEMES = new Set(['javascript', 'vbscript']);
+
+/**
+ * Find literal CSS `url(...)` functions without treating strings and comments as references.
+ * This is a lexer, not a CSS formatter: the original CSS is retained byte-for-byte unless a local
+ * asset is successfully copied and needs its URL rewritten.
+ */
+export function scanCssUrlReferences(sourceCss: string, sourcePath?: string): CssUrlReference[] {
+  const ranges = fontFaceRanges(sourceCss);
+  const references: CssUrlReference[] = [];
+
+  let index = 0;
+  while (index < sourceCss.length) {
+    if (startsComment(sourceCss, index)) {
+      index = skipComment(sourceCss, index + 2);
+      continue;
+    }
+    if (isQuote(sourceCss[index])) {
+      index = skipQuoted(sourceCss, index);
+      continue;
+    }
+
+    if (isImageSetFunctionAt(sourceCss, index)) {
+      const parsed = parseUrlFunction(sourceCss, index);
+      if (parsed) {
+        references.push(
+          ...imageSetStringReferences(sourceCss, parsed.valueStart, parsed.end - 1, sourcePath, ranges),
+        );
+      }
+      // Do not skip the function: a later pass through its body still finds `url(...)` candidates
+      // (which have different syntax and replacement boundaries than direct image-set strings).
+      index += 1;
+      continue;
+    }
+
+    if (!isUrlFunctionAt(sourceCss, index)) {
+      index += 1;
+      continue;
+    }
+
+    const parsed = parseUrlFunction(sourceCss, index);
+    if (!parsed) {
+      // A malformed url( is not safe to reinterpret as a file reference. Keep looking after the
+      // token so a later, valid URL still gets a ledger entry.
+      index += 3;
+      continue;
+    }
+
+    references.push({
+      raw: sourceCss.slice(index, parsed.end),
+      url: unescapeCssUrl(parsed.value.trim()),
+      start: index,
+      end: parsed.end,
+      location: locationAt(sourceCss, index, sourcePath),
+      kind: ranges.some((range) => index >= range.start && index < range.end) || isFontUrl(parsed.value)
+        ? 'font'
+        : 'asset',
+      syntax: 'url',
+    });
+    index = parsed.end;
+  }
+
+  return references;
+}
+
+/**
+ * Pure classification for a CSS reference. Local files remain `unresolved` here because copying
+ * is intentionally the responsibility of `rewriteCssAssets`; nothing is fetched or written by
+ * classification alone.
+ */
+export function classifyCssUrlReference(
+  reference: CssUrlReference,
+  options: Pick<RewriteCssAssetsOptions, 'sourcePath' | 'assetRoot' | 'allowFontLicense'>,
+): CssAssetLedgerEntry {
+  const classified = classify(reference, options);
+  return {
+    ...reference,
+    outcome: classified.outcome,
+    reason: classified.reason,
+    ...(classified.localPath ? { sourceAssetPath: classified.localPath } : {}),
+  };
+}
+
+/**
+ * Copy safe local URL targets to `destinationAssetDir` and replace exactly those `url(...)`
+ * tokens in the returned CSS. HTTP(S) and protocol-relative URLs are deliberately never fetched;
+ * they are ledgered as external and left as authored.
+ */
+export async function rewriteCssAssets(options: RewriteCssAssetsOptions): Promise<RewriteCssAssetsResult> {
+  const references = scanCssUrlReferences(options.sourceCss, options.sourcePath);
+  const prefix = publicPrefix(options.destinationAssetDir, options.assetUrlPrefix);
+  const copied = new Map<string, { destinationAssetPath: string; rewrittenUrl: string }>();
+  const ledger: CssAssetLedgerEntry[] = [];
+
+  for (const reference of references) {
+    const classified = classify(reference, options);
+    if (!classified.localPath) {
+      ledger.push({ ...reference, outcome: classified.outcome, reason: classified.reason });
+      continue;
+    }
+
+    const reused = copied.get(classified.localPath);
+    if (reused) {
+      ledger.push({
+        ...reference,
+        outcome: 'copied',
+        reason: 'local asset copied to destination assets directory',
+        sourceAssetPath: classified.localPath,
+        destinationAssetPath: reused.destinationAssetPath,
+        rewrittenUrl: `${reused.rewrittenUrl}${classified.suffix ?? ''}`,
+      });
+      continue;
+    }
+
+    const result = await copyLocalAsset(
+      classified.localPath,
+      options.destinationAssetDir,
+      prefix,
+      path.resolve(options.assetRoot ?? sourceDirectoryFor(options.sourcePath)!),
+    );
+    if ('reason' in result) {
+      ledger.push({
+        ...reference,
+        outcome: result.outcome,
+        reason: result.reason,
+        sourceAssetPath: classified.localPath,
+      });
+      continue;
+    }
+
+    copied.set(classified.localPath, result);
+    ledger.push({
+      ...reference,
+      outcome: 'copied',
+      reason: 'local asset copied to destination assets directory',
+      sourceAssetPath: classified.localPath,
+      destinationAssetPath: result.destinationAssetPath,
+      rewrittenUrl: `${result.rewrittenUrl}${classified.suffix ?? ''}`,
+    });
+  }
+
+  const css = rewriteReferences(options.sourceCss, ledger);
+  return { css, rewrittenCss: css, assets: ledger, ledger };
+}
+
+/** Compatibility-friendly spelling for callers that describe this as processing rather than rewriting. */
+export const processCssAssets = rewriteCssAssets;
+
+function classify(
+  reference: CssUrlReference,
+  options: Pick<RewriteCssAssetsOptions, 'sourcePath' | 'assetRoot' | 'allowFontLicense'>,
+): AssetClassification {
+  const value = reference.url.trim();
+  const compact = stripUrlControls(value);
+  const scheme = schemeOf(compact);
+
+  if (!compact) {
+    return { outcome: 'blocked', reason: 'empty CSS url() reference is not an asset' };
+  }
+  if (DANGEROUS_SCHEMES.has(scheme ?? '')) {
+    return { outcome: 'blocked', reason: `unsafe CSS URL scheme "${scheme}:"` };
+  }
+  // These have no local file to copy. Keeping their literal values is safe and avoids inventing a
+  // filesystem/media identity for inline data or a same-document fragment.
+  if (compact.startsWith('#') || /^data:/i.test(compact)) {
+    return { outcome: 'external', reason: 'inline or fragment CSS URL left unchanged' };
+  }
+  if (reference.kind === 'font' && options.allowFontLicense !== true) {
+    return { outcome: 'unresolved', reason: 'font asset requires explicit font-license approval' };
+  }
+  if (/^https?:\/\//i.test(compact) || compact.startsWith('//') || /^blob:/i.test(compact)) {
+    return { outcome: 'external', reason: 'external CSS URL left unchanged; remote fetching is disabled' };
+  }
+  if (scheme === 'file') {
+    return { outcome: 'blocked', reason: 'file: CSS URLs are not allowed for asset copying' };
+  }
+  if (scheme) {
+    return { outcome: 'blocked', reason: `unsupported CSS URL scheme "${scheme}:"` };
+  }
+  if (isRootRelative(compact)) {
+    return { outcome: 'external', reason: 'root-relative CSS URL left unchanged' };
+  }
+  if (/^(?:var|env)\s*\(/i.test(compact)) {
+    return { outcome: 'unresolved', reason: 'dynamic CSS URL cannot be resolved to a local asset' };
+  }
+
+  const sourceDirectory = sourceDirectoryFor(options.sourcePath);
+  if (!sourceDirectory) {
+    return { outcome: 'unresolved', reason: 'local CSS URL needs a sourcePath to resolve safely' };
+  }
+  const assetRoot = path.resolve(options.assetRoot ?? sourceDirectory);
+
+  const { pathname, suffix } = splitSuffix(compact);
+  if (!pathname) {
+    return { outcome: 'external', reason: 'query-only CSS URL left unchanged' };
+  }
+  if (pathname.includes('\0')) {
+    return { outcome: 'blocked', reason: 'CSS URL contains a null character' };
+  }
+
+  const localPath = path.resolve(sourceDirectory, pathname);
+  if (!isWithin(assetRoot, localPath)) {
+    return {
+      outcome: 'blocked',
+      reason: 'relative CSS URL escapes the allowed asset root',
+    };
+  }
+
+  return {
+    outcome: 'unresolved',
+    reason: 'local CSS URL awaits copying',
+    localPath,
+    suffix,
+  };
+}
+
+async function copyLocalAsset(
+  sourceAssetPath: string,
+  destinationAssetDir: string,
+  prefix: string,
+  allowedRoot: string,
+): Promise<
+  | { destinationAssetPath: string; rewrittenUrl: string }
+  | { outcome: 'unresolved' | 'blocked'; reason: string }
+> {
+  let info: Awaited<ReturnType<typeof lstat>>;
+  try {
+    info = await lstat(sourceAssetPath);
+  } catch {
+    return { outcome: 'unresolved', reason: 'local CSS asset file was not found' };
+  }
+  if (info.isSymbolicLink()) {
+    return { outcome: 'blocked', reason: 'symbolic-link CSS assets are not copied' };
+  }
+  if (!info.isFile()) {
+    return { outcome: 'unresolved', reason: 'local CSS asset is not a regular file' };
+  }
+
+  // A lexical `..` check is not enough: a directory *inside* the asset root can itself be a
+  // symlink. Resolve both ends after lstat and keep the final target inside the declared root.
+  try {
+    const [realRoot, realAsset] = await Promise.all([realpath(allowedRoot), realpath(sourceAssetPath)]);
+    if (!isWithin(realRoot, realAsset)) {
+      return { outcome: 'blocked', reason: 'CSS asset resolves outside the allowed asset root' };
+    }
+  } catch {
+    return { outcome: 'unresolved', reason: 'could not resolve local CSS asset safely' };
+  }
+
+  try {
+    const bytes = await readFile(sourceAssetPath);
+    const filename = copiedFilename(sourceAssetPath, bytes);
+    const destinationAssetPath = path.resolve(destinationAssetDir, filename);
+    await mkdir(path.dirname(destinationAssetPath), { recursive: true });
+    try {
+      await writeFile(destinationAssetPath, bytes, { flag: 'wx' });
+    } catch (error) {
+      if (!isAlreadyExists(error)) {
+        throw error;
+      }
+      // A content-addressed filename should name identical bytes. Verify before treating an
+      // existing file as reusable; never overwrite a user-owned asset on a hash collision.
+      const existing = await readFile(destinationAssetPath);
+      if (!existing.equals(bytes)) {
+        return { outcome: 'blocked', reason: 'destination asset filename collision; existing file was not overwritten' };
+      }
+    }
+    return { destinationAssetPath, rewrittenUrl: `${prefix}${encodeURIComponent(filename)}` };
+  } catch (error) {
+    return {
+      outcome: 'unresolved',
+      reason: `could not copy local CSS asset: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+function rewriteReferences(sourceCss: string, entries: CssAssetLedgerEntry[]): string {
+  // Rewrite from the tail so an earlier source offset is never disturbed by a later replacement.
+  const replacements = entries.filter((entry) => entry.outcome === 'copied' && entry.rewrittenUrl);
+  let output = sourceCss;
+  for (const entry of [...replacements].sort((first, second) => second.start - first.start)) {
+    const replacement = entry.syntax === 'string' ? renderString(entry.rewrittenUrl!) : renderUrl(entry.rewrittenUrl!);
+    output = `${output.slice(0, entry.start)}${replacement}${output.slice(entry.end)}`;
+  }
+  return output;
+}
+
+function renderUrl(url: string): string {
+  // A quoted URL is valid for every copied filename/prefix and cannot be confused with CSS syntax.
+  return `url("${url.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}")`;
+}
+
+function renderString(url: string): string {
+  return `"${url.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+function copiedFilename(sourceAssetPath: string, bytes: Buffer): string {
+  const parsed = path.parse(path.basename(sourceAssetPath));
+  const base = safeFilenamePart(parsed.name || 'asset');
+  const extension = safeFilenamePart(parsed.ext).replace(/^\.+/, '');
+  const digest = createHash('sha256').update(bytes).digest('hex').slice(0, 16);
+  return `${base}-${digest}${extension ? `.${extension}` : ''}`;
+}
+
+function safeFilenamePart(value: string): string {
+  const safe = value.normalize('NFKD').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  return safe || 'asset';
+}
+
+function publicPrefix(destinationAssetDir: string, configured?: string): string {
+  const value = configured ?? `./${path.basename(path.resolve(destinationAssetDir))}/`;
+  return value.endsWith('/') ? value : `${value}/`;
+}
+
+function sourceDirectoryFor(sourcePath: string | undefined): string | undefined {
+  if (!sourcePath || sourcePath === '-' || /^<.*>$/.test(sourcePath)) {
+    return undefined;
+  }
+  return path.dirname(path.resolve(sourcePath));
+}
+
+function isWithin(root: string, candidate: string): boolean {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+function splitSuffix(value: string): { pathname: string; suffix: string } {
+  const index = value.search(/[?#]/);
+  return index === -1 ? { pathname: value, suffix: '' } : { pathname: value.slice(0, index), suffix: value.slice(index) };
+}
+
+function isFontUrl(value: string): boolean {
+  const { pathname } = splitSuffix(value.trim().toLowerCase());
+  return FONT_EXTENSIONS.has(path.extname(pathname));
+}
+
+function isRootRelative(value: string): boolean {
+  return value.startsWith('/') || value.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(value);
+}
+
+function schemeOf(value: string): string | undefined {
+  return /^([A-Za-z][A-Za-z0-9+.-]*):/.exec(value)?.[1]?.toLowerCase();
+}
+
+function stripUrlControls(value: string): string {
+  return [...value].filter((char) => {
+    const code = char.codePointAt(0)!;
+    return code > 0x20 && code !== 0x7f;
+  }).join('');
+}
+
+function isAlreadyExists(error: unknown): error is NodeJS.ErrnoException {
+  return typeof error === 'object' && error !== null && (error as NodeJS.ErrnoException).code === 'EEXIST';
+}
+
+function startsComment(css: string, index: number): boolean {
+  return css[index] === '/' && css[index + 1] === '*';
+}
+
+function skipComment(css: string, index: number): number {
+  const end = css.indexOf('*/', index);
+  return end === -1 ? css.length : end + 2;
+}
+
+function isQuote(value: string | undefined): value is '"' | "'" {
+  return value === '"' || value === "'";
+}
+
+function skipQuoted(css: string, start: number): number {
+  const quote = css[start];
+  let index = start + 1;
+  while (index < css.length) {
+    if (css[index] === '\\') {
+      index += 2;
+      continue;
+    }
+    if (css[index] === quote) {
+      return index + 1;
+    }
+    index += 1;
+  }
+  return css.length;
+}
+
+function isUrlFunctionAt(css: string, index: number): boolean {
+  if (css.slice(index, index + 3).toLowerCase() !== 'url') {
+    return false;
+  }
+  const previous = css[index - 1];
+  if (previous && /[-_A-Za-z0-9]/.test(previous)) {
+    return false;
+  }
+  let cursor = index + 3;
+  while (/\s/.test(css[cursor] ?? '')) {
+    cursor += 1;
+  }
+  return css[cursor] === '(';
+}
+
+function isImageSetFunctionAt(css: string, index: number): boolean {
+  const match = /^(?:-webkit-)?image-set\b/i.exec(css.slice(index));
+  if (!match) return false;
+  const previous = css[index - 1];
+  if (previous && /[-_A-Za-z0-9]/.test(previous)) return false;
+  let cursor = index + match[0].length;
+  while (/\s/.test(css[cursor] ?? '')) cursor += 1;
+  return css[cursor] === '(';
+}
+
+function parseUrlFunction(css: string, start: number): { value: string; valueStart: number; end: number } | undefined {
+  const name = /^(?:url|(?:-webkit-)?image-set)\b/i.exec(css.slice(start))?.[0];
+  if (!name) return undefined;
+  let open = start + name.length;
+  while (/\s/.test(css[open] ?? '')) {
+    open += 1;
+  }
+  if (/image-set$/i.test(name)) {
+    return parseBalancedFunction(css, open);
+  }
+  let cursor = open + 1;
+  while (/\s/.test(css[cursor] ?? '')) {
+    cursor += 1;
+  }
+
+  if (isQuote(css[cursor])) {
+    const quote = css[cursor];
+    const valueStart = cursor + 1;
+    cursor = valueStart;
+    while (cursor < css.length) {
+      if (css[cursor] === '\\') {
+        cursor += 2;
+        continue;
+      }
+      if (css[cursor] === quote) {
+        const value = css.slice(valueStart, cursor);
+        cursor += 1;
+        while (/\s/.test(css[cursor] ?? '')) {
+          cursor += 1;
+        }
+        return css[cursor] === ')' ? { value, valueStart, end: cursor + 1 } : undefined;
+      }
+      cursor += 1;
+    }
+    return undefined;
+  }
+
+  const valueStart = cursor;
+  let depth = 1;
+  while (cursor < css.length) {
+    if (css[cursor] === '\\') {
+      cursor += 2;
+      continue;
+    }
+    if (startsComment(css, cursor)) {
+      cursor = skipComment(css, cursor + 2);
+      continue;
+    }
+    if (isQuote(css[cursor])) {
+      cursor = skipQuoted(css, cursor);
+      continue;
+    }
+    if (css[cursor] === '(') {
+      depth += 1;
+    } else if (css[cursor] === ')') {
+      depth -= 1;
+      if (depth === 0) {
+        return { value: css.slice(valueStart, cursor), valueStart, end: cursor + 1 };
+      }
+    }
+    cursor += 1;
+  }
+  return undefined;
+}
+
+function parseBalancedFunction(css: string, open: number): { value: string; valueStart: number; end: number } | undefined {
+  if (css[open] !== '(') return undefined;
+  const valueStart = open + 1;
+  let cursor = valueStart;
+  let depth = 1;
+  while (cursor < css.length) {
+    if (css[cursor] === '\\') {
+      cursor += 2;
+      continue;
+    }
+    if (startsComment(css, cursor)) {
+      cursor = skipComment(css, cursor + 2);
+      continue;
+    }
+    if (isQuote(css[cursor])) {
+      cursor = skipQuoted(css, cursor);
+      continue;
+    }
+    if (css[cursor] === '(') depth += 1;
+    if (css[cursor] === ')') {
+      depth -= 1;
+      if (depth === 0) {
+        return { value: css.slice(valueStart, cursor), valueStart, end: cursor + 1 };
+      }
+    }
+    cursor += 1;
+  }
+  return undefined;
+}
+
+function imageSetStringReferences(
+  css: string,
+  start: number,
+  end: number,
+  sourcePath: string | undefined,
+  fontRanges: Array<{ start: number; end: number }>,
+): CssUrlReference[] {
+  const references: CssUrlReference[] = [];
+  let index = start;
+  while (index < end) {
+    if (!isQuote(css[index])) {
+      index += 1;
+      continue;
+    }
+    const quote = css[index];
+    const valueStart = index + 1;
+    let cursor = valueStart;
+    while (cursor < end) {
+      if (css[cursor] === '\\') {
+        cursor += 2;
+        continue;
+      }
+      if (css[cursor] === quote) break;
+      cursor += 1;
+    }
+    if (cursor >= end) break;
+
+    // A quoted `url("...")` candidate is accounted for by the ordinary url() scanner. Only
+    // image-set's direct string grammar needs this additional reference type.
+    const before = css.slice(Math.max(start, index - 12), index);
+    if (!/url\(\s*$/i.test(before)) {
+      const value = unescapeCssUrl(css.slice(valueStart, cursor).trim());
+      references.push({
+        raw: css.slice(index, cursor + 1),
+        url: value,
+        start: index,
+        end: cursor + 1,
+        location: locationAt(css, index, sourcePath),
+        kind: fontRanges.some((range) => index >= range.start && index < range.end) || isFontUrl(value) ? 'font' : 'asset',
+        syntax: 'string',
+      });
+    }
+    index = cursor + 1;
+  }
+  return references;
+}
+
+function unescapeCssUrl(value: string): string {
+  return value.replace(/\\([0-9A-Fa-f]{1,6}[ \t\r\n\f]?|.)/g, (_, escaped: string) => {
+    const hexadecimal = /^([0-9A-Fa-f]{1,6})/.exec(escaped)?.[1];
+    if (!hexadecimal) {
+      return escaped;
+    }
+    const codePoint = Number.parseInt(hexadecimal, 16);
+    return codePoint === 0 || codePoint > 0x10ffff ? '\uFFFD' : String.fromCodePoint(codePoint);
+  });
+}
+
+function locationAt(css: string, offset: number, sourcePath?: string): CssAssetLocation {
+  let line = 1;
+  let column = 1;
+  for (let index = 0; index < offset; index += 1) {
+    if (css[index] === '\n') {
+      line += 1;
+      column = 1;
+    } else {
+      column += 1;
+    }
+  }
+  return { path: sourcePath, offset, line, column };
+}
+
+function fontFaceRanges(css: string): Array<{ start: number; end: number }> {
+  const ranges: Array<{ start: number; end: number }> = [];
+  const expression = /@font-face\b/gi;
+  let match: RegExpExecArray | null;
+  while ((match = expression.exec(css))) {
+    let cursor = match.index + match[0].length;
+    while (cursor < css.length && css[cursor] !== '{') {
+      if (startsComment(css, cursor)) {
+        cursor = skipComment(css, cursor + 2);
+      } else if (isQuote(css[cursor])) {
+        cursor = skipQuoted(css, cursor);
+      } else {
+        cursor += 1;
+      }
+    }
+    if (css[cursor] !== '{') {
+      continue;
+    }
+    const start = cursor + 1;
+    let depth = 1;
+    cursor += 1;
+    while (cursor < css.length && depth > 0) {
+      if (startsComment(css, cursor)) {
+        cursor = skipComment(css, cursor + 2);
+      } else if (isQuote(css[cursor])) {
+        cursor = skipQuoted(css, cursor);
+      } else {
+        if (css[cursor] === '{') depth += 1;
+        if (css[cursor] === '}') depth -= 1;
+        cursor += 1;
+      }
+    }
+    ranges.push({ start, end: cursor });
+  }
+  return ranges;
+}
diff --git a/src/author/index.ts b/src/author/index.ts
new file mode 100644
index 0000000..b5d8514
--- /dev/null
+++ b/src/author/index.ts
@@ -0,0 +1,723 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { JSDOM } from 'jsdom';
+import { loadConfig } from '../config/load.js';
+import { convert } from '../convert/assemble.js';
+import { parseMarkup } from '../headless/wp.js';
+import {
+  AssetLedgerEntry,
+  AuthoredStyleLedgerEntry,
+  AuthorConfig,
+  AuthorOptions,
+  BlockRunnerReport,
+  GeneratedBlockPackage,
+  ReportItem,
+  WpBlock,
+} from '../types.js';
+import { classifyCssUrlReference, rewriteCssAssets, scanCssUrlReferences } from './assets.js';
+import {
+  createSelectorDependencyTransport,
+  referencedCssClasses,
+  scanStylesheet,
+  scopeStylesheet,
+  validateCssBuildGraph,
+} from './styles.js';
+import type { StyleLedgerEntry } from '../styles/apply.js';
+
+/**
+ * Produce the small, static source package for one registered block.
+ *
+ * This is deliberately an authoring path rather than a variation on `convert`: conversion emits
+ * post content, while this function creates a block root which owns its CSS/assets.  It accepts
+ * compiled CSS only.  It never runs Tailwind, guesses utility classes, downloads a remote asset,
+ * or manufactures a media ID.
+ */
+export async function author(input: string, options: AuthorOptions = {}): Promise<BlockRunnerReport> {
+  const config = await loadConfig(options);
+  const definition = mergeAuthorConfig(config.author, options.author);
+  const name = definition.name;
+  if (!name || !isBlockName(name)) {
+    return authorFailure('author.name must be a registered block name such as "acme/hero"');
+  }
+  const behaviour = unsupportedBehaviour(input);
+  if (behaviour) {
+    return authorFailure(behaviour);
+  }
+  if (!definition.styles?.css && linkedStylesheets(input).length > 0) {
+    return authorFailure(
+      'external stylesheet input requires compiled CSS in author.styles.css; remote stylesheet fetching and implicit import graphs are disabled',
+    );
+  }
+
+  const rootSelector = `.wp-block-${name.replace('/', '-')}`;
+  const styleInput = definition.styles?.css ?? stylesFromHtml(input);
+  const buildGraph = validateCssBuildGraph(definition.styles?.tailwind, { css: styleInput });
+  const stylesheet = scanStylesheet(styleInput);
+  const selectorTransport = createSelectorDependencyTransport();
+  const safetyScopedStyles = scopeStylesheet(stylesheet, {
+    root: rootSelector,
+    disposition: (declaration) => unsafeResidualDeclaration(declaration.property, declaration.value),
+    selectorTransform: selectorTransport.rewrite,
+  });
+  const safetyLedger = safetyScopedStyles.ledger.map(toAuthoredStyleLedgerEntry(options.sourcePath));
+  const hardSafetyStyleFailure = safetyScopedStyles.ledger.some((entry) => entry.outcome === 'blocked' || entry.outcome === 'warned')
+    || safetyScopedStyles.ruleRecords.some((record) => record.outcome === 'blocked');
+  const graphItems: ReportItem[] = [
+    ...(buildGraph.tailwindDetected ? buildGraph.issues : []).map((issue) => ({
+      block: name,
+      status: 'warning' as const,
+      reason: issue.reason,
+      details: { outcome: issue.status, field: issue.field },
+    })),
+    ...safetyScopedStyles.ledger
+      .filter((entry) => entry.outcome === 'warned' || entry.outcome === 'blocked')
+      .map<ReportItem>((entry) => ({
+      block: name,
+      status: 'warning',
+      reason: `${entry.property}: ${entry.value}${entry.reason ? ` — ${entry.reason}` : ''}`,
+      details: {
+        outcome: entry.outcome,
+        property: entry.property,
+        value: entry.value,
+        atRules: entry.atRules,
+      },
+      })),
+    ...safetyScopedStyles.ruleRecords
+      .filter((record) => record.outcome === 'blocked' && !safetyScopedStyles.ledger.some((entry) => entry.ruleId === record.ruleId))
+      .map<ReportItem>((record) => ({
+        block: name,
+        status: 'warning',
+        reason: `${record.prelude}${record.reason ? ` — ${record.reason}` : ''}`,
+        details: { outcome: 'blocked', rule: record.ruleId },
+      })),
+  ];
+
+  // A missing build input is not a recoverable fidelity loss.  Stop before generating a package
+  // that looks successful but contains an incomplete Tailwind transport layer.
+  if (buildGraph.blocked) {
+    return {
+      ok: false,
+      command: 'author',
+      summary: { blocks: 0, valid: 0, invalid: 0, warnings: graphItems.length },
+      items: graphItems,
+      styleLedger: safetyLedger,
+    };
+  }
+  // Scoping deliberately removes selectors/declarations that cannot retain their source meaning.
+  // That is not a successful partial package: stop before any CSS asset copying or package file
+  // write can leave output on disk that looks ready to use.
+  if (hardSafetyStyleFailure) {
+    return {
+      ok: false,
+      command: 'author',
+      summary: { blocks: 0, valid: 0, invalid: 0, warnings: graphItems.length },
+      items: graphItems,
+      styleLedger: safetyLedger,
+    };
+  }
+  const nativeSource = await collectNativeSourceDeclarations(input, options, config);
+  const preflightStyleLedger = [...safetyLedger, ...nativeSource.inlineLedger];
+  const preflightInlineFailure = nativeSource.inlineLedger.some(
+    (entry) => entry.outcome === 'blocked' || entry.outcome === 'warned',
+  );
+  if (!nativeSource.conversion.ok || preflightInlineFailure) {
+    return {
+      ...nativeSource.conversion,
+      ok: false,
+      command: 'author',
+      summary: {
+        ...nativeSource.conversion.summary,
+        warnings: nativeSource.conversion.summary.warnings + graphItems.length,
+      },
+      items: [...nativeSource.conversion.items, ...graphItems],
+      styleLedger: preflightStyleLedger,
+    };
+  }
+  const scopedStyles = scopeStylesheet(stylesheet, {
+    root: rootSelector,
+    selectorTransform: selectorTransport.rewrite,
+    disposition: (declaration, rule) =>
+      unsafeResidualDeclaration(declaration.property, declaration.value)
+      ?? (nativeSource.declarations.has(sourceDeclarationKey(rule.selector, declaration.property, declaration.value))
+        ? {
+            outcome: 'native' as const,
+            reason: 'mapped through the destination block support; omitted from residual CSS',
+          }
+        : undefined),
+  });
+  const stylesheetLedger = scopedStyles.ledger.map(toAuthoredStyleLedgerEntry(options.sourcePath));
+  const hardStyleFailure = scopedStyles.ledger.some((entry) => entry.outcome === 'blocked' || entry.outcome === 'warned')
+    || scopedStyles.ruleRecords.some((record) => record.outcome === 'blocked');
+  let css = scopedStyles.css;
+  // The source ledger includes URLs from rules we intentionally block (notably @font-face and
+  // Preflight). Those assets still need a terminal outcome even though their declarations will
+  // not reach style.css.
+  const sourceAssets = scanCssUrlReferences(styleInput, options.sourcePath).map((reference) =>
+    toAssetLedgerEntry(
+      classifyCssUrlReference(reference, {
+        sourcePath: options.sourcePath,
+        allowFontLicense: false,
+      }),
+    ),
+  );
+  const destinationAssetDir = options.outDir
+    ? path.join(options.outDir, 'assets')
+    : path.join(process.cwd(), '.block-runner-unwritten-assets');
+  // Copy/account from the complete source stylesheet, not merely residual CSS. A declaration can
+  // quite correctly become native (for example a class background becoming a Cover) while its URL
+  // still needs a package asset and a terminal ledger outcome.
+  const processedSource = await rewriteCssAssets({
+    sourceCss: styleInput,
+    sourcePath: options.outDir ? options.sourcePath : undefined,
+    destinationAssetDir,
+    allowFontLicense: false,
+  });
+  let assets: AssetLedgerEntry[] = mergeAssetLedgers(sourceAssets, processedSource.assets.map(toAssetLedgerEntry));
+  if (css) {
+    const processed = await rewriteCssAssets({
+      sourceCss: css,
+      sourcePath: options.outDir ? options.sourcePath : undefined,
+      destinationAssetDir,
+      allowFontLicense: false,
+    });
+    css = processed.css;
+  }
+
+  // Rewrite every concrete source asset before conversion. That makes assets inside Custom HTML
+  // fallbacks just as accountable as assets that happen to map to a native media block.
+  const rewrittenMarkup = await rewriteMarkupAssets(input, {
+      sourcePath: options.sourcePath,
+    destinationAssetDir,
+    write: Boolean(options.outDir),
+    stylesheetAssetsAlreadyAccounted: definition.styles?.css === undefined,
+  });
+  assets = [...assets, ...rewrittenMarkup.assets];
+
+  const inlineStyleLedger: AuthoredStyleLedgerEntry[] = [];
+  const conversion = await convert(rewrittenMarkup.input, {
+    ...options,
+    // The author package carries any unsupported authored selector/property in style.css; the
+    // legacy open sidecar would duplicate it as a global post stylesheet.
+    styling: 'relaxed',
+    config,
+    preserveSourceClasses: referencedCssClasses(scopedStyles.css),
+    preserveSourceSelectorDependencies: selectorTransport.dependencies,
+    preserveAssetForms: true,
+    styleLedgerObserver(entries, source) {
+      for (const entry of entries) {
+        // The author stylesheet is accounted for by the CSS scanner. With source class styles
+        // disabled above, everything reaching this observer is an inline declaration or an
+        // inline parse problem, which otherwise had no authored-package ledger at all.
+        if (!entry.origin) {
+          inlineStyleLedger.push(toInlineStyleLedgerEntry(entry, source));
+        }
+      }
+    },
+  });
+  const blocks = conversion.output ? await parseMarkup(conversion.output) : [];
+  const styleLedger = [...stylesheetLedger, ...inlineStyleLedger];
+  const hardInlineStyleFailure = inlineStyleLedger.some((entry) => entry.outcome === 'blocked' || entry.outcome === 'warned');
+  const packageSource = buildPackage({
+    definition,
+    name,
+    rootSelector,
+    css,
+    template: blocks.map(toTemplateNode),
+  });
+
+  const assetItems = assets
+    .filter((asset) => asset.outcome === 'unresolved' || asset.outcome === 'blocked')
+    .map<ReportItem>((asset) => ({
+      block: name,
+      status: 'warning',
+      reason: `${asset.kind} asset ${asset.reference} ${asset.outcome}${asset.reason ? ` — ${asset.reason}` : ''}`,
+      source: asset.source,
+      details: { outcome: asset.outcome, rewritten: asset.rewritten },
+    }));
+  const hardAssetFailure = assets.some((asset) => asset.outcome === 'unresolved' || asset.outcome === 'blocked');
+
+  // Do not leave a seemingly usable package on disk when a local asset/font could not be carried
+  // legally or safely. The in-memory package remains in the report for diagnosis.
+  if (options.outDir && !hardAssetFailure && !hardStyleFailure && !hardInlineStyleFailure && conversion.ok) {
+    await writePackage(options.outDir, packageSource);
+  }
+
+  return {
+    ...conversion,
+    ok: conversion.ok && !hardAssetFailure && !hardStyleFailure && !hardInlineStyleFailure,
+    command: 'author',
+    summary: {
+      ...conversion.summary,
+      warnings: conversion.summary.warnings + graphItems.length + assetItems.length,
+    },
+    items: [...conversion.items, ...graphItems, ...assetItems],
+    assets: assets.length > 0 ? assets : undefined,
+    styleLedger,
+    package: packageSource,
+  };
+}
+
+function mergeAuthorConfig(configured: AuthorConfig | undefined, explicit: AuthorConfig | undefined): AuthorConfig {
+  return {
+    ...configured,
+    ...explicit,
+    styles: { ...configured?.styles, ...explicit?.styles },
+  };
+}
+
+/**
+ * Prove a stylesheet declaration has exactly one native destination before omitting it from
+ * style.css. The existing converter is the capability oracle: it only reports `mapped` when the
+ * concrete emitted Core block declares the relevant support in the pinned/target registry.
+ */
+interface NativeSourceCollection {
+  declarations: Set<string>;
+  inlineLedger: AuthoredStyleLedgerEntry[];
+  conversion: BlockRunnerReport;
+}
+
+async function collectNativeSourceDeclarations(
+  input: string,
+  options: AuthorOptions,
+  config: Awaited<ReturnType<typeof loadConfig>>,
+): Promise<NativeSourceCollection> {
+  const outcomes = new Map<string, { native: boolean; other: boolean }>();
+  const inlineLedger: AuthoredStyleLedgerEntry[] = [];
+  const conversion = await convert(input, {
+    ...options,
+    config,
+    styling: 'relaxed',
+    preserveAssetForms: true,
+    styleLedgerObserver(entries, source) {
+      for (const entry of entries) {
+        if (!entry.origin) {
+          inlineLedger.push(toInlineStyleLedgerEntry(entry, source));
+          continue;
+        }
+        const key = sourceDeclarationKey(entry.origin, entry.property, entry.value);
+        const state = outcomes.get(key) ?? { native: false, other: false };
+        if (entry.outcome === 'mapped' || (entry.outcome === 'consumed' && entry.reason === 'read by the structural rules')) {
+          state.native = true;
+        } else {
+          state.other = true;
+        }
+        outcomes.set(key, state);
+      }
+    },
+  });
+  return {
+    declarations: new Set([...outcomes].filter(([, state]) => state.native && !state.other).map(([key]) => key)),
+    inlineLedger,
+    conversion,
+  };
+}
+
+function sourceDeclarationKey(selector: string, property: string, value: string): string {
+  return `${selector.trim()}\u0000${property.trim().toLowerCase()}\u0000${value.trim()}`;
+}
+
+function authorFailure(reason: string): BlockRunnerReport {
+  return {
+    ok: false,
+    command: 'author',
+    summary: { blocks: 0, valid: 0, invalid: 0, warnings: 1 },
+    items: [{ block: 'input', status: 'warning', reason }],
+  };
+}
+
+function isBlockName(value: string): boolean {
+  return /^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/.test(value);
+}
+
+function stylesFromHtml(input: string): string {
+  // The style compiler does its own CSS parsing.  This small extractor only joins the actual style
+  // graph supplied with an HTML design; it does not infer CSS from Tailwind class names.
+  return [...input.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi)].map((match) => match[1]).join('\n');
+}
+
+function linkedStylesheets(input: string): string[] {
+  return [...input.matchAll(/<link\b[^>]*\brel\s*=\s*(['"]?)[^'"\s>]*stylesheet[^'"\s>]*\1[^>]*>/gi)].map(
+    (match) => match[0],
+  );
+}
+
+function unsupportedBehaviour(input: string): string | undefined {
+  if (/<script\b/i.test(input)) {
+    return 'script behaviour is not authorized in a generated static block';
+  }
+  if (/\son[a-z][\w-]*\s*=/i.test(input)) {
+    return 'event-handler behaviour is not authorized in a generated static block';
+  }
+  return undefined;
+}
+
+function unsafeResidualDeclaration(property: string, value: string): { outcome: 'blocked'; reason: string } | undefined {
+  if (/^(?:behavior|-moz-binding)$/i.test(property.trim())) {
+    return { outcome: 'blocked', reason: `${property} can require executable browser behaviour` };
+  }
+  if (/\burl\(\s*(['"]?)\s*(?:javascript|vbscript)\s*:/i.test(value)) {
+    return { outcome: 'blocked', reason: 'unsafe executable CSS URL scheme' };
+  }
+  return undefined;
+}
+
+function mergeAssetLedgers(
+  sourceAssets: AssetLedgerEntry[],
+  processedAssets: AssetLedgerEntry[],
+): AssetLedgerEntry[] {
+  const processedByReference = new Map<string, AssetLedgerEntry[]>();
+  for (const asset of processedAssets) {
+    const entries = processedByReference.get(asset.reference) ?? [];
+    entries.push(asset);
+    processedByReference.set(asset.reference, entries);
+  }
+
+  return sourceAssets.map((source) => {
+    const match = processedByReference.get(source.reference)?.shift();
+    if (!match) {
+      return source;
+    }
+    return {
+      ...source,
+      outcome: match.outcome,
+      rewritten: match.rewritten,
+      reason: match.reason,
+    };
+  });
+}
+
+interface RewriteMarkupAssetsOptions {
+  sourcePath?: string;
+  destinationAssetDir: string;
+  write: boolean;
+  /** True when styleInput already supplied ledger entries for every inline <style> URL. */
+  stylesheetAssetsAlreadyAccounted: boolean;
+}
+
+interface SrcsetCandidate {
+  url: string;
+  start: number;
+  end: number;
+}
+
+/**
+ * Account for every concrete URL in the design markup before the walker can turn it into native
+ * blocks or Custom HTML. Scanning the post-conversion block tree misses raw fallback content and
+ * is too late to preserve `srcset`/inline image-set candidates.
+ */
+async function rewriteMarkupAssets(input: string, options: RewriteMarkupAssetsOptions): Promise<{
+  input: string;
+  assets: AssetLedgerEntry[];
+}> {
+  const dom = new JSDOM(input, { contentType: 'text/html' });
+  const assets: AssetLedgerEntry[] = [];
+  const document = dom.window.document;
+
+  const processReference = async (
+    reference: string,
+    kind: AssetLedgerEntry['kind'],
+  ): Promise<string | undefined> => {
+    const processed = await rewriteCssAssets({
+      sourceCss: `x{background-image:url(${JSON.stringify(reference)})}`,
+      sourcePath: options.write ? options.sourcePath : undefined,
+      destinationAssetDir: options.destinationAssetDir,
+      allowFontLicense: false,
+    });
+    const entry = processed.assets[0];
+    if (!entry) {
+      assets.push({ reference, kind, outcome: 'unresolved', reason: 'asset reference could not be classified' });
+      return undefined;
+    }
+    const record = toAssetLedgerEntry(entry);
+    record.kind = kind;
+    assets.push(record);
+    return entry.outcome === 'copied' ? entry.rewrittenUrl : undefined;
+  };
+
+  for (const element of [...document.querySelectorAll('*')]) {
+    if (element.tagName.toLowerCase() === 'style') {
+      // Keep the rewritten stylesheet in the conversion DOM as well: a declaration that maps to
+      // native media reads this URL before residual CSS is emitted. Its ledger was already built
+      // from styleInput unless explicit configured CSS superseded the document styles.
+      const sourceCss = element.textContent ?? '';
+      const processed = await rewriteCssAssets({
+        sourceCss,
+        sourcePath: options.write ? options.sourcePath : undefined,
+        destinationAssetDir: options.destinationAssetDir,
+        allowFontLicense: false,
+      });
+      if (!options.stylesheetAssetsAlreadyAccounted) {
+        assets.push(...processed.assets.map(toAssetLedgerEntry));
+      }
+      if (processed.css !== sourceCss) {
+        element.textContent = processed.css;
+      }
+      continue;
+    }
+
+    const style = element.getAttribute('style');
+    if (style?.trim()) {
+      const processed = await rewriteCssAssets({
+        sourceCss: style,
+        sourcePath: options.write ? options.sourcePath : undefined,
+        destinationAssetDir: options.destinationAssetDir,
+        allowFontLicense: false,
+      });
+      assets.push(...processed.assets.map(toAssetLedgerEntry));
+      if (processed.css !== style) {
+        element.setAttribute('style', processed.css);
+      }
+    }
+
+    for (const attribute of ['src', 'poster'] as const) {
+      const value = element.getAttribute(attribute);
+      if (!value?.trim()) continue;
+      const rewritten = await processReference(value, assetKindFor(element, attribute));
+      if (rewritten) {
+        element.setAttribute(attribute, rewritten);
+      }
+    }
+
+    const srcset = element.getAttribute('srcset');
+    if (!srcset?.trim()) continue;
+    let rewrittenSrcset = srcset;
+    for (const candidate of [...srcsetCandidates(srcset)].sort((left, right) => right.start - left.start)) {
+      const rewritten = await processReference(candidate.url, 'image');
+      if (rewritten) {
+        rewrittenSrcset = `${rewrittenSrcset.slice(0, candidate.start)}${rewritten}${rewrittenSrcset.slice(candidate.end)}`;
+      }
+    }
+    if (rewrittenSrcset !== srcset) {
+      element.setAttribute('srcset', rewrittenSrcset);
+    }
+  }
+
+  // Keep head-owned `<style>` elements as well as body markup. JSDOM correctly relocates a
+  // leading stylesheet into `<head>`; returning body.innerHTML would make the final conversion
+  // forget declarations the preflight proved native, recreating the very ledger mismatch here.
+  return { input: dom.serialize(), assets };
+}
+
+function assetKindFor(element: Element, attribute: 'src' | 'poster'): AssetLedgerEntry['kind'] {
+  if (attribute === 'poster' || element.tagName.toLowerCase() === 'img') return 'image';
+  if (/^(audio|video|track|source)$/i.test(element.tagName)) return 'media';
+  return 'other';
+}
+
+/** Extract URL tokens only; descriptors are retained byte-for-byte when a candidate is rewritten. */
+function srcsetCandidates(value: string): SrcsetCandidate[] {
+  const candidates: SrcsetCandidate[] = [];
+  let index = 0;
+  while (index < value.length) {
+    while (index < value.length && /[\s,]/.test(value[index])) index += 1;
+    const start = index;
+    if (start >= value.length) break;
+
+    // Data URLs legitimately contain commas. They end at the candidate's first whitespace, not
+    // its first comma; external classification keeps them intact without a filesystem lookup.
+    const data = /^data:/i.test(value.slice(start));
+    while (index < value.length && !(data ? /\s/.test(value[index]) : /[\s,]/.test(value[index]))) index += 1;
+    const end = index;
+    const url = value.slice(start, end);
+    if (url) candidates.push({ url, start, end });
+
+    let quote: string | undefined;
+    while (index < value.length) {
+      const char = value[index];
+      if (quote) {
+        if (char === '\\') index += 2;
+        else {
+          if (char === quote) quote = undefined;
+          index += 1;
+        }
+        continue;
+      }
+      if (char === '"' || char === "'") {
+        quote = char;
+      } else if (char === ',') {
+        index += 1;
+        break;
+      }
+      index += 1;
+    }
+  }
+  return candidates;
+}
+
+interface BuildPackageInput {
+  definition: AuthorConfig;
+  name: string;
+  rootSelector: string;
+  css: string;
+  template: unknown[];
+}
+
+function buildPackage(input: BuildPackageInput): GeneratedBlockPackage {
+  const { definition, name, rootSelector, css, template } = input;
+  const namespace = name.split('/')[0];
+  const title = definition.title ?? titleFromSlug(name.split('/')[1]);
+  const editorCss = definition.styles?.editorCss?.trim();
+  const blockJson: Record<string, unknown> = {
+    $schema: 'https://schemas.wp.org/trunk/block.json',
+    apiVersion: 3,
+    name,
+    title,
+    category: definition.category ?? 'widgets',
+    textdomain: namespace,
+    editorScript: 'file:./index.js',
+    // CSS which affects parity is deliberately registered here. WordPress loads `style` in both
+    // the editor and on the frontend; `editorStyle` is only for explicitly supplied affordances.
+    ...(css ? { style: 'file:./style.css' } : {}),
+    ...(editorCss ? { editorStyle: 'file:./editor.css' } : {}),
+    supports: { html: false, ...(definition.supports ?? {}) },
+  };
+
+  const files: Record<string, string> = {
+    'block.json': `${JSON.stringify(blockJson, null, 2)}\n`,
+    'index.js': renderIndexModule(template),
+  };
+  if (css) {
+    files['style.css'] = ensureTrailingNewline(css);
+  }
+  if (editorCss) {
+    files['editor.css'] = ensureTrailingNewline(editorCss);
+  }
+  return { name, rootSelector, files };
+}
+
+function renderIndexModule(template: unknown[]): string {
+  // No JSX means this file can be consumed by the ordinary @wordpress/scripts build without a
+  // transform-specific source dependency. The template is data, not runtime source CSS/classes.
+  return `import { createElement } from '@wordpress/element';
+import { registerBlockType } from '@wordpress/blocks';
+import { InnerBlocks, useBlockProps } from '@wordpress/block-editor';
+import metadata from './block.json';
+
+const TEMPLATE = ${JSON.stringify(template, null, 2)};
+
+function Edit() {
+  return createElement('div', useBlockProps(), createElement(InnerBlocks, { template: TEMPLATE }));
+}
+
+function Save() {
+  return createElement('div', useBlockProps.save(), createElement(InnerBlocks.Content));
+}
+
+registerBlockType(metadata.name, { edit: Edit, save: Save });
+`;
+}
+
+function toTemplateNode(block: WpBlock): unknown[] {
+  return [
+    block.name,
+    block.name === 'core/html' && typeof block.originalContent === 'string'
+      ? { ...cleanAttributes(block.attributes), content: block.originalContent }
+      : cleanAttributes(block.attributes),
+    block.innerBlocks.map(toTemplateNode),
+  ];
+}
+
+function cleanAttributes(attributes: Record<string, unknown>): Record<string, unknown> {
+  // Sources are diagnostic data for this process, not serialized attributes of an authored block.
+  return Object.fromEntries(Object.entries(attributes).filter(([key]) => !key.startsWith('__blockRunner')));
+}
+
+function titleFromSlug(slug: string): string {
+  return slug.replace(/[-_]+/g, ' ').replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+
+function ensureTrailingNewline(value: string): string {
+  return value.endsWith('\n') ? value : `${value}\n`;
+}
+
+async function writePackage(outDir: string, packageSource: GeneratedBlockPackage): Promise<void> {
+  const destination = path.resolve(outDir);
+  await mkdir(destination, { recursive: true });
+  // Individual, declared files only. We never clean the output directory or overwrite copied
+  // assets as a side effect of authoring; files are written atomically by the caller's explicit
+  // destination choice.
+  await Promise.all(
+    Object.entries(packageSource.files).map(async ([relativePath, content]) => {
+      const target = path.resolve(destination, relativePath);
+      if (!target.startsWith(`${destination}${path.sep}`)) {
+        throw new Error(`invalid generated package path: ${relativePath}`);
+      }
+      await mkdir(path.dirname(target), { recursive: true });
+      await writeFile(target, content, { encoding: 'utf8', flag: 'wx' });
+    }),
+  );
+}
+
+function toAssetLedgerEntry(asset: {
+  url: string;
+  kind: 'asset' | 'font';
+  outcome: AssetLedgerEntry['outcome'];
+  reason: string;
+  rewrittenUrl?: string;
+  location: { path?: string; offset: number; line: number; column: number };
+}): AssetLedgerEntry {
+  return {
+    reference: asset.url,
+    rewritten: asset.rewrittenUrl,
+    kind: asset.kind === 'font' ? 'font' : 'image',
+    outcome: asset.outcome,
+    reason: asset.reason,
+    source: {
+      path: asset.location.path,
+      htmlLine: asset.location.line,
+      htmlColumn: asset.location.column,
+      offset: asset.location.offset,
+    },
+  };
+}
+
+function toAuthoredStyleLedgerEntry(
+  sourcePath: string | undefined,
+): (entry: {
+  property: string;
+  value: string;
+  outcome: string;
+  reason?: string;
+  atRules: string[];
+  source: { start: { offset: number; line: number; column: number } };
+}) => AuthoredStyleLedgerEntry {
+  return (entry) => ({
+    property: entry.property,
+    value: entry.value,
+    outcome: normalizeStyleOutcome(entry.outcome),
+    reason: entry.reason,
+    atRules: entry.atRules,
+    source: {
+      path: sourcePath,
+      offset: entry.source.start.offset,
+      htmlLine: entry.source.start.line,
+      htmlColumn: entry.source.start.column,
+    },
+  });
+}
+
+function normalizeStyleOutcome(value: string): AuthoredStyleLedgerEntry['outcome'] {
+  return value === 'native' || value === 'preset' || value === 'literal' || value === 'scoped-css' || value === 'blocked'
+    ? value
+    : 'warned';
+}
+
+function toInlineStyleLedgerEntry(entry: StyleLedgerEntry, source: AuthoredStyleLedgerEntry['source']): AuthoredStyleLedgerEntry {
+  // The legacy styling mapper calls this `mapped`/`consumed`; package reports use the more useful
+  // authoring vocabulary. A declaration preserved verbatim inside rich text or Custom HTML is a
+  // literal, while anything the mapper cannot carry is blocking parity loss.
+  const outcome: AuthoredStyleLedgerEntry['outcome'] =
+    entry.outcome === 'mapped'
+      ? 'native'
+      : entry.outcome === 'consumed' || entry.outcome === 'overridden'
+        ? 'literal'
+        : 'blocked';
+  return {
+    property: entry.shorthand ?? entry.property,
+    value: entry.value,
+    outcome,
+    reason: entry.reason,
+    atRules: [],
+    source,
+  };
+}
diff --git a/src/author/styles.ts b/src/author/styles.ts
new file mode 100644
index 0000000..a8cce25
--- /dev/null
+++ b/src/author/styles.ts
@@ -0,0 +1,1324 @@
+/**
+ * Source-style graph utilities for generated blocks.
+ *
+ * This module intentionally does not compile Tailwind. A Tailwind class is not CSS, and guessing
+ * its declaration from a token would make the generated block depend on an unknown version,
+ * configuration, plugin set, source set, and browser target. Callers may give us compiled CSS, but
+ * must first prove the build graph that produced it is complete.
+ *
+ * The scanner is deliberately small and conservative. It preserves the conditional constructs that
+ * can safely remain in a block stylesheet (`@media`, `@supports`, and `@container`) and records all
+ * other global or unsupported constructs rather than silently flattening or dropping them.
+ */
+
+export type BuildGraphField =
+  | 'cssEntries'
+  | 'imports'
+  | 'directives'
+  | 'sources'
+  | 'safelist'
+  | 'plugins'
+  | 'environment'
+  | 'browserTarget';
+
+/**
+ * The inputs that determine a Tailwind (or Tailwind-like) generated stylesheet. Empty arrays are
+ * meaningful: they say that the author explicitly has no imports, safelist, or plugins. Omitted
+ * fields are not meaningful and therefore cannot support a fidelity claim.
+ */
+export interface CssBuildGraph {
+  cssEntries?: readonly string[];
+  imports?: readonly string[];
+  directives?: readonly string[];
+  sources?: readonly string[];
+  safelist?: readonly string[];
+  plugins?: readonly string[];
+  environment?: Readonly<Record<string, string | number | boolean | null | undefined>>;
+  browserTarget?: string | readonly string[];
+}
+
+export interface BuildGraphIssue {
+  field: BuildGraphField;
+  status: 'warning' | 'blocked';
+  reason: string;
+}
+
+export interface BuildGraphValidation {
+  /** All eight graph inputs were supplied and entry/source values are non-empty. */
+  complete: boolean;
+  /** A Tailwind source directive/import or an explicit caller signal was found. */
+  tailwindDetected: boolean;
+  /** The supplied CSS is a compiled, self-contained stylesheet rather than Tailwind source. */
+  compiled: boolean;
+  /** `--tw-*` variables referenced by the CSS but not defined anywhere in that CSS. */
+  unresolvedVariables: string[];
+  /** Tailwind fidelity is blocked for an incomplete graph or an uncompiled/incomplete CSS result. */
+  blocked: boolean;
+  missing: BuildGraphField[];
+  issues: BuildGraphIssue[];
+}
+
+export interface BuildGraphValidationOptions {
+  /** Compiled or source CSS to inspect for Tailwind directives/variables. */
+  css?: string;
+  /** Use when the caller detected Tailwind outside the stylesheet, for example from a config file. */
+  tailwindDetected?: boolean;
+}
+
+const BUILD_GRAPH_FIELDS: readonly BuildGraphField[] = [
+  'cssEntries',
+  'imports',
+  'directives',
+  'sources',
+  'safelist',
+  'plugins',
+  'environment',
+  'browserTarget',
+];
+
+const BUILD_GRAPH_LABELS: Record<BuildGraphField, string> = {
+  cssEntries: 'CSS entry points',
+  imports: 'resolved CSS imports',
+  directives: 'Tailwind/CSS directives',
+  sources: 'explicit content sources',
+  safelist: 'explicit safelist',
+  plugins: 'plugin list',
+  environment: 'build environment',
+  browserTarget: 'browser target',
+};
+
+/**
+ * Validate the source inputs needed to make a Tailwind fidelity statement. This is validation, not
+ * compilation: callers can use it before invoking their own approved compiler and pass the
+ * resulting CSS into `scanStylesheet`.
+ */
+export function validateCssBuildGraph(
+  graph: CssBuildGraph | undefined,
+  options: BuildGraphValidationOptions = {},
+): BuildGraphValidation {
+  const css = options.css ?? '';
+  // Passing a graph is an explicit Tailwind/build-graph signal. A static stylesheet that has no
+  // directive/import is also a valid compiler result even if it no longer contains a recognisable
+  // Tailwind token — there is no safe way (or need) to reverse-engineer its original toolchain.
+  const unresolvedVariables = unresolvedTailwindVariables(css);
+  const tailwindDetected =
+    options.tailwindDetected === true || graph !== undefined || hasTailwindSourceSignal(css) || unresolvedVariables.length > 0;
+  const missing = BUILD_GRAPH_FIELDS.filter((field) => graphFieldMissing(graph, field));
+  const compiled = !hasTailwindSourceSignal(css) && unresolvedVariables.length === 0;
+  const blocked = tailwindDetected && (missing.length > 0 || !compiled);
+  const issues = missing.map<BuildGraphIssue>((field) => ({
+    field,
+    status: blocked ? 'blocked' : 'warning',
+    reason: `${BUILD_GRAPH_LABELS[field]} were not supplied${
+      tailwindDetected
+        ? ' — Tailwind fidelity is blocked until the complete build graph is supplied'
+        : ' — provide the complete source style graph before claiming generated-CSS fidelity'
+    }`,
+  }));
+
+  if (tailwindDetected && !compiled) {
+    issues.push({
+      field: 'directives',
+      status: 'blocked',
+      reason: hasTailwindSourceSignal(css)
+        ? 'Tailwind source directives/imports remain — supply the compiler output, not its source stylesheet'
+        : `compiled CSS still references undefined Tailwind variables: ${unresolvedVariables.join(', ')}`,
+    });
+  }
+
+  return { complete: missing.length === 0, tailwindDetected, compiled, unresolvedVariables, blocked, missing, issues };
+}
+
+/** True only for Tailwind *source* that still needs a compiler, never for compiled declarations. */
+export function hasTailwindSignal(css: string): boolean {
+  return hasTailwindSourceSignal(css);
+}
+
+function hasTailwindSourceSignal(css: string): boolean {
+  return /(?:^|[;{}\s])@(?:tailwind|apply|config|source|theme|utility|variant|custom-variant|plugin)\b|@import\s+(?:url\([^)]*tailwindcss[^)]*\)|["'][^"']*tailwindcss[^"']*["'])/im.test(css);
+}
+
+function unresolvedTailwindVariables(css: string): string[] {
+  const defined = new Set<string>();
+  for (const match of css.matchAll(/(--tw-[\w-]+)\s*:/gi)) {
+    defined.add(match[1].toLowerCase());
+  }
+  const unresolved = new Set<string>();
+  for (const match of css.matchAll(/var\(\s*(--tw-[\w-]+)/gi)) {
+    const name = match[1].toLowerCase();
+    if (!defined.has(name)) {
+      unresolved.add(name);
+    }
+  }
+  return [...unresolved].sort();
+}
+
+function graphFieldMissing(graph: CssBuildGraph | undefined, field: BuildGraphField): boolean {
+  if (!graph || !(field in graph)) {
+    return true;
+  }
+
+  const value = graph[field];
+  if (field === 'cssEntries' || field === 'sources') {
+    return !Array.isArray(value) || value.length === 0 || value.some((entry) => typeof entry !== 'string' || !entry.trim());
+  }
+  if (field === 'browserTarget') {
+    return (
+      (typeof value === 'string' && !value.trim()) ||
+      (typeof value !== 'string' &&
+        (!Array.isArray(value) || value.length === 0 || value.some((entry) => typeof entry !== 'string' || !entry.trim())))
+    );
+  }
+  if (field === 'environment') {
+    return !value || typeof value !== 'object' || Array.isArray(value);
+  }
+
+  // The field's presence is intentional for imports/directives/safelist/plugins: [] is a complete
+  // assertion that there are none, while `undefined` is not.
+  return !Array.isArray(value);
+}
+
+export interface CssPosition {
+  offset: number;
+  line: number;
+  column: number;
+}
+
+export interface CssSourceRange {
+  start: CssPosition;
+  end: CssPosition;
+}
+
+export interface CssDeclaration {
+  id: string;
+  property: string;
+  value: string;
+  important: boolean;
+  source: CssSourceRange;
+}
+
+export interface CssStyleRule {
+  id: string;
+  kind: 'style';
+  selector: string;
+  declarations: CssDeclaration[];
+  source: CssSourceRange;
+  /** Present for CSS nesting. Nested selectors are parsed and ledgered, then conservatively blocked. */
+  nestedIn?: string;
+}
+
+export interface CssConditionalRule {
+  id: string;
+  kind: 'conditional';
+  name: 'media' | 'supports' | 'container';
+  prelude: string;
+  rules: CssRule[];
+  source: CssSourceRange;
+}
+
+export interface CssBlockedRule {
+  id: string;
+  kind: 'blocked';
+  name: string;
+  prelude: string;
+  declarations: CssDeclaration[];
+  rules: CssRule[];
+  reason: string;
+  source: CssSourceRange;
+}
+
+export type CssRule = CssStyleRule | CssConditionalRule | CssBlockedRule;
+
+export type StyleLedgerOutcome = 'pending' | 'native' | 'preset' | 'literal' | 'scoped-css' | 'warned' | 'blocked';
+
+/** One and only one of these entries is created for every parsed source declaration. */
+export interface SourceStyleLedgerEntry {
+  declarationId: string;
+  ruleId: string;
+  property: string;
+  value: string;
+  important: boolean;
+  source: CssSourceRange;
+  atRules: string[];
+  outcome: StyleLedgerOutcome;
+  reason?: string;
+}
+
+export interface CssRuleRecord {
+  ruleId: string;
+  kind: CssRule['kind'];
+  prelude: string;
+  source: CssSourceRange;
+  outcome: 'pending' | 'scoped-css' | 'blocked';
+  reason?: string;
+}
+
+export interface CssStylesheet {
+  rules: CssRule[];
+  ledger: SourceStyleLedgerEntry[];
+  ruleRecords: CssRuleRecord[];
+}
+
+/**
+ * Scan a stylesheet without flattening its conditional structure. CSS comments, quotes, url(),
+ * attribute selectors, and escaped quotes are respected while finding braces and declarations.
+ * Malformed tail content becomes a blocked rule record instead of disappearing.
+ */
+export function scanStylesheet(css: string): CssStylesheet {
+  return new StylesheetScanner(css).scan();
+}
+
+export interface DeclarationDisposition {
+  outcome: Exclude<StyleLedgerOutcome, 'pending' | 'scoped-css'> | 'scoped-css';
+  reason?: string;
+}
+
+export interface ScopeStylesheetOptions {
+  /** The deterministic generated-block root, e.g. `.wp-block-acme-hero`. */
+  root: string;
+  /**
+   * Called only for a safe, local style rule. Returning native/preset/literal leaves that
+   * declaration out of parity CSS; returning nothing keeps it as scoped CSS.
+   */
+  disposition?: (declaration: CssDeclaration, rule: CssStyleRule) => DeclarationDisposition | undefined;
+  /** Rewrite source selector atoms before the root prefix is applied. */
+  selectorTransform?: (selector: string, rule: CssStyleRule) => string;
+}
+
+export interface ScopedStylesheet {
+  root: string;
+  rules: CssRule[];
+  ledger: SourceStyleLedgerEntry[];
+  ruleRecords: CssRuleRecord[];
+  css: string;
+}
+
+/**
+ * Scope safe local selectors under a generated block root. Foundation rules and selectors that can
+ * name or depend on the document outside that root are not rewritten: their declarations and rule
+ * records are explicitly blocked. This is intentionally stricter than merely prefixing every
+ * selector, because that would turn Preflight into a misleading claim of semantic equivalence.
+ */
+export function scopeStylesheet(stylesheet: CssStylesheet, options: ScopeStylesheetOptions): ScopedStylesheet {
+  const ledger = stylesheet.ledger.map((entry) => ({ ...entry, atRules: [...entry.atRules] }));
+  const ledgerByDeclaration = new Map(ledger.map((entry) => [entry.declarationId, entry]));
+  const ruleRecords = stylesheet.ruleRecords.map((record) => ({ ...record }));
+  const recordsByRule = new Map(ruleRecords.map((record) => [record.ruleId, record]));
+  const rootProblem = validateScopeRoot(options.root);
+
+  const blockRule = (rule: CssRule, reason: string): void => {
+    const record = recordsByRule.get(rule.id);
+    if (record) {
+      record.outcome = 'blocked';
+      record.reason = reason;
+    }
+    forEachDeclaration(rule, (declaration) => {
+      const entry = ledgerByDeclaration.get(declaration.id);
+      if (entry) {
+        entry.outcome = 'blocked';
+        entry.reason = reason;
+      }
+    });
+  };
+
+  const scopeRule = (rule: CssRule): CssRule | undefined => {
+    if (rootProblem) {
+      blockRule(rule, rootProblem);
+      return undefined;
+    }
+
+    if (rule.kind === 'blocked') {
+      blockRule(rule, rule.reason);
+      return undefined;
+    }
+
+    if (rule.kind === 'conditional') {
+      const children = rule.rules.map(scopeRule).filter((child): child is CssRule => Boolean(child));
+      const record = recordsByRule.get(rule.id);
+      if (children.length === 0) {
+        if (record) {
+          record.outcome = 'blocked';
+          record.reason = 'contains no safe residual CSS after scoping';
+        }
+        return undefined;
+      }
+      if (record) {
+        record.outcome = 'scoped-css';
+      }
+      return { ...rule, rules: children };
+    }
+
+    if (rule.nestedIn) {
+      blockRule(rule, 'nested CSS selectors are not safely re-rootable without a nesting compiler');
+      return undefined;
+    }
+
+    const scoped = scopeLocalSelectorList(options.selectorTransform?.(rule.selector, rule) ?? rule.selector, options.root);
+    if (!scoped.ok) {
+      blockRule(rule, scoped.reason);
+      return undefined;
+    }
+
+    const declarations: CssDeclaration[] = [];
+    for (const declaration of rule.declarations) {
+      const entry = ledgerByDeclaration.get(declaration.id);
+      const disposition = options.disposition?.(declaration, rule) ?? { outcome: 'scoped-css' as const };
+      if (!entry) {
+        continue;
+      }
+      entry.outcome = disposition.outcome;
+      entry.reason = disposition.reason;
+      if (disposition.outcome === 'scoped-css') {
+        declarations.push(declaration);
+      }
+    }
+
+    const record = recordsByRule.get(rule.id);
+    if (declarations.length === 0) {
+      if (record) {
+        const blocked = rule.declarations.some(
+          (declaration) => ledgerByDeclaration.get(declaration.id)?.outcome === 'blocked',
+        );
+        record.outcome = blocked ? 'blocked' : 'scoped-css';
+        record.reason = blocked
+          ? 'contains no safe residual CSS after declaration safety checks'
+          : 'all declarations were emitted through destination-native styles';
+      }
+      return undefined;
+    }
+    if (record) {
+      record.outcome = 'scoped-css';
+    }
+    return { ...rule, selector: scoped.selector, declarations };
+  };
+
+  const rules = stylesheet.rules.map(scopeRule).filter((rule): rule is CssRule => Boolean(rule));
+  const result: ScopedStylesheet = { root: options.root.trim(), rules, ledger, ruleRecords, css: '' };
+  result.css = renderResidualCss(result);
+  return result;
+}
+
+/** Render the original rule order in a normalized, deterministic format. */
+export function renderResidualCss(stylesheet: Pick<ScopedStylesheet, 'rules'>): string {
+  return stylesheet.rules.map((rule) => renderRule(rule, 0)).filter(Boolean).join('\n');
+}
+
+/** Prefix a safe selector list, retaining pseudo states and a comma-list's original ordering. */
+export function scopeLocalSelectorList(
+  selectorList: string,
+  root: string,
+): { ok: true; selector: string } | { ok: false; reason: string } {
+  const rootProblem = validateScopeRoot(root);
+  if (rootProblem) {
+    return { ok: false, reason: rootProblem };
+  }
+
+  const selectors = splitTopLevel(selectorList, ',').map((selector) => selector.trim()).filter(Boolean);
+  if (selectors.length === 0) {
+    return { ok: false, reason: 'empty selector cannot be scoped' };
+  }
+
+  for (const selector of selectors) {
+    const problem = unsafeSelectorReason(selector);
+    if (problem) {
+      return { ok: false, reason: problem };
+    }
+  }
+
+  return { ok: true, selector: selectors.map((selector) => `${root.trim()} ${selector}`).join(', ') };
+}
+
+export interface SelectorDependencyTransport {
+  /** Marker conditions the conversion DOM must retain before native blocks discard raw attributes. */
+  dependencies: SourceSelectorDependency[];
+  /** Rewrite only id/attribute selector atoms; ordinary class selectors remain author-visible. */
+  rewrite(selector: string): string;
+}
+
+/**
+ * Preserve selector semantics across native conversion without blindly copying arbitrary source
+ * attributes onto block attributes (which Gutenberg would silently discard). Each `#id` and
+ * `[attribute]` atom becomes a deterministic class that is attached only to source elements that
+ * actually match it. The scoped stylesheet then selects that transport class instead.
+ */
+export function createSelectorDependencyTransport(): SelectorDependencyTransport {
+  const dependencies: SourceSelectorDependency[] = [];
+  const markers = new Map<string, string>();
+  const usedMarkers = new Set<string>();
+
+  const markerFor = (kind: SourceSelectorDependency['kind'], value: string): string => {
+    const key = `${kind}\u0000${value}`;
+    const existing = markers.get(key);
+    if (existing) {
+      return existing;
+    }
+    const base = `block-runner-selector-${kind}-${fnv1a(value)}`;
+    let marker = base;
+    let suffix = 1;
+    while (usedMarkers.has(marker)) {
+      suffix += 1;
+      marker = `${base}-${suffix}`;
+    }
+    usedMarkers.add(marker);
+    markers.set(key, marker);
+    dependencies.push({ markerClass: marker, kind, value });
+    return marker;
+  };
+
+  return {
+    dependencies,
+    rewrite(selector) {
+      let output = '';
+      let index = 0;
+      let quote: string | undefined;
+
+      while (index < selector.length) {
+        const char = selector[index];
+        if (quote) {
+          output += char;
+          if (char === '\\') {
+            output += selector[index + 1] ?? '';
+            index += 2;
+            continue;
+          }
+          if (char === quote) {
+            quote = undefined;
+          }
+          index += 1;
+          continue;
+        }
+        if (char === '"' || char === "'") {
+          quote = char;
+          output += char;
+          index += 1;
+          continue;
+        }
+        if (char === '#') {
+          const identifier = readCssIdentifier(selector, index + 1);
+          if (identifier) {
+            output += `.${markerFor('id', identifier.value)}`;
+            index = identifier.end;
+            continue;
+          }
+        }
+        if (char === '[') {
+          const attribute = readAttributeSelector(selector, index);
+          if (attribute) {
+            output += `.${markerFor('attribute', attribute.value)}`;
+            index = attribute.end;
+            continue;
+          }
+        }
+        output += char;
+        index += 1;
+      }
+      return output;
+    },
+  };
+}
+
+/** Read class names from selectors/CSS with CSS escape semantics (`.\\32xl\\:block` → `2xl:block`). */
+export function referencedCssClasses(css: string): string[] {
+  const classes = new Set<string>();
+  let index = 0;
+  let quote: string | undefined;
+  let comment = false;
+
+  while (index < css.length) {
+    if (comment) {
+      if (css[index] === '*' && css[index + 1] === '/') {
+        comment = false;
+        index += 2;
+      } else {
+        index += 1;
+      }
+      continue;
+    }
+    if (quote) {
+      if (css[index] === '\\') {
+        index += 2;
+      } else {
+        if (css[index] === quote) quote = undefined;
+        index += 1;
+      }
+      continue;
+    }
+    if (css[index] === '/' && css[index + 1] === '*') {
+      comment = true;
+      index += 2;
+      continue;
+    }
+    if (css[index] === '"' || css[index] === "'") {
+      quote = css[index];
+      index += 1;
+      continue;
+    }
+    if (css[index] === '.') {
+      const identifier = readCssIdentifier(css, index + 1);
+      if (identifier) {
+        classes.add(identifier.value);
+        index = identifier.end;
+        continue;
+      }
+    }
+    index += 1;
+  }
+  return [...classes];
+}
+
+function readCssIdentifier(value: string, start: number): { value: string; end: number } | undefined {
+  let decoded = '';
+  let index = start;
+  while (index < value.length) {
+    const char = value[index];
+    if (char === '\\') {
+      const escaped = readCssEscape(value, index + 1);
+      if (!escaped) break;
+      decoded += escaped.value;
+      index = escaped.end;
+      continue;
+    }
+    if (!isCssIdentifierCharacter(char)) {
+      break;
+    }
+    decoded += char;
+    index += 1;
+  }
+  return decoded ? { value: decoded, end: index } : undefined;
+}
+
+function readCssEscape(value: string, start: number): { value: string; end: number } | undefined {
+  if (start >= value.length) return undefined;
+  let end = start;
+  while (end < value.length && end - start < 6 && /[0-9a-f]/i.test(value[end])) {
+    end += 1;
+  }
+  if (end > start) {
+    const codePoint = Number.parseInt(value.slice(start, end), 16);
+    if (/\s/.test(value[end] ?? '')) end += 1;
+    return {
+      value: codePoint === 0 || codePoint > 0x10ffff ? '\uFFFD' : String.fromCodePoint(codePoint),
+      end,
+    };
+  }
+  return { value: value[start], end: start + 1 };
+}
+
+function isCssIdentifierCharacter(value: string): boolean {
+  return /[-_A-Za-z0-9]/.test(value) || value.codePointAt(0)! >= 0x80;
+}
+
+function readAttributeSelector(value: string, start: number): { value: string; end: number } | undefined {
+  let index = start + 1;
+  let quote: string | undefined;
+  while (index < value.length) {
+    const char = value[index];
+    if (quote) {
+      if (char === '\\') {
+        index += 2;
+        continue;
+      }
+      if (char === quote) quote = undefined;
+      index += 1;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      index += 1;
+      continue;
+    }
+    if (char === '\\') {
+      index += 2;
+      continue;
+    }
+    if (char === ']') {
+      return { value: value.slice(start, index + 1), end: index + 1 };
+    }
+    index += 1;
+  }
+  return undefined;
+}
+
+function fnv1a(value: string): string {
+  let hash = 0x811c9dc5;
+  for (const char of value) {
+    hash ^= char.codePointAt(0)!;
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(36);
+}
+
+function validateScopeRoot(root: string): string | undefined {
+  const value = root.trim();
+  if (!value) {
+    return 'generated block root is required for residual CSS';
+  }
+  if (/[{},;]/.test(value) || value.includes('\n') || value.includes('\r')) {
+    return 'generated block root is not a single safe selector';
+  }
+  return undefined;
+}
+
+function unsafeSelectorReason(selector: string): string | undefined {
+  const normalized = unescapeCss(selector).toLowerCase();
+  if (!normalized) {
+    return 'empty selector cannot be scoped';
+  }
+  if (/^[>+~]/.test(normalized) || /[&]|\/deep\/|>>>/.test(normalized)) {
+    return 'selector uses a relative, nested, or deep-combinator form that cannot be safely rooted';
+  }
+  if (/:global\s*\(|:host(?:-context)?\b|::(?:part|slotted|backdrop)\b|:scope\b/.test(normalized)) {
+    return 'selector can escape the generated block subtree';
+  }
+  if (/(?:^|[\s>+~,(])(?:html|body)(?=$|[\s>+~.#[:])|:root\b/.test(normalized)) {
+    return 'global document selector is not safe to scope';
+  }
+  // A bare element, universal selector, or pseudo-only selector is a foundation/Preflight rule.
+  // It can be rendered below a root, but doing so changes the rule from global CSS to component CSS
+  // and must not be called semantically equivalent without an explicit foundation policy.
+  if (!/[.#\[]/.test(normalized)) {
+    return 'global foundation/Preflight selector is not scoped as an equivalent block rule';
+  }
+  return undefined;
+}
+
+function renderRule(rule: CssRule, depth: number): string {
+  const indent = '  '.repeat(depth);
+  if (rule.kind === 'style') {
+    if (rule.declarations.length === 0) {
+      return '';
+    }
+    const body = rule.declarations
+      .map((declaration) => `${declaration.property}: ${declaration.value}${declaration.important ? ' !important' : ''};`)
+      .join(' ');
+    return `${indent}${rule.selector} { ${body} }`;
+  }
+  if (rule.kind === 'conditional') {
+    const body = rule.rules.map((child) => renderRule(child, depth + 1)).filter(Boolean).join('\n');
+    return body ? `${indent}@${rule.name} ${rule.prelude} {\n${body}\n${indent}}` : '';
+  }
+  return '';
+}
+
+function forEachDeclaration(rule: CssRule, visit: (declaration: CssDeclaration) => void): void {
+  if (rule.kind === 'style' || rule.kind === 'blocked') {
+    for (const declaration of rule.declarations) {
+      visit(declaration);
+    }
+  }
+  if (rule.kind === 'conditional' || rule.kind === 'blocked') {
+    for (const child of rule.rules) {
+      forEachDeclaration(child, visit);
+    }
+  }
+}
+
+class StylesheetScanner {
+  private readonly css: string;
+  private readonly lineStarts: number[];
+  private readonly ledger: SourceStyleLedgerEntry[] = [];
+  private readonly ruleRecords: CssRuleRecord[] = [];
+  private ruleNumber = 0;
+  private declarationNumber = 0;
+
+  constructor(css: string) {
+    this.css = css;
+    this.lineStarts = [0];
+    for (let index = 0; index < css.length; index += 1) {
+      if (css[index] === '\n') {
+        this.lineStarts.push(index + 1);
+      }
+    }
+  }
+
+  scan(): CssStylesheet {
+    return { rules: this.parseRules(0, this.css.length, []), ledger: this.ledger, ruleRecords: this.ruleRecords };
+  }
+
+  private parseRules(start: number, end: number, atRules: string[]): CssRule[] {
+    const rules: CssRule[] = [];
+    let cursor = start;
+
+    while (cursor < end) {
+      cursor = skipTrivia(this.css, cursor, end);
+      if (cursor >= end) {
+        break;
+      }
+      const headerStart = cursor;
+      const boundary = findRuleBoundary(this.css, cursor, end);
+      if (!boundary) {
+        const id = this.nextRuleId();
+        const source = this.range(headerStart, end);
+        const reason = 'unterminated stylesheet rule';
+        const rule: CssBlockedRule = {
+          id,
+          kind: 'blocked',
+          name: 'malformed',
+          prelude: this.css.slice(headerStart, end).trim(),
+          declarations: [],
+          rules: [],
+          reason,
+          source,
+        };
+        this.recordRule(rule, 'pending');
+        rules.push(rule);
+        break;
+      }
+
+      const header = this.css.slice(headerStart, boundary.index).trim();
+      if (boundary.kind === ';') {
+        if (header) {
+          rules.push(this.parseStatement(header, headerStart, boundary.index + 1));
+        }
+        cursor = boundary.index + 1;
+        continue;
+      }
+      if (boundary.kind === '}') {
+        // The caller owns this closing brace. At top level it is malformed but is still recorded.
+        if (header) {
+          const id = this.nextRuleId();
+          const source = this.range(headerStart, boundary.index + 1);
+          const rule: CssBlockedRule = {
+            id,
+            kind: 'blocked',
+            name: 'malformed',
+            prelude: header,
+            declarations: [],
+            rules: [],
+            reason: 'unexpected closing brace in stylesheet',
+            source,
+          };
+          this.recordRule(rule, 'pending');
+          rules.push(rule);
+        }
+        cursor = boundary.index + 1;
+        continue;
+      }
+
+      const close = findMatchingBrace(this.css, boundary.index, end);
+      if (close === -1) {
+        const id = this.nextRuleId();
+        const source = this.range(headerStart, end);
+        const rule: CssBlockedRule = {
+          id,
+          kind: 'blocked',
+          name: header.startsWith('@') ? atRuleName(header) : 'malformed',
+          prelude: header,
+          declarations: [],
+          rules: [],
+          reason: 'unterminated stylesheet block',
+          source,
+        };
+        this.recordRule(rule, 'pending');
+        rules.push(rule);
+        break;
+      }
+
+      if (header.startsWith('@')) {
+        rules.push(this.parseAtRule(header, headerStart, boundary.index + 1, close, atRules));
+      } else if (header) {
+        rules.push(this.parseStyleRule(header, headerStart, boundary.index + 1, close, atRules));
+      }
+      cursor = close + 1;
+    }
+
+    return rules;
+  }
+
+  private parseStatement(header: string, start: number, end: number): CssBlockedRule {
+    const id = this.nextRuleId();
+    const name = header.startsWith('@') ? atRuleName(header) : 'statement';
+    const reason = name === 'import' ? '@import is a source-graph dependency and is never emitted into a generated block' : 'standalone CSS statement is not safe residual block CSS';
+    const rule: CssBlockedRule = {
+      id,
+      kind: 'blocked',
+      name,
+      prelude: header,
+      declarations: [],
+      rules: [],
+      reason,
+      source: this.range(start, end),
+    };
+    this.recordRule(rule, 'pending');
+    return rule;
+  }
+
+  private parseAtRule(header: string, start: number, bodyStart: number, close: number, atRules: string[]): CssRule {
+    const id = this.nextRuleId();
+    const name = atRuleName(header);
+    const prelude = header.slice(name.length + 1).trim();
+    const source = this.range(start, close + 1);
+
+    if (name === 'media' || name === 'supports' || name === 'container') {
+      const rule: CssConditionalRule = {
+        id,
+        kind: 'conditional',
+        name,
+        prelude,
+        rules: this.parseRules(bodyStart, close, [...atRules, `@${name} ${prelude}`.trim()]),
+        source,
+      };
+      this.recordRule(rule, 'pending');
+      return rule;
+    }
+
+    const reason = blockedAtRuleReason(name);
+    const descriptors = isDescriptorAtRule(name);
+    const declarations = descriptors ? this.parseDeclarations(bodyStart, close, id, [...atRules, header]) : [];
+    // Even a blocked at-rule can contain authored selector rules. Parse those children purely for
+    // accounting so `@layer { .card { … } }` cannot lose its declarations behind one aggregate
+    // "unsupported at-rule" warning. They remain blocked by the parent during scoping.
+    const rules = descriptors ? [] : this.parseRules(bodyStart, close, [...atRules, header]);
+    const rule: CssBlockedRule = { id, kind: 'blocked', name, prelude, declarations, rules, reason, source };
+    this.recordRule(rule, 'pending');
+    return rule;
+  }
+
+  private parseStyleRule(
+    selector: string,
+    start: number,
+    bodyStart: number,
+    close: number,
+    atRules: string[],
+    nestedIn?: string,
+  ): CssStyleRule {
+    const id = this.nextRuleId();
+    const rule: CssStyleRule = {
+      id,
+      kind: 'style',
+      selector,
+      declarations: this.parseDeclarations(bodyStart, close, id, atRules),
+      source: this.range(start, close + 1),
+      ...(nestedIn ? { nestedIn } : {}),
+    };
+    this.recordRule(rule, 'pending');
+    return rule;
+  }
+
+  /** Parse declaration statements, retaining every authored declaration rather than expanding it. */
+  private parseDeclarations(start: number, end: number, ruleId: string, atRules: string[]): CssDeclaration[] {
+    const declarations: CssDeclaration[] = [];
+    let cursor = start;
+
+    while (cursor < end) {
+      cursor = skipTrivia(this.css, cursor, end);
+      if (cursor >= end) {
+        break;
+      }
+      const segmentStart = cursor;
+      const boundary = findRuleBoundary(this.css, cursor, end);
+      if (!boundary || boundary.kind === '}') {
+        const declaration = this.parseDeclaration(segmentStart, end, ruleId, atRules);
+        if (declaration) {
+          declarations.push(declaration);
+        }
+        break;
+      }
+      if (boundary.kind === ';') {
+        const declaration = this.parseDeclaration(segmentStart, boundary.index, ruleId, atRules);
+        if (declaration) {
+          declarations.push(declaration);
+        }
+        cursor = boundary.index + 1;
+        continue;
+      }
+
+      // A block in a declaration body is CSS nesting or an at-rule. Its declarations still need
+      // ledger entries, so parse it as a nested selector and leave it for the scoper to block.
+      const close = findMatchingBrace(this.css, boundary.index, end);
+      if (close === -1) {
+        break;
+      }
+      const nestedHeader = this.css.slice(segmentStart, boundary.index).trim();
+      if (nestedHeader.startsWith('@')) {
+        const nested = this.parseAtRule(nestedHeader, segmentStart, boundary.index + 1, close, atRules);
+        this.markNestedRuleBlocked(nested);
+      } else if (nestedHeader) {
+        const nested = this.parseStyleRule(nestedHeader, segmentStart, boundary.index + 1, close, atRules, ruleId);
+        this.markNestedRuleBlocked(nested);
+      }
+      cursor = close + 1;
+    }
+    return declarations;
+  }
+
+  private parseDeclaration(start: number, end: number, ruleId: string, atRules: string[]): CssDeclaration | undefined {
+    const raw = stripComments(this.css.slice(start, end)).trim();
+    if (!raw) {
+      return undefined;
+    }
+    const colon = indexOfTopLevel(raw, ':');
+    if (colon === -1) {
+      this.recordMalformedDeclaration(raw, start, end, ruleId, atRules, 'not a parseable CSS declaration');
+      return undefined;
+    }
+    const property = raw.slice(0, colon).trim();
+    const rawValue = raw.slice(colon + 1).trim();
+    if (!property || !rawValue) {
+      this.recordMalformedDeclaration(raw, start, end, ruleId, atRules, 'CSS declaration needs both a property and a value');
+      return undefined;
+    }
+    const importantMatch = /^(.*?)\s*!\s*important\s*$/is.exec(rawValue);
+    const value = (importantMatch?.[1] ?? rawValue).trim();
+    if (!value) {
+      return undefined;
+    }
+    const declaration: CssDeclaration = {
+      id: this.nextDeclarationId(),
+      property,
+      value,
+      important: Boolean(importantMatch),
+      source: this.range(start, end),
+    };
+    this.ledger.push({
+      declarationId: declaration.id,
+      ruleId,
+      property,
+      value,
+      important: declaration.important,
+      source: declaration.source,
+      atRules: [...atRules],
+      outcome: 'pending',
+    });
+    return declaration;
+  }
+
+  private recordMalformedDeclaration(
+    raw: string,
+    start: number,
+    end: number,
+    ruleId: string,
+    atRules: string[],
+    reason: string,
+  ): void {
+    const colon = indexOfTopLevel(raw, ':');
+    this.ledger.push({
+      declarationId: this.nextDeclarationId(),
+      ruleId,
+      property: (colon === -1 ? raw : raw.slice(0, colon)).trim() || '<empty>',
+      value: colon === -1 ? '' : raw.slice(colon + 1).trim(),
+      important: false,
+      source: this.range(start, end),
+      atRules: [...atRules],
+      outcome: 'warned',
+      reason,
+    });
+  }
+
+  private nextRuleId(): string {
+    this.ruleNumber += 1;
+    return `rule-${this.ruleNumber}`;
+  }
+
+  private nextDeclarationId(): string {
+    this.declarationNumber += 1;
+    return `declaration-${this.declarationNumber}`;
+  }
+
+  private recordRule(rule: CssRule, outcome: CssRuleRecord['outcome']): void {
+    this.ruleRecords.push({
+      ruleId: rule.id,
+      kind: rule.kind,
+      prelude: rule.kind === 'style' ? rule.selector : `@${rule.name} ${rule.prelude}`.trim(),
+      source: rule.source,
+      outcome,
+      ...(rule.kind === 'blocked' ? { reason: rule.reason } : {}),
+    });
+  }
+
+  /**
+   * CSS nesting needs a nesting compiler to combine `&` and parent selectors. We still scan every
+   * nested declaration, then mark it now because the nested rule is not a standalone CSS rule that
+   * can safely be emitted later.
+   */
+  private markNestedRuleBlocked(rule: CssRule): void {
+    const reason = 'nested CSS requires a nesting compiler before it can be safely block-scoped';
+    const record = this.ruleRecords.find((entry) => entry.ruleId === rule.id);
+    if (record) {
+      record.outcome = 'blocked';
+      record.reason = reason;
+    }
+    forEachDeclaration(rule, (declaration) => {
+      const ledger = this.ledger.find((entry) => entry.declarationId === declaration.id);
+      if (ledger) {
+        ledger.outcome = 'blocked';
+        ledger.reason = reason;
+      }
+    });
+  }
+
+  private range(start: number, end: number): CssSourceRange {
+    return { start: this.position(start), end: this.position(end) };
+  }
+
+  private position(offset: number): CssPosition {
+    let low = 0;
+    let high = this.lineStarts.length;
+    while (low + 1 < high) {
+      const middle = Math.floor((low + high) / 2);
+      if (this.lineStarts[middle] <= offset) {
+        low = middle;
+      } else {
+        high = middle;
+      }
+    }
+    return { offset, line: low + 1, column: offset - this.lineStarts[low] + 1 };
+  }
+}
+
+function blockedAtRuleReason(name: string): string {
+  if (name === 'import') {
+    return '@import is a source-graph dependency and is never emitted into a generated block';
+  }
+  if (name === 'font-face') {
+    return '@font-face is global and font licensing/asset handling must be decided separately';
+  }
+  if (isKeyframes(name)) {
+    return '@keyframes are global identifiers and require collision-safe renaming before they can be emitted';
+  }
+  return `@${name} is not a safe, block-scoped residual CSS construct`;
+}
+
+function isKeyframes(name: string): boolean {
+  return /(?:^|-)keyframes$/i.test(name);
+}
+
+/** At-rules whose bodies are descriptor declarations rather than nested selector rules. */
+function isDescriptorAtRule(name: string): boolean {
+  return name === 'font-face' || name === 'property' || name === 'counter-style' || name === 'page';
+}
+
+function atRuleName(header: string): string {
+  return /^@([\w-]+)/.exec(header)?.[1].toLowerCase() ?? 'unknown';
+}
+
+function skipTrivia(css: string, start: number, end: number): number {
+  let cursor = start;
+  while (cursor < end) {
+    if (/\s/.test(css[cursor])) {
+      cursor += 1;
+      continue;
+    }
+    if (css[cursor] === '/' && css[cursor + 1] === '*') {
+      const close = css.indexOf('*/', cursor + 2);
+      cursor = close === -1 || close >= end ? end : close + 2;
+      continue;
+    }
+    break;
+  }
+  return cursor;
+}
+
+type RuleBoundary = { index: number; kind: '{' | ';' | '}' };
+
+function findRuleBoundary(css: string, start: number, end: number): RuleBoundary | undefined {
+  let quote: string | undefined;
+  let escaped = false;
+  let parens = 0;
+  let brackets = 0;
+
+  for (let index = start; index < end; index += 1) {
+    const char = css[index];
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === quote) {
+        quote = undefined;
+      }
+      continue;
+    }
+    if (char === '/' && css[index + 1] === '*') {
+      const close = css.indexOf('*/', index + 2);
+      if (close === -1 || close >= end) {
+        return undefined;
+      }
+      index = close + 1;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === '(') {
+      parens += 1;
+    } else if (char === ')') {
+      parens = Math.max(0, parens - 1);
+    } else if (char === '[') {
+      brackets += 1;
+    } else if (char === ']') {
+      brackets = Math.max(0, brackets - 1);
+    } else if (parens === 0 && brackets === 0 && (char === '{' || char === ';' || char === '}')) {
+      return { index, kind: char };
+    }
+  }
+  return undefined;
+}
+
+function findMatchingBrace(css: string, open: number, end: number): number {
+  let quote: string | undefined;
+  let escaped = false;
+  let depth = 0;
+
+  for (let index = open; index < end; index += 1) {
+    const char = css[index];
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === quote) {
+        quote = undefined;
+      }
+      continue;
+    }
+    if (char === '/' && css[index + 1] === '*') {
+      const close = css.indexOf('*/', index + 2);
+      if (close === -1 || close >= end) {
+        return -1;
+      }
+      index = close + 1;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === '{') {
+      depth += 1;
+    } else if (char === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+  return -1;
+}
+
+function splitTopLevel(value: string, separator: string): string[] {
+  const out: string[] = [];
+  let start = 0;
+  let quote: string | undefined;
+  let escaped = false;
+  let parens = 0;
+  let brackets = 0;
+
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === quote) {
+        quote = undefined;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === '(') {
+      parens += 1;
+    } else if (char === ')') {
+      parens = Math.max(0, parens - 1);
+    } else if (char === '[') {
+      brackets += 1;
+    } else if (char === ']') {
+      brackets = Math.max(0, brackets - 1);
+    } else if (char === separator && parens === 0 && brackets === 0) {
+      out.push(value.slice(start, index));
+      start = index + 1;
+    }
+  }
+  out.push(value.slice(start));
+  return out;
+}
+
+function indexOfTopLevel(value: string, separator: string): number {
+  let quote: string | undefined;
+  let escaped = false;
+  let parens = 0;
+  let brackets = 0;
+
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === quote) {
+        quote = undefined;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === '(') {
+      parens += 1;
+    } else if (char === ')') {
+      parens = Math.max(0, parens - 1);
+    } else if (char === '[') {
+      brackets += 1;
+    } else if (char === ']') {
+      brackets = Math.max(0, brackets - 1);
+    } else if (char === separator && parens === 0 && brackets === 0) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function stripComments(value: string): string {
+  let out = '';
+  let quote: string | undefined;
+  let escaped = false;
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (quote) {
+      out += char;
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === quote) {
+        quote = undefined;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      out += char;
+      continue;
+    }
+    if (char === '/' && value[index + 1] === '*') {
+      const close = value.indexOf('*/', index + 2);
+      if (close === -1) {
+        break;
+      }
+      index = close + 1;
+      continue;
+    }
+    out += char;
+  }
+  return out;
+}
+
+/** Decode enough CSS escapes to stop escaped `body`/`:root` spellings bypassing the safety gate. */
+function unescapeCss(value: string): string {
+  return value.replace(/\\([0-9a-f]{1,6}\s?|.)/gi, (_, escaped: string) => {
+    const hex = escaped.trim();
+    if (/^[0-9a-f]{1,6}$/i.test(hex)) {
+      const point = Number.parseInt(hex, 16);
+      return Number.isSafeInteger(point) ? String.fromCodePoint(point) : '';
+    }
+    return escaped;
+  });
+}
+import type { SourceSelectorDependency } from '../types.js';
diff --git a/src/cli.ts b/src/cli.ts
index 439259f..5a0029e 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -10,6 +10,7 @@ import fg from 'fast-glob';
 import { canonicalize } from './gate/canonicalize.js';
 import { validate } from './gate/validate.js';
 import { convert } from './convert/assemble.js';
+import { author } from './author/index.js';
 import { realize } from './intent/index.js';
 import { loadConfig } from './config/load.js';
 import { collectSiteContext } from './context/run.js';
@@ -29,6 +30,10 @@ interface CliOptions extends CommonOptions {
   out?: string;
   cssOut?: string;
   wpAppPasswordEnv?: string;
+  name?: string;
+  title?: string;
+  category?: string;
+  outDir?: string;
 }
 
 interface ContextCliOptions {
@@ -92,6 +97,45 @@ addTokenOptions(
     process.exitCode = report.ok ? 0 : 1;
   });
 
+addTokenOptions(
+  addWpCredentialOptions(
+    addSharedOptions(program.command('author <htmlOrStdin>').description('Generate one static, registered block package.'), {
+      output: false,
+    }),
+  ),
+  { styling: false },
+)
+  .requiredOption('--name <namespace/slug>', 'registered block name, for example acme/hero')
+  .option('--title <title>', 'block title (defaults from the slug)')
+  .option('--category <category>', 'block category (default: widgets)')
+  .option('--out-dir <path>', 'write the generated package and copied assets to this directory')
+  .action(async (htmlOrStdin: string, options: CliOptions) => {
+    const apiOptions = normalizeOptions(options);
+    const inputs = await readInputs(htmlOrStdin, { allowInline: true });
+    if (inputs.length !== 1) {
+      program.error('error: author accepts exactly one design input because it generates exactly one registered block');
+    }
+    if (!options.outDir && !options.json) {
+      program.error('error: author needs --out-dir <path> to write its package, or --json to inspect the generated package');
+    }
+    const input = inputs[0];
+    if (!input) {
+      return;
+    }
+    const report = await author(input.content, {
+      ...apiOptions,
+      sourcePath: input.path,
+      outDir: options.outDir,
+      author: {
+        name: options.name,
+        title: options.title,
+        category: options.category,
+      },
+    });
+    await emit(report, options, inputs);
+    process.exitCode = report.ok ? 0 : 1;
+  });
+
 addTokenOptions(
   addWpCredentialOptions(
     addSharedOptions(program.command('assemble <jsonOrStdin>').description('Assemble an intent tree into native block markup.')),
@@ -409,7 +453,7 @@ function addTokenOptions(command: Command, options: { styling?: boolean } = {}):
 }
 
 function normalizeOptions(options: CliOptions): CommonOptions {
-  const { config, json, out, wpAppPasswordEnv, ...rest } = options;
+  const { config, json, out, wpAppPasswordEnv, name, title, category, outDir, ...rest } = options;
   const wpAppPassword = wpAppPasswordEnv ? process.env[wpAppPasswordEnv] : rest.wpAppPassword;
   return {
     ...rest,
diff --git a/src/config/schema.ts b/src/config/schema.ts
index c3272d2..078d745 100644
--- a/src/config/schema.ts
+++ b/src/config/schema.ts
@@ -62,6 +62,12 @@ export function mergeConfig(config: BlockRunnerConfig = {}, options: CommonOptio
       context: options.context ?? config.tokens?.context,
     },
     rules: normalizeRules(config.rules),
+    author: config.author
+      ? {
+          ...config.author,
+          styles: config.author.styles ? { ...config.author.styles } : undefined,
+        }
+      : undefined,
   };
 }
 
diff --git a/src/convert/assemble.ts b/src/convert/assemble.ts
index 5aa8f2e..41c62d0 100644
--- a/src/convert/assemble.ts
+++ b/src/convert/assemble.ts
@@ -21,7 +21,15 @@ import {
   StylingRung,
   WpBlock,
 } from '../types.js';
-import { contextHtml, contextText, isElementNode, makeContextWarning, prepareDom, sourceForNode } from './dom.js';
+import {
+  contextHtml,
+  contextText,
+  isElementNode,
+  makeContextWarning,
+  prepareDom,
+  retainSelectorDependencies,
+  sourceForNode,
+} from './dom.js';
 import { defaultRules } from './defaults.js';
 import { finalizeBlocks } from './finalize.js';
 import { walkChildren } from './walk.js';
@@ -66,6 +74,10 @@ async function runConvert(
   wp: Awaited<ReturnType<typeof getWp>>,
 ): Promise<BlockRunnerReport> {
   const prepared = prepareDom(input, options.sourcePath);
+  retainSelectorDependencies(
+    prepared.dom.window.document,
+    options.preserveSourceSelectorDependencies ?? [],
+  );
   const warnings: ReportItem[] = [...prepared.warnings];
   const explainItems: ReportItem[] = [];
   const rules = buildRules(config);
@@ -90,6 +102,7 @@ async function runConvert(
     explain: options.explain === true,
     cssBackgrounds: prepared.cssBackgrounds,
     cssClassRules: prepared.cssClassRules,
+    preserveAssetForms: options.preserveAssetForms === true,
     warn(reason, node, block, rule, details) {
       warnings.push(makeContextWarning(context, reason, node, block, rule, details));
     },
@@ -117,6 +130,19 @@ async function runConvert(
           })
         : unattributableStyles(element, blocks.length, prepared.cssClassRules);
 
+      // Registered-block authoring owns a stylesheet rooted at its generated wrapper. Retain only
+      // the source classes that stylesheet actually references, and only on the one native block
+      // that claimed this source element. The ordinary convert path deliberately keeps its prior
+      // no-source-class output, so a transport class can never leak accidentally into post content.
+      if (block && options.preserveSourceClasses) {
+        const retained = new Set(options.preserveSourceClasses);
+        for (const className of element.classList) {
+          if (retained.has(className)) {
+            addClassName(block, className);
+          }
+        }
+      }
+
       reportLedger(carryToSidecar(ledger, block), element, block?.name, 'styles');
     },
     noteRichTextStyles(node, block, rule) {
@@ -224,6 +250,7 @@ async function runConvert(
   // `overridden` and clean `mapped` outcomes are accounted for under --explain, because warning on
   // them would bury the entries that need action.
   function reportLedger(ledger: StyleLedgerEntry[], element: Element, block: string | undefined, rule: string): void {
+    options.styleLedgerObserver?.(ledger, context.sourceFor(element), block);
     for (const entry of ledger) {
       const authored = entry.shorthand ? `${entry.shorthand} (${entry.property})` : entry.property;
       // An unparseable chunk has no value to quote — it *is* the quoted text. Name the rule a
diff --git a/src/convert/dom.ts b/src/convert/dom.ts
index e1d2f7b..5e45ea1 100644
--- a/src/convert/dom.ts
+++ b/src/convert/dom.ts
@@ -1,5 +1,5 @@
 import { JSDOM } from 'jsdom';
-import { ReportItem, RuleContext, SourceLocation } from '../types.js';
+import { ReportItem, RuleContext, SourceLocation, SourceSelectorDependency } from '../types.js';
 import { effectiveDeclarations } from '../styles/apply.js';
 import { extractUrl } from '../styles/declarations.js';
 import { Declaration, parseDeclarationBlock, parseInlineStyle, resolvePrecedence } from '../styles/parse.js';
@@ -31,6 +31,36 @@ export function prepareDom(input: string, sourcePath?: string): PreparedDom {
   };
 }
 
+/**
+ * Native blocks cannot retain arbitrary source attributes, and most cannot retain a raw `id`.
+ * Registered-block authoring rewrites those selector atoms to marker classes, then marks the
+ * matching source elements before conversion so the scoped CSS still selects the same nodes.
+ */
+export function retainSelectorDependencies(document: Document, dependencies: readonly SourceSelectorDependency[]): void {
+  if (dependencies.length === 0) {
+    return;
+  }
+
+  for (const element of [...document.querySelectorAll('*')]) {
+    for (const dependency of dependencies) {
+      if (dependency.kind === 'id') {
+        if (element.id === dependency.value) {
+          element.classList.add(dependency.markerClass);
+        }
+        continue;
+      }
+      try {
+        if (element.matches(dependency.value)) {
+          element.classList.add(dependency.markerClass);
+        }
+      } catch {
+        // The stylesheet scanner will report the associated selector as blocked rather than
+        // pretending an invalid attribute selector has a meaningful runtime dependency.
+      }
+    }
+  }
+}
+
 export function sanitizeDocument(dom: JSDOM, warnings: ReportItem[], sourcePath?: string): void {
   const document = dom.window.document;
 
diff --git a/src/convert/walk.ts b/src/convert/walk.ts
index 3a83dce..b64de17 100644
--- a/src/convert/walk.ts
+++ b/src/convert/walk.ts
@@ -36,6 +36,13 @@ export async function walkNode(node: Node, context: RuleContext): Promise<WpBloc
     return [emitCustomHtml(node, context, 'foreign element emitted as Custom HTML fallback')];
   }
 
+  // `srcset` and inline `image-set()` values describe multiple concrete assets. Core's simple
+  // media blocks only retain one URL, so authoring preserves the original markup rather than
+  // emitting a successful-looking block that silently drops candidates.
+  if (context.preserveAssetForms && hasNonNativeAssetForm(node)) {
+    return [emitCustomHtml(node, context, 'asset-bearing source form emitted as Custom HTML fallback')];
+  }
+
   for (const rule of context.rules) {
     let matched: boolean;
     let reason: string | undefined;
@@ -81,6 +88,10 @@ export async function walkNode(node: Node, context: RuleContext): Promise<WpBloc
   return [];
 }
 
+function hasNonNativeAssetForm(node: Element): boolean {
+  return node.hasAttribute('srcset') || /(?:-webkit-)?image-set\s*\(/i.test(node.getAttribute('style') ?? '');
+}
+
 function emitCustomHtml(node: Element, context: RuleContext, reason: string): WpBlock {
   context.warn(reason, node, 'core/html', 'html');
   const block = createHtmlFallback(context.wp, node.outerHTML);
diff --git a/src/index.ts b/src/index.ts
index 3532df4..733c6ae 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,6 +1,21 @@
 export { canonicalize } from './gate/canonicalize.js';
 export { validate } from './gate/validate.js';
 export { convert } from './convert/assemble.js';
+export { author } from './author/index.js';
+export {
+  hasTailwindSignal,
+  renderResidualCss,
+  scanStylesheet,
+  scopeLocalSelectorList,
+  scopeStylesheet,
+  validateCssBuildGraph,
+} from './author/styles.js';
+export {
+  classifyCssUrlReference,
+  processCssAssets,
+  rewriteCssAssets,
+  scanCssUrlReferences,
+} from './author/assets.js';
 export { assemble, extractIntent, realize } from './intent/index.js';
 export { compileAuthoringBlock, compileAuthoringPlan } from './authoring/compile.js';
 export { collectSiteContext } from './context/run.js';
@@ -50,6 +65,13 @@ export type {
   AuthoringPlan,
   AuthoringRole,
   AuthoringTemplate,
+  AssetLedgerEntry,
+  AssetOutcome,
+  AuthoredStyleLedgerEntry,
+  AuthoredStyleOutcome,
+  AuthorConfig,
+  AuthorOptions,
+  AuthorStyleConfig,
   BlockRunnerConfig,
   BlockRunnerReport,
   CanonicalizeOptions,
@@ -60,6 +82,7 @@ export type {
   IntentNode,
   IntentTree,
   InnerBlocksLock,
+  GeneratedBlockPackage,
   MediaConfig,
   MediaMapEntry,
   MediaResult,
@@ -78,6 +101,7 @@ export type {
   TokenMatchMode,
   TokenResolver,
   TokenResolverKind,
+  TailwindBuildGraph,
   ValidateOptions,
   WpBlock,
 } from './types.js';
diff --git a/src/styles/apply.ts b/src/styles/apply.ts
index 73fc62d..107a82e 100644
--- a/src/styles/apply.ts
+++ b/src/styles/apply.ts
@@ -135,6 +135,12 @@ function collectDeclarations(input: ApplyStylesInput) {
 export function applyElementStyles(input: ApplyStylesInput): StyleLedgerEntry[] {
   const { element, block } = input;
 
+  // A Custom HTML fallback can contain inline styles below its outer element, and the walker does
+  // not visit those descendants. Inspect it before the root-only fast path below.
+  if (block.name === 'core/html') {
+    return customHtmlStyles(element, input);
+  }
+
   const { declarations, overridden, problems } = collectDeclarations(input);
   if (declarations.length === 0 && overridden.length === 0 && problems.length === 0) {
     return [];
@@ -152,25 +158,44 @@ export function applyElementStyles(input: ApplyStylesInput): StyleLedgerEntry[]
     ...overridden.map(overriddenEntry),
   ];
 
-  // A Custom HTML fallback keeps the original markup verbatim, style attribute and all. Mapping
-  // it onto the wrapper would apply the same CSS twice.
-  if (block.name === 'core/html') {
-    return [
-      ...accounting,
-      ...declarations.map((declaration) => ({
-        ...declaration,
-        outcome: 'consumed' as const,
-        reason: 'preserved inline in the Custom HTML fallback',
-      })),
-    ];
-  }
-
   return [
     ...accounting,
     ...declarations.map((declaration) => noteImportant(declaration, applyDeclaration(declaration, input))),
   ];
 }
 
+/**
+ * The walker claims a Custom HTML fallback at its outer element and intentionally does not walk
+ * descendants. Their inline declarations nevertheless survive verbatim, so account every one
+ * here rather than leaving nested styles (and their asset-bearing values) invisible to authoring.
+ */
+function customHtmlStyles(root: Element, input: ApplyStylesInput): StyleLedgerEntry[] {
+  const entries: StyleLedgerEntry[] = [];
+  for (const element of [root, ...root.querySelectorAll('*')]) {
+    const { declarations, overridden, problems } = collectDeclarations({
+      element,
+      classRules: input.classRules,
+    } as ApplyStylesInput);
+    entries.push(
+      ...problems.map<StyleLedgerEntry>((chunk) => ({
+        property: chunk,
+        value: '',
+        outcome: 'consumed',
+        reason: 'preserved verbatim in the Custom HTML fallback',
+      })),
+      ...overridden.map(overriddenEntry),
+      ...declarations.map<StyleLedgerEntry>((declaration) => ({
+        ...declaration,
+        outcome: 'consumed',
+        reason: declaration.origin
+          ? 'preserved by the authored selector in the Custom HTML fallback'
+          : 'preserved inline in the Custom HTML fallback',
+      })),
+    );
+  }
+  return entries;
+}
+
 /** A mapped declaration that was authored `!important` landed without its priority — say so. */
 function noteImportant(declaration: Declaration, entry: StyleLedgerEntry): StyleLedgerEntry {
   if (!declaration.important || entry.outcome !== 'mapped') {
diff --git a/src/types.ts b/src/types.ts
index 6dd74e1..3952a72 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -1,6 +1,7 @@
+import type { StyleLedgerEntry } from './styles/apply.js';
 import type { Declaration } from './styles/parse.js';
 
-export type CommandName = 'validate' | 'fix' | 'convert' | 'assemble';
+export type CommandName = 'validate' | 'fix' | 'convert' | 'assemble' | 'author';
 
 export type ReportStatus = 'valid' | 'invalid' | 'warning';
 
@@ -12,6 +13,17 @@ export interface SourceLocation {
   offset?: number;
 }
 
+/**
+ * A selector condition rewritten to a transport class before native conversion removes arbitrary
+ * source IDs/attributes. It is internal to the registered-block authoring handoff.
+ */
+export interface SourceSelectorDependency {
+  markerClass: string;
+  kind: 'id' | 'attribute';
+  /** Decoded id value, or the complete attribute selector such as `[data-state="open"]`. */
+  value: string;
+}
+
 export interface ReportItem {
   block?: string;
   status: ReportStatus;
@@ -42,6 +54,83 @@ export interface BlockRunnerReport {
    * honest if it does, which is why `open` requires an explicit sink.
    */
   sidecarCss?: string;
+  /**
+   * Every asset observed while authoring a registered block.  This is deliberately separate from
+   * Gutenberg media IDs: static block assets do not need (and must never invent) media-library
+   * records.
+   */
+  assets?: AssetLedgerEntry[];
+  /** One terminal disposition for every declaration in an authored stylesheet graph. */
+  styleLedger?: AuthoredStyleLedgerEntry[];
+  /** Files that make up an authored registered block, keyed by their package-relative path. */
+  package?: GeneratedBlockPackage;
+}
+
+export type AuthoredStyleOutcome = 'native' | 'preset' | 'literal' | 'scoped-css' | 'warned' | 'blocked';
+
+export interface AuthoredStyleLedgerEntry {
+  property: string;
+  value: string;
+  outcome: AuthoredStyleOutcome;
+  reason?: string;
+  atRules: string[];
+  source?: SourceLocation;
+}
+
+/** The terminal disposition of a source asset. */
+export type AssetOutcome = 'copied' | 'uploaded' | 'reused' | 'external' | 'unresolved' | 'blocked';
+
+export interface AssetLedgerEntry {
+  /** The source spelling, before any package-relative rewrite. */
+  reference: string;
+  /** The package-relative replacement, where a local asset was copied. */
+  rewritten?: string;
+  /** How the asset was encountered. */
+  kind: 'image' | 'font' | 'stylesheet' | 'media' | 'other';
+  outcome: AssetOutcome;
+  reason?: string;
+  source?: SourceLocation;
+}
+
+/**
+ * Inputs required to make a Tailwind fidelity claim.  Empty arrays/objects are meaningful: they
+ * say that a project has explicitly supplied no plugins/safelist/etc.  An omitted field is not
+ * equivalent to an empty one and is reported as missing.
+ */
+export interface TailwindBuildGraph {
+  cssEntries?: string[];
+  imports?: string[];
+  directives?: string[];
+  sources?: string[];
+  safelist?: string[];
+  plugins?: string[];
+  environment?: Record<string, string | undefined>;
+  browserTarget?: string | string[];
+}
+
+export interface AuthorStyleConfig {
+  /** Actual compiled CSS. Block Runner never derives it from Tailwind class tokens. */
+  css?: string;
+  /** Optional source build graph, required when the CSS uses Tailwind directives or variables. */
+  tailwind?: TailwindBuildGraph;
+  /** Explicitly supplied editor-only affordances. Parity CSS is always emitted through `style`. */
+  editorCss?: string;
+}
+
+export interface AuthorConfig {
+  /** Namespace/slug, for example `acme/hero`. Must name exactly one registered block. */
+  name?: string;
+  title?: string;
+  category?: string;
+  /** Optional known supports of the generated block. Values are never assumed from a slug. */
+  supports?: Record<string, unknown>;
+  styles?: AuthorStyleConfig;
+}
+
+export interface GeneratedBlockPackage {
+  name: string;
+  rootSelector: string;
+  files: Record<string, string>;
 }
 
 export type ResolverKind = 'noop' | 'map' | 'wpcli' | 'rest';
@@ -131,6 +220,8 @@ export interface BlockRunnerConfig {
   media?: MediaConfig;
   tokens?: TokenConfig;
   rules?: RuleConfig | unknown[];
+  /** Registered-block authoring options. Kept separate from the legacy post-content converter. */
+  author?: AuthorConfig;
 }
 
 export interface CommonOptions {
@@ -151,6 +242,24 @@ export interface CommonOptions {
 
 export interface ConvertOptions extends CommonOptions {
   config?: BlockRunnerConfig;
+  /**
+   * Internal authoring hook: retain only source classes referenced by generated scoped CSS on the
+   * native block that claimed the source element. Undefined preserves legacy conversion output.
+   */
+  preserveSourceClasses?: readonly string[];
+  /** Internal authoring handoff for IDs/attributes referenced by the generated scoped CSS. */
+  preserveSourceSelectorDependencies?: readonly SourceSelectorDependency[];
+  /** Internal authoring boundary for asset forms a native Core block cannot faithfully retain. */
+  preserveAssetForms?: boolean;
+  /** Internal observer used by registered-block authoring to account for inline declarations. */
+  styleLedgerObserver?: (entries: readonly StyleLedgerEntry[], source: SourceLocation, block?: string) => void;
+}
+
+export interface AuthorOptions extends ConvertOptions {
+  /** Directory to write the generated package. Omit to inspect `report.package` without writing. */
+  outDir?: string;
+  /** Per-run author settings, which override `config.author`. */
+  author?: AuthorConfig;
 }
 
 export interface AssembleOptions extends CommonOptions {
@@ -342,6 +451,8 @@ export interface RuleContext {
    * should resolve it from these plus the inline attribute, never from either alone.
    */
   cssClassRules: Array<{ className: string; declarations: Declaration[]; problems: string[] }>;
+  /** Preserve asset-bearing source markup as Custom HTML when a native block would drop it. */
+  preserveAssetForms?: boolean;
   /**
    * Carry an element's inline CSS onto the block a rule just claimed. Called by the walker for
    * every claimed node; rules never need to invoke it.
diff --git a/test/author.test.ts b/test/author.test.ts
new file mode 100644
index 0000000..d213591
--- /dev/null
+++ b/test/author.test.ts
@@ -0,0 +1,247 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { classifyCssUrlReference, rewriteCssAssets, scanCssUrlReferences } from '../src/author/assets.js';
+import { author } from '../src/author/index.js';
+import { scanStylesheet, scopeStylesheet, validateCssBuildGraph } from '../src/author/styles.js';
+
+const scratch: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(scratch.splice(0).map((directory) => rm(directory, { recursive: true, force: true })));
+});
+
+describe('registered-block stylesheet graph', () => {
+  it('keeps responsive, state, and container rules beneath the generated root', () => {
+    const scoped = scopeStylesheet(
+      scanStylesheet(`
+        @media (min-width: 48rem) { .hero:hover { color: rebeccapurple; } }
+        @container card (inline-size > 30rem) { .card::before { content: ""; display: block; } }
+      `),
+      { root: '.wp-block-acme-hero' },
+    );
+
+    expect(scoped.css).toContain('@media (min-width: 48rem)');
+    expect(scoped.css).toContain('.wp-block-acme-hero .hero:hover');
+    expect(scoped.css).toContain('@container card (inline-size > 30rem)');
+    expect(scoped.css).toContain('.wp-block-acme-hero .card::before');
+    expect(scoped.ledger.every((entry) => entry.outcome === 'scoped-css')).toBe(true);
+  });
+
+  it('blocks global foundation and escaping selectors rather than pretending that a prefix preserves them', () => {
+    const scoped = scopeStylesheet(
+      scanStylesheet(`html, body { margin: 0; } * { box-sizing: border-box; } :root { color: red; } .card { color: blue; }`),
+      { root: '.wp-block-acme-hero' },
+    );
+
+    expect(scoped.css).toContain('.wp-block-acme-hero .card');
+    expect(scoped.css).not.toContain('box-sizing');
+    expect(scoped.ledger.filter((entry) => entry.outcome === 'blocked')).toHaveLength(3);
+    expect(scoped.ruleRecords.filter((rule) => rule.outcome === 'blocked').map((rule) => rule.reason).join('\n')).toMatch(
+      /global|foundation|Preflight/i,
+    );
+  });
+
+  it('gives declarations inside blocked layers and malformed declarations an explicit ledger outcome', () => {
+    const scoped = scopeStylesheet(
+      scanStylesheet(`@layer utilities { .card { color: teal; } } .notice { broken; padding: ; }`),
+      { root: '.wp-block-acme-hero' },
+    );
+
+    expect(scoped.css).toBe('');
+    expect(scoped.ledger).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ property: 'color', outcome: 'blocked' }),
+        expect.objectContaining({ property: 'broken', outcome: 'warned' }),
+        expect.objectContaining({ property: 'padding', outcome: 'warned' }),
+      ]),
+    );
+  });
+
+  it('lets the caller block a declaration without leaving unsafe residual CSS behind', () => {
+    const scoped = scopeStylesheet(scanStylesheet(`.card { behavior: url(widget.htc); color: teal; }`), {
+      root: '.wp-block-acme-hero',
+      disposition: (declaration) =>
+        declaration.property === 'behavior'
+          ? { outcome: 'blocked', reason: 'requires executable browser behaviour' }
+          : undefined,
+    });
+
+    expect(scoped.css).toContain('color: teal');
+    expect(scoped.css).not.toContain('behavior');
+    expect(scoped.ledger).toContainEqual(expect.objectContaining({ property: 'behavior', outcome: 'blocked' }));
+  });
+
+  it('requires the complete explicit Tailwind graph before fidelity can be claimed', () => {
+    const missing = validateCssBuildGraph(undefined, { css: '@tailwind utilities;' });
+    expect(missing.blocked).toBe(true);
+    expect(missing.missing).toEqual([
+      'cssEntries',
+      'imports',
+      'directives',
+      'sources',
+      'safelist',
+      'plugins',
+      'environment',
+      'browserTarget',
+    ]);
+
+    const complete = validateCssBuildGraph(
+      {
+        cssEntries: ['src/style.css'],
+        imports: [],
+        directives: ['@tailwind utilities'],
+        sources: ['src/**/*.html'],
+        safelist: [],
+        plugins: [],
+        environment: {},
+        browserTarget: 'defaults',
+      },
+      { css: '.utility { --tw-translate-x: 0; transform: translateX(var(--tw-translate-x)); }' },
+    );
+    expect(complete.complete).toBe(true);
+    expect(complete.compiled).toBe(true);
+    expect(complete.blocked).toBe(false);
+
+    const incompleteOutput = validateCssBuildGraph(
+      {
+        cssEntries: ['src/style.css'],
+        imports: [],
+        directives: ['@tailwind utilities'],
+        sources: ['src/**/*.html'],
+        safelist: [],
+        plugins: [],
+        environment: {},
+        browserTarget: 'defaults',
+      },
+      { css: '.utility { transform: translateX(var(--tw-translate-x)); }' },
+    );
+    expect(incompleteOutput.blocked).toBe(true);
+    expect(incompleteOutput.issues.map((issue) => issue.reason).join('\n')).toMatch(/undefined Tailwind variables/i);
+
+    const selfContainedOutput = validateCssBuildGraph(undefined, {
+      css: '.utility { --tw-translate-x: 0; transform: translateX(var(--tw-translate-x)); }',
+    });
+    expect(selfContainedOutput.compiled).toBe(true);
+    expect(selfContainedOutput.blocked).toBe(false);
+  });
+});
+
+describe('registered-block CSS assets', () => {
+  it('classifies remote, inline, unsafe, and unlicensed font URLs without fetching them', () => {
+    const refs = scanCssUrlReferences(
+      `a{background:url(https://cdn.example/a.png)} b{background:url(data:image/png;base64,AA)} c{mask:url(javascript:alert(1))} @font-face{src:url(font.woff2)}`,
+      '/design/style.css',
+    );
+    expect(refs.map((ref) => classifyCssUrlReference(ref, { sourcePath: '/design/style.css' }).outcome)).toEqual([
+      'external',
+      'external',
+      'blocked',
+      'unresolved',
+    ]);
+  });
+
+  it('copies local CSS assets once and rewrites every reference to the package asset', async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), 'block-runner-author-'));
+    scratch.push(directory);
+    const design = path.join(directory, 'design.html');
+    const sourceAsset = path.join(directory, 'logo.svg');
+    const destination = path.join(directory, 'block', 'assets');
+    await writeFile(design, '<style></style>');
+    await writeFile(sourceAsset, '<svg/>');
+
+    const result = await rewriteCssAssets({
+      sourcePath: design,
+      sourceCss: `.logo { background-image: url("./logo.svg"); } .again { mask-image: url(./logo.svg); }`,
+      destinationAssetDir: destination,
+    });
+
+    expect(result.assets.map((asset) => asset.outcome)).toEqual(['copied', 'copied']);
+    const [first, second] = result.assets;
+    expect(first).toBeDefined();
+    expect(second).toBeDefined();
+    expect(first!.rewrittenUrl).toBe(second!.rewrittenUrl);
+    expect(result.css).not.toContain('./logo.svg');
+    expect(await readFile(first!.destinationAssetPath!, 'utf8')).toBe('<svg/>');
+  });
+
+  it('blocks a relative URL that escapes the stylesheet asset root', async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), 'block-runner-author-'));
+    scratch.push(directory);
+    const design = path.join(directory, 'assets', 'design.html');
+    const outside = path.join(directory, '.env');
+    await mkdir(path.dirname(design), { recursive: true });
+    await writeFile(design, '<style></style>');
+    await writeFile(outside, 'do-not-copy');
+
+    const reference = scanCssUrlReferences('x{background:url(../.env)}', design)[0]!;
+    expect(classifyCssUrlReference(reference, { sourcePath: design })).toMatchObject({ outcome: 'blocked' });
+  });
+});
+
+describe('registered-block authoring parity ledger', () => {
+  it('maps a stylesheet declaration once to a supported native destination without duplicate CSS', async () => {
+    const report = await author('<style>.notice { color: red; }</style><p class="notice">Hello</p>', {
+      author: { name: 'acme/notice' },
+    });
+
+    expect(report.ok).toBe(true);
+    expect(report.styleLedger).toContainEqual(expect.objectContaining({ property: 'color', outcome: 'native' }));
+    expect(report.package?.files['style.css']).toBeUndefined();
+    expect(report.package?.files['index.js']).toContain('"color"');
+  });
+
+  it('refuses to write a package after dropping a blocked selector or declaration', async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), 'block-runner-author-'));
+    scratch.push(directory);
+    const outDir = path.join(directory, 'package');
+
+    const report = await author('<style>body { color: red; }</style><p>Hello</p>', {
+      outDir,
+      author: { name: 'acme/notice' },
+    });
+
+    expect(report.ok).toBe(false);
+    await expect(readFile(path.join(outDir, 'block.json'), 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
+  });
+
+  it('retains escaped class, ID, and attribute selector dependencies through native conversion', async () => {
+    const report = await author(
+      '<style>@media (min-width: 40rem) { .\\32xl\\:open#hero[data-state="open"] { color: red; } }</style><p id="hero" data-state="open" class="2xl:open">Hello</p>',
+      { author: { name: 'acme/notice' } },
+    );
+
+    expect(report.ok).toBe(true);
+    expect(report.package?.files['style.css']).toContain('.\\32xl\\:open.block-runner-selector-id-');
+    expect(report.package?.files['index.js']).toContain('"className": "2xl:open block-runner-selector-id-');
+    expect(report.package?.files['index.js']).toContain('block-runner-selector-attribute-');
+  });
+
+  it('accounts for inline CSS and rewrites srcset assets retained in Custom HTML', async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), 'block-runner-author-'));
+    scratch.push(directory);
+    const design = path.join(directory, 'design.html');
+    const source = path.join(directory, 'photo.png');
+    const outDir = path.join(directory, 'package');
+    await writeFile(design, '');
+    await writeFile(source, 'photo');
+
+    const report = await author(
+      '<p style="color: red">Hello</p><img src="photo.png" srcset="photo.png 1x, photo.png 2x"><div><span style="background-image:image-set(\'photo.png\' 1x)"></span></div>',
+      {
+      sourcePath: design,
+      outDir,
+      author: { name: 'acme/notice' },
+      },
+    );
+
+    expect(report.ok).toBe(true);
+    expect(report.styleLedger).toContainEqual(expect.objectContaining({ property: 'color', outcome: 'native' }));
+    expect(report.styleLedger).toContainEqual(expect.objectContaining({ property: 'background-image', outcome: 'literal' }));
+    expect(report.assets?.filter((asset) => asset.reference === 'photo.png')).toHaveLength(4);
+    expect(report.package?.files['index.js']).toContain('srcset=');
+    expect(report.package?.files['index.js']).toContain('image-set(');
+    expect(await readFile(path.join(outDir, 'block.json'), 'utf8')).toContain('acme/notice');
+  });
+});

From e0c9b68d2c0008e4800593f4fd77468409b507df Mon Sep 17 00:00:00 2001
From: Noel Tock <hello@noeltock.com>
Date: Thu, 3 Sep 2026 13:43:12 +0700
Subject: [PATCH 2/4] Translate Tailwind/CSS into destination-native styles and
 assets

Closes #5
---
 README.md               |  15 +-
 package-lock.json       |   5 +-
 package.json            |   2 +
 src/author/assets.ts    |  96 ++++++---
 src/author/index.ts     | 277 ++++++++++++++++++++-----
 src/author/styles.ts    | 442 +++++++++++++++++++++++++++++++++++++---
 src/convert/assemble.ts |  27 ++-
 src/convert/dom.ts      |  94 +++------
 src/index.ts            |   4 +
 src/styles/apply.ts     |  19 ++
 src/styles/parse.ts     |   8 +
 src/types.ts            |  57 +++++-
 test/author.test.ts     | 241 +++++++++++++++++++++-
 13 files changed, 1082 insertions(+), 205 deletions(-)

diff --git a/README.md b/README.md
index fd9cfb7..a4239c2 100644
--- a/README.md
+++ b/README.md
@@ -391,12 +391,15 @@ comes from a block plugin, or is dropped, and every drop or escalation is report
 
 ### Registered-block CSS and assets
 
-`author` accepts compiled CSS through `author.styles.css` (or `<style>` content in the design).
-It does not infer Tailwind output from class names or ship Tailwind at runtime. When Tailwind is
-detected, supply its complete `author.styles.tailwind` graph: CSS entries, resolved imports and
-directives, sources, safelist, plugins, environment, and browser target. Missing inputs are
-reported field by field and generation stops; the supplied CSS must be compiler output, with every
-referenced `--tw-*` variable defined in that output.
+`author` accepts compiled CSS through `author.styles.css` (or `<style>` content in the design), but
+its `author.styles.mode` must explicitly be `css` or `tailwind`. It does not infer Tailwind from
+compiled utility declarations or ship it at runtime. In `tailwind` mode, supply the complete
+`author.styles.tailwind` graph: CSS entries, resolved imports and directives, sources, safelist,
+plugins, environment, browser target, and the project’s pinned compiler. `author` materializes that
+graph and runs the compiler; source directives use its output, while separately supplied CSS must
+match it. Missing inputs, unreadable entries/imports, compiler failures, and mismatches are reported
+field by field and generation stops. Every referenced `--tw-*` variable must also be defined in that
+output.
 
 Non-native selectors are preserved only when they can be rooted beneath the generated block's
 deterministic `.wp-block-<namespace>-<slug>` class. Responsive, container-query, and pseudo-state
diff --git a/package-lock.json b/package-lock.json
index a31f3b6..038f61e 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -16,6 +16,8 @@
         "commander": "15.0.0",
         "fast-glob": "3.3.3",
         "jsdom": "29.1.1",
+        "react": "18.3.1",
+        "react-dom": "18.3.1",
         "wesper": "0.0.2"
       },
       "bin": {
@@ -6005,7 +6007,6 @@
       "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz",
       "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "loose-envify": "^1.1.0"
       },
@@ -6069,7 +6070,6 @@
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz",
       "integrity": "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "loose-envify": "^1.1.0",
         "scheduler": "^0.23.2"
@@ -6417,7 +6417,6 @@
       "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz",
       "integrity": "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "loose-envify": "^1.1.0"
       }
diff --git a/package.json b/package.json
index 7b69621..21d1896 100644
--- a/package.json
+++ b/package.json
@@ -82,6 +82,8 @@
     "commander": "15.0.0",
     "fast-glob": "3.3.3",
     "jsdom": "29.1.1",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
     "wesper": "0.0.2"
   },
   "devDependencies": {
diff --git a/src/author/assets.ts b/src/author/assets.ts
index 41acc52..6883efe 100644
--- a/src/author/assets.ts
+++ b/src/author/assets.ts
@@ -604,16 +604,17 @@ function imageSetStringReferences(
   fontRanges: Array<{ start: number; end: number }>,
 ): CssUrlReference[] {
   const references: CssUrlReference[] = [];
-  let index = start;
-  while (index < end) {
-    if (!isQuote(css[index])) {
-      index += 1;
+  for (const candidate of imageSetCandidates(css, start, end)) {
+    // CSS Images permits a direct string only in the candidate image position. Quoted strings in
+    // descriptors such as `type("image/avif")`, or inside url(), are not assets themselves.
+    const candidateStart = skipCssSpaceAndComments(css, candidate.start, candidate.end);
+    if (!isQuote(css[candidateStart])) {
       continue;
     }
-    const quote = css[index];
-    const valueStart = index + 1;
+    const quote = css[candidateStart];
+    const valueStart = candidateStart + 1;
     let cursor = valueStart;
-    while (cursor < end) {
+    while (cursor < candidate.end) {
       if (css[cursor] === '\\') {
         cursor += 2;
         continue;
@@ -621,28 +622,75 @@ function imageSetStringReferences(
       if (css[cursor] === quote) break;
       cursor += 1;
     }
-    if (cursor >= end) break;
-
-    // A quoted `url("...")` candidate is accounted for by the ordinary url() scanner. Only
-    // image-set's direct string grammar needs this additional reference type.
-    const before = css.slice(Math.max(start, index - 12), index);
-    if (!/url\(\s*$/i.test(before)) {
-      const value = unescapeCssUrl(css.slice(valueStart, cursor).trim());
-      references.push({
-        raw: css.slice(index, cursor + 1),
-        url: value,
-        start: index,
-        end: cursor + 1,
-        location: locationAt(css, index, sourcePath),
-        kind: fontRanges.some((range) => index >= range.start && index < range.end) || isFontUrl(value) ? 'font' : 'asset',
-        syntax: 'string',
-      });
+    if (cursor >= candidate.end) {
+      continue;
     }
-    index = cursor + 1;
+    const value = unescapeCssUrl(css.slice(valueStart, cursor).trim());
+    references.push({
+      raw: css.slice(candidateStart, cursor + 1),
+      url: value,
+      start: candidateStart,
+      end: cursor + 1,
+      location: locationAt(css, candidateStart, sourcePath),
+      kind: fontRanges.some((range) => candidateStart >= range.start && candidateStart < range.end) || isFontUrl(value) ? 'font' : 'asset',
+      syntax: 'string',
+    });
   }
   return references;
 }
 
+/** Top-level image-set candidates; commas in url(), type(), comments, and strings stay nested. */
+function imageSetCandidates(css: string, start: number, end: number): Array<{ start: number; end: number }> {
+  const candidates: Array<{ start: number; end: number }> = [];
+  let candidateStart = start;
+  let depth = 0;
+  let quote: string | undefined;
+  for (let index = start; index < end; index += 1) {
+    const char = css[index];
+    if (quote) {
+      if (char === '\\') index += 1;
+      else if (char === quote) quote = undefined;
+      continue;
+    }
+    if (startsComment(css, index)) {
+      index = skipComment(css, index + 2) - 1;
+      continue;
+    }
+    if (isQuote(char)) {
+      quote = char;
+      continue;
+    }
+    if (char === '(') {
+      depth += 1;
+      continue;
+    }
+    if (char === ')') {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+    if (char === ',' && depth === 0) {
+      candidates.push({ start: candidateStart, end: index });
+      candidateStart = index + 1;
+    }
+  }
+  candidates.push({ start: candidateStart, end });
+  return candidates;
+}
+
+function skipCssSpaceAndComments(css: string, start: number, end: number): number {
+  let index = start;
+  while (index < end) {
+    if (/\s/.test(css[index])) {
+      index += 1;
+    } else if (startsComment(css, index)) {
+      index = Math.min(end, skipComment(css, index + 2));
+    } else {
+      break;
+    }
+  }
+  return index;
+}
+
 function unescapeCssUrl(value: string): string {
   return value.replace(/\\([0-9A-Fa-f]{1,6}[ \t\r\n\f]?|.)/g, (_, escaped: string) => {
     const hexadecimal = /^([0-9A-Fa-f]{1,6})/.exec(escaped)?.[1];
diff --git a/src/author/index.ts b/src/author/index.ts
index b5d8514..6ece06a 100644
--- a/src/author/index.ts
+++ b/src/author/index.ts
@@ -16,21 +16,23 @@ import {
 } from '../types.js';
 import { classifyCssUrlReference, rewriteCssAssets, scanCssUrlReferences } from './assets.js';
 import {
+  compileTailwindBuildGraph,
   createSelectorDependencyTransport,
+  hasTailwindSignal,
   referencedCssClasses,
   scanStylesheet,
   scopeStylesheet,
   validateCssBuildGraph,
 } from './styles.js';
-import type { StyleLedgerEntry } from '../styles/apply.js';
+import { sourceDeclarationKey, type StyleLedgerEntry } from '../styles/apply.js';
 
 /**
  * Produce the small, static source package for one registered block.
  *
  * This is deliberately an authoring path rather than a variation on `convert`: conversion emits
  * post content, while this function creates a block root which owns its CSS/assets.  It accepts
- * compiled CSS only.  It never runs Tailwind, guesses utility classes, downloads a remote asset,
- * or manufactures a media ID.
+ * plain CSS directly, or Tailwind only through the caller's pinned compiler. It never guesses
+ * utility classes, downloads a remote asset, or manufactures a media ID.
  */
 export async function author(input: string, options: AuthorOptions = {}): Promise<BlockRunnerReport> {
   const config = await loadConfig(options);
@@ -50,11 +52,61 @@ export async function author(input: string, options: AuthorOptions = {}): Promis
   }
 
   const rootSelector = `.wp-block-${name.replace('/', '-')}`;
-  const styleInput = definition.styles?.css ?? stylesFromHtml(input);
-  const buildGraph = validateCssBuildGraph(definition.styles?.tailwind, { css: styleInput });
-  const stylesheet = scanStylesheet(styleInput);
+  let styleInput = definition.styles?.css ?? stylesFromHtml(input);
+  const styleMode = definition.styles?.mode;
+  if (styleInput.trim() && styleMode !== 'css' && styleMode !== 'tailwind') {
+    return authorFailure(
+      'author.styles.mode must explicitly be "css" or "tailwind" whenever stylesheet input is supplied',
+    );
+  }
+  if (styleMode !== undefined && styleMode !== 'css' && styleMode !== 'tailwind') {
+    return authorFailure('author.styles.mode must be "css" or "tailwind"');
+  }
+  if (styleMode === 'css' && definition.styles?.tailwind) {
+    return authorFailure('author.styles.tailwind requires author.styles.mode to be "tailwind"');
+  }
+  if (styleMode === 'css' && (hasTailwindSignal(styleInput) || hasTailwindRuntimeSignal(styleInput))) {
+    return authorFailure('Tailwind source or runtime CSS requires author.styles.mode to be "tailwind"');
+  }
+  let buildGraph = validateCssBuildGraph(definition.styles?.tailwind, {
+    css: styleInput,
+    tailwindDetected: styleMode === 'tailwind',
+  });
+  let compilerIssues: ReportItem[] = [];
+
+  if (buildGraph.tailwindDetected) {
+    // Do not treat a field-complete graph as proof. First materialize and run its own pinned
+    // compiler, then either use that result (Tailwind source in the design) or compare it with
+    // separately supplied output.
+    if (buildGraph.missing.length === 0 && definition.styles?.tailwind) {
+      const expectedCss = definition.styles?.css !== undefined || (buildGraph.compiled && styleInput.trim())
+        ? styleInput
+        : undefined;
+      const compiled = await compileTailwindBuildGraph(definition.styles.tailwind, {
+        sourcePath: options.sourcePath,
+        expectedCss,
+      });
+      compilerIssues = compiled.issues.map((issue) => ({
+        block: name,
+        status: 'warning' as const,
+        reason: issue.reason,
+        details: { outcome: issue.status, field: issue.field },
+      }));
+      if (compiled.css) {
+        // In source mode this is the CSS that is scanned, scoped, and made available to the
+        // converter. In output mode the equality check above proves it is the same CSS.
+        styleInput = compiled.css;
+      }
+      buildGraph = validateCssBuildGraph(definition.styles.tailwind, {
+        css: styleInput,
+        tailwindDetected: true,
+        provenanceVerified: compiled.verified,
+      });
+    }
+  }
+  const safetyStylesheet = scanStylesheet(styleInput);
   const selectorTransport = createSelectorDependencyTransport();
-  const safetyScopedStyles = scopeStylesheet(stylesheet, {
+  const safetyScopedStyles = scopeStylesheet(safetyStylesheet, {
     root: rootSelector,
     disposition: (declaration) => unsafeResidualDeclaration(declaration.property, declaration.value),
     selectorTransform: selectorTransport.rewrite,
@@ -69,6 +121,7 @@ export async function author(input: string, options: AuthorOptions = {}): Promis
       reason: issue.reason,
       details: { outcome: issue.status, field: issue.field },
     })),
+    ...compilerIssues,
     ...safetyScopedStyles.ledger
       .filter((entry) => entry.outcome === 'warned' || entry.outcome === 'blocked')
       .map<ReportItem>((entry) => ({
@@ -115,7 +168,36 @@ export async function author(input: string, options: AuthorOptions = {}): Promis
       styleLedger: safetyLedger,
     };
   }
-  const nativeSource = await collectNativeSourceDeclarations(input, options, config);
+  const sourceAssets = scanCssUrlReferences(styleInput, options.sourcePath).map((reference) =>
+    toAssetLedgerEntry(
+      classifyCssUrlReference(reference, {
+        sourcePath: options.sourcePath,
+        allowFontLicense: false,
+      }),
+    ),
+  );
+  const destinationAssetDir = options.outDir
+    ? path.join(options.outDir, 'assets')
+    : path.join(process.cwd(), '.block-runner-unwritten-assets');
+  // Rewriting is part of source identity: the native probe, declaration suppression, residual
+  // stylesheet, and final conversion must all read the same values. Probing the original source
+  // but emitting rewritten `url()` values makes a mixed native/scoped declaration miss its
+  // suppression key and land twice.
+  const processedSource = await rewriteCssAssets({
+    sourceCss: styleInput,
+    sourcePath: options.outDir ? options.sourcePath : undefined,
+    destinationAssetDir,
+    allowFontLicense: false,
+  });
+  let assets: AssetLedgerEntry[] = mergeAssetLedgers(sourceAssets, processedSource.assets.map(toAssetLedgerEntry));
+  styleInput = processedSource.css;
+  const stylesheet = scanStylesheet(styleInput);
+  // The converter's native-mapping probe must see the same compiled stylesheet as the CSS
+  // scanner, including the final local-asset rewrites. A configured stylesheet otherwise has no
+  // `<style>` node for its class rules, and Tailwind source would be incorrectly treated as an
+  // empty stylesheet.
+  const sourceStyledInput = withAuthorStyles(input, styleInput);
+  const nativeSource = await collectNativeSourceDeclarations(sourceStyledInput, options, config);
   const preflightStyleLedger = [...safetyLedger, ...nativeSource.inlineLedger];
   const preflightInlineFailure = nativeSource.inlineLedger.some(
     (entry) => entry.outcome === 'blocked' || entry.outcome === 'warned',
@@ -138,7 +220,7 @@ export async function author(input: string, options: AuthorOptions = {}): Promis
     selectorTransform: selectorTransport.rewrite,
     disposition: (declaration, rule) =>
       unsafeResidualDeclaration(declaration.property, declaration.value)
-      ?? (nativeSource.declarations.has(sourceDeclarationKey(rule.selector, declaration.property, declaration.value))
+      ?? (nativeSource.declarations.has(sourceDeclarationKey(rule.selector, declaration.property, declaration.value, rule.id))
         ? {
             outcome: 'native' as const,
             reason: 'mapped through the destination block support; omitted from residual CSS',
@@ -149,39 +231,6 @@ export async function author(input: string, options: AuthorOptions = {}): Promis
   const hardStyleFailure = scopedStyles.ledger.some((entry) => entry.outcome === 'blocked' || entry.outcome === 'warned')
     || scopedStyles.ruleRecords.some((record) => record.outcome === 'blocked');
   let css = scopedStyles.css;
-  // The source ledger includes URLs from rules we intentionally block (notably @font-face and
-  // Preflight). Those assets still need a terminal outcome even though their declarations will
-  // not reach style.css.
-  const sourceAssets = scanCssUrlReferences(styleInput, options.sourcePath).map((reference) =>
-    toAssetLedgerEntry(
-      classifyCssUrlReference(reference, {
-        sourcePath: options.sourcePath,
-        allowFontLicense: false,
-      }),
-    ),
-  );
-  const destinationAssetDir = options.outDir
-    ? path.join(options.outDir, 'assets')
-    : path.join(process.cwd(), '.block-runner-unwritten-assets');
-  // Copy/account from the complete source stylesheet, not merely residual CSS. A declaration can
-  // quite correctly become native (for example a class background becoming a Cover) while its URL
-  // still needs a package asset and a terminal ledger outcome.
-  const processedSource = await rewriteCssAssets({
-    sourceCss: styleInput,
-    sourcePath: options.outDir ? options.sourcePath : undefined,
-    destinationAssetDir,
-    allowFontLicense: false,
-  });
-  let assets: AssetLedgerEntry[] = mergeAssetLedgers(sourceAssets, processedSource.assets.map(toAssetLedgerEntry));
-  if (css) {
-    const processed = await rewriteCssAssets({
-      sourceCss: css,
-      sourcePath: options.outDir ? options.sourcePath : undefined,
-      destinationAssetDir,
-      allowFontLicense: false,
-    });
-    css = processed.css;
-  }
 
   // Rewrite every concrete source asset before conversion. That makes assets inside Custom HTML
   // fallbacks just as accountable as assets that happen to map to a native media block.
@@ -194,7 +243,7 @@ export async function author(input: string, options: AuthorOptions = {}): Promis
   assets = [...assets, ...rewrittenMarkup.assets];
 
   const inlineStyleLedger: AuthoredStyleLedgerEntry[] = [];
-  const conversion = await convert(rewrittenMarkup.input, {
+  const conversion = await convert(withAuthorStyles(rewrittenMarkup.input, processedSource.css), {
     ...options,
     // The author package carries any unsupported authored selector/property in style.css; the
     // legacy open sidecar would duplicate it as a global post stylesheet.
@@ -202,6 +251,7 @@ export async function author(input: string, options: AuthorOptions = {}): Promis
     config,
     preserveSourceClasses: referencedCssClasses(scopedStyles.css),
     preserveSourceSelectorDependencies: selectorTransport.dependencies,
+    suppressSourceDeclarations: [...nativeSource.suppressedDeclarations],
     preserveAssetForms: true,
     styleLedgerObserver(entries, source) {
       for (const entry of entries) {
@@ -272,6 +322,8 @@ function mergeAuthorConfig(configured: AuthorConfig | undefined, explicit: Autho
  */
 interface NativeSourceCollection {
   declarations: Set<string>;
+  /** Observed stylesheet declarations that must stay in parity CSS for at least one match. */
+  suppressedDeclarations: Set<string>;
   inlineLedger: AuthoredStyleLedgerEntry[];
   conversion: BlockRunnerReport;
 }
@@ -294,7 +346,7 @@ async function collectNativeSourceDeclarations(
           inlineLedger.push(toInlineStyleLedgerEntry(entry, source));
           continue;
         }
-        const key = sourceDeclarationKey(entry.origin, entry.property, entry.value);
+        const key = sourceDeclarationKey(entry.origin, entry.property, entry.value, entry.originId);
         const state = outcomes.get(key) ?? { native: false, other: false };
         if (entry.outcome === 'mapped' || (entry.outcome === 'consumed' && entry.reason === 'read by the structural rules')) {
           state.native = true;
@@ -307,15 +359,14 @@ async function collectNativeSourceDeclarations(
   });
   return {
     declarations: new Set([...outcomes].filter(([, state]) => state.native && !state.other).map(([key]) => key)),
+    suppressedDeclarations: new Set(
+      [...outcomes].filter(([, state]) => !state.native || state.other).map(([key]) => key),
+    ),
     inlineLedger,
     conversion,
   };
 }
 
-function sourceDeclarationKey(selector: string, property: string, value: string): string {
-  return `${selector.trim()}\u0000${property.trim().toLowerCase()}\u0000${value.trim()}`;
-}
-
 function authorFailure(reason: string): BlockRunnerReport {
   return {
     ok: false,
@@ -335,6 +386,29 @@ function stylesFromHtml(input: string): string {
   return [...input.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi)].map((match) => match[1]).join('\n');
 }
 
+function hasTailwindRuntimeSignal(css: string): boolean {
+  return /--tw-[\w-]+\s*:|var\(\s*--tw-[\w-]+/i.test(css);
+}
+
+/**
+ * Conversion reads class rules from `<style>` nodes before it sanitizes the design. Keep exactly
+ * one node containing the stylesheet that authoring actually vetted, rather than allowing stale
+ * source directives or an independently supplied stylesheet to influence native mapping.
+ */
+function withAuthorStyles(input: string, css: string): string {
+  const dom = new JSDOM(input, { contentType: 'text/html' });
+  const document = dom.window.document;
+  for (const style of [...document.querySelectorAll('style')]) {
+    style.remove();
+  }
+  if (css.trim()) {
+    const style = document.createElement('style');
+    style.textContent = css;
+    (document.head ?? document.documentElement).append(style);
+  }
+  return dom.serialize();
+}
+
 function linkedStylesheets(input: string): string[] {
   return [...input.matchAll(/<link\b[^>]*\brel\s*=\s*(['"]?)[^'"\s>]*stylesheet[^'"\s>]*\1[^>]*>/gi)].map(
     (match) => match[0],
@@ -434,6 +508,27 @@ async function rewriteMarkupAssets(input: string, options: RewriteMarkupAssetsOp
     return entry.outcome === 'copied' ? entry.rewrittenUrl : undefined;
   };
 
+  const processCssValue = async (
+    value: string,
+    kind: AssetLedgerEntry['kind'],
+  ): Promise<string> => {
+    // The CSS asset lexer deliberately works on source fragments too. That lets SVG presentation
+    // attributes such as `fill="url(texture.svg#paint)"` retain their full value while every
+    // concrete URL gets the same copy/classification/ledger treatment as a stylesheet value.
+    const processed = await rewriteCssAssets({
+      sourceCss: value,
+      sourcePath: options.write ? options.sourcePath : undefined,
+      destinationAssetDir: options.destinationAssetDir,
+      allowFontLicense: false,
+    });
+    for (const asset of processed.assets) {
+      const record = toAssetLedgerEntry(asset);
+      record.kind = kind;
+      assets.push(record);
+    }
+    return processed.css;
+  };
+
   for (const element of [...document.querySelectorAll('*')]) {
     if (element.tagName.toLowerCase() === 'style') {
       // Keep the rewritten stylesheet in the conversion DOM as well: a declaration that maps to
@@ -469,15 +564,31 @@ async function rewriteMarkupAssets(input: string, options: RewriteMarkupAssetsOp
       }
     }
 
-    for (const attribute of ['src', 'poster'] as const) {
+    for (const { name: attribute, kind } of assetAttributesFor(element)) {
       const value = element.getAttribute(attribute);
       if (!value?.trim()) continue;
-      const rewritten = await processReference(value, assetKindFor(element, attribute));
+      const rewritten = await processReference(value, kind);
       if (rewritten) {
         element.setAttribute(attribute, rewritten);
       }
     }
 
+    if (element.namespaceURI === 'http://www.w3.org/2000/svg') {
+      for (const attribute of [...element.attributes]) {
+        const name = attribute.name.toLowerCase();
+        // `style` above and concrete href forms above each have their own handling. Any other
+        // SVG presentation value can legally contain `url()`, including fill, filter, clip-path,
+        // mask, marker, and cursor; account for the URL rather than maintaining a lossy list.
+        if (name === 'style' || name === 'href' || name === 'xlink:href' || !/\burl\s*\(/i.test(attribute.value)) {
+          continue;
+        }
+        const rewritten = await processCssValue(attribute.value, 'image');
+        if (rewritten !== attribute.value) {
+          element.setAttribute(attribute.name, rewritten);
+        }
+      }
+    }
+
     const srcset = element.getAttribute('srcset');
     if (!srcset?.trim()) continue;
     let rewrittenSrcset = srcset;
@@ -498,10 +609,68 @@ async function rewriteMarkupAssets(input: string, options: RewriteMarkupAssetsOp
   return { input: dom.serialize(), assets };
 }
 
-function assetKindFor(element: Element, attribute: 'src' | 'poster'): AssetLedgerEntry['kind'] {
-  if (attribute === 'poster' || element.tagName.toLowerCase() === 'img') return 'image';
-  if (/^(audio|video|track|source)$/i.test(element.tagName)) return 'media';
-  return 'other';
+interface AssetAttribute {
+  name: string;
+  kind: AssetLedgerEntry['kind'];
+}
+
+/**
+ * Asset-bearing attributes are not interchangeable: HTML anchors use `href` for navigation while
+ * SVG `<image href>` is a concrete image dependency. Keep the table element/namespace-aware so
+ * every actual asset form reaches the same copy/classify ledger without turning ordinary links
+ * into package assets.
+ */
+function assetAttributesFor(element: Element): AssetAttribute[] {
+  const tag = element.localName.toLowerCase();
+  if (element.namespaceURI === 'http://www.w3.org/2000/svg') {
+    if (tag === 'image' || tag === 'feimage') {
+      return [{ name: 'href', kind: 'image' }, { name: 'xlink:href', kind: 'image' }];
+    }
+    if (tag === 'use' || tag === 'mpath' || tag === 'textpath') {
+      return [{ name: 'href', kind: 'other' }, { name: 'xlink:href', kind: 'other' }];
+    }
+    return [];
+  }
+
+  switch (tag) {
+    case 'img':
+      return [{ name: 'src', kind: 'image' }];
+    case 'video':
+      return [{ name: 'src', kind: 'media' }, { name: 'poster', kind: 'image' }];
+    case 'audio':
+    case 'track':
+    case 'embed':
+      return [{ name: 'src', kind: 'media' }];
+    case 'source':
+      // A source nested in picture is an image; audio/video source remains media.
+      return [{ name: 'src', kind: element.parentElement?.localName.toLowerCase() === 'picture' ? 'image' : 'media' }];
+    case 'object':
+      return [{ name: 'data', kind: 'other' }];
+    case 'iframe':
+      return [{ name: 'src', kind: 'other' }];
+    case 'input':
+      return [{ name: 'src', kind: 'image' }];
+    case 'link': {
+      const rel = (element.getAttribute('rel') ?? '').toLowerCase().split(/\s+/);
+      if (rel.includes('icon') || rel.includes('apple-touch-icon') || rel.includes('mask-icon')) {
+        return [{ name: 'href', kind: 'image' }];
+      }
+      if (rel.includes('stylesheet')) return [{ name: 'href', kind: 'stylesheet' }];
+      if (rel.includes('manifest') || rel.includes('modulepreload')) return [{ name: 'href', kind: 'other' }];
+      if (rel.includes('preload')) {
+        const as = (element.getAttribute('as') ?? '').toLowerCase();
+        if (as === 'font') return [{ name: 'href', kind: 'font' }];
+        if (as === 'image') return [{ name: 'href', kind: 'image' }];
+        if (as === 'video' || as === 'audio') return [{ name: 'href', kind: 'media' }];
+        if (as === 'style') return [{ name: 'href', kind: 'stylesheet' }];
+        return [{ name: 'href', kind: 'other' }];
+      }
+      if (rel.includes('prefetch')) return [{ name: 'href', kind: 'other' }];
+      return [];
+    }
+    default:
+      return [];
+  }
 }
 
 /** Extract URL tokens only; descriptors are retained byte-for-byte when a candidate is rewritten. */
diff --git a/src/author/styles.ts b/src/author/styles.ts
index a8cce25..1648d2e 100644
--- a/src/author/styles.ts
+++ b/src/author/styles.ts
@@ -1,10 +1,15 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { TailwindBuildGraph, TailwindCompilerInput } from '../types.js';
+
 /**
  * Source-style graph utilities for generated blocks.
  *
- * This module intentionally does not compile Tailwind. A Tailwind class is not CSS, and guessing
- * its declaration from a token would make the generated block depend on an unknown version,
- * configuration, plugin set, source set, and browser target. Callers may give us compiled CSS, but
- * must first prove the build graph that produced it is complete.
+ * Tailwind is compiled only by the project's explicitly supplied, pinned compiler. A Tailwind
+ * class is not CSS, and guessing its declaration from a token would make the generated block
+ * depend on an unknown version, configuration, plugin set, source set, and browser target. The
+ * compiler receives the complete materialized graph and its result is the only Tailwind CSS this
+ * module will author.
  *
  * The scanner is deliberately small and conservative. It preserves the conditional constructs that
  * can safely remain in a block stylesheet (`@media`, `@supports`, and `@container`) and records all
@@ -19,14 +24,15 @@ export type BuildGraphField =
   | 'safelist'
   | 'plugins'
   | 'environment'
-  | 'browserTarget';
+  | 'browserTarget'
+  | 'compiler';
 
 /**
  * The inputs that determine a Tailwind (or Tailwind-like) generated stylesheet. Empty arrays are
  * meaningful: they say that the author explicitly has no imports, safelist, or plugins. Omitted
  * fields are not meaningful and therefore cannot support a fidelity claim.
  */
-export interface CssBuildGraph {
+export interface CssBuildGraph extends TailwindBuildGraph {
   cssEntries?: readonly string[];
   imports?: readonly string[];
   directives?: readonly string[];
@@ -44,12 +50,14 @@ export interface BuildGraphIssue {
 }
 
 export interface BuildGraphValidation {
-  /** All eight graph inputs were supplied and entry/source values are non-empty. */
+  /** All required graph inputs were supplied and entry/source values are non-empty. */
   complete: boolean;
-  /** A Tailwind source directive/import or an explicit caller signal was found. */
+  /** Tailwind mode was explicitly declared by the caller or by supplying a graph. */
   tailwindDetected: boolean;
   /** The supplied CSS is a compiled, self-contained stylesheet rather than Tailwind source. */
   compiled: boolean;
+  /** A pinned compiler actually generated and, when supplied, matched this CSS. */
+  provenanceVerified: boolean;
   /** `--tw-*` variables referenced by the CSS but not defined anywhere in that CSS. */
   unresolvedVariables: string[];
   /** Tailwind fidelity is blocked for an incomplete graph or an uncompiled/incomplete CSS result. */
@@ -61,8 +69,10 @@ export interface BuildGraphValidation {
 export interface BuildGraphValidationOptions {
   /** Compiled or source CSS to inspect for Tailwind directives/variables. */
   css?: string;
-  /** Use when the caller detected Tailwind outside the stylesheet, for example from a config file. */
+  /** Explicitly declare Tailwind mode when the compiled CSS has no recognizable source token. */
   tailwindDetected?: boolean;
+  /** Set only after `compileTailwindBuildGraph()` produced the CSS being validated. */
+  provenanceVerified?: boolean;
 }
 
 const BUILD_GRAPH_FIELDS: readonly BuildGraphField[] = [
@@ -74,6 +84,7 @@ const BUILD_GRAPH_FIELDS: readonly BuildGraphField[] = [
   'plugins',
   'environment',
   'browserTarget',
+  'compiler',
 ];
 
 const BUILD_GRAPH_LABELS: Record<BuildGraphField, string> = {
@@ -85,27 +96,29 @@ const BUILD_GRAPH_LABELS: Record<BuildGraphField, string> = {
   plugins: 'plugin list',
   environment: 'build environment',
   browserTarget: 'browser target',
+  compiler: 'pinned Tailwind compiler',
 };
 
 /**
- * Validate the source inputs needed to make a Tailwind fidelity statement. This is validation, not
- * compilation: callers can use it before invoking their own approved compiler and pass the
- * resulting CSS into `scanStylesheet`.
+ * Validate the source inputs needed to make a Tailwind fidelity statement. Tailwind mode is not
+ * considered usable until a caller has also run `compileTailwindBuildGraph()` and marked the exact
+ * output as verified. Keeping this synchronous utility strict prevents a complete-looking graph
+ * plus independently supplied CSS from being mistaken for compiler provenance.
  */
 export function validateCssBuildGraph(
   graph: CssBuildGraph | undefined,
   options: BuildGraphValidationOptions = {},
 ): BuildGraphValidation {
   const css = options.css ?? '';
-  // Passing a graph is an explicit Tailwind/build-graph signal. A static stylesheet that has no
-  // directive/import is also a valid compiler result even if it no longer contains a recognisable
-  // Tailwind token — there is no safe way (or need) to reverse-engineer its original toolchain.
   const unresolvedVariables = unresolvedTailwindVariables(css);
-  const tailwindDetected =
-    options.tailwindDetected === true || graph !== undefined || hasTailwindSourceSignal(css) || unresolvedVariables.length > 0;
+  // Compiled CSS is not a trustworthy provenance signal: a one-rule Tailwind build can look
+  // exactly like hand-written CSS. Tailwind mode therefore comes only from the caller's explicit
+  // declaration (or from the presence of the graph itself), never from utility-shaped output.
+  const tailwindDetected = options.tailwindDetected === true || graph !== undefined;
   const missing = BUILD_GRAPH_FIELDS.filter((field) => graphFieldMissing(graph, field));
   const compiled = !hasTailwindSourceSignal(css) && unresolvedVariables.length === 0;
-  const blocked = tailwindDetected && (missing.length > 0 || !compiled);
+  const provenanceVerified = tailwindDetected ? options.provenanceVerified === true : true;
+  const blocked = tailwindDetected && (missing.length > 0 || !compiled || !provenanceVerified);
   const issues = missing.map<BuildGraphIssue>((field) => ({
     field,
     status: blocked ? 'blocked' : 'warning',
@@ -126,7 +139,24 @@ export function validateCssBuildGraph(
     });
   }
 
-  return { complete: missing.length === 0, tailwindDetected, compiled, unresolvedVariables, blocked, missing, issues };
+  if (tailwindDetected && missing.length === 0 && !provenanceVerified) {
+    issues.push({
+      field: 'compiler',
+      status: 'blocked',
+      reason: 'Tailwind graph has not been compiled by its pinned compiler, so this CSS has no verified provenance',
+    });
+  }
+
+  return {
+    complete: missing.length === 0,
+    tailwindDetected,
+    compiled,
+    provenanceVerified,
+    unresolvedVariables,
+    blocked,
+    missing,
+    issues,
+  };
 }
 
 /** True only for Tailwind *source* that still needs a compiler, never for compiled declarations. */
@@ -159,6 +189,15 @@ function graphFieldMissing(graph: CssBuildGraph | undefined, field: BuildGraphFi
   }
 
   const value = graph[field];
+  if (field === 'compiler') {
+    const compiler = graph.compiler;
+    return !compiler
+      || typeof compiler.name !== 'string'
+      || !compiler.name.trim()
+      || typeof compiler.version !== 'string'
+      || !compiler.version.trim()
+      || typeof compiler.compile !== 'function';
+  }
   if (field === 'cssEntries' || field === 'sources') {
     return !Array.isArray(value) || value.length === 0 || value.some((entry) => typeof entry !== 'string' || !entry.trim());
   }
@@ -178,6 +217,269 @@ function graphFieldMissing(graph: CssBuildGraph | undefined, field: BuildGraphFi
   return !Array.isArray(value);
 }
 
+export interface TailwindCompilationOptions {
+  /** Design HTML path, used as the base for graph paths when available. */
+  sourcePath?: string;
+  /** CSS supplied as purported compiler output. It must exactly match when present. */
+  expectedCss?: string;
+}
+
+export interface TailwindCompilation {
+  css?: string;
+  issues: BuildGraphIssue[];
+  /** True only when the compiler ran and its output matched the supplied output (if any). */
+  verified: boolean;
+}
+
+/**
+ * Materialize and compile the declared Tailwind graph. This intentionally has no fallback that
+ * infers a utility from class names or accepts a prebuilt stylesheet on trust: the supplied
+ * compiler is the project's pin for Tailwind, plugins, custom variants, and browser targeting.
+ */
+export async function compileTailwindBuildGraph(
+  graph: CssBuildGraph,
+  options: TailwindCompilationOptions = {},
+): Promise<TailwindCompilation> {
+  const missing = BUILD_GRAPH_FIELDS.filter((field) => graphFieldMissing(graph, field));
+  if (missing.length > 0) {
+    return {
+      issues: missing.map((field) => ({
+        field,
+        status: 'blocked',
+        reason: `${BUILD_GRAPH_LABELS[field]} were not supplied — Tailwind cannot be compiled from an incomplete graph`,
+      })),
+      verified: false,
+    };
+  }
+
+  const base = graphBaseDirectory(options.sourcePath);
+  const entries = await materializeGraphFiles(graph.cssEntries!, base, 'cssEntries');
+  const imports = await materializeGraphFiles(graph.imports!, base, 'imports');
+  const issues = [...entries.issues, ...imports.issues];
+  issues.push(...declaredTailwindInputIssues([...entries.files, ...imports.files], graph));
+  if (issues.length > 0) {
+    return { issues, verified: false };
+  }
+
+  const declaredImports = new Set(imports.files.map((file) => file.path));
+  for (const entry of [...entries.files, ...imports.files]) {
+    for (const specifier of cssImportSpecifiers(entry.css)) {
+      const resolved = path.resolve(path.dirname(entry.path), specifier);
+      if (!declaredImports.has(resolved)) {
+        issues.push({
+          field: 'imports',
+          status: 'blocked',
+          reason: `CSS entry ${entry.path} imports ${specifier}, but that import was not materialized in tailwind.imports`,
+        });
+      }
+    }
+  }
+  if (issues.length > 0) {
+    return { issues, verified: false };
+  }
+
+  const input: TailwindCompilerInput = {
+    cssEntries: entries.files,
+    imports: imports.files,
+    directives: [...graph.directives!],
+    sources: [...graph.sources!],
+    safelist: [...graph.safelist!],
+    plugins: [...graph.plugins!],
+    environment: graph.environment!,
+    browserTarget: graph.browserTarget!,
+  };
+
+  let css: string;
+  try {
+    css = await graph.compiler!.compile(input);
+  } catch (error) {
+    return {
+      issues: [{
+        field: 'compiler',
+        status: 'blocked',
+        reason: `pinned Tailwind compiler ${graph.compiler!.name}@${graph.compiler!.version} failed: ${errorMessage(error)}`,
+      }],
+      verified: false,
+    };
+  }
+  if (typeof css !== 'string') {
+    return {
+      issues: [{
+        field: 'compiler',
+        status: 'blocked',
+        reason: `pinned Tailwind compiler ${graph.compiler!.name}@${graph.compiler!.version} did not return CSS text`,
+      }],
+      verified: false,
+    };
+  }
+  if (options.expectedCss !== undefined && canonicalCompilerCss(options.expectedCss) !== canonicalCompilerCss(css)) {
+    return {
+      css,
+      issues: [{
+        field: 'compiler',
+        status: 'blocked',
+        reason: `supplied CSS does not match output from pinned Tailwind compiler ${graph.compiler!.name}@${graph.compiler!.version}`,
+      }],
+      verified: false,
+    };
+  }
+  return { css, issues: [], verified: true };
+}
+
+function graphBaseDirectory(sourcePath: string | undefined): string {
+  if (!sourcePath || sourcePath === '-' || /^<.*>$/.test(sourcePath)) {
+    return process.cwd();
+  }
+  return path.dirname(path.resolve(sourcePath));
+}
+
+async function materializeGraphFiles(
+  values: readonly string[],
+  base: string,
+  field: 'cssEntries' | 'imports',
+): Promise<{ files: Array<{ path: string; css: string }>; issues: BuildGraphIssue[] }> {
+  const files: Array<{ path: string; css: string }> = [];
+  const issues: BuildGraphIssue[] = [];
+  for (const value of values) {
+    const file = path.resolve(base, value);
+    try {
+      files.push({ path: file, css: await readFile(file, 'utf8') });
+    } catch (error) {
+      issues.push({
+        field,
+        status: 'blocked',
+        reason: `declared ${field === 'cssEntries' ? 'CSS entry' : 'CSS import'} ${value} could not be read: ${errorMessage(error)}`,
+      });
+    }
+  }
+  return { files, issues };
+}
+
+function cssImportSpecifiers(css: string): string[] {
+  const imports: string[] = [];
+  const expression = /@import\s+(?:url\(\s*)?(?:["']([^"']+)["']|([^\s;)]+))/gi;
+  let match: RegExpExecArray | null;
+  while ((match = expression.exec(css))) {
+    const specifier = (match[1] ?? match[2] ?? '').trim();
+    if (specifier) imports.push(specifier);
+  }
+  return imports;
+}
+
+/**
+ * The graph must describe the material we actually hand to the compiler. In particular, an empty
+ * `directives` or `plugins` field is an explicit assertion that source entries contain none; do
+ * not accept a custom variant/plugin merely because the field happened to be present.
+ */
+function declaredTailwindInputIssues(
+  files: ReadonlyArray<{ path: string; css: string }>,
+  graph: CssBuildGraph,
+): BuildGraphIssue[] {
+  const issues: BuildGraphIssue[] = [];
+  const directives = graph.directives!.map(normalizeGraphDirective);
+  const plugins = new Set(graph.plugins!.map((plugin) => plugin.trim()));
+  const sources = new Set(graph.sources!.map((source) => source.trim()));
+  const safelist = new Set(graph.safelist!.map((entry) => entry.trim()));
+
+  for (const entry of files) {
+    for (const directive of tailwindDirectives(entry.css)) {
+      const normalized = normalizeGraphDirective(directive);
+      if (!directives.includes(normalized)) {
+        issues.push({
+          field: 'directives',
+          status: 'blocked',
+          reason: `CSS entry ${entry.path} contains ${directive}, but it was not supplied in tailwind.directives`,
+        });
+      }
+    }
+    for (const plugin of tailwindPluginSpecifiers(entry.css)) {
+      if (!plugins.has(plugin)) {
+        issues.push({
+          field: 'plugins',
+          status: 'blocked',
+          reason: `CSS entry ${entry.path} loads Tailwind plugin ${plugin}, but it was not supplied in tailwind.plugins`,
+        });
+      }
+    }
+    for (const source of tailwindSourceSpecifiers(entry.css)) {
+      if (!sources.has(source)) {
+        issues.push({
+          field: 'sources',
+          status: 'blocked',
+          reason: `CSS entry ${entry.path} declares Tailwind source ${source}, but it was not supplied in tailwind.sources`,
+        });
+      }
+    }
+    for (const candidate of tailwindInlineSafelist(entry.css)) {
+      if (!safelist.has(candidate)) {
+        issues.push({
+          field: 'safelist',
+          status: 'blocked',
+          reason: `CSS entry ${entry.path} declares inline Tailwind source ${candidate}, but it was not supplied in tailwind.safelist`,
+        });
+      }
+    }
+  }
+  return issues;
+}
+
+function tailwindDirectives(css: string): string[] {
+  const directives: string[] = [];
+  const expression = /@(tailwind|apply|config|theme|utility|variant|custom-variant)\b[^;{}]*(?:;|\{)?/gi;
+  let match: RegExpExecArray | null;
+  while ((match = expression.exec(css))) {
+    directives.push(match[0].replace(/[;{]\s*$/, '').trim());
+  }
+  return directives;
+}
+
+function tailwindPluginSpecifiers(css: string): string[] {
+  const plugins: string[] = [];
+  const expression = /@plugin\s+(?:["']([^"']+)["']|([^\s;{}]+))/gi;
+  let match: RegExpExecArray | null;
+  while ((match = expression.exec(css))) {
+    const plugin = (match[1] ?? match[2] ?? '').trim();
+    if (plugin) plugins.push(plugin);
+  }
+  return plugins;
+}
+
+function tailwindSourceSpecifiers(css: string): string[] {
+  const sources: string[] = [];
+  const expression = /@source\s+(?:["']([^"']+)["']|([^\s;{}]+))/gi;
+  let match: RegExpExecArray | null;
+  while ((match = expression.exec(css))) {
+    const source = (match[1] ?? match[2] ?? '').trim();
+    if (source && !/^inline\(/i.test(source)) sources.push(source);
+  }
+  return sources;
+}
+
+function tailwindInlineSafelist(css: string): string[] {
+  const candidates: string[] = [];
+  const expression = /@source\s+inline\(\s*(["'])(.*?)\1\s*\)/gi;
+  let match: RegExpExecArray | null;
+  while ((match = expression.exec(css))) {
+    const candidate = (match[2] ?? '').trim();
+    if (candidate) candidates.push(candidate);
+  }
+  return candidates;
+}
+
+function normalizeGraphDirective(value: string): string {
+  return value.replace(/\s+/g, ' ').replace(/[;{]\s*$/, '').trim();
+}
+
+function canonicalCompilerCss(css: string): string {
+  // Compilers may vary only in final newlines. Any other byte change has not been proven to be the
+  // declared compiler output, so preserve the stronger provenance contract rather than guessing.
+  return css.replace(/\r\n?/g, '\n').replace(/\n+$/, '');
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 export interface CssPosition {
   offset: number;
   line: number;
@@ -353,7 +655,14 @@ export function scopeStylesheet(stylesheet: CssStylesheet, options: ScopeStylesh
       return undefined;
     }
 
-    const scoped = scopeLocalSelectorList(options.selectorTransform?.(rule.selector, rule) ?? rule.selector, options.root);
+    let transformedSelector = rule.selector;
+    try {
+      transformedSelector = options.selectorTransform?.(rule.selector, rule) ?? rule.selector;
+    } catch (error) {
+      blockRule(rule, errorMessage(error));
+      return undefined;
+    }
+    const scoped = scopeLocalSelectorList(transformedSelector, options.root);
     if (!scoped.ok) {
       blockRule(rule, scoped.reason);
       return undefined;
@@ -437,9 +746,10 @@ export interface SelectorDependencyTransport {
 
 /**
  * Preserve selector semantics across native conversion without blindly copying arbitrary source
- * attributes onto block attributes (which Gutenberg would silently discard). Each `#id` and
- * `[attribute]` atom becomes a deterministic class that is attached only to source elements that
- * actually match it. The scoped stylesheet then selects that transport class instead.
+ * attributes onto block attributes (which Gutenberg would silently discard). Attribute atoms
+ * become deterministic marker classes attached only to matching source elements. ID atoms keep an
+ * ID-specific `:is()` branch as well as their marker, preserving cascade specificity after the
+ * raw ID disappears from a native block.
  */
 export function createSelectorDependencyTransport(): SelectorDependencyTransport {
   const dependencies: SourceSelectorDependency[] = [];
@@ -496,18 +806,22 @@ export function createSelectorDependencyTransport(): SelectorDependencyTransport
         if (char === '#') {
           const identifier = readCssIdentifier(selector, index + 1);
           if (identifier) {
-            output += `.${markerFor('id', identifier.value)}`;
+            // :is() takes the specificity of its most specific argument. Keep the exact raw ID
+            // branch (which also remains correct inside a Custom HTML fallback) while the marker
+            // branch makes the selector survive native conversion.
+            output += `:is(${selector.slice(index, identifier.end)}, .${markerFor('id', identifier.value)})`;
             index = identifier.end;
             continue;
           }
         }
         if (char === '[') {
           const attribute = readAttributeSelector(selector, index);
-          if (attribute) {
-            output += `.${markerFor('attribute', attribute.value)}`;
-            index = attribute.end;
-            continue;
+          if (!attribute || !isValidAttributeSelector(attribute.value)) {
+            throw new Error(`invalid attribute selector ${attribute?.value ?? selector.slice(index)} cannot be transported into generated block CSS`);
           }
+          output += `.${markerFor('attribute', attribute.value)}`;
+          index = attribute.end;
+          continue;
         }
         output += char;
         index += 1;
@@ -517,6 +831,78 @@ export function createSelectorDependencyTransport(): SelectorDependencyTransport
   };
 }
 
+/**
+ * Accept the portable attribute-selector subset the DOM matcher handles in HTML. Deliberately
+ * reject namespaces/comments/exotic forms rather than creating a marker for a selector we cannot
+ * prove will match after conversion.
+ */
+function isValidAttributeSelector(selector: string): boolean {
+  if (!selector.startsWith('[') || !selector.endsWith(']')) {
+    return false;
+  }
+  const body = selector.slice(1, -1);
+  let index = skipSelectorWhitespace(body, 0);
+  const name = readValidCssIdentifier(body, index);
+  if (!name) return false;
+  index = skipSelectorWhitespace(body, name.end);
+  if (index === body.length) return true;
+
+  const operator = /^(?:[~|^$*]?=)/.exec(body.slice(index))?.[0];
+  if (!operator) return false;
+  index = skipSelectorWhitespace(body, index + operator.length);
+  if (index >= body.length) return false;
+
+  if (isSelectorQuote(body[index])) {
+    const quote = body[index];
+    index += 1;
+    while (index < body.length) {
+      if (body[index] === '\\') {
+        index += 2;
+      } else if (body[index] === quote) {
+        index += 1;
+        break;
+      } else {
+        index += 1;
+      }
+    }
+    if (body[index - 1] !== quote) return false;
+  } else {
+    const value = readValidCssIdentifier(body, index);
+    if (!value) return false;
+    index = value.end;
+  }
+
+  index = skipSelectorWhitespace(body, index);
+  if (index === body.length) return true;
+  if ((body[index] === 'i' || body[index] === 'I' || body[index] === 's' || body[index] === 'S')
+    && skipSelectorWhitespace(body, index + 1) === body.length) {
+    return true;
+  }
+  return false;
+}
+
+function skipSelectorWhitespace(value: string, start: number): number {
+  let index = start;
+  while (/\s/.test(value[index] ?? '')) index += 1;
+  return index;
+}
+
+function isSelectorQuote(value: string | undefined): value is '"' | "'" {
+  return value === '"' || value === "'";
+}
+
+function readValidCssIdentifier(value: string, start: number): { end: number } | undefined {
+  const raw = value[start];
+  if (!raw || (raw !== '\\' && !raw.startsWith('-') && !/[A-Za-z_]/.test(raw) && raw.codePointAt(0)! < 0x80)) {
+    return undefined;
+  }
+  if (raw === '-' && /[0-9]/.test(value[start + 1] ?? '')) {
+    return undefined;
+  }
+  const identifier = readCssIdentifier(value, start);
+  return identifier ? { end: identifier.end } : undefined;
+}
+
 /** Read class names from selectors/CSS with CSS escape semantics (`.\\32xl\\:block` → `2xl:block`). */
 export function referencedCssClasses(css: string): string[] {
   const classes = new Set<string>();
diff --git a/src/convert/assemble.ts b/src/convert/assemble.ts
index 41c62d0..3d4b725 100644
--- a/src/convert/assemble.ts
+++ b/src/convert/assemble.ts
@@ -7,6 +7,7 @@ import {
   applyElementStyles,
   isCarryable,
   richTextDescendantStyles,
+  sourceDeclarationKey,
   unattributableStyles,
 } from '../styles/apply.js';
 import { SidecarCollector, addClassName } from '../styles/sidecar.js';
@@ -24,6 +25,7 @@ import {
 import {
   contextHtml,
   contextText,
+  cssBackgroundsFromRules,
   isElementNode,
   makeContextWarning,
   prepareDom,
@@ -78,6 +80,21 @@ async function runConvert(
     prepared.dom.window.document,
     options.preserveSourceSelectorDependencies ?? [],
   );
+  // A registered-block stylesheet owns declarations that could not be mapped natively for every
+  // matching element. Remove exactly those source declarations before structural/style mapping so
+  // a mixed result cannot emit both a native value and the residual rule.
+  const suppressed = new Set(options.suppressSourceDeclarations ?? []);
+  const cssClassRules = suppressed.size === 0
+    ? prepared.cssClassRules
+    : prepared.cssClassRules.map((rule) => ({
+        ...rule,
+        declarations: rule.declarations.filter(
+          (declaration) => !declaration.origin || !suppressed.has(
+            sourceDeclarationKey(declaration.origin, declaration.property, declaration.value, declaration.originId),
+          ),
+        ),
+      }));
+  const cssBackgrounds = cssBackgroundsFromRules(cssClassRules);
   const warnings: ReportItem[] = [...prepared.warnings];
   const explainItems: ReportItem[] = [];
   const rules = buildRules(config);
@@ -100,8 +117,8 @@ async function runConvert(
     rules,
     sourcePath: options.sourcePath,
     explain: options.explain === true,
-    cssBackgrounds: prepared.cssBackgrounds,
-    cssClassRules: prepared.cssClassRules,
+    cssBackgrounds,
+    cssClassRules,
     preserveAssetForms: options.preserveAssetForms === true,
     warn(reason, node, block, rule, details) {
       warnings.push(makeContextWarning(context, reason, node, block, rule, details));
@@ -126,9 +143,9 @@ async function runConvert(
             styling,
             capabilities,
             tokens: tokenInvMap,
-            classRules: prepared.cssClassRules,
+            classRules: cssClassRules,
           })
-        : unattributableStyles(element, blocks.length, prepared.cssClassRules);
+        : unattributableStyles(element, blocks.length, cssClassRules);
 
       // Registered-block authoring owns a stylesheet rooted at its generated wrapper. Retain only
       // the source classes that stylesheet actually references, and only on the one native block
@@ -151,7 +168,7 @@ async function runConvert(
       }
       // Rich-text descendants have no block of their own, so only author-selector rules can be
       // rescued — passing the enclosing block would put the class in the wrong place.
-      const ledger = richTextDescendantStyles(node as Element, styling, prepared.cssClassRules);
+      const ledger = richTextDescendantStyles(node as Element, styling, cssClassRules);
       reportLedger(carryToSidecar(ledger, undefined), node as Element, block, rule ?? 'styles');
     },
     explainRule(node, rule, reason, details) {
diff --git a/src/convert/dom.ts b/src/convert/dom.ts
index 5e45ea1..09a9bfd 100644
--- a/src/convert/dom.ts
+++ b/src/convert/dom.ts
@@ -1,5 +1,6 @@
 import { JSDOM } from 'jsdom';
 import { ReportItem, RuleContext, SourceLocation, SourceSelectorDependency } from '../types.js';
+import { scanStylesheet } from '../author/styles.js';
 import { effectiveDeclarations } from '../styles/apply.js';
 import { extractUrl } from '../styles/declarations.js';
 import { Declaration, parseDeclarationBlock, parseInlineStyle, resolvePrecedence } from '../styles/parse.js';
@@ -49,13 +50,11 @@ export function retainSelectorDependencies(document: Document, dependencies: rea
         }
         continue;
       }
-      try {
-        if (element.matches(dependency.value)) {
-          element.classList.add(dependency.markerClass);
-        }
-      } catch {
-        // The stylesheet scanner will report the associated selector as blocked rather than
-        // pretending an invalid attribute selector has a meaningful runtime dependency.
+      // Authoring validates attribute-selector syntax before it creates a dependency. Let an
+      // unexpected selector-engine failure surface instead of emitting a marker CSS rule that can
+      // never match the converted DOM.
+      if (element.matches(dependency.value)) {
+        element.classList.add(dependency.markerClass);
       }
     }
   }
@@ -123,7 +122,7 @@ export interface CssClassRule {
 }
 
 /**
- * Extract single-class rules (`.hero { … }`) from `<style>` elements, in document order.
+ * Extract top-level single-class rules (`.hero { … }`) from `<style>` elements, in document order.
  *
  * Single-class only, deliberately: those are the rules a design-HTML generator emits, and they are
  * the only ones whose declarations map onto exactly one element with no specificity reasoning.
@@ -134,26 +133,30 @@ export function extractCssClassRules(document: Document): CssClassRule[] {
   const rules: CssClassRule[] = [];
 
   for (const style of [...document.querySelectorAll('style')]) {
-    // At-rule blocks are dropped whole. Their inner rules are conditional (`@media print`,
-    // `@supports`) and applying them unconditionally would style every render with CSS meant for
-    // one — and a flat rule scan happily matches rules nested inside them.
-    const css = stripAtRuleBlocks(style.textContent ?? '');
-    // Split into selector/body pairs, then keep only the ones whose selector is exactly one class.
-    // Matching `.name{…}` directly cannot handle consecutive rules (the previous rule's `}` is
-    // already consumed) and would also match the `.b` inside a compound selector like `div.a .b`.
-    const rulePattern = /([^{}]+)\{([^{}]*)\}/g;
-    let ruleMatch: RegExpExecArray | null;
-
-    while ((ruleMatch = rulePattern.exec(css))) {
-      const [, selector, body] = ruleMatch;
-      const single = /^\s*\.([_a-zA-Z][\w-]*)\s*$/.exec(selector);
+    const css = style.textContent ?? '';
+    const stylesheet = scanStylesheet(css);
+    for (const rule of stylesheet.rules) {
+      // Conditional rules deliberately do not take part in native mapping: their conditions are
+      // not evaluated by the conversion probe. Scanning the complete sheet (rather than deleting
+      // at-rule text first) still gives every top-level rule its true source identity.
+      if (rule.kind !== 'style') continue;
+      const single = /^\s*\.([_a-zA-Z][\w-]*)\s*$/.exec(rule.selector);
       if (!single) {
         continue;
       }
       const className = single[1];
-      // The index is the rule's position across all stylesheets, so the sidecar can keep two rules
-      // sharing a selector as separate rules in their authored positions.
-      const { declarations, problems } = parseDeclarationBlock(body, `.${className}`, rules.length);
+      const rawRule = css.slice(rule.source.start.offset, rule.source.end.offset);
+      const bodyStart = rawRule.indexOf('{');
+      const bodyEnd = rawRule.lastIndexOf('}');
+      if (bodyStart === -1 || bodyEnd <= bodyStart) continue;
+      // The index retains sidecar order. The scanner rule ID is the stronger identity used by
+      // authoring, so repeated selectors and conditionally nested rules cannot alias each other.
+      const { declarations, problems } = parseDeclarationBlock(
+        rawRule.slice(bodyStart + 1, bodyEnd),
+        `.${className}`,
+        rules.length,
+        rule.id,
+      );
       if (declarations.length > 0 || problems.length > 0) {
         rules.push({ className, declarations, problems });
       }
@@ -163,49 +166,6 @@ export function extractCssClassRules(document: Document): CssClassRule[] {
   return rules;
 }
 
-/**
- * Remove `@media`/`@supports`/`@layer` blocks, brace-balanced so nested rules go with them.
- */
-function stripAtRuleBlocks(css: string): string {
-  let out = '';
-  let index = 0;
-
-  while (index < css.length) {
-    if (css[index] !== '@') {
-      out += css[index];
-      index += 1;
-      continue;
-    }
-
-    // Skip to the end of the at-rule: either a `;` (e.g. @import) or a balanced block.
-    let cursor = index;
-    while (cursor < css.length && css[cursor] !== '{' && css[cursor] !== ';') {
-      cursor += 1;
-    }
-    if (cursor >= css.length || css[cursor] === ';') {
-      index = cursor + 1;
-      continue;
-    }
-
-    let depth = 0;
-    while (cursor < css.length) {
-      if (css[cursor] === '{') {
-        depth += 1;
-      } else if (css[cursor] === '}') {
-        depth -= 1;
-        if (depth === 0) {
-          cursor += 1;
-          break;
-        }
-      }
-      cursor += 1;
-    }
-    index = cursor;
-  }
-
-  return out;
-}
-
 /**
  * Background image per class, after resolving the cascade across *every* rule for that class — so
  * the structural rules pick the same image the ledger does.
diff --git a/src/index.ts b/src/index.ts
index 733c6ae..1e4bcde 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -3,6 +3,7 @@ export { validate } from './gate/validate.js';
 export { convert } from './convert/assemble.js';
 export { author } from './author/index.js';
 export {
+  compileTailwindBuildGraph,
   hasTailwindSignal,
   renderResidualCss,
   scanStylesheet,
@@ -10,6 +11,7 @@ export {
   scopeStylesheet,
   validateCssBuildGraph,
 } from './author/styles.js';
+export type { CssBuildGraph, TailwindCompilation, TailwindCompilationOptions } from './author/styles.js';
 export {
   classifyCssUrlReference,
   processCssAssets,
@@ -102,6 +104,8 @@ export type {
   TokenResolver,
   TokenResolverKind,
   TailwindBuildGraph,
+  TailwindCompiler,
+  TailwindCompilerInput,
   ValidateOptions,
   WpBlock,
 } from './types.js';
diff --git a/src/styles/apply.ts b/src/styles/apply.ts
index 107a82e..92573f9 100644
--- a/src/styles/apply.ts
+++ b/src/styles/apply.ts
@@ -44,6 +44,8 @@ export interface StyleLedgerEntry {
   important?: boolean;
   /** Position of the originating stylesheet rule, so the sidecar can keep rules in authored order. */
   originIndex?: number;
+  /** Stable stylesheet-rule identity for authoring's exact declaration handoff. */
+  originId?: string;
   /** Why it was dropped, or what it became. Phrased to point at the input. */
   reason?: string;
   /** The shorthand the author actually wrote, when this came from expanding one. */
@@ -62,6 +64,23 @@ export interface StyleLedgerEntry {
   carryable?: false;
 }
 
+/**
+ * Stable identity for one declaration across authoring's preflight and emit pass.
+ *
+ * Selector/property/value is not sufficient: `.card { color:red }` and the identical declaration
+ * inside `@media` are different source declarations with different runtime meaning. `originId`
+ * is the scanner's rule identity when available, while the empty fallback keeps this utility
+ * compatible with inline/non-authoring callers.
+ */
+export function sourceDeclarationKey(
+  selector: string,
+  property: string,
+  value: string,
+  originId?: string,
+): string {
+  return `${originId ?? ''}\u0000${selector.trim()}\u0000${property.trim().toLowerCase()}\u0000${value.trim()}`;
+}
+
 /**
  * Whether the `open` rung can preserve this entry as sidecar CSS. Well-formed CSS that simply has no
  * block home qualifies; genuinely broken input does not, and neither does CSS with no single block
diff --git a/src/styles/parse.ts b/src/styles/parse.ts
index 71f7942..b88a14e 100644
--- a/src/styles/parse.ts
+++ b/src/styles/parse.ts
@@ -21,6 +21,12 @@ export interface Declaration {
    * original positions — collapsing them onto the first occurrence reverses the author's cascade.
    */
   originIndex?: number;
+  /**
+   * Stable stylesheet-rule identity used internally by registered-block authoring. Unlike the
+   * selector text, it distinguishes repeated selectors and the same selector inside a conditional
+   * at-rule from its top-level counterpart.
+   */
+  originId?: string;
 }
 
 export interface OverriddenDeclaration extends Declaration {
@@ -71,6 +77,7 @@ export function parseDeclarationBlock(
   css: string,
   origin?: string,
   originIndex?: number,
+  originId?: string,
 ): { declarations: Declaration[]; problems: string[] } {
   const parsed: Declaration[] = [];
   const problems: string[] = [];
@@ -110,6 +117,7 @@ export function parseDeclarationBlock(
         ...(important ? { important } : {}),
         ...(origin ? { origin } : {}),
         ...(originIndex === undefined ? {} : { originIndex }),
+        ...(originId === undefined ? {} : { originId }),
       })),
     );
   }
diff --git a/src/types.ts b/src/types.ts
index 3952a72..50e0831 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -92,26 +92,58 @@ export interface AssetLedgerEntry {
   source?: SourceLocation;
 }
 
+/** The materialized inputs handed to the project's pinned Tailwind compiler. */
+export interface TailwindCompilerInput {
+  /** Each declared entry after Block Runner has read it from the supplied style graph. */
+  cssEntries: ReadonlyArray<{ path: string; css: string }>;
+  /** Resolved local imports supplied as part of the graph. */
+  imports: ReadonlyArray<{ path: string; css: string }>;
+  directives: readonly string[];
+  sources: readonly string[];
+  safelist: readonly string[];
+  plugins: readonly string[];
+  environment: Readonly<Record<string, string | number | boolean | null | undefined>>;
+  browserTarget: string | readonly string[];
+}
+
+/**
+ * A compiler deliberately comes from the calling project, where its Tailwind version and plugins
+ * are pinned.  Block Runner invokes it during authoring and never ships it with the generated
+ * block.  The name/version fields make that provenance visible in configuration and reports.
+ */
+export interface TailwindCompiler {
+  name: string;
+  version: string;
+  compile(input: TailwindCompilerInput): string | Promise<string>;
+}
+
 /**
  * Inputs required to make a Tailwind fidelity claim.  Empty arrays/objects are meaningful: they
  * say that a project has explicitly supplied no plugins/safelist/etc.  An omitted field is not
  * equivalent to an empty one and is reported as missing.
  */
 export interface TailwindBuildGraph {
-  cssEntries?: string[];
-  imports?: string[];
-  directives?: string[];
-  sources?: string[];
-  safelist?: string[];
-  plugins?: string[];
-  environment?: Record<string, string | undefined>;
-  browserTarget?: string | string[];
+  cssEntries?: readonly string[];
+  imports?: readonly string[];
+  directives?: readonly string[];
+  sources?: readonly string[];
+  safelist?: readonly string[];
+  plugins?: readonly string[];
+  environment?: Readonly<Record<string, string | number | boolean | null | undefined>>;
+  browserTarget?: string | readonly string[];
+  /** The pinned compiler that must produce the stylesheet used for authoring. */
+  compiler?: TailwindCompiler;
 }
 
 export interface AuthorStyleConfig {
-  /** Actual compiled CSS. Block Runner never derives it from Tailwind class tokens. */
+  /**
+   * Declares how the stylesheet was produced. CSS provenance cannot be recovered from compiled
+   * declarations, so this is required whenever authoring receives non-empty stylesheet input.
+   */
+  mode?: 'css' | 'tailwind';
+  /** Actual compiled CSS. In Tailwind mode it must match the pinned compiler output. */
   css?: string;
-  /** Optional source build graph, required when the CSS uses Tailwind directives or variables. */
+  /** Required for Tailwind source or runtime output; its compiler is run during authoring. */
   tailwind?: TailwindBuildGraph;
   /** Explicitly supplied editor-only affordances. Parity CSS is always emitted through `style`. */
   editorCss?: string;
@@ -249,6 +281,11 @@ export interface ConvertOptions extends CommonOptions {
   preserveSourceClasses?: readonly string[];
   /** Internal authoring handoff for IDs/attributes referenced by the generated scoped CSS. */
   preserveSourceSelectorDependencies?: readonly SourceSelectorDependency[];
+  /**
+   * Source class declarations retained by the authored stylesheet. They are excluded from the
+   * native styling pass so one declaration never lands both as scoped CSS and as a block style.
+   */
+  suppressSourceDeclarations?: readonly string[];
   /** Internal authoring boundary for asset forms a native Core block cannot faithfully retain. */
   preserveAssetForms?: boolean;
   /** Internal observer used by registered-block authoring to account for inline declarations. */
diff --git a/test/author.test.ts b/test/author.test.ts
index d213591..77e5027 100644
--- a/test/author.test.ts
+++ b/test/author.test.ts
@@ -4,7 +4,13 @@ import path from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
 import { classifyCssUrlReference, rewriteCssAssets, scanCssUrlReferences } from '../src/author/assets.js';
 import { author } from '../src/author/index.js';
-import { scanStylesheet, scopeStylesheet, validateCssBuildGraph } from '../src/author/styles.js';
+import {
+  compileTailwindBuildGraph,
+  createSelectorDependencyTransport,
+  scanStylesheet,
+  scopeStylesheet,
+  validateCssBuildGraph,
+} from '../src/author/styles.js';
 
 const scratch: string[] = [];
 
@@ -74,7 +80,7 @@ describe('registered-block stylesheet graph', () => {
   });
 
   it('requires the complete explicit Tailwind graph before fidelity can be claimed', () => {
-    const missing = validateCssBuildGraph(undefined, { css: '@tailwind utilities;' });
+    const missing = validateCssBuildGraph(undefined, { css: '@tailwind utilities;', tailwindDetected: true });
     expect(missing.blocked).toBe(true);
     expect(missing.missing).toEqual([
       'cssEntries',
@@ -85,6 +91,7 @@ describe('registered-block stylesheet graph', () => {
       'plugins',
       'environment',
       'browserTarget',
+      'compiler',
     ]);
 
     const complete = validateCssBuildGraph(
@@ -97,12 +104,14 @@ describe('registered-block stylesheet graph', () => {
         plugins: [],
         environment: {},
         browserTarget: 'defaults',
+        compiler: { name: 'tailwindcss', version: '3.4.0', compile: () => '' },
       },
       { css: '.utility { --tw-translate-x: 0; transform: translateX(var(--tw-translate-x)); }' },
     );
     expect(complete.complete).toBe(true);
     expect(complete.compiled).toBe(true);
-    expect(complete.blocked).toBe(false);
+    expect(complete.blocked).toBe(true);
+    expect(complete.provenanceVerified).toBe(false);
 
     const incompleteOutput = validateCssBuildGraph(
       {
@@ -114,6 +123,7 @@ describe('registered-block stylesheet graph', () => {
         plugins: [],
         environment: {},
         browserTarget: 'defaults',
+        compiler: { name: 'tailwindcss', version: '3.4.0', compile: () => '' },
       },
       { css: '.utility { transform: translateX(var(--tw-translate-x)); }' },
     );
@@ -122,9 +132,111 @@ describe('registered-block stylesheet graph', () => {
 
     const selfContainedOutput = validateCssBuildGraph(undefined, {
       css: '.utility { --tw-translate-x: 0; transform: translateX(var(--tw-translate-x)); }',
+      tailwindDetected: true,
     });
     expect(selfContainedOutput.compiled).toBe(true);
-    expect(selfContainedOutput.blocked).toBe(false);
+    expect(selfContainedOutput.blocked).toBe(true);
+  });
+
+  it('uses the supplied pinned compiler and rejects CSS that is not its output', async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), 'block-runner-author-'));
+    scratch.push(directory);
+    await writeFile(path.join(directory, 'design.html'), '');
+    await writeFile(path.join(directory, 'style.css'), '@tailwind utilities;');
+    const compiler = {
+      name: 'tailwindcss',
+      version: '3.4.0',
+      compile: (input: { cssEntries: ReadonlyArray<{ path: string; css: string }> }) => {
+        expect(input.cssEntries[0]?.css).toBe('@tailwind utilities;');
+        return '.notice { color: red; }';
+      },
+    };
+    const graph = {
+      cssEntries: ['style.css'],
+      imports: [],
+      directives: ['@tailwind utilities'],
+      sources: ['design.html'],
+      safelist: [],
+      plugins: [],
+      environment: {},
+      browserTarget: 'defaults',
+      compiler,
+    };
+
+    const compiled = await compileTailwindBuildGraph(graph, { sourcePath: path.join(directory, 'design.html') });
+    expect(compiled).toMatchObject({ css: '.notice { color: red; }', verified: true, issues: [] });
+
+    const authoredFromSource = await author('<style>@tailwind utilities;</style><p class="notice">Hello</p>', {
+      sourcePath: path.join(directory, 'design.html'),
+      author: { name: 'acme/notice', styles: { mode: 'tailwind', tailwind: graph } },
+    });
+    expect(authoredFromSource.ok).toBe(true);
+    expect(authoredFromSource.package?.files['index.js']).toContain('"text": "red"');
+
+    const rejected = await author('<p class="notice">Hello</p>', {
+      sourcePath: path.join(directory, 'design.html'),
+      author: { name: 'acme/notice', styles: { mode: 'tailwind', css: '.notice { color: blue; }', tailwind: graph } },
+    });
+    expect(rejected.ok).toBe(false);
+    expect(rejected.items.map((item) => item.reason).join('\n')).toMatch(/does not match output from pinned Tailwind compiler/i);
+  });
+
+  it('reports undeclared custom variants and plugins from the materialized source graph', async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), 'block-runner-author-'));
+    scratch.push(directory);
+    await writeFile(
+      path.join(directory, 'style.css'),
+      '@tailwind utilities; @custom-variant night (&:where(.night, .night *)); @plugin "tailwind-motion";',
+    );
+    const result = await compileTailwindBuildGraph({
+      cssEntries: ['style.css'],
+      imports: [],
+      directives: ['@tailwind utilities'],
+      sources: ['design.html'],
+      safelist: [],
+      plugins: [],
+      environment: {},
+      browserTarget: 'defaults',
+      compiler: { name: 'tailwindcss', version: '4.0.0', compile: () => '.x {}' },
+    }, { sourcePath: path.join(directory, 'design.html') });
+
+    expect(result.verified).toBe(false);
+    expect(result.issues.map((issue) => issue.reason).join('\n')).toMatch(/custom-variant night|Tailwind plugin tailwind-motion/i);
+  });
+
+  it('requires an explicit stylesheet mode before accepting compiled CSS without Tailwind tokens', async () => {
+    const anonymous = await author('<style>.p-4 { padding: 1rem; }</style><p class="p-4">Hello</p>', {
+      author: { name: 'acme/padding' },
+    });
+    expect(anonymous.ok).toBe(false);
+    expect(anonymous.items.map((item) => item.reason).join('\n')).toMatch(/styles\.mode.*css.*tailwind/i);
+
+    const unprovenTailwind = await author('<style>.p-4 { padding: 1rem; }</style><p class="p-4">Hello</p>', {
+      author: { name: 'acme/padding', styles: { mode: 'tailwind' } },
+    });
+    expect(unprovenTailwind.ok).toBe(false);
+    expect(unprovenTailwind.items.map((item) => item.reason).join('\n')).toMatch(/pinned Tailwind compiler/i);
+  });
+
+  it('requires every local, package, and remote CSS import to be materialized', async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), 'block-runner-author-'));
+    scratch.push(directory);
+    await writeFile(path.join(directory, 'style.css'), '@import "tailwindcss"; @import url("https://cdn.example/theme.css");');
+
+    const result = await compileTailwindBuildGraph({
+      cssEntries: ['style.css'],
+      imports: [],
+      directives: [],
+      sources: ['design.html'],
+      safelist: [],
+      plugins: [],
+      environment: {},
+      browserTarget: 'defaults',
+      compiler: { name: 'tailwindcss', version: '4.0.0', compile: () => '.p-4 { padding: 1rem; }' },
+    }, { sourcePath: path.join(directory, 'design.html') });
+
+    expect(result.verified).toBe(false);
+    expect(result.issues.map((issue) => issue.reason).join('\n')).toMatch(/tailwindcss.*not materialized|https:\/\/cdn\.example.*not materialized/i);
   });
 });
 
@@ -178,12 +290,19 @@ describe('registered-block CSS assets', () => {
     const reference = scanCssUrlReferences('x{background:url(../.env)}', design)[0]!;
     expect(classifyCssUrlReference(reference, { sourcePath: design })).toMatchObject({ outcome: 'blocked' });
   });
+
+  it('reads only image positions from image-set(), not quoted type descriptors', () => {
+    const refs = scanCssUrlReferences(
+      'x { background-image: image-set("photo.avif" 1x type("image/avif"), url("photo.png") 2x type("image/png")); }',
+    );
+    expect(refs.map((reference) => reference.url)).toEqual(['photo.avif', 'photo.png']);
+  });
 });
 
 describe('registered-block authoring parity ledger', () => {
   it('maps a stylesheet declaration once to a supported native destination without duplicate CSS', async () => {
     const report = await author('<style>.notice { color: red; }</style><p class="notice">Hello</p>', {
-      author: { name: 'acme/notice' },
+      author: { name: 'acme/notice', styles: { mode: 'css' } },
     });
 
     expect(report.ok).toBe(true);
@@ -199,7 +318,7 @@ describe('registered-block authoring parity ledger', () => {
 
     const report = await author('<style>body { color: red; }</style><p>Hello</p>', {
       outDir,
-      author: { name: 'acme/notice' },
+      author: { name: 'acme/notice', styles: { mode: 'css' } },
     });
 
     expect(report.ok).toBe(false);
@@ -209,15 +328,81 @@ describe('registered-block authoring parity ledger', () => {
   it('retains escaped class, ID, and attribute selector dependencies through native conversion', async () => {
     const report = await author(
       '<style>@media (min-width: 40rem) { .\\32xl\\:open#hero[data-state="open"] { color: red; } }</style><p id="hero" data-state="open" class="2xl:open">Hello</p>',
-      { author: { name: 'acme/notice' } },
+      { author: { name: 'acme/notice', styles: { mode: 'css' } } },
     );
 
     expect(report.ok).toBe(true);
-    expect(report.package?.files['style.css']).toContain('.\\32xl\\:open.block-runner-selector-id-');
+    expect(report.package?.files['style.css']).toContain('.\\32xl\\:open:is(#hero, .block-runner-selector-id-');
     expect(report.package?.files['index.js']).toContain('"className": "2xl:open block-runner-selector-id-');
     expect(report.package?.files['index.js']).toContain('block-runner-selector-attribute-');
   });
 
+  it('preserves stylesheet ownership when one selector maps natively for only some matching elements', async () => {
+    const report = await author(
+      '<style>.notice { color: red; }</style><p class="notice">Outer <span class="notice">inner</span></p>',
+      { author: { name: 'acme/notice', styles: { mode: 'css' } } },
+    );
+
+    expect(report.ok).toBe(true);
+    expect(report.styleLedger?.filter((entry) => entry.property === 'color')).toEqual([
+      expect.objectContaining({ outcome: 'scoped-css' }),
+    ]);
+    expect(report.package?.files['style.css']).toContain('.wp-block-acme-notice .notice { color: red; }');
+    expect(report.package?.files['index.js']).not.toContain('"color": "red"');
+  });
+
+  it('keeps an identical conditional declaration in residual CSS instead of aliasing a native top-level rule', async () => {
+    const report = await author(
+      '<style>.notice { color: red; } @media (min-width: 40rem) { .notice { color: red; } }</style><p class="notice">Hello</p>',
+      { author: { name: 'acme/notice', styles: { mode: 'css' } } },
+    );
+
+    expect(report.ok).toBe(true);
+    expect(report.styleLedger).toEqual(expect.arrayContaining([
+      expect.objectContaining({ property: 'color', outcome: 'native', atRules: [] }),
+      expect.objectContaining({ property: 'color', outcome: 'scoped-css', atRules: ['@media (min-width: 40rem)'] }),
+    ]));
+    expect(report.package?.files['style.css']).toContain('@media (min-width: 40rem)');
+    expect(report.package?.files['style.css']).toContain('.wp-block-acme-notice .notice { color: red; }');
+  });
+
+  it('suppresses rewritten mixed declarations with the same identity used by final conversion', async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), 'block-runner-author-'));
+    scratch.push(directory);
+    const design = path.join(directory, 'design.html');
+    const outDir = path.join(directory, 'package');
+    await writeFile(design, '');
+    await writeFile(path.join(directory, 'photo.png'), 'photo');
+
+    const report = await author(
+      '<style>.notice { background-image: url("photo.png"); }</style><div class="notice"><p>Hero</p></div><span class="notice">Fallback</span>',
+      { sourcePath: design, outDir, author: { name: 'acme/notice', styles: { mode: 'css' } } },
+    );
+
+    expect(report.ok).toBe(true);
+    expect(report.styleLedger).toContainEqual(expect.objectContaining({ property: 'background-image', outcome: 'scoped-css' }));
+    expect(report.package?.files['style.css']).toContain('./assets/');
+    expect(report.package?.files['index.js']).not.toContain('"url": "./assets/');
+  });
+
+  it('blocks invalid attribute selectors before emitting a marker dependency and retains ID specificity', () => {
+    const transport = createSelectorDependencyTransport();
+    const idScoped = scopeStylesheet(scanStylesheet('#hero { color: red; }'), {
+      root: '.wp-block-acme-notice',
+      selectorTransform: transport.rewrite,
+    });
+    expect(idScoped.css).toContain(':is(#hero, .block-runner-selector-id-');
+
+    const invalidTransport = createSelectorDependencyTransport();
+    const invalid = scopeStylesheet(scanStylesheet('[data-state=] { color: red; }'), {
+      root: '.wp-block-acme-notice',
+      selectorTransform: invalidTransport.rewrite,
+    });
+    expect(invalid.css).toBe('');
+    expect(invalid.ledger).toContainEqual(expect.objectContaining({ outcome: 'blocked', reason: expect.stringMatching(/invalid attribute selector/i) }));
+    expect(invalidTransport.dependencies).toEqual([]);
+  });
+
   it('accounts for inline CSS and rewrites srcset assets retained in Custom HTML', async () => {
     const directory = await mkdtemp(path.join(tmpdir(), 'block-runner-author-'));
     scratch.push(directory);
@@ -244,4 +429,44 @@ describe('registered-block authoring parity ledger', () => {
     expect(report.package?.files['index.js']).toContain('image-set(');
     expect(await readFile(path.join(outDir, 'block.json'), 'utf8')).toContain('acme/notice');
   });
+
+  it('accounts for object data and SVG href asset forms', async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), 'block-runner-author-'));
+    scratch.push(directory);
+    const design = path.join(directory, 'design.html');
+    const source = path.join(directory, 'photo.png');
+    await writeFile(design, '');
+    await writeFile(source, 'photo');
+
+    const report = await author(
+      '<object data="photo.png"></object><svg><image href="photo.png" /><use xlink:href="photo.png#symbol" /></svg>',
+      { sourcePath: design, outDir: path.join(directory, 'package'), author: { name: 'acme/assets' } },
+    );
+
+    expect(report.assets?.filter((asset) => asset.reference.startsWith('photo.png'))).toHaveLength(3);
+    expect(report.assets?.filter((asset) => asset.reference.startsWith('photo.png')).every((asset) => asset.outcome === 'copied')).toBe(true);
+  });
+
+  it('accounts for SVG presentation URLs, SVG href variants, and link href asset forms', async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), 'block-runner-author-'));
+    scratch.push(directory);
+    const design = path.join(directory, 'design.html');
+    await writeFile(design, '');
+    await writeFile(path.join(directory, 'photo.png'), 'photo');
+
+    const report = await author(
+      '<link rel="icon" href="photo.png"><link rel="preload" as="image" href="photo.png"><link rel="manifest" href="photo.png"><link rel="stylesheet" href="photo.png"><svg><path fill="url(photo.png#paint)" filter="url(photo.png#filter)"/><mpath href="photo.png#motion"/><textPath href="photo.png#text">Text</textPath></svg>',
+      {
+        sourcePath: design,
+        outDir: path.join(directory, 'package'),
+        author: { name: 'acme/assets', styles: { mode: 'css', css: ' ' } },
+      },
+    );
+
+    expect(report.ok).toBe(true);
+    const assetReferences = report.assets?.filter((asset) => asset.reference.startsWith('photo.png')) ?? [];
+    expect(assetReferences).toHaveLength(8);
+    expect(assetReferences.every((asset) => asset.outcome === 'copied')).toBe(true);
+    expect(assetReferences.map((asset) => asset.kind)).toEqual(expect.arrayContaining(['image', 'stylesheet', 'other']));
+  });
 });

From c92379f815368dcc8bd1acc243bc1cf47283ca52 Mon Sep 17 00:00:00 2001
From: Noel Tock <hello@noeltock.com>
Date: Thu, 3 Sep 2026 15:23:22 +0700
Subject: [PATCH 3/4] Translate Tailwind/CSS into destination-native styles and
 assets

Closes #5
---
 package-lock.json   | 38 +----------------------
 src/author/index.ts | 75 +++++++++++++++++++++++++++++++++++++++------
 test/author.test.ts | 57 ++++++++++++++++++++++++++++++++++
 3 files changed, 123 insertions(+), 47 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 038f61e..fdccc3c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -4575,7 +4575,7 @@
       "version": "0.28.1",
       "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.1.tgz",
       "integrity": "sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==",
-      "devOptional": true,
+      "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
       "bin": {
@@ -6874,24 +6874,6 @@
         "node": ">= 12"
       }
     },
-    "node_modules/tsup/node_modules/yaml": {
-      "version": "2.9.0",
-      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
-      "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
-      "dev": true,
-      "license": "ISC",
-      "optional": true,
-      "peer": true,
-      "bin": {
-        "yaml": "bin.mjs"
-      },
-      "engines": {
-        "node": ">= 14.6"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/eemeli"
-      }
-    },
     "node_modules/tsx": {
       "version": "4.23.0",
       "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.23.0.tgz",
@@ -7265,24 +7247,6 @@
         }
       }
     },
-    "node_modules/vitest/node_modules/yaml": {
-      "version": "2.9.0",
-      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
-      "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
-      "dev": true,
-      "license": "ISC",
-      "optional": true,
-      "peer": true,
-      "bin": {
-        "yaml": "bin.mjs"
-      },
-      "engines": {
-        "node": ">= 14.6"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/eemeli"
-      }
-    },
     "node_modules/w3c-xmlserializer": {
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz",
diff --git a/src/author/index.ts b/src/author/index.ts
index 6ece06a..1d4f778 100644
--- a/src/author/index.ts
+++ b/src/author/index.ts
@@ -491,8 +491,13 @@ async function rewriteMarkupAssets(input: string, options: RewriteMarkupAssetsOp
     reference: string,
     kind: AssetLedgerEntry['kind'],
   ): Promise<string | undefined> => {
+    // Legacy SVG font-face-uri references do not necessarily carry a modern font extension. Put
+    // those through a synthetic @font-face so the shared classifier preserves its font-license
+    // rules rather than mistaking one for a generic image asset.
     const processed = await rewriteCssAssets({
-      sourceCss: `x{background-image:url(${JSON.stringify(reference)})}`,
+      sourceCss: kind === 'font'
+        ? `@font-face{src:url(${JSON.stringify(reference)})}`
+        : `x{background-image:url(${JSON.stringify(reference)})}`,
       sourcePath: options.write ? options.sourcePath : undefined,
       destinationAssetDir: options.destinationAssetDir,
       allowFontLicense: false,
@@ -564,9 +569,29 @@ async function rewriteMarkupAssets(input: string, options: RewriteMarkupAssetsOp
       }
     }
 
-    for (const { name: attribute, kind } of assetAttributesFor(element)) {
+    const assetAttributes = assetAttributesFor(element);
+    if (element.namespaceURI === 'http://www.w3.org/2000/svg') {
+      const knownAssetAttributes = new Set(assetAttributes.map(({ name }) => name.toLowerCase()));
+      for (const attribute of [...element.attributes]) {
+        const name = attribute.name.toLowerCase();
+        // SVG links are not all assets: `<a>` remains a normal navigational link. Every other
+        // element must be in the semantic table below before its href can pass through. This is
+        // deliberately fail-closed because an unknown link could otherwise leave a source-relative
+        // dependency in the generated package with no ledger outcome.
+        if (isSvgHrefAttribute(name) && element.localName.toLowerCase() !== 'a' && !knownAssetAttributes.has(name)) {
+          assets.push({
+            reference: attribute.value,
+            kind: 'other',
+            outcome: 'blocked',
+            reason: `SVG <${element.localName}> ${attribute.name} is not a recognized asset/reference attribute`,
+          });
+        }
+      }
+    }
+
+    for (const { name: attribute, kind } of assetAttributes) {
       const value = element.getAttribute(attribute);
-      if (!value?.trim()) continue;
+      if (value === null) continue;
       const rewritten = await processReference(value, kind);
       if (rewritten) {
         element.setAttribute(attribute, rewritten);
@@ -614,6 +639,41 @@ interface AssetAttribute {
   kind: AssetLedgerEntry['kind'];
 }
 
+const SVG_HREF_ASSET_KINDS: Readonly<Record<string, AssetLedgerEntry['kind']>> = {
+  // External image resources.
+  image: 'image',
+  feimage: 'image',
+  // SVG 2 reference attributes. These can point at an external SVG document as well as an
+  // element in this document, so they must receive the same classification/copy treatment as an
+  // ordinary asset reference instead of being inferred from a class or left source-relative.
+  animate: 'other',
+  animatecolor: 'other',
+  animatemotion: 'other',
+  animatetransform: 'other',
+  discard: 'other',
+  lineargradient: 'other',
+  mpath: 'other',
+  pattern: 'other',
+  radialgradient: 'other',
+  set: 'other',
+  textpath: 'other',
+  use: 'other',
+  // SVG 1.1/XLink forms remain in authored assets. Keep their kinds explicit rather than
+  // silently downgrading a legacy cursor/font/reference into an untracked string attribute.
+  altglyph: 'other',
+  'color-profile': 'other',
+  cursor: 'image',
+  'definition-src': 'font',
+  filter: 'other',
+  'font-face-uri': 'font',
+  tref: 'other',
+  glyphref: 'other',
+};
+
+function isSvgHrefAttribute(name: string): boolean {
+  return name === 'href' || name === 'xlink:href';
+}
+
 /**
  * Asset-bearing attributes are not interchangeable: HTML anchors use `href` for navigation while
  * SVG `<image href>` is a concrete image dependency. Keep the table element/namespace-aware so
@@ -623,13 +683,8 @@ interface AssetAttribute {
 function assetAttributesFor(element: Element): AssetAttribute[] {
   const tag = element.localName.toLowerCase();
   if (element.namespaceURI === 'http://www.w3.org/2000/svg') {
-    if (tag === 'image' || tag === 'feimage') {
-      return [{ name: 'href', kind: 'image' }, { name: 'xlink:href', kind: 'image' }];
-    }
-    if (tag === 'use' || tag === 'mpath' || tag === 'textpath') {
-      return [{ name: 'href', kind: 'other' }, { name: 'xlink:href', kind: 'other' }];
-    }
-    return [];
+    const kind = SVG_HREF_ASSET_KINDS[tag];
+    return kind ? [{ name: 'href', kind }, { name: 'xlink:href', kind }] : [];
   }
 
   switch (tag) {
diff --git a/test/author.test.ts b/test/author.test.ts
index 77e5027..262c452 100644
--- a/test/author.test.ts
+++ b/test/author.test.ts
@@ -469,4 +469,61 @@ describe('registered-block authoring parity ledger', () => {
     expect(assetReferences.every((asset) => asset.outcome === 'copied')).toBe(true);
     expect(assetReferences.map((asset) => asset.kind)).toEqual(expect.arrayContaining(['image', 'stylesheet', 'other']));
   });
+
+  it('accounts for SVG gradient, pattern, and animation href references without treating SVG links as navigation', async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), 'block-runner-author-'));
+    scratch.push(directory);
+    const design = path.join(directory, 'design.html');
+    const outDir = path.join(directory, 'package');
+    await writeFile(design, '');
+    await writeFile(path.join(directory, 'gradients.svg'), '<svg/>');
+
+    const report = await author(
+      `<a href="guide.pdf">Guide</a><svg>
+        <linearGradient href="gradients.svg#linear" />
+        <radialGradient href="https://cdn.example/gradients.svg#radial" />
+        <pattern xlink:href="#pattern" />
+        <animate href="gradients.svg#animated" />
+        <animateMotion xlink:href="gradients.svg#motion" />
+        <animateTransform href="gradients.svg#transform" />
+        <set xlink:href="gradients.svg#set" />
+        <discard href="gradients.svg#discard" />
+      </svg>`,
+      { sourcePath: design, outDir, author: { name: 'acme/assets' } },
+    );
+
+    expect(report.ok).toBe(true);
+    const assets = report.assets ?? [];
+    expect(assets).toHaveLength(8);
+    expect(assets.filter((asset) => asset.reference.startsWith('gradients.svg')).every((asset) => asset.outcome === 'copied')).toBe(true);
+    expect(assets).toContainEqual(expect.objectContaining({
+      reference: 'https://cdn.example/gradients.svg#radial',
+      outcome: 'external',
+    }));
+    expect(assets).toContainEqual(expect.objectContaining({ reference: '#pattern', outcome: 'external' }));
+    expect(assets.some((asset) => asset.reference === 'guide.pdf')).toBe(false);
+    expect(report.package?.files['index.js']).toContain('./assets/');
+  });
+
+  it('blocks an unrecognized SVG href form instead of silently leaving it source-relative', async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), 'block-runner-author-'));
+    scratch.push(directory);
+    const design = path.join(directory, 'design.html');
+    const outDir = path.join(directory, 'package');
+    await writeFile(design, '');
+    await writeFile(path.join(directory, 'unknown.svg'), '<svg/>');
+
+    const report = await author(
+      '<svg><foreignObject xlink:href="unknown.svg#content" /></svg>',
+      { sourcePath: design, outDir, author: { name: 'acme/assets' } },
+    );
+
+    expect(report.ok).toBe(false);
+    expect(report.assets).toContainEqual(expect.objectContaining({
+      reference: 'unknown.svg#content',
+      outcome: 'blocked',
+      reason: expect.stringMatching(/foreignObject.*xlink:href.*recognized/i),
+    }));
+    await expect(readFile(path.join(outDir, 'block.json'), 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
+  });
 });

From c4058bd06b3c26de8342ec7cdb6bb73bcf02ba35 Mon Sep 17 00:00:00 2001
From: Noel Tock <hello@noeltock.com>
Date: Fri, 4 Sep 2026 08:57:08 +0700
Subject: [PATCH 4/4] Resolve authoring merge conflicts

---
 src/cli.ts   | 25 +++++++++++++++++++------
 src/index.ts |  2 +-
 2 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/src/cli.ts b/src/cli.ts
index 5a0029e..81f4b27 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -10,7 +10,7 @@ import fg from 'fast-glob';
 import { canonicalize } from './gate/canonicalize.js';
 import { validate } from './gate/validate.js';
 import { convert } from './convert/assemble.js';
-import { author } from './author/index.js';
+import { author as generateRegisteredBlock } from './author/index.js';
 import { realize } from './intent/index.js';
 import { loadConfig } from './config/load.js';
 import { collectSiteContext } from './context/run.js';
@@ -97,19 +97,27 @@ addTokenOptions(
     process.exitCode = report.ok ? 0 : 1;
   });
 
+const author = program.command('author').description('Review and materialize a versioned registered-block authoring plan.');
+
 addTokenOptions(
   addWpCredentialOptions(
-    addSharedOptions(program.command('author <htmlOrStdin>').description('Generate one static, registered block package.'), {
+    addSharedOptions(program.command('generate-author <htmlOrStdin>', { hidden: true }), {
       output: false,
     }),
   ),
   { styling: false },
 )
-  .requiredOption('--name <namespace/slug>', 'registered block name, for example acme/hero')
+  .option('--name <namespace/slug>', 'registered block name, for example acme/hero')
   .option('--title <title>', 'block title (defaults from the slug)')
   .option('--category <category>', 'block category (default: widgets)')
   .option('--out-dir <path>', 'write the generated package and copied assets to this directory')
   .action(async (htmlOrStdin: string, options: CliOptions) => {
+    if (!htmlOrStdin) {
+      program.error('error: author needs exactly one design input');
+    }
+    if (!options.name) {
+      program.error("error: required option '--name <namespace/slug>' not specified");
+    }
     const apiOptions = normalizeOptions(options);
     const inputs = await readInputs(htmlOrStdin, { allowInline: true });
     if (inputs.length !== 1) {
@@ -122,7 +130,7 @@ addTokenOptions(
     if (!input) {
       return;
     }
-    const report = await author(input.content, {
+    const report = await generateRegisteredBlock(input.content, {
       ...apiOptions,
       sourcePath: input.path,
       outDir: options.outDir,
@@ -305,8 +313,6 @@ program
     }
   });
 
-const author = program.command('author').description('Review and materialize a versioned registered-block authoring plan.');
-
 author
   .command('preview <planOrStdin>')
   .description('Validate and render an authoring plan without writing files.')
@@ -400,6 +406,7 @@ author
 
 async function main(): Promise<void> {
   try {
+    routeDirectAuthorInvocation(process.argv);
     rejectAssembleStylingOptions(process.argv);
     await program.parseAsync(process.argv);
   } catch (error) {
@@ -419,6 +426,12 @@ async function main(): Promise<void> {
   }
 }
 
+function routeDirectAuthorInvocation(argv: string[]): void {
+  if (argv[2] === 'author' && argv[3] && !['preview', 'write'].includes(argv[3])) {
+    argv[2] = 'generate-author';
+  }
+}
+
 function addSharedOptions(command: Command, options: { output?: boolean } = {}): Command {
   const withCommon = command
     .option('--config <path>', 'path to block-runner config')
diff --git a/src/index.ts b/src/index.ts
index 1e4bcde..ffe24a2 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -47,7 +47,7 @@ export type {
   AuthoringNodeLock,
   AuthoringPattern,
   AuthoringPatternOverride,
-  AuthoringPlan,
+  AuthoringPlan as GeneratedAuthoringPlan,
   AuthoringStructureNode,
   AuthoringStyleOutcome,
   AuthoringStyleOutcomeKind,