@jxsuite/import 0.34.0

package/src/style-capture.ts

@@ -0,0 +1,386 @@
+/**
+ * In-browser style capture — runs inside page.evaluate().
+ *
+ * Walks the live DOM depth-first and records getComputedStyle for each element, keyed by a stable
+ * tree path (array of child-element indices) that matches the htmlToJx walk order. Also collects
+ * UA-default baselines per unique tagName by rendering throwaway elements.
+ */
+
+import type { Page } from "puppeteer-core";
+
+export interface CapturedStyle {
+  /** Depth-first element-index path from <body>, e.g. [0, 2, 1]. */
+  path: number[];
+  tagName: string;
+  styles: Record<string, string>;
+}
+
+export interface StyleCaptureResult {
+  /** Per-element captured styles (allowlisted props only). */
+  elements: CapturedStyle[];
+  /** UA-default baselines per tagName. */
+  uaDefaults: Record<string, Record<string, string>>;
+  /** Media queries discovered in the page's stylesheets. */
+  mediaQueries: string[];
+  /** CSS custom property declarations found in stylesheets (name → value). */
+  customProperties: Record<string, string>;
+  /** Computed styles from <html> and <body>, diffed against UA defaults. */
+  documentStyles: Record<string, string>;
+}
+
+/** Visually meaningful CSS properties worth capturing. */
+const STYLE_ALLOWLIST: string[] = [
+  // Layout
+  "display",
+  "position",
+  "top",
+  "right",
+  "bottom",
+  "left",
+  "float",
+  "clear",
+  "z-index",
+  "overflow",
+  "overflow-x",
+  "overflow-y",
+  "box-sizing",
+  "vertical-align",
+  // Flex
+  "flex-direction",
+  "flex-wrap",
+  "justify-content",
+  "align-items",
+  "align-content",
+  "align-self",
+  "flex",
+  "flex-grow",
+  "flex-shrink",
+  "flex-basis",
+  "gap",
+  "row-gap",
+  "column-gap",
+  "order",
+  // Grid
+  "grid-template-columns",
+  "grid-template-rows",
+  "grid-column",
+  "grid-row",
+  "grid-area",
+  "grid-auto-flow",
+  "grid-auto-columns",
+  "grid-auto-rows",
+  // Box model
+  "width",
+  "height",
+  "min-width",
+  "min-height",
+  "max-width",
+  "max-height",
+  "margin-top",
+  "margin-right",
+  "margin-bottom",
+  "margin-left",
+  "padding-top",
+  "padding-right",
+  "padding-bottom",
+  "padding-left",
+  // Border
+  "border-top-width",
+  "border-right-width",
+  "border-bottom-width",
+  "border-left-width",
+  "border-top-style",
+  "border-right-style",
+  "border-bottom-style",
+  "border-left-style",
+  "border-top-color",
+  "border-right-color",
+  "border-bottom-color",
+  "border-left-color",
+  "border-top-left-radius",
+  "border-top-right-radius",
+  "border-bottom-right-radius",
+  "border-bottom-left-radius",
+  // Background
+  "background-color",
+  "background-image",
+  "background-size",
+  "background-position",
+  "background-repeat",
+  "background-clip",
+  // Typography
+  "font-family",
+  "font-size",
+  "font-weight",
+  "font-style",
+  "font-variant",
+  "line-height",
+  "letter-spacing",
+  "word-spacing",
+  "text-align",
+  "text-decoration",
+  "text-decoration-line",
+  "text-decoration-color",
+  "text-decoration-style",
+  "text-transform",
+  "text-indent",
+  "text-overflow",
+  "text-shadow",
+  "white-space",
+  "word-break",
+  "overflow-wrap",
+  "color",
+  // Visual
+  "opacity",
+  "visibility",
+  "box-shadow",
+  "transform",
+  "transition",
+  "cursor",
+  "outline-style",
+  "outline-width",
+  "outline-color",
+  "outline-offset",
+  // List
+  "list-style-type",
+  "list-style-position",
+  // Table
+  "table-layout",
+  "border-collapse",
+  "border-spacing",
+  // Content
+  "content",
+  "object-fit",
+  "object-position",
+  // Appearance
+  "appearance",
+  "pointer-events",
+  "user-select",
+  "resize",
+];
+
+/**
+ * Run the style capture in a puppeteer page. Executes entirely in-browser via page.evaluate() — no
+ * round-trips per element.
+ */
+export async function captureStyles(page: Page): Promise<StyleCaptureResult> {
+  return page.evaluate((allowlist: string[]) => {
+    const elements: { path: number[]; tagName: string; styles: Record<string, string> }[] = [];
+    const tagsSeen = new Set<string>();
+
+    // Depth-first walk matching htmlToJx traversal order (element children only,
+    // Skipping text/comment nodes — same as hast element indexing).
+    function walk(el: Element, path: number[]) {
+      const tag = el.tagName.toLowerCase();
+      tagsSeen.add(tag);
+
+      const cs = window.getComputedStyle(el);
+      const styles: Record<string, string> = {};
+      for (const prop of allowlist) {
+        const val = cs.getPropertyValue(prop);
+        if (val) {
+          styles[prop] = val;
+        }
+      }
+      elements.push({ path: [...path], tagName: tag, styles });
+
+      let childIdx = 0;
+      for (const child of el.children) {
+        walk(child, [...path, childIdx]);
+        childIdx += 1;
+      }
+    }
+
+    // Walk from <body>'s children (htmlToJx receives body.innerHTML, not body itself)
+    let bodyChildIdx = 0;
+    for (const child of document.body.children) {
+      walk(child, [bodyChildIdx]);
+      bodyChildIdx += 1;
+    }
+
+    // Build UA-default baselines per unique tagName
+    const uaDefaults: Record<string, Record<string, string>> = {};
+    const sandbox = document.createElement("div");
+    sandbox.style.cssText =
+      "position:fixed;top:-9999px;left:-9999px;visibility:hidden;pointer-events:none;";
+    document.body.append(sandbox);
+
+    for (const tag of tagsSeen) {
+      try {
+        const probe = document.createElement(tag);
+        sandbox.append(probe);
+        const cs = window.getComputedStyle(probe);
+        const defaults: Record<string, string> = {};
+        for (const prop of allowlist) {
+          const val = cs.getPropertyValue(prop);
+          if (val) {
+            defaults[prop] = val;
+          }
+        }
+        uaDefaults[tag] = defaults;
+        probe.remove();
+      } catch {
+        // Skip exotic elements
+      }
+    }
+    sandbox.remove();
+
+    // Discover @media queries from stylesheets (recurse into @layer, @supports, etc.)
+    const mediaQueries: string[] = [];
+    const mediaSeen = new Set<string>();
+    function collectMediaRules(rules: CSSRuleList) {
+      for (const rule of rules) {
+        if (rule instanceof CSSMediaRule) {
+          const q = rule.conditionText;
+          if (!mediaSeen.has(q)) {
+            mediaSeen.add(q);
+            mediaQueries.push(q);
+          }
+          collectMediaRules(rule.cssRules);
+        } else if ("cssRules" in rule) {
+          collectMediaRules((rule as CSSGroupingRule).cssRules);
+        }
+      }
+    }
+    for (const sheet of document.styleSheets) {
+      try {
+        collectMediaRules(sheet.cssRules);
+      } catch {
+        // Cross-origin stylesheet — cssRules inaccessible
+      }
+    }
+
+    // Extract CSS custom property declarations (R5 — design tokens)
+    const customProperties: Record<string, string> = {};
+    function collectCustomProps(rules: CSSRuleList) {
+      for (const rule of rules) {
+        if (rule instanceof CSSStyleRule) {
+          const { style } = rule;
+          for (const name of style) {
+            if (name.startsWith("--")) {
+              const val = style.getPropertyValue(name).trim();
+              if (val && !val.includes("var(")) {
+                customProperties[name] = val;
+              }
+            }
+          }
+        }
+        if ("cssRules" in rule) {
+          try {
+            collectCustomProps((rule as CSSGroupingRule).cssRules);
+          } catch {
+            /* Skip */
+          }
+        }
+      }
+    }
+    for (const sheet of document.styleSheets) {
+      try {
+        collectCustomProps(sheet.cssRules);
+      } catch {
+        /* Cross-origin */
+      }
+    }
+
+    // Capture <html> and <body> styles that won't be in the element tree
+    // (the Jx tree starts from body.children, not body itself)
+    const documentStyles: Record<string, string> = {};
+
+    const TRANSPARENT = new Set(["rgba(0, 0, 0, 0)", "transparent", ""]);
+    function isDefault(val: string, probeVal: string): boolean {
+      return !val || val === probeVal || TRANSPARENT.has(val);
+    }
+
+    const htmlCs = window.getComputedStyle(document.documentElement);
+    const bodyCs = window.getComputedStyle(document.body);
+
+    // Create a clean probe in an iframe to get true UA defaults
+    // (a probe appended to body would inherit body's own styles)
+    const iframe = document.createElement("iframe");
+    iframe.style.cssText = "position:fixed;top:-9999px;left:-9999px;width:0;height:0;border:none;";
+    document.body.append(iframe);
+    const iframeDoc = iframe.contentDocument!;
+    const probeDiv = iframeDoc.createElement("div");
+    iframeDoc.body.append(probeDiv);
+    const probeCs = iframe.contentWindow!.getComputedStyle(probeDiv);
+    const probeBodyCs = iframe.contentWindow!.getComputedStyle(iframeDoc.body);
+
+    const DOC_PROPS = [
+      "background-color",
+      "background-image",
+      "color",
+      "font-family",
+      "font-size",
+      "line-height",
+      "letter-spacing",
+    ];
+    for (const prop of DOC_PROPS) {
+      const bodyVal = bodyCs.getPropertyValue(prop);
+      const htmlVal = htmlCs.getPropertyValue(prop);
+      const probeDefault = probeCs.getPropertyValue(prop);
+      const probeBodyDefault = probeBodyCs.getPropertyValue(prop);
+
+      // Body takes priority, but skip transparent/default values
+      if (!isDefault(bodyVal, probeBodyDefault)) {
+        documentStyles[prop] = bodyVal;
+      } else if (!isDefault(htmlVal, probeDefault)) {
+        documentStyles[prop] = htmlVal;
+      }
+    }
+    iframe.remove();
+
+    return { elements, uaDefaults, mediaQueries, customProperties, documentStyles };
+  }, STYLE_ALLOWLIST);
+}
+
+/**
+ * Re-capture computed styles at a different viewport width (for $media extraction). Returns only
+ * the per-element styles — no UA defaults or media queries (reuse from base).
+ */
+export async function captureStylesAtWidth(page: Page, width: number): Promise<CapturedStyle[]> {
+  await page.setViewport({ width, height: 900 });
+  // Let layout reflow settle
+  await page.evaluate(
+    () =>
+      new Promise<void>((r) => {
+        requestAnimationFrame(() => {
+          requestAnimationFrame(() => {
+            r();
+          });
+        });
+      }),
+  );
+
+  return page.evaluate((allowlist: string[]) => {
+    const elements: { path: number[]; tagName: string; styles: Record<string, string> }[] = [];
+
+    function walk(el: Element, path: number[]) {
+      const tag = el.tagName.toLowerCase();
+      const cs = window.getComputedStyle(el);
+      const styles: Record<string, string> = {};
+      for (const prop of allowlist) {
+        const val = cs.getPropertyValue(prop);
+        if (val) {
+          styles[prop] = val;
+        }
+      }
+      elements.push({ path: [...path], tagName: tag, styles });
+
+      let childIdx = 0;
+      for (const child of el.children) {
+        walk(child, [...path, childIdx]);
+        childIdx += 1;
+      }
+    }
+
+    let bodyChildIdx = 0;
+    for (const child of document.body.children) {
+      walk(child, [bodyChildIdx]);
+      bodyChildIdx += 1;
+    }
+
+    return elements;
+  }, STYLE_ALLOWLIST);
+}
+
+export { STYLE_ALLOWLIST };

package/src/style-diff.ts

@@ -0,0 +1,183 @@
+/**
+ * Diff captured computed styles against UA-default baselines. Produces a minimal set of meaningful
+ * style declarations per element.
+ */
+
+import type { CapturedStyle } from "./style-capture.ts";
+
+export interface DiffedStyle {
+  path: number[];
+  style: Record<string, string | number>;
+}
+
+/** Convert a kebab-case CSS property to camelCase for Jx style objects. */
+export function kebabToCamel(prop: string): string {
+  if (prop.startsWith("-webkit-") || prop.startsWith("-moz-") || prop.startsWith("-ms-")) {
+    const withoutPrefix = prop.replace(/^-(?:webkit|moz|ms)-/, "");
+    const camel = withoutPrefix.replaceAll(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+    const vendor = prop.startsWith("-webkit-") ? "webkit" : prop.startsWith("-moz-") ? "moz" : "ms";
+    return `${vendor}${camel[0]!.toUpperCase()}${camel.slice(1)}`;
+  }
+  return prop.replaceAll(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+/**
+ * Values that are effectively "no value set" — drop them even if they differ from UA default
+ * (they're computed noise, not intentional styling).
+ */
+const NOISE_VALUES = new Set([
+  "auto",
+  "normal",
+  "none",
+  "0px",
+  "0s",
+  "start",
+  "baseline",
+  "stretch",
+  "visible",
+  "content-box",
+  "currentcolor",
+  "medium none currentcolor",
+]);
+
+/**
+ * Properties where "auto" / "normal" / "none" IS meaningful and should not be dropped — e.g.,
+ * overflow: hidden vs overflow: visible.
+ */
+const KEEP_NOISE_FOR = new Set([
+  "overflow",
+  "overflow-x",
+  "overflow-y",
+  "display",
+  "visibility",
+  "position",
+  "pointer-events",
+  "cursor",
+  "white-space",
+  "text-overflow",
+  "object-fit",
+  "flex-wrap",
+  "flex-direction",
+  "box-sizing",
+  "text-align",
+  "text-decoration",
+  "text-decoration-line",
+  "text-transform",
+  "word-break",
+  "overflow-wrap",
+  "list-style-type",
+  "table-layout",
+  "border-collapse",
+  "appearance",
+  "resize",
+  "user-select",
+]);
+
+/**
+ * Try to convert a CSS value to a number where appropriate (e.g., "0" → 0, opacity "0.5" → 0.5).
+ * Keeps strings for anything with units or complex values.
+ */
+function maybeNumeric(value: string): string | number {
+  if (/^-?\d+(\.\d+)?$/.test(value)) {
+    return Number(value);
+  }
+  return value;
+}
+
+/**
+ * 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> {
+  const result: Record<string, string | number> = {};
+
+  for (const [prop, value] of Object.entries(captured)) {
+    const uaValue = uaDefaults[prop] ?? "";
+
+    // Same as default → skip
+    if (value === uaValue) {
+      continue;
+    }
+
+    // Drop noise values unless the property's noise values are meaningful
+    if (!KEEP_NOISE_FOR.has(prop) && NOISE_VALUES.has(value)) {
+      continue;
+    }
+
+    // Even for KEEP_NOISE_FOR properties, skip if value equals UA default
+    // (already handled above) — but don't skip if it's a meaningful override
+
+    const camelProp = kebabToCamel(prop);
+    result[camelProp] = maybeNumeric(value);
+  }
+
+  return result;
+}
+
+/**
+ * Diff all captured elements against UA defaults. Returns an array of { path, style } for elements
+ * with non-empty diffs.
+ */
+export function diffAllStyles(
+  elements: CapturedStyle[],
+  uaDefaults: Record<string, Record<string, string>>,
+): DiffedStyle[] {
+  const results: DiffedStyle[] = [];
+
+  for (const el of elements) {
+    const defaults = uaDefaults[el.tagName] ?? {};
+    const style = diffStyles(el.styles, defaults);
+
+    if (Object.keys(style).length > 0) {
+      results.push({ path: el.path, style });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Compute style deltas between a base capture and a breakpoint capture. Returns only properties
+ * that changed at the new viewport width.
+ */
+export function computeMediaDelta(
+  baseElements: CapturedStyle[],
+  bpElements: CapturedStyle[],
+  uaDefaults: Record<string, Record<string, string>>,
+): DiffedStyle[] {
+  const baseByPath = new Map<string, CapturedStyle>();
+  for (const el of baseElements) {
+    baseByPath.set(el.path.join(","), el);
+  }
+
+  const deltas: DiffedStyle[] = [];
+
+  for (const bpEl of bpElements) {
+    const key = bpEl.path.join(",");
+    const baseEl = baseByPath.get(key);
+    if (!baseEl) {
+      continue;
+    }
+
+    const defaults = uaDefaults[bpEl.tagName] ?? {};
+    const baseStyle = diffStyles(baseEl.styles, defaults);
+    const bpStyle = diffStyles(bpEl.styles, defaults);
+
+    // Only keep properties that changed from base
+    const delta: Record<string, string | number> = {};
+    for (const [prop, val] of Object.entries(bpStyle)) {
+      if (baseStyle[prop] !== val) {
+        delta[prop] = val;
+      }
+    }
+
+    if (Object.keys(delta).length > 0) {
+      deltas.push({ path: bpEl.path, style: delta });
+    }
+  }
+
+  return deltas;
+}

package/src/to-jx.ts

@@ -0,0 +1,89 @@
+import { htmlToJx } from "@jxsuite/parser/html-to-jx";
+import type { JxElement } from "@jxsuite/schema/types";
+
+export interface ToJxResult {
+  /** The page document root — a wrapper div with the converted children. */
+  document: JxElement;
+  /** Element count in the emitted tree. */
+  nodeCount: number;
+  /** Inline <style> contents collected for Phase 1 CSS resolution. */
+  collectedStyles: string[];
+}
+
+const STRIP_TAGS = new Set(["script", "noscript", "iframe", "object", "embed", "link", "meta"]);
+
+function countNodes(node: JxElement | string): number {
+  if (typeof node === "string") {
+    return 0;
+  }
+  let n = 1;
+  if (Array.isArray(node.children)) {
+    for (const c of node.children) {
+      n += countNodes(c as JxElement | string);
+    }
+  }
+  return n;
+}
+
+function stripTags(nodes: (JxElement | string)[]): {
+  cleaned: (JxElement | string)[];
+  styles: string[];
+} {
+  const cleaned: (JxElement | string)[] = [];
+  const styles: string[] = [];
+
+  for (const node of nodes) {
+    if (typeof node === "string") {
+      cleaned.push(node);
+      continue;
+    }
+
+    const tag = String(node.tagName ?? "").toLowerCase();
+
+    // Collect inline <style> content for Phase 1
+    if (tag === "style") {
+      if (typeof node.textContent === "string") {
+        styles.push(node.textContent);
+      }
+      if (Array.isArray(node.children)) {
+        for (const c of node.children) {
+          if (typeof c === "string") {
+            styles.push(c);
+          }
+        }
+      }
+      continue;
+    }
+
+    if (STRIP_TAGS.has(tag)) {
+      continue;
+    }
+
+    // Recurse into children
+    if (Array.isArray(node.children)) {
+      const sub = stripTags(node.children as (JxElement | string)[]);
+      node.children = sub.cleaned as JxElement[];
+      styles.push(...sub.styles);
+    }
+
+    cleaned.push(node);
+  }
+
+  return { cleaned, styles };
+}
+
+export function convertToJx(bodyHtml: string): ToJxResult {
+  const rawNodes = htmlToJx(bodyHtml);
+  const { cleaned, styles } = stripTags(rawNodes);
+
+  const document: JxElement = {
+    tagName: "div",
+    children: cleaned as JxElement[],
+  };
+
+  return {
+    document,
+    nodeCount: countNodes(document),
+    collectedStyles: styles,
+  };
+}