@hienlh/ppm 0.22.11 → 0.23.1

package/src/services/design/preview/design-preview-scope.ts

@@ -0,0 +1,66 @@
+import { realpath } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { guardPreviewAsset, isInsideRoot, previewDenied } from "../../../server/helpers/preview-asset-guard.ts";
+import { resolveDesignDir, resolveDesignsRoot } from "../design-paths.ts";
+import type { DesignRef } from "./design-preview-tokens.ts";
+
+/**
+ * Which file a preview request under one token may read.
+ *
+ * A token covers `designs/<slug>/**` and exactly one alias, `tokens.css`, which is the
+ * shared `designs/tokens.css` (a design links it as `../tokens.css`, and from
+ * `/content/<token>/<slug>/index.html` that resolves to `/content/<token>/tokens.css`).
+ * Everything else — another design, `DESIGN.md`, anything under a dot-directory such as
+ * the design's own `.design/` — is a 403.
+ *
+ * The design folder is re-resolved on every request rather than remembered from mint, so a
+ * design deleted or swapped for a symlink after the token was issued stops being served.
+ */
+
+export const TOKENS_CSS_ALIAS = "tokens.css";
+
+export interface ScopedAsset {
+  abs: string;
+  /** Path relative to the design folder, `/`-separated; `../tokens.css` for the alias. */
+  rel: string;
+  designDir: string;
+}
+
+function decodeRequestPath(encoded: string): string {
+  try {
+    return decodeURIComponent(encoded);
+  } catch {
+    previewDenied();
+  }
+}
+
+async function containedFile(root: string, candidate: string): Promise<string> {
+  if (!isInsideRoot(root, candidate)) previewDenied();
+  guardPreviewAsset(candidate, root);
+  const real = await realpath(candidate);
+  if (!isInsideRoot(root, real)) previewDenied();
+  guardPreviewAsset(real, root);
+  return real;
+}
+
+/** Throws `{status: 403}` for anything outside the token's scope, ENOENT when missing. */
+export async function resolveScopedAsset(design: DesignRef, encodedPath: string): Promise<ScopedAsset> {
+  return resolveScopedPath(design, decodeRequestPath(encodedPath));
+}
+
+/** {@link resolveScopedAsset} for a path that is already decoded (`<slug>/…` or the alias). */
+export async function resolveScopedPath(design: DesignRef, path: string): Promise<ScopedAsset> {
+  // Checked after decoding, so `%2F`, `%5C` and `%00` cannot smuggle a separator past it.
+  if (!path || path.includes("\\") || path.includes("\0") || path.includes(":")) previewDenied();
+  const designDir = await resolveDesignDir(design.projectPath, design.slug);
+  if (path === TOKENS_CSS_ALIAS) {
+    const root = await resolveDesignsRoot(design.projectPath);
+    if (!root) previewDenied();
+    return { abs: await containedFile(root, join(root, TOKENS_CSS_ALIAS)), rel: `../${TOKENS_CSS_ALIAS}`, designDir };
+  }
+  const prefix = `${design.slug}/`;
+  if (!path.startsWith(prefix) || path.length === prefix.length) previewDenied();
+  const candidate = resolve(designDir, path.slice(prefix.length));
+  const abs = await containedFile(designDir, candidate);
+  return { abs, rel: relative(designDir, candidate).split(sep).join("/"), designDir };
+}

package/src/services/design/preview/design-preview-tokens.ts

@@ -0,0 +1,137 @@
+/**
+ * Capabilities for the design preview route: an unguessable token that lets a sandboxed
+ * iframe (which carries no PPM credentials) read one design's files.
+ *
+ * The rules, and why:
+ *  - A token names one design (`projectPath` + `slug`) and one purpose. It never authorises
+ *    another design, even in the same project.
+ *  - Resolving a token — what every unauthenticated content GET does — never extends it. If
+ *    reads slid the expiry, anything that learned a token could keep it alive forever.
+ *  - Only the authenticated refresh extends a canvas token, by the idle TTL, and never past a
+ *    hard cap counted from mint. Close to that cap the refresh *rotates*: it returns a new
+ *    token for the canvas's next reload, while the old one keeps serving the document already
+ *    loaded — refreshing the new token extends the old one too — until its own hard cap.
+ *  - Print and standalone tokens are short-lived and cannot be refreshed.
+ *
+ * Pure logic with `now` injected; the store lives in memory, so a restart invalidates every
+ * token and the canvas re-mints.
+ */
+
+export const DESIGN_PREVIEW_PURPOSES = ["canvas", "print", "standalone"] as const;
+export type DesignPreviewPurpose = (typeof DESIGN_PREVIEW_PURPOSES)[number];
+
+export function isDesignPreviewPurpose(value: unknown): value is DesignPreviewPurpose {
+  return typeof value === "string" && (DESIGN_PREVIEW_PURPOSES as readonly string[]).includes(value);
+}
+
+const MINUTE = 60 * 1000;
+const HOUR = 60 * MINUTE;
+export const CANVAS_IDLE_TTL = 30 * MINUTE;
+export const CANVAS_HARD_TTL = 8 * HOUR;
+/** Refreshing inside this window before the hard cap hands out a successor token. */
+export const ROTATE_WINDOW = HOUR;
+export const ONE_SHOT_TTL = 10 * MINUTE;
+export const MAX_PREVIEW_TOKENS = 128;
+
+export interface DesignPreviewCapability {
+  token: string;
+  projectPath: string;
+  slug: string;
+  purpose: DesignPreviewPurpose;
+  mintedAt: number;
+  idleExpires: number;
+  hardExpires: number;
+  /** Set once this token has been rotated, so repeated refreshes return one successor. */
+  successor?: string;
+  /** The token this one replaced, which may still be serving the loaded document. */
+  predecessor?: string;
+}
+
+export interface DesignRef {
+  projectPath: string;
+  slug: string;
+}
+
+export type RefreshResult =
+  | { ok: true; capability: DesignPreviewCapability; rotated: boolean }
+  | { ok: false; reason: "unknown" | "wrong-design" | "not-refreshable" };
+
+export interface DesignPreviewTokenStore {
+  mint(design: DesignRef, purpose: DesignPreviewPurpose): DesignPreviewCapability;
+  /** Authenticated only: extends a canvas token, rotating it near the hard cap. */
+  refresh(token: string, design: DesignRef): RefreshResult;
+  /** The live capability for a token, or null. Never changes any expiry. */
+  resolve(token: string): DesignPreviewCapability | null;
+  size(): number;
+}
+
+export function createDesignPreviewTokenStore(
+  now: () => number = Date.now,
+  maxTokens = MAX_PREVIEW_TOKENS,
+): DesignPreviewTokenStore {
+  const tokens = new Map<string, DesignPreviewCapability>();
+  const alive = (cap: DesignPreviewCapability, at: number): boolean => at < cap.idleExpires && at < cap.hardExpires;
+
+  function prune(at: number): void {
+    for (const [token, cap] of tokens) if (!alive(cap, at)) tokens.delete(token);
+  }
+
+  function mint(design: DesignRef, purpose: DesignPreviewPurpose): DesignPreviewCapability {
+    const at = now();
+    prune(at);
+    // Oldest first: Map iteration is insertion order.
+    while (tokens.size >= maxTokens) tokens.delete(tokens.keys().next().value!);
+    const hard = at + (purpose === "canvas" ? CANVAS_HARD_TTL : ONE_SHOT_TTL);
+    const cap: DesignPreviewCapability = {
+      token: crypto.randomUUID(),
+      projectPath: design.projectPath,
+      slug: design.slug,
+      purpose,
+      mintedAt: at,
+      idleExpires: purpose === "canvas" ? Math.min(at + CANVAS_IDLE_TTL, hard) : hard,
+      hardExpires: hard,
+    };
+    tokens.set(cap.token, cap);
+    return cap;
+  }
+
+  function resolve(token: string): DesignPreviewCapability | null {
+    const cap = tokens.get(token);
+    if (!cap) return null;
+    if (!alive(cap, now())) {
+      tokens.delete(token);
+      return null;
+    }
+    return cap;
+  }
+
+  function refresh(token: string, design: DesignRef): RefreshResult {
+    const cap = resolve(token);
+    if (!cap) return { ok: false, reason: "unknown" };
+    if (cap.projectPath !== design.projectPath || cap.slug !== design.slug) return { ok: false, reason: "wrong-design" };
+    if (cap.purpose !== "canvas") return { ok: false, reason: "not-refreshable" };
+    const at = now();
+    const extend = (c: DesignPreviewCapability): void => { c.idleExpires = Math.min(at + CANVAS_IDLE_TTL, c.hardExpires); };
+    extend(cap);
+    // After a rotation the canvas refreshes with the new token while the document it loaded
+    // with the old one is still on screen and may fetch lazy assets. Keep that one alive too,
+    // up to its own hard cap.
+    const previous = cap.predecessor ? resolve(cap.predecessor) : null;
+    if (previous) extend(previous);
+    if (at < cap.hardExpires - ROTATE_WINDOW) return { ok: true, capability: cap, rotated: false };
+    const existing = cap.successor ? resolve(cap.successor) : null;
+    if (existing) {
+      extend(existing);
+      return { ok: true, capability: existing, rotated: true };
+    }
+    const next = mint(design, "canvas");
+    // mint() may have evicted the old token to make room; it is still the one being
+    // refreshed, so put it back rather than strand the loaded document.
+    if (!tokens.has(cap.token)) tokens.set(cap.token, cap);
+    cap.successor = next.token;
+    next.predecessor = cap.token;
+    return { ok: true, capability: next, rotated: true };
+  }
+
+  return { mint, refresh, resolve, size: () => tokens.size };
+}

package/src/services/design/preview/expired-page.ts

@@ -0,0 +1,30 @@
+import { BRIDGE_CHANNEL, BRIDGE_NONCE_RE, BRIDGE_VERSION } from "../../../shared/design-bridge-protocol.ts";
+
+/**
+ * What the design frame receives instead of the design when its token is dead (expired,
+ * unknown, or lost to a server restart).
+ *
+ * A JSON 404 would do nothing useful: the frame is an opaque origin, so the parent cannot
+ * read its contents or tell an error page from a slow design. This page tells the parent
+ * itself, with the load's nonce, and the canvas re-mints a token and reloads.
+ */
+
+export const EXPIRED_PAGE_CSP = [
+  "sandbox allow-scripts",
+  "default-src 'none'",
+  "script-src 'unsafe-inline'",
+  "style-src 'unsafe-inline'",
+  "base-uri 'none'",
+  "form-action 'none'",
+  "frame-ancestors 'self'",
+].join("; ");
+
+export function expiredPageHtml(nonce: string | null): string {
+  // Only a nonce of the validated shape is ever written into the script, as a JSON literal.
+  const safeNonce = nonce && BRIDGE_NONCE_RE.test(nonce) ? nonce : null;
+  const message = JSON.stringify({ ppm: BRIDGE_CHANNEL, v: BRIDGE_VERSION, nonce: safeNonce, type: "expired" });
+  return `<!doctype html><html><head><meta charset="utf-8"><title>Preview expired</title>`
+    + `<script>try{parent.postMessage(${message},"*")}catch(e){}</script>`
+    + `<style>body{font:14px system-ui,sans-serif;color:#666;display:grid;place-items:center;height:100vh;margin:0}</style>`
+    + `</head><body><p>This preview has expired. Reopening the design refreshes it.</p></body></html>`;
+}

package/src/services/design/preview/html-instrument.ts

@@ -0,0 +1,119 @@
+import { parse, type DefaultTreeAdapterMap } from "parse5";
+
+/**
+ * Serve-time instrumentation of a design's HTML.
+ *
+ * Every element whose start tag is in the source gets `data-ppm-id="<offset>"`, where the
+ * offset is the index of its `<` in the (BOM-less) source text. The offset *is* the id: it
+ * lets a later write find the element's tag in the file without re-serialising anything,
+ * and it is only meaningful together with the file's `gen`.
+ *
+ * The attribute is spliced in right after the tag name, so it is always the element's
+ * first attribute — a stale `data-ppm-id` copied into the file loses to it, because the
+ * HTML parser keeps the first of two duplicate attributes. The source is never
+ * re-serialised; only these insertions change.
+ *
+ * parse5 offsets are UTF-16 code-unit indices into exactly the string it was given (CRLF
+ * counts as two, an astral character as two), which is what `String#slice` uses. Elements
+ * the parser invents (an implicit `<html>`, `<head>`, `<tbody>`) have no start tag and so no
+ * id; an element cloned by the adoption agency algorithm shares its original's.
+ */
+
+type Node = DefaultTreeAdapterMap["node"];
+type Element = DefaultTreeAdapterMap["element"];
+
+export interface HtmlAnalysis {
+  /** Sorted, unique start-tag offsets. */
+  elementOffsets: number[];
+  /** Where a script must go to run before any of the page's own. */
+  headOffset: number;
+  /** `href`s of local `<link rel=stylesheet>`, as written, in document order. */
+  stylesheetHrefs: string[];
+}
+
+const isElement = (node: Node): node is Element => "tagName" in node;
+
+function attr(el: Element, name: string): string | undefined {
+  return el.attrs.find((a) => a.name === name)?.value;
+}
+
+/** Relative URLs only: no scheme, no protocol-relative or root-relative path, no fragment. */
+export function isLocalHref(href: string): boolean {
+  const h = href.trim();
+  return h !== "" && !/^[a-z][a-z0-9+.-]*:/i.test(h) && !h.startsWith("/") && !h.startsWith("\\") && !h.startsWith("#");
+}
+
+export function analyzeHtml(text: string): HtmlAnalysis {
+  const doc = parse(text, { sourceCodeLocationInfo: true });
+  const offsets = new Set<number>();
+  const stylesheetHrefs: string[] = [];
+  let doctypeEnd = 0;
+  let htmlEnd: number | undefined;
+  let headEnd: number | undefined;
+
+  // Iterative, so a pathologically deep document cannot overflow the stack.
+  const stack: Array<{ node: Node; inTemplate: boolean }> = [];
+  for (let i = doc.childNodes.length - 1; i >= 0; i--) stack.push({ node: doc.childNodes[i]!, inTemplate: false });
+  while (stack.length) {
+    const { node, inTemplate } = stack.pop()!;
+    if (node.nodeName === "#documentType" && node.sourceCodeLocation) doctypeEnd = node.sourceCodeLocation.endOffset;
+    if (!isElement(node)) continue;
+    const start = node.sourceCodeLocation?.startTag;
+    if (start && text.charCodeAt(start.startOffset) === 60 /* < */) {
+      offsets.add(start.startOffset);
+      if (node.tagName === "html" && htmlEnd === undefined) htmlEnd = start.endOffset;
+      if (node.tagName === "head" && headEnd === undefined) headEnd = start.endOffset;
+    }
+    if (!inTemplate && node.tagName === "link") {
+      const rel = (attr(node, "rel") ?? "").toLowerCase().split(/\s+/);
+      const href = attr(node, "href");
+      if (rel.includes("stylesheet") && href !== undefined && isLocalHref(href)) stylesheetHrefs.push(href.trim());
+    }
+    const children = node.tagName === "template"
+      ? (node as DefaultTreeAdapterMap["template"]).content.childNodes
+      : node.childNodes;
+    const childInTemplate = inTemplate || node.tagName === "template";
+    for (let i = children.length - 1; i >= 0; i--) stack.push({ node: children[i]!, inTemplate: childInTemplate });
+  }
+  return {
+    elementOffsets: [...offsets].sort((a, b) => a - b),
+    headOffset: headEnd ?? htmlEnd ?? doctypeEnd,
+    stylesheetHrefs,
+  };
+}
+
+export const elementStartOffsets = (text: string): number[] => analyzeHtml(text).elementOffsets;
+export const headInsertOffset = (text: string): number => analyzeHtml(text).headOffset;
+export const localStylesheetHrefs = (text: string): string[] => analyzeHtml(text).stylesheetHrefs;
+
+/** Index just past the tag name of the start tag at `offset` (the tokenizer's own stop set). */
+export function tagNameEnd(text: string, offset: number): number {
+  let i = offset + 1;
+  while (i < text.length && !/[\t\n\f\r />]/.test(text[i]!)) i++;
+  return i;
+}
+
+/** Splice ids and the bridge into `text`. `analysis` must come from this same text. */
+export function instrumentHtml(text: string, bridgeTag: string, analysis: HtmlAnalysis = analyzeHtml(text)): string {
+  const inserts: Array<[number, string]> = analysis.elementOffsets.map((o) => [tagNameEnd(text, o), ` data-ppm-id="${o}"`]);
+  inserts.push([analysis.headOffset, bridgeTag]);
+  inserts.sort((a, b) => a[0] - b[0]);
+  const out: string[] = [];
+  let cursor = 0;
+  for (const [at, snippet] of inserts) {
+    out.push(text.slice(cursor, at), snippet);
+    cursor = at;
+  }
+  out.push(text.slice(cursor));
+  return out.join("");
+}
+
+/**
+ * The bridge alone, for documents too large to parse: after a leading doctype, so the page
+ * stays out of quirks mode, and otherwise at the very start.
+ */
+export function injectWithoutParsing(text: string, bridgeTag: string): string {
+  const doctype = /^\s*<!doctype[^>]*>/i.exec(text);
+  const at = doctype ? doctype[0].length : 0;
+  return text.slice(0, at) + bridgeTag + text.slice(at);
+}

package/src/services/design/preview/print-view.ts

@@ -0,0 +1,62 @@
+import type { DesignKind } from "../../../shared/design-types.ts";
+
+/**
+ * What the print view adds to a design page: page geometry, and a script that opens the
+ * print dialog once the page (fonts included) has settled.
+ *
+ * Only a document served under a print-purpose token gets this, and that document is the
+ * one design document whose CSP sandbox carries `allow-modals` — a canvas never does. A deck
+ * prints one `section.slide` (or `[data-slide]`) per 1280x720 page with no margin; any other
+ * design prints on the browser's paper size with a 12 mm margin. The rules are `!important`
+ * because they are inserted before the page's own styles and must still win.
+ *
+ * `print()` can be refused without an exception (a browser ignoring modals in a sandboxed
+ * document, or one that only prints from a user gesture), and nothing but `beforeprint` says
+ * whether the dialog opened. When it did not, a banner asks for Ctrl/Cmd+P and offers a
+ * button, whose click is a gesture. The banner never prints itself.
+ */
+
+const SLIDE_RULES = "@page{size:1280px 720px;margin:0}"
+  + "html,body{margin:0!important;padding:0!important}"
+  + "section.slide,[data-slide]{break-after:page!important;page-break-after:always!important;break-inside:avoid!important;margin:0!important;box-shadow:none!important}"
+  + "section.slide:last-of-type,[data-slide]:last-of-type{break-after:auto!important;page-break-after:auto!important}";
+const PAGE_RULES = "@page{margin:12mm}";
+const COMMON_RULES = "html{-webkit-print-color-adjust:exact;print-color-adjust:exact}"
+  + "#ppm-print-banner{position:fixed;top:12px;left:50%;transform:translateX(-50%);z-index:2147483647;display:flex;gap:12px;align-items:center;"
+  + "padding:10px 16px;border-radius:8px;background:#111827;color:#fff;font:14px/1.4 system-ui,sans-serif;box-shadow:0 4px 16px rgba(0,0,0,.3)}"
+  + "#ppm-print-banner button{min-height:44px;padding:0 16px;border:0;border-radius:6px;background:#fff;color:#111827;font:inherit;cursor:pointer}"
+  + "@media print{#ppm-print-banner{display:none!important}}";
+
+// One constant, with no request-derived value in it; checked below like the bridge.
+const PRINT_SCRIPT = `(function(){
+var opened=false,started=false;
+window.addEventListener("beforeprint",function(){opened=true;var b=document.getElementById("ppm-print-banner");if(b)b.remove();});
+function banner(){
+if(opened||document.getElementById("ppm-print-banner"))return;
+var mac=/Mac|iPhone|iPad/.test(navigator.platform||navigator.userAgent);
+var b=document.createElement("div");b.id="ppm-print-banner";b.setAttribute("role","alert");
+var t=document.createElement("span");t.textContent="The print dialog did not open. Press "+(mac?"Cmd":"Ctrl")+"+P to save this as a PDF.";
+var k=document.createElement("button");k.type="button";k.textContent="Print";k.onclick=function(){try{window.print();}catch(e){}};
+b.appendChild(t);b.appendChild(k);(document.body||document.documentElement).appendChild(b);
+}
+function go(){
+if(started)return;started=true;
+setTimeout(function(){
+try{window.print();}catch(e){}
+setTimeout(banner,1000);
+},300);
+}
+window.addEventListener("load",function(){
+var f=document.fonts&&document.fonts.ready;
+if(f)f.then(go,go);else go();
+});
+})();`;
+
+if (/<\/script|<!--|<script/i.test(PRINT_SCRIPT)) {
+  throw new Error("The print script contains a sequence that would break out of its <script> element");
+}
+
+export function printInjection(kind: DesignKind): string {
+  const rules = (kind === "slides" ? SLIDE_RULES : PAGE_RULES) + COMMON_RULES;
+  return `<style data-ppm-print="1">${rules}</style><script data-ppm-print="1">${PRINT_SCRIPT}</script>`;
+}

package/src/services/design/source/css-root-selector.ts

@@ -0,0 +1,20 @@
+/**
+ * Whether a style rule's selector targets the document root, for the `:root` variable
+ * scanner. Only a list entry that is exactly `:root` or `html` counts: `html:root`, `:is(...)`
+ * and friends are left alone rather than guessed at. `exclusive` means the rule names the
+ * root and nothing else, so rewriting one of its declarations cannot restyle other elements.
+ */
+export function rootSelectorKind(selector: string): { root: boolean; exclusive: boolean } {
+  const parts: string[] = [];
+  let depth = 0, from = 0;
+  const plain = selector.replace(/\/\*[\s\S]*?\*\//g, " ");
+  for (let k = 0; k < plain.length; k++) {
+    if (plain[k] === "(") depth++;
+    else if (plain[k] === ")") depth--;
+    else if (plain[k] === "," && depth === 0) { parts.push(plain.slice(from, k)); from = k + 1; }
+  }
+  parts.push(plain.slice(from));
+  const names = parts.map((p) => p.trim().replace(/\s+/g, " ").toLowerCase());
+  const root = names.some((n) => n === ":root" || n === "html");
+  return { root, exclusive: root && names.length === 1 };
+}

package/src/services/design/source/css-root-vars-patch.ts

@@ -0,0 +1,202 @@
+import { rootSelectorKind } from "./css-root-selector.ts";
+
+/**
+ * Finds and rewrites custom-property declarations of top-level `:root` / `html` rules in a
+ * stylesheet, touching nothing else: every edit is a splice at offsets this scanner found,
+ * never a re-serialisation, so the rest of the file stays byte-identical.
+ *
+ * It is a scanner, not a CSS parser. It knows enough to never be fooled by `:root{` inside a
+ * comment, a string or an unquoted `url(...)` (a data URL holds `;` and `{`), to skip nested
+ * blocks, and to mark a declaration inside any at-rule block (`@media`, `@supports`,
+ * `@layer`, …) as `conditional`, since it is not always in effect. Everything it does not
+ * understand is skipped rather than guessed at; the caller then appends a fresh `:root`
+ * block at the end, which wins the cascade, and never prepends one, which would lose it.
+ */
+
+export interface RootVarDeclaration {
+  var: string;
+  /** The value, without surrounding whitespace, comments or `!important`. */
+  valueStart: number;
+  valueEnd: number;
+  conditional: boolean;
+  /** The innermost enclosing at-rule (`@media`), when conditional. */
+  atRule: string | null;
+  /** The selector is `:root` or `html` alone, not a list that also names other elements. */
+  exclusive: boolean;
+  important: boolean;
+}
+
+export interface CssRootScan {
+  declarations: RootVarDeclaration[];
+  /** False when the text ends inside a comment, string, block or rule prelude: appending there would be swallowed. */
+  endsClean: boolean;
+}
+
+const GROUPING_AT_RULES = new Set(["media", "supports", "layer", "container", "document", "scope", "starting-style"]);
+const WS = /\s/;
+const CLOSER: Record<string, string> = { "(": ")", "[": "]", "{": "}" };
+/** An unquoted `url(`: its contents are literal up to `)`, quotes, `;` and `{` included. */
+const UNQUOTED_URL = /url\(\s*[^\s"')]/iy;
+
+export function scanRootVars(css: string): CssRootScan {
+  const len = css.length;
+  const declarations: RootVarDeclaration[] = [];
+  let clean = true;
+
+  const skipComment = (i: number): number => {
+    const close = css.indexOf("*/", i + 2);
+    if (close < 0) { clean = false; return len; }
+    return close + 2;
+  };
+  const skipString = (i: number): number => {
+    const quote = css[i];
+    for (let j = i + 1; j < len; j++) {
+      if (css[j] === "\\") j++;
+      else if (css[j] === quote) return j + 1;
+      else if (css[j] === "\n") return j; // an unterminated string ends at the line break
+    }
+    clean = false;
+    return len;
+  };
+  /** Index of the first `stops` character outside comments, strings and nested brackets. */
+  const scanUntil = (from: number, stops: string): number => {
+    const stack: string[] = [];
+    let i = from;
+    while (i < len) {
+      const c = css[i]!;
+      if (c === "/" && css[i + 1] === "*") { i = skipComment(i); continue; }
+      if (c === '"' || c === "'") { i = skipString(i); continue; }
+      if (c === "\\") { if (i + 1 >= len) clean = false; i += 2; continue; }
+      if (stack.length === 0 && stops.includes(c)) return i;
+      UNQUOTED_URL.lastIndex = i;
+      if ((c === "u" || c === "U") && UNQUOTED_URL.test(css) && !/[\w-]/.test(css[i - 1] ?? "")) {
+        const close = css.indexOf(")", i + 4);
+        if (close < 0) { clean = false; return len; }
+        i = close + 1;
+        continue;
+      }
+      if (CLOSER[c]) stack.push(CLOSER[c]!);
+      else if (stack.length && c === stack[stack.length - 1]) stack.pop();
+      i++;
+    }
+    if (stack.length) clean = false;
+    return len;
+  };
+  /** `open` is a `{`; answers the index of its `}` (len when unterminated). */
+  const blockEnd = (open: number): number => {
+    const end = scanUntil(open + 1, "}");
+    if (end >= len) clean = false;
+    return end;
+  };
+  const skipSpace = (i: number, end: number): number => {
+    while (i < end) {
+      if (WS.test(css[i]!)) i++;
+      else if (css.startsWith("/*", i)) i = skipComment(i);
+      else if (css.startsWith("<!--", i)) i += 4;
+      else if (css.startsWith("-->", i)) i += 3;
+      else break;
+    }
+    return i;
+  };
+
+  const declaration = (start: number, end: number, ctx: { atRule: string | null; exclusive: boolean }): void => {
+    const name = /^--[A-Za-z0-9_-]+/.exec(css.slice(start, Math.min(end, start + 200)));
+    if (!name) return;
+    const colon = skipSpace(start + name[0].length, end);
+    if (css[colon] !== ":") return;
+    let first = -1, last = colon + 1;
+    for (let k = colon + 1; k < end;) {
+      if (css.startsWith("/*", k)) { k = skipComment(k); continue; }
+      if (WS.test(css[k]!)) { k++; continue; }
+      if (first < 0) first = k;
+      k = css[k] === '"' || css[k] === "'" ? skipString(k) : k + 1;
+      last = Math.min(k, end);
+    }
+    let valueStart = first < 0 ? colon + 1 : first;
+    let valueEnd = first < 0 ? colon + 1 : last;
+    const important = /!\s*important$/i.exec(css.slice(valueStart, valueEnd));
+    if (important) {
+      valueEnd -= important[0].length;
+      while (valueEnd > valueStart && WS.test(css[valueEnd - 1]!)) valueEnd--;
+    }
+    declarations.push({
+      var: name[0], valueStart, valueEnd, conditional: ctx.atRule !== null, atRule: ctx.atRule,
+      exclusive: ctx.exclusive, important: !!important,
+    });
+  };
+
+  const declarations_ = (start: number, end: number, ctx: { atRule: string | null; exclusive: boolean }): void => {
+    let i = start;
+    while (i < end) {
+      i = skipSpace(i, end);
+      if (css[i] === ";") { i++; continue; }
+      if (i >= end) break;
+      let stop = Math.min(scanUntil(i, ";{}"), end);
+      if (css[stop] === "{") {
+        const close = blockEnd(stop);
+        // A custom property may hold a `{}` block as its value; anything else is a nested rule.
+        if (!/^--[A-Za-z0-9_-]+\s*:/.test(css.slice(i, stop))) { i = close + 1; continue; }
+        stop = Math.min(scanUntil(close + 1, ";}"), end);
+      }
+      declaration(i, stop, ctx);
+      i = stop;
+    }
+  };
+
+  const rules = (start: number, end: number, atRule: string | null): void => {
+    let i = start;
+    while (i < end) {
+      i = skipSpace(i, end);
+      if (i >= end) break;
+      if (css[i] === "}" || css[i] === ";") { i++; continue; }
+      const stop = scanUntil(i, css[i] === "@" ? "{;" : "{");
+      if (stop >= end) {
+        // A prelude with nothing after it: text appended now would join it.
+        if (stop >= len) clean = false;
+        break;
+      }
+      if (css[stop] === ";") { i = stop + 1; continue; }
+      const close = blockEnd(stop);
+      if (css[i] === "@") {
+        const name = (/^@([A-Za-z-]+)/.exec(css.slice(i, stop))?.[1] ?? "").toLowerCase();
+        if (GROUPING_AT_RULES.has(name)) rules(stop + 1, close, `@${name}`);
+      } else {
+        const kind = rootSelectorKind(css.slice(i, stop));
+        if (kind.root) declarations_(stop + 1, close, { atRule, exclusive: kind.exclusive });
+      }
+      i = close + 1;
+    }
+  };
+
+  rules(0, len, null);
+  return { declarations, endsClean: clean };
+}
+
+/** Every declaration of a custom property in a top-level (or at-rule nested) `:root`/`html` rule, in order. */
+export function findRootVarDeclarations(css: string): RootVarDeclaration[] {
+  return scanRootVars(css).declarations;
+}
+
+/** `css` with one declaration's value replaced; every other byte kept. */
+export function replaceValue(css: string, decl: Pick<RootVarDeclaration, "valueStart" | "valueEnd">, value: string): string {
+  return css.slice(0, decl.valueStart) + value + css.slice(decl.valueEnd);
+}
+
+/**
+ * `css` with a new `:root { ... }` block after its last rule (before trailing whitespace), or
+ * null when the text does not end cleanly — the block would land inside an open comment or
+ * rule and never apply.
+ */
+export function appendRootBlock(css: string, values: ReadonlyArray<readonly [string, string]>): string | null {
+  if (values.length === 0) return css;
+  if (!scanRootVars(css).endsClean) return null;
+  // Written in the file's own line endings, so a CRLF file does not come back mixed.
+  const eol = css.includes("\r\n") ? "\r\n" : "\n";
+  const body = values.map(([name, value]) => `  ${name}: ${value};${eol}`).join("");
+  const block = `:root {${eol}${body}}`;
+  let cut = css.length;
+  while (cut > 0 && WS.test(css[cut - 1]!)) cut--;
+  const head = css.slice(0, cut);
+  const tail = css.slice(cut);
+  return `${head}${head ? eol + eol : ""}${block}${tail || eol}`;
+}