@jxsuite/import 0.40.8 → 0.40.10

package/src/componentize.ts

@@ -1,5 +1,5 @@
 import type { JxElement } from "@jxsuite/schema/types";
-import { displayTagName } from "@jxsuite/schema/guards";
+import { displayTagName, isBoolean, isNumber, isString } from "@jxsuite/schema/guards";
 
 export interface ComponentizeOptions {
   minInstances?: number;
@@ -25,27 +25,27 @@ interface SubtreeLocation {
 }
 
 function nodeDepth(node: JxElement | string): number {
-  if (typeof node === "string") {
+  if (isString(node)) {
     return 0;
   }
   let max = 0;
   if (Array.isArray(node.children)) {
     for (const c of node.children) {
-      max = Math.max(max, nodeDepth(c as JxElement | string));
+      max = Math.max(max, nodeDepth(c));
     }
   }
   return 1 + max;
 }
 
 function structuralHash(node: JxElement | string): string {
-  if (typeof node === "string") {
+  if (isString(node)) {
     return "#text";
   }
   const tag = node.tagName ?? "div";
   const childHashes: string[] = [];
   if (Array.isArray(node.children)) {
     for (const child of node.children) {
-      childHashes.push(structuralHash(child as JxElement | string));
+      childHashes.push(structuralHash(child));
     }
   }
   if (node.textContent) {
@@ -65,11 +65,13 @@ function structuralHash(node: JxElement | string): string {
 const PRESENTATION_ATTRS = new Set(["class", "className"]);
 
 function collectLeafValues(node: JxElement | string, prefix: string, out: Map<string, string>) {
-  if (typeof node === "string") {
+  if (isString(node)) {
     out.set(`${prefix}.$text`, node);
     return;
   }
   if (node.textContent) {
+    /* SAFETY: import trees come from `htmlToJx`, which sets `textContent` only from a lone string
+       child, so a truthy `textContent` here is a string and never a `$ref` binding. */
     out.set(`${prefix}.textContent`, node.textContent as string);
   }
   if (node.attributes) {
@@ -77,14 +79,14 @@ function collectLeafValues(node: JxElement | string, prefix: string, out: Map<st
       if (PRESENTATION_ATTRS.has(k)) {
         continue;
       }
-      if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+      if (isString(v) || isNumber(v) || isBoolean(v)) {
         out.set(`${prefix}.attr.${k}`, String(v));
       }
     }
   }
   if (Array.isArray(node.children)) {
-    for (let i = 0; i < node.children.length; i++) {
-      collectLeafValues(node.children[i] as JxElement | string, `${prefix}.${i}`, out);
+    for (const [i, child] of node.children.entries()) {
+      collectLeafValues(child, `${prefix}.${i}`, out);
     }
   }
 }
@@ -111,19 +113,11 @@ function leafPathToStateName(leafPath: string): string {
 }
 
 function applyStateInterpolation(
-  node: JxElement | string,
+  node: JxElement,
   prefix: string,
   varyingPaths: Set<string>,
   nameMap: Map<string, string>,
-): JxElement | string {
-  if (typeof node === "string") {
-    const key = `${prefix}.$text`;
-    if (varyingPaths.has(key)) {
-      return `\${state.${nameMap.get(key)}}`;
-    }
-    return node;
-  }
-
+): JxElement {
   const result: JxElement = { ...node };
 
   if (node.textContent) {
@@ -144,9 +138,14 @@ function applyStateInterpolation(
   }
 
   if (Array.isArray(node.children)) {
-    result.children = node.children.map((child, i) =>
-      applyStateInterpolation(child as JxElement | string, `${prefix}.${i}`, varyingPaths, nameMap),
-    ) as JxElement[];
+    result.children = node.children.map((child, i) => {
+      const childPrefix = `${prefix}.${i}`;
+      if (!isString(child)) {
+        return applyStateInterpolation(child, childPrefix, varyingPaths, nameMap);
+      }
+      const key = `${childPrefix}.$text`;
+      return varyingPaths.has(key) ? `\${state.${nameMap.get(key)}}` : child;
+    });
   }
 
   return result;
@@ -170,15 +169,17 @@ function setNodeAt(root: JxElement, path: number[], replacement: JxElement): JxE
 
   const result: JxElement = { ...root };
   if (Array.isArray(root.children)) {
-    result.children = [...root.children] as JxElement[];
+    const children = [...root.children];
+    result.children = children;
     const head = path[0]!;
     const rest = path.slice(1);
     if (rest.length === 0) {
-      (result.children as JxElement[])[head] = replacement;
+      children[head] = replacement;
     } else {
-      const child = result.children[head];
-      if (typeof child !== "string") {
-        (result.children as JxElement[])[head] = setNodeAt(child as JxElement, rest, replacement);
+      // Paths come from `collectSubtrees`, so `head` always indexes an existing child.
+      const child = children[head];
+      if (child !== undefined && !isString(child)) {
+        children[head] = setNodeAt(child, rest, replacement);
       }
     }
   }
@@ -231,10 +232,9 @@ function collectSubtrees(
     out.push({ pageRoute, path: [...path], node });
   }
   if (Array.isArray(node.children)) {
-    for (let i = 0; i < node.children.length; i++) {
-      const child = node.children[i];
-      if (typeof child !== "string") {
-        collectSubtrees(child as JxElement, pageRoute, [...path, i], minDepth, out);
+    for (const [i, child] of node.children.entries()) {
+      if (!isString(child)) {
+        collectSubtrees(child, pageRoute, [...path, i], minDepth, out);
       }
     }
   }
@@ -343,12 +343,7 @@ export function componentize(
       state[stateName] = allLeaves[0]!.get(leafPath) ?? "";
     }
 
-    const template = applyStateInterpolation(
-      unclaimed[0]!.node,
-      "root",
-      varyingPaths,
-      nameMap,
-    ) as JxElement;
+    const template = applyStateInterpolation(unclaimed[0]!.node, "root", varyingPaths, nameMap);
 
     const component: ExtractedComponent = {
       $id: pascalName,

package/src/crawl.ts

@@ -47,7 +47,7 @@ export interface CrawlOptions {
   breakpoints?: BreakpointPolicy | undefined;
   onProgress?: (msg: string) => void;
   /** Abort the crawl between pages; the loop throws before capturing the next page. */
-  signal?: AbortSignal;
+  signal?: AbortSignal | undefined;
 }
 
 export interface CrawledPage {
@@ -309,7 +309,7 @@ export async function crawlSite(options: CrawlOptions): Promise<CrawlResult> {
               options.breakpoints ?? DEFAULT_BREAKPOINT_POLICY,
             ).keep;
             if (breakpointPlan.length < declared.length) {
-              onProgress?.(
+              onProgress(
                 `  ${declared.length} breakpoints declared, keeping ` +
                   `${breakpointPlan.length}: ${breakpointPlan.map((b) => b.name).join(", ")}\n`,
               );

package/src/css-tokens.ts

@@ -3,6 +3,7 @@
  * var(--name) references. Hoists token declarations for project.json.$style.
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import type { DiffedStyle } from "./style-diff.ts";
 
 export interface TokenExtractionResult {
@@ -125,7 +126,7 @@ export function applyTokens(
       if (!TOKEN_ELIGIBLE_PROPS.has(prop)) {
         continue;
       }
-      if (typeof value !== "string") {
+      if (!isString(value)) {
         continue;
       }
       // Already a var() reference

package/src/derived-geometry.ts

@@ -25,7 +25,8 @@
  * imply, so their measurements are kept.
  */
 
-import type { JxElement } from "@jxsuite/schema/types";
+import { isString } from "@jxsuite/schema/guards";
+import type { JxElement, JxStyle } from "@jxsuite/schema/types";
 
 /** Elements sized by their own content or attributes rather than by their container. */
 const REPLACED = new Set([
@@ -49,8 +50,8 @@ const OUT_OF_FLOW = new Set(["absolute", "fixed", "sticky"]);
 /** A bare pixel length, which is the only shape a measurement takes. */
 const PIXEL_LENGTH = /^-?[\d.]+px$/;
 
-function isMeasured(value: unknown): boolean {
-  return typeof value === "string" && PIXEL_LENGTH.test(value);
+function isMeasured(value: JxStyle[string]): boolean {
+  return isString(value) && PIXEL_LENGTH.test(value);
 }
 
 /**
@@ -62,30 +63,28 @@ function isMeasured(value: unknown): boolean {
  * nothing else in the document that would reproduce it.
  */
 function hasContent(node: JxElement): boolean {
-  if (typeof node.textContent === "string" && node.textContent.trim().length > 0) {
+  if (isString(node.textContent) && node.textContent.trim().length > 0) {
     return true;
   }
   const children = Array.isArray(node.children) ? node.children : [];
-  return children.some((child) =>
-    typeof child === "string" ? child.trim().length > 0 : child !== undefined,
-  );
+  return children.some((child) => !isString(child) || child.trim().length > 0);
 }
 
 /**
  * Remove measured geometry from a style object, in place.
  *
  * @param {JxElement} node - The element the style belongs to; its tag and content decide the answer
- * @param {Record<string, unknown>} style - The style object to filter, mutated
- * @param {Record<string, unknown>} [context] - Where `position` and `display` are read from, when
- *   they are not in `style` itself. A breakpoint delta carries only what CHANGED, so it usually
- *   states neither, and judging it on its own would strip an absolutely-positioned box's width on
- *   the grounds that it looked like an in-flow one.
+ * @param {JxStyle} style - The style object to filter, mutated
+ * @param {JxStyle} [context] - Where `position` and `display` are read from, when they are not in
+ *   `style` itself. A breakpoint delta carries only what CHANGED, so it usually states neither, and
+ *   judging it on its own would strip an absolutely-positioned box's width on the grounds that it
+ *   looked like an in-flow one.
  * @returns {number} How many declarations were removed
  */
 export function dropDerivedGeometry(
   node: JxElement,
-  style: Record<string, unknown>,
-  context: Record<string, unknown> = style,
+  style: JxStyle,
+  context: JxStyle = style,
 ): number {
   const tag = String(node.tagName ?? "").toLowerCase();
   if (REPLACED.has(tag)) {

package/src/emit.ts

@@ -1,4 +1,5 @@
-import type { JxElement } from "@jxsuite/schema/types";
+import { isString } from "@jxsuite/schema/guards";
+import type { JxElement, JxHeadEntry } from "@jxsuite/schema/types";
 import { componentize } from "./componentize.ts";
 import { stripClasses } from "./strip-classes.ts";
 import type { ComponentizeOptions, ComponentizeResult } from "./componentize.ts";
@@ -19,6 +20,19 @@ function mediaKeyWidth(key: string): number {
   return Number.isFinite(width) ? width : -1;
 }
 
+/**
+ * The `project.json` an import writes: only keys the project schema declares, in the order they are
+ * written (`$media`, `style` and `$head` are added after the three seeded keys, when present).
+ */
+interface ImportedProjectConfig {
+  name: string;
+  imports: Record<string, string>;
+  images: { optimize: boolean };
+  $media?: Record<string, string>;
+  style?: Record<string, string>;
+  $head?: JxHeadEntry[];
+}
+
 export interface EmitResult {
   /** Project-relative, forward-slashed paths of every file written, in the order they were written. */
   files: string[];
@@ -123,7 +137,7 @@ export async function emitMultiPageProject({
    * nearest candidate and the wrong one: it is the site's own user-facing description, and
    * "Imported from …" is provenance, not a description of the site. The importer reports it instead.
    */
-  const projectJson: Record<string, unknown> = {
+  const projectJson: ImportedProjectConfig = {
     name: title || "Imported Site",
     imports: {},
     images: { optimize: false },
@@ -139,7 +153,7 @@ export async function emitMultiPageProject({
     const sorted = Object.entries(breakpoints).toSorted(
       ([a], [b]) => mediaKeyWidth(a) - mediaKeyWidth(b),
     );
-    projectJson.$media = { ...(projectJson.$media as object), ...Object.fromEntries(sorted) };
+    projectJson.$media = { ...projectJson.$media, ...Object.fromEntries(sorted) };
   }
 
   if (styleTokens && Object.keys(styleTokens).length > 0) {
@@ -172,10 +186,9 @@ export async function emitMultiPageProject({
          lost it on the way out, and every interpolation referencing it went dead. */
       const derived: Record<string, string> = {};
       extractStateDefaults(comp.template, derived);
-      const declared = (comp.template.state ?? {}) as Record<string, unknown>;
-      const state = { ...derived, ...declared };
+      const state = { ...derived, ...comp.template.state };
       if (Object.keys(state).length > 0) {
-        compDoc.state = state as Record<string, string>;
+        compDoc.state = state;
       }
 
       componentFiles.set(fileName, compDoc);
@@ -231,7 +244,7 @@ export async function emitMultiPageProject({
     if (!projectJson.$head) {
       projectJson.$head = [];
     }
-    (projectJson.$head as unknown[]).push({
+    projectJson.$head.push({
       tagName: "link",
       attributes: { rel: "stylesheet", href: "/assets/fonts.css" },
     });
@@ -267,19 +280,14 @@ export async function emitMultiPageProject({
   // Build $elements refs for component registration
   const elementRefs: JxElement[] =
     componentFiles.size > 0
-      ? [...componentFiles.keys()].map(
-          (f) => ({ $ref: `../components/${f}` }) as unknown as JxElement,
-        )
+      ? [...componentFiles.keys()].map((f) => ({ $ref: `../components/${f}` }))
       : [];
 
   // Write each page
   for (const [route, doc] of finalPages) {
     const pageDoc = { ...doc };
     if (elementRefs.length > 0) {
-      pageDoc.$elements = [
-        ...elementRefs,
-        ...((pageDoc.$elements as JxElement[]) ?? []),
-      ] as JxElement[];
+      prependElementRefs(pageDoc, elementRefs);
     }
     await io.write(route, `${JSON.stringify(pageDoc, null, 2)}\n`);
     files.push(route);
@@ -292,10 +300,7 @@ export async function emitMultiPageProject({
     children: [{ tagName: "slot" }],
   };
   if (elementRefs.length > 0 && layout) {
-    (layoutDoc as Record<string, unknown>).$elements = [
-      ...elementRefs,
-      ...(((layoutDoc as Record<string, unknown>).$elements as JxElement[]) ?? []),
-    ];
+    prependElementRefs(layoutDoc, elementRefs);
   }
   classesStripped += stripClasses(layoutDoc);
   await io.write(layoutPath, `${JSON.stringify(layoutDoc, null, 2)}\n`);
@@ -304,6 +309,16 @@ export async function emitMultiPageProject({
   return { classesStripped, files, projectJson: projectText };
 }
 
+/** Put the component registrations ahead of whatever `$elements` the document already declares. */
+function prependElementRefs(doc: JxElement, refs: JxElement[]): void {
+  /* SAFETY: `$elements` is the document schema's registration list, an array of element entries
+     or specifier strings. The pages and layout reaching emit are built by the import pipeline
+     (toJx, detectLayout, componentize, the AI rename pass), none of which writes anything else
+     under that key. */
+  const existing = doc.$elements as (JxElement | string)[] | undefined;
+  doc.$elements = [...refs, ...(existing ?? [])];
+}
+
 /**
  * The state key a whole-string `${state.x}` names, or null.
  *
@@ -318,14 +333,14 @@ function stateKey(text: string): string | undefined {
 }
 
 function extractStateDefaults(node: JxElement | string, out: Record<string, string>) {
-  if (typeof node === "string") {
+  if (isString(node)) {
     const key = stateKey(node);
     if (key && !(key in out)) {
       out[key] = "";
     }
     return;
   }
-  if (typeof node.textContent === "string") {
+  if (isString(node.textContent)) {
     const key = stateKey(node.textContent);
     if (key && !(key in out)) {
       out[key] = "";
@@ -333,7 +348,7 @@ function extractStateDefaults(node: JxElement | string, out: Record<string, stri
   }
   if (node.attributes) {
     for (const v of Object.values(node.attributes)) {
-      if (typeof v === "string") {
+      if (isString(v)) {
         const key = stateKey(v);
         if (key && !(key in out)) {
           out[key] = "";
@@ -343,7 +358,7 @@ function extractStateDefaults(node: JxElement | string, out: Record<string, stri
   }
   if (Array.isArray(node.children)) {
     for (const child of node.children) {
-      extractStateDefaults(child as JxElement | string, out);
+      extractStateDefaults(child, out);
     }
   }
 }

package/src/layout-detect.ts

@@ -1,3 +1,4 @@
+import { isString } from "@jxsuite/schema/guards";
 import type { JxElement } from "@jxsuite/schema/types";
 
 export interface LayoutResult {
@@ -12,7 +13,7 @@ export interface LayoutResult {
  * values. Used to detect structurally identical subtrees across pages.
  */
 export function hashSubtree(node: JxElement | string): string {
-  if (typeof node === "string") {
+  if (isString(node)) {
     return `#text`;
   }
 
@@ -21,7 +22,7 @@ export function hashSubtree(node: JxElement | string): string {
 
   if (Array.isArray(node.children)) {
     for (const child of node.children) {
-      childHashes.push(hashSubtree(child as JxElement | string));
+      childHashes.push(hashSubtree(child));
     }
   }
 
@@ -38,10 +39,10 @@ export function hashSubtree(node: JxElement | string): string {
  * headers/footers, not fuzzy matches.
  */
 export function treesEqual(a: JxElement | string, b: JxElement | string): boolean {
-  if (typeof a === "string" && typeof b === "string") {
+  if (isString(a) && isString(b)) {
     return a === b;
   }
-  if (typeof a === "string" || typeof b === "string") {
+  if (isString(a) || isString(b)) {
     return false;
   }
 
@@ -60,7 +61,7 @@ export function treesEqual(a: JxElement | string, b: JxElement | string): boolea
   }
 
   for (let i = 0; i < aChildren.length; i++) {
-    if (!treesEqual(aChildren[i] as JxElement | string, bChildren[i] as JxElement | string)) {
+    if (!treesEqual(aChildren[i]!, bChildren[i]!)) {
       return false;
     }
   }
@@ -83,9 +84,7 @@ export function detectLayout(pages: Map<string, JxElement>): LayoutResult | null
   }
 
   const entries = [...pages.entries()];
-  const allRoots = entries.map(([, doc]) =>
-    Array.isArray(doc.children) ? (doc.children as (JxElement | string)[]) : [],
-  );
+  const allRoots = entries.map(([, doc]) => (Array.isArray(doc.children) ? doc.children : []));
   const firstRoot = allRoots[0]!;
 
   // Find shared prefix (header elements)
@@ -129,20 +128,20 @@ export function detectLayout(pages: Map<string, JxElement>): LayoutResult | null
 
   const layout: JxElement = {
     tagName: "div",
-    children: [...(headerChildren as JxElement[]), slot, ...(footerChildren as JxElement[])],
+    children: [...headerChildren, slot, ...footerChildren],
   };
 
   // Strip shared elements from each page
   const strippedPages = new Map<string, JxElement>();
   for (const [route, doc] of entries) {
-    const children = Array.isArray(doc.children) ? (doc.children as (JxElement | string)[]) : [];
+    const children = Array.isArray(doc.children) ? doc.children : [];
 
     const endIdx = sharedSuffixLen > 0 ? children.length - sharedSuffixLen : children.length;
     const uniqueChildren = children.slice(sharedPrefixLen, endIdx);
 
     strippedPages.set(route, {
       ...doc,
-      children: uniqueChildren as JxElement[],
+      children: uniqueChildren,
       $layout: "layouts/base.json",
     });
   }

package/src/pipeline.ts

@@ -496,7 +496,7 @@ export async function runImportPipeline(
       fullPageScreenshots: referenceFullPage,
       breakpoints: breakpointPolicy,
       onProgress: (msg) => progress("crawl", msg.trim()),
-      ...(signal === undefined ? {} : { signal }),
+      signal,
     });
 
     progress(

package/src/run.ts

@@ -16,6 +16,7 @@ import { createLocalIo } from "./io.ts";
 import { runImportPipeline } from "./pipeline.ts";
 import type { BreakpointPolicy } from "./breakpoint-plan.ts";
 import type { ImportPhase, ImportProgressEvent } from "./pipeline.ts";
+import type { VerifyOptions } from "./verify.ts";
 import type { Browser } from "puppeteer-core";
 
 export type { ImportPhase, ImportProgressEvent } from "./pipeline.ts";
@@ -65,6 +66,15 @@ export interface ImportSiteOptions {
   signal?: AbortSignal;
 }
 
+/** One page's verify outcome, as counts rather than the verifier's full lists. */
+export interface VerifiedPageSummary {
+  route: string;
+  fidelity: number;
+  consoleErrors: number;
+  failedRequests: number;
+  error?: string;
+}
+
 export interface ImportSiteResult {
   outDir: string;
   pages: { route: string; title: string; nodeCount: number }[];
@@ -92,13 +102,7 @@ export interface ImportSiteResult {
      * The counts alongside it are what a percentage cannot say: a page that 404s on fifteen images
      * scores badly, and only `failedRequests` says why.
      */
-    pages: {
-      route: string;
-      fidelity: number;
-      consoleErrors: number;
-      failedRequests: number;
-      error?: string;
-    }[];
+    pages: VerifiedPageSummary[];
   } | null;
   warnings: string[];
 }
@@ -250,15 +254,18 @@ export async function importSite(
     for (const [route, ref] of references) {
       verifyPages.set(route, { sourceUrl: ref.sourceUrl, screenshot: Buffer.from(ref.screenshot) });
     }
-    const verifyResult = await verifyProject({
+    const verifyOptions: VerifyOptions = {
       projectDir: outDir,
       pages: verifyPages,
       threshold: verifyThreshold,
       minFidelity: verifyMinFidelity,
       fullPage: verifyFullPage,
       onProgress: (msg) => progress("verify", msg),
-      ...(browser === undefined ? {} : { browser }),
-    });
+    };
+    if (browser !== undefined) {
+      verifyOptions.browser = browser;
+    }
+    const verifyResult = await verifyProject(verifyOptions);
     /*
      * Build errors were logged inside the verifier and dropped there. They are warnings on the
      * import as a whole: a project that did not compile is not a clone of anything, however the
@@ -288,13 +295,7 @@ export async function importSite(
       minFidelity: verifyMinFidelity,
       buildErrors: verifyResult.buildErrors,
       pages: verifyResult.pages.map((page) => {
-        const entry: {
-          route: string;
-          fidelity: number;
-          consoleErrors: number;
-          failedRequests: number;
-          error?: string;
-        } = {
+        const entry: VerifiedPageSummary = {
           route: page.route,
           fidelity: page.fidelity,
           consoleErrors: page.consoleErrors.length,
@@ -322,8 +323,11 @@ function throwIfAborted(signal?: AbortSignal): void {
  * absent `signal` and the pipeline would reject it. Copying present keys is also what keeps every
  * default in ONE place — restating `maxPages = 25` here is how the CLI and the cloud drift apart.
  */
-function pick<T extends object, K extends keyof T>(source: T, keys: readonly K[]): Pick<T, K> {
-  const out = {} as Pick<T, K>;
+function pick<T extends object, K extends keyof T>(
+  source: T,
+  keys: readonly K[],
+): Partial<Pick<T, K>> {
+  const out: Partial<Pick<T, K>> = {};
   for (const key of keys) {
     if (source[key] !== undefined) {
       out[key] = source[key];

package/src/strip-classes.ts

@@ -24,6 +24,7 @@
  * @docs studio/projects/create
  */
 
+import { isNonNullObject } from "@jxsuite/schema/guards";
 import type { JxElement } from "@jxsuite/schema/types";
 
 /** The two spellings a class can arrive in — `attributes.class` from HTML, `className` from Jx. */
@@ -36,22 +37,22 @@ const CLASS_KEYS = ["class", "className"] as const;
  * @returns {number} How many class names were removed, for the progress line.
  */
 export function stripClasses(node: JxElement | string): number {
-  if (typeof node !== "object" || node === null) {
+  if (!isNonNullObject(node)) {
     return 0;
   }
 
   let removed = 0;
 
-  if ("className" in node && node.className !== undefined) {
+  if (node.className !== undefined) {
     delete node.className;
     removed += 1;
   }
 
   const { attributes } = node;
-  if (attributes && typeof attributes === "object") {
+  if (isNonNullObject(attributes)) {
     for (const key of CLASS_KEYS) {
       if (key in attributes) {
-        delete (attributes as Record<string, unknown>)[key];
+        delete attributes[key];
         removed += 1;
       }
     }
@@ -65,7 +66,7 @@ export function stripClasses(node: JxElement | string): number {
 
   if (Array.isArray(node.children)) {
     for (const child of node.children) {
-      removed += stripClasses(child as JxElement | string);
+      removed += stripClasses(child);
     }
   }
 

package/src/style-capture.ts

@@ -256,6 +256,9 @@ export async function captureStyles(page: ImportPage): Promise<StyleCaptureResul
             }
             collectMediaRules(rule.cssRules);
           } else if ("cssRules" in rule) {
+            /* SAFETY: every CSSOM rule interface that has a `cssRules` member (the grouping rules,
+               CSSKeyframesRule, and a nesting CSSStyleRule) types it as a CSSRuleList, which is the
+               only member read here. */
             collectMediaRules((rule as CSSGroupingRule).cssRules);
           }
         }
@@ -285,6 +288,8 @@ export async function captureStyles(page: ImportPage): Promise<StyleCaptureResul
           }
           if ("cssRules" in rule) {
             try {
+              /* SAFETY: every CSSOM rule interface that has a `cssRules` member types it as a
+                 CSSRuleList, which is the only member read here. */
               collectCustomProps((rule as CSSGroupingRule).cssRules);
             } catch {
               /* Skip */

package/src/style-diff.ts

@@ -88,10 +88,7 @@ function maybeNumeric(value: string): string | number {
  * Diff a single element's captured styles against its tagName's UA defaults. Returns only the
  * declarations that represent intentional styling.
  */
-export function diffStyles(
-  captured: Record<string, string>,
-  uaDefaults: Record<string, string>,
-): Record<string, string | number> {
+export function diffStyles(captured: Record<string, string>, uaDefaults: Record<string, string>) {
   const result: Record<string, string | number> = {};
 
   for (const [prop, value] of Object.entries(captured)) {