@jxsuite/import 0.40.9 → 0.40.12

package/src/apply-popovers.ts

@@ -26,7 +26,8 @@
  * ignored it would produce a popover that opens into nothing.
  */
 
-import type { JxElement } from "@jxsuite/schema/types";
+import { getNestedStyle, isString } from "@jxsuite/schema/guards";
+import type { JxElement, JxStyle } from "@jxsuite/schema/types";
 import { POPOVER_DEFAULT_MODE, POPOVER_INVOKER_TAGS } from "@jxsuite/schema/overlays";
 
 /** Attributes naming the panel an invoker controls, in the order they are trusted. */
@@ -41,22 +42,14 @@ const CONCEALING = new Set(["display", "visibility", "opacity"]);
 /** A concealed panel is only a popover if it is also lifted out of the flow. */
 const POSITIONED = new Set(["absolute", "fixed"]);
 
-function styleOf(node: JxElement): Record<string, unknown> | undefined {
-  return node.style as Record<string, unknown> | undefined;
-}
-
-function attributesOf(node: JxElement): Record<string, unknown> | undefined {
-  return node.attributes as Record<string, unknown> | undefined;
-}
-
 function childrenOf(node: JxElement): JxElement[] {
   return Array.isArray(node.children)
-    ? (node.children.filter((child) => typeof child !== "string") as JxElement[])
+    ? node.children.filter((child): child is JxElement => !isString(child))
     : [];
 }
 
 /** Whether a style hides the node outright, and by which declaration. */
-function concealedBy(style: Record<string, unknown> | undefined): string[] {
+function concealedBy(style: JxStyle | undefined): string[] {
   if (!style) {
     return [];
   }
@@ -84,11 +77,11 @@ function concealedBy(style: Record<string, unknown> | undefined): string[] {
  * explicit statements of the same intent.
  */
 export function looksLikePanel(node: JxElement): boolean {
-  const style = styleOf(node);
+  const { style } = node;
   if (concealedBy(style).length === 0) {
     return false;
   }
-  const attributes = attributesOf(node);
+  const { attributes } = node;
   if (attributes?.["role"] === "dialog" || attributes?.["inert"] !== undefined) {
     return true;
   }
@@ -97,13 +90,13 @@ export function looksLikePanel(node: JxElement): boolean {
 
 /** The id an invoker names, from whichever attribute carries it. */
 export function targetIdOf(node: JxElement): string | null {
-  const attributes = attributesOf(node);
+  const { attributes } = node;
   if (!attributes) {
     return null;
   }
   for (const name of TARGET_ATTRIBUTES) {
     const raw = attributes[name];
-    if (typeof raw !== "string" || raw.length === 0) {
+    if (!isString(raw) || raw.length === 0) {
       continue;
     }
     const id = raw.startsWith("#") ? raw.slice(1) : name === "href" ? "" : raw;
@@ -120,7 +113,7 @@ function looksLikeInvoker(node: JxElement): boolean {
   if (tag !== "button" && tag !== "input" && tag !== "a") {
     return false;
   }
-  const attributes = attributesOf(node);
+  const { attributes } = node;
   if (!attributes) {
     return false;
   }
@@ -133,8 +126,8 @@ function looksLikeInvoker(node: JxElement): boolean {
 function indexById(root: JxElement): Map<string, JxElement> {
   const index = new Map<string, JxElement>();
   const visit = (node: JxElement): void => {
-    const id = attributesOf(node)?.["id"];
-    if (typeof id === "string" && !index.has(id)) {
+    const id = node.attributes?.["id"];
+    if (isString(id) && !index.has(id)) {
       index.set(id, node);
     }
     for (const child of childrenOf(node)) {
@@ -183,7 +176,7 @@ function panelBesideAncestor(ancestry: readonly JxElement[]): JxElement | null {
  * writing `block` there would be inventing a fact: the element's own default is the honest answer,
  * so nothing is written and the warning is accepted.
  */
-function openValueFor(property: string, closed: unknown): string | null {
+function openValueFor(property: string, closed: JxStyle[string]): string | null {
   if (property === "opacity" && (closed === 0 || closed === "0")) {
     return "1";
   }
@@ -197,12 +190,12 @@ function openValueFor(property: string, closed: unknown): string | null {
  * Move a panel's closed-state declarations into `:popover-open`, where they describe the open one.
  *
  * `node` is always a panel `looksLikePanel` already accepted, and that requires a concealing style
- * declaration to exist (`concealedBy(style).length === 0` rejects it otherwise) — so
- * `styleOf(node)` is never empty here.
+ * declaration to exist (`concealedBy(style).length === 0` rejects it otherwise) — so `node.style`
+ * is never empty here.
  */
 function liftConcealment(node: JxElement): void {
-  const style = styleOf(node)!;
-  const open = (style[":popover-open"] as Record<string, unknown> | undefined) ?? {};
+  const style = node.style!;
+  const open = getNestedStyle(style, ":popover-open") ?? {};
   for (const property of Object.keys(style)) {
     if (!CONCEALING.has(property)) {
       continue;
@@ -213,12 +206,12 @@ function liftConcealment(node: JxElement): void {
        design and is carried across unchanged, because the base rule is no longer where it belongs. */
     const openValue = isConcealment ? openValueFor(property, value) : value;
     if (openValue !== null) {
-      (open as Record<string, unknown>)[property] = openValue;
+      open[property] = openValue;
     }
     delete style[property];
   }
   if (Object.keys(open).length > 0) {
-    (style as Record<string, unknown>)[":popover-open"] = open;
+    style[":popover-open"] = open;
   }
 }
 
@@ -248,14 +241,15 @@ export function applyPopovers(root: JxElement): PopoverResult {
 
       if (panel && panel !== node && !claimed.has(panel) && looksLikePanel(panel)) {
         const tag = String(node.tagName ?? "").toLowerCase();
-        const attributes = (node.attributes ??= {}) as Record<string, unknown>;
+        node.attributes ??= {};
+        const { attributes } = node;
 
         /* `popovertarget` exists only on button and input. An anchor that is really a button
            becomes one; an anchor that navigates keeps its job, because a dead link is a worse
            defect than an unconverted menu. */
         if (!POPOVER_INVOKER_TAGS.has(tag)) {
           const { href } = attributes;
-          const navigates = typeof href === "string" && href.length > 0 && href !== "#";
+          const navigates = isString(href) && href.length > 0 && href !== "#";
           if (navigates) {
             result.skippedNavigatingLinks += 1;
             for (const child of childrenOf(node)) {
@@ -268,9 +262,10 @@ export function applyPopovers(root: JxElement): PopoverResult {
           delete attributes["href"];
         }
 
-        const panelAttributes = (panel.attributes ??= {}) as Record<string, unknown>;
+        panel.attributes ??= {};
+        const { attributes: panelAttributes } = panel;
         let { id: panelId } = panelAttributes;
-        if (typeof panelId !== "string" || panelId.length === 0) {
+        if (!isString(panelId) || panelId.length === 0) {
           generated += 1;
           panelId = `jx-popover-${generated}`;
           panelAttributes["id"] = panelId;

package/src/apply-styles.ts

@@ -3,6 +3,7 @@
  * same depth-first element-index order as the browser DOM walk in style-capture.ts.
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import type { JxElement, JxStyle } from "@jxsuite/schema/types";
 import type { DiffedStyle } from "./style-diff.ts";
 import { parseWidthQuery } from "./breakpoint-plan.ts";
@@ -38,7 +39,7 @@ export function orderBreakpointKeys(
   names: readonly string[],
   queries: Record<string, string> | undefined,
 ): string[] {
-  const rank = (name: string): { band: number; width: number } => {
+  const rank = (name: string) => {
     const parsed = queries?.[name] === undefined ? null : parseWidthQuery(queries[name]!);
     if (!parsed) {
       return { band: 2, width: 0 };
@@ -83,7 +84,7 @@ export function applyStylesToTree(
 
   let childIdx = 0;
   for (const child of root.children) {
-    if (typeof child === "string") {
+    if (isString(child)) {
       continue;
     }
     walkAndApply(child, [childIdx], baseMap, mediaMaps);
@@ -115,12 +116,12 @@ function walkAndApply(
     const delta = deltaMap.get(key);
     if (delta) {
       const filtered = { ...delta };
-      dropDerivedGeometry(node, filtered, (node.style ?? {}) as Record<string, unknown>);
+      dropDerivedGeometry(node, filtered, node.style ?? {});
       if (Object.keys(filtered).length > 0) {
         if (!node.style) {
           node.style = {};
         }
-        (node.style as Record<string, unknown>)[`@${bpName}`] = filtered;
+        node.style[`@${bpName}`] = filtered;
       }
     }
   }
@@ -132,7 +133,7 @@ function walkAndApply(
 
   let childIdx = 0;
   for (const child of node.children) {
-    if (typeof child === "string") {
+    if (isString(child)) {
       continue;
     }
     walkAndApply(child, [...path, childIdx], baseMap, mediaMaps);

package/src/asset-collect.ts

@@ -53,11 +53,11 @@ export async function collectAssets(page: ImportPage): Promise<AssetCollectionRe
    */
   const result = await page.evaluate((srcsetSeparator: string) => {
     const separator = new RegExp(srcsetSeparator);
-    const assets: { url: string; source: string }[] = [];
+    const assets: DiscoveredAsset[] = [];
     const seen = new Set<string>();
     let inlineSvgCount = 0;
 
-    function add(url: string, source: string) {
+    function add(url: string, source: DiscoveredAsset["source"]) {
       if (!url || seen.has(url)) {
         return;
       }
@@ -98,8 +98,10 @@ export async function collectAssets(page: ImportPage): Promise<AssetCollectionRe
     }
 
     // Img[src]
-    for (const el of document.querySelectorAll("img[src]")) {
-      add((el as HTMLImageElement).src, "img-src");
+    /* Each selector below names its element by tag, so the type argument states what the
+       selector already guarantees. */
+    for (const el of document.querySelectorAll<HTMLImageElement>("img[src]")) {
+      add(el.src, "img-src");
     }
 
     // Img[srcset] and source[srcset]
@@ -112,13 +114,13 @@ export async function collectAssets(page: ImportPage): Promise<AssetCollectionRe
     }
 
     // Picture > source (type-based, not just srcset)
-    for (const el of document.querySelectorAll("picture > source[src]")) {
-      add((el as HTMLSourceElement).src, "picture-source");
+    for (const el of document.querySelectorAll<HTMLSourceElement>("picture > source[src]")) {
+      add(el.src, "picture-source");
     }
 
     // Video[poster]
-    for (const el of document.querySelectorAll("video[poster]")) {
-      add((el as HTMLVideoElement).poster, "video-poster");
+    for (const el of document.querySelectorAll<HTMLVideoElement>("video[poster]")) {
+      add(el.poster, "video-poster");
     }
 
     // Inline style url() on any element
@@ -141,8 +143,7 @@ export async function collectAssets(page: ImportPage): Promise<AssetCollectionRe
     }
 
     // @font-face from stylesheets + retain full source CSS (F0)
-    const stylesheets: { href: string | null; cssText: string | null; fontFaceRules: string[] }[] =
-      [];
+    const stylesheets: CapturedStylesheet[] = [];
     for (const sheet of document.styleSheets) {
       let rules: CSSRuleList | null = null;
       let fullCssText: string | null = null;
@@ -174,18 +175,18 @@ export async function collectAssets(page: ImportPage): Promise<AssetCollectionRe
     }
 
     // Favicon and other link icons
-    for (const el of document.querySelectorAll(
+    for (const el of document.querySelectorAll<HTMLLinkElement>(
       'link[rel~="icon"], link[rel="shortcut icon"], link[rel="apple-touch-icon"]',
     )) {
-      const { href } = el as HTMLLinkElement;
+      const { href } = el;
       if (href) {
         add(href, "favicon");
       }
     }
 
     // Open Graph images
-    for (const el of document.querySelectorAll('meta[property="og:image"]')) {
-      const { content } = el as HTMLMetaElement;
+    for (const el of document.querySelectorAll<HTMLMetaElement>('meta[property="og:image"]')) {
+      const { content } = el;
       if (content) {
         add(content, "og-image");
       }
@@ -194,11 +195,7 @@ export async function collectAssets(page: ImportPage): Promise<AssetCollectionRe
     // Count inline SVGs (kept inline, not downloaded)
     inlineSvgCount = document.querySelectorAll("svg").length;
 
-    return { assets, inlineSvgCount, stylesheets } as {
-      assets: { url: string; source: string }[];
-      inlineSvgCount: number;
-      stylesheets: { href: string | null; cssText: string | null; fontFaceRules: string[] }[];
-    };
+    return { assets, inlineSvgCount, stylesheets };
   }, SRCSET_SEPARATOR.source);
 
   // R2: For cross-origin sheets we couldn't access (cssText=null, has href), fetch them
@@ -256,5 +253,5 @@ export async function collectAssets(page: ImportPage): Promise<AssetCollectionRe
     }
   }
 
-  return result as AssetCollectionResult;
+  return result;
 }

package/src/asset-download.ts

@@ -179,12 +179,12 @@ export async function downloadAssets(
     const relativePath = `/assets/${subdir}/${filename}`;
 
     try {
-      const headers: Record<string, string> = {
+      const headers = new Headers({
         "User-Agent":
           "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
-      };
+      });
       if (sourceUrl) {
-        headers["Referer"] = sourceUrl;
+        headers.set("Referer", sourceUrl);
       }
       const response = await fetch(url, { headers, redirect: "follow" });
       if (!response.ok) {

package/src/asset-rewrite.ts

@@ -5,6 +5,7 @@
  * style.backgroundImage (url() references) - $media nested style objects with backgroundImage
  */
 
+import { isNestedStyle, isString } from "@jxsuite/schema/guards";
 import type { JxElement, JxStyle } from "@jxsuite/schema/types";
 import { SRCSET_SEPARATOR } from "./srcset.ts";
 
@@ -52,26 +53,25 @@ export function rewriteAssetUrls(
    * the importer would fetch one set of URLs and rewrite another — the attribute would be
    * reassembled around fragments nothing had downloaded.
    */
-  function rewriteSrcset(srcset: string): { srcset: string; collapsedTo: string | null } {
+  function rewriteSrcset(srcset: string) {
     const locals = new Set<string>();
     let unresolved = false;
 
-    const rewritten = srcset
-      .split(SRCSET_SEPARATOR)
-      .map((entry) => {
-        const parts = entry.trim().split(/\s+/);
-        const [url = ""] = parts;
-        const local = rewriteUrl(url);
-        if (local) {
-          count += 1;
-          parts[0] = local;
-          locals.add(local);
-        } else {
-          unresolved = true;
-        }
-        return parts.join(" ");
-      })
-      .join(", ");
+    const candidates: string[] = [];
+    for (const entry of srcset.split(SRCSET_SEPARATOR)) {
+      const parts = entry.trim().split(/\s+/);
+      const [url = ""] = parts;
+      const local = rewriteUrl(url);
+      if (local) {
+        count += 1;
+        parts[0] = local;
+        locals.add(local);
+      } else {
+        unresolved = true;
+      }
+      candidates.push(parts.join(" "));
+    }
+    const rewritten = candidates.join(", ");
 
     /* Every candidate now points at the ONE file the family kept, so the attribute has become a
        list of the same path repeated with different width descriptors — which lies to the browser
@@ -95,20 +95,20 @@ export function rewriteAssetUrls(
 
   function rewriteStyleObject(style: JxStyle): void {
     for (const [key, value] of Object.entries(style)) {
-      if (typeof value === "string" && value.includes("url(")) {
-        (style as Record<string, unknown>)[key] = rewriteCssUrls(value);
-      } else if (typeof value === "object" && value !== null && key.startsWith("@")) {
-        rewriteStyleObject(value as JxStyle);
+      if (isString(value) && value.includes("url(")) {
+        style[key] = rewriteCssUrls(value);
+      } else if (isNestedStyle(value) && key.startsWith("@")) {
+        rewriteStyleObject(value);
       }
     }
   }
 
   function walk(node: JxElement): void {
-    const attrs = node.attributes as Record<string, unknown> | undefined;
+    const attrs = node.attributes;
 
     if (attrs) {
       // Src attribute (img, video, audio, source, etc.)
-      if (typeof attrs.src === "string") {
+      if (isString(attrs.src)) {
         const rewritten = rewriteUrl(attrs.src);
         if (rewritten) {
           attrs.src = rewritten;
@@ -117,8 +117,8 @@ export function rewriteAssetUrls(
       }
 
       // Href on non-anchor elements (could be link icon, etc.)
-      if (typeof attrs.href === "string") {
-        const tag = (typeof node.tagName === "string" ? node.tagName : "").toLowerCase();
+      if (isString(attrs.href)) {
+        const tag = (isString(node.tagName) ? node.tagName : "").toLowerCase();
         if (tag !== "a") {
           const rewritten = rewriteUrl(attrs.href);
           if (rewritten) {
@@ -129,7 +129,7 @@ export function rewriteAssetUrls(
       }
 
       // Poster attribute (video)
-      if (typeof attrs.poster === "string") {
+      if (isString(attrs.poster)) {
         const rewritten = rewriteUrl(attrs.poster);
         if (rewritten) {
           attrs.poster = rewritten;
@@ -138,7 +138,7 @@ export function rewriteAssetUrls(
       }
 
       // Srcset attribute
-      if (typeof attrs.srcset === "string") {
+      if (isString(attrs.srcset)) {
         const result = rewriteSrcset(attrs.srcset);
         if (result.collapsedTo === null) {
           attrs.srcset = result.srcset;
@@ -161,7 +161,7 @@ export function rewriteAssetUrls(
     // Recurse
     if (Array.isArray(node.children)) {
       for (const child of node.children) {
-        if (typeof child !== "string") {
+        if (!isString(child)) {
           walk(child);
         }
       }

package/src/breakpoint-plan.ts

@@ -20,6 +20,8 @@
  * @docs studio/design/breakpoints
  */
 
+import { IMPORT_MAX_BREAKPOINTS } from "@jxsuite/protocol/types";
+
 /** One breakpoint: what to call it, what to emit, and the viewport width to sample it at. */
 export interface Breakpoint {
   /** Jx breakpoint name, e.g. `--768`. */
@@ -60,8 +62,11 @@ export const DEFAULT_BREAKPOINT_POLICY: BreakpointPolicy = {
   rounding: "nearest",
 };
 
-/** The most breakpoints a project may be asked to keep. Past this, "limit" is not limiting. */
-export const MAX_BREAKPOINTS = 12;
+/**
+ * The most breakpoints a project may be asked to keep. Past this, "limit" is not limiting. The
+ * value is the wire contract's, so a client that offers a count offers the same ceiling.
+ */
+export const MAX_BREAKPOINTS = IMPORT_MAX_BREAKPOINTS;
 
 /** The viewport widths an override may name. Outside this a "width" is a typo, not a breakpoint. */
 export const MIN_BREAKPOINT_WIDTH = 120;

package/src/capture.ts

@@ -20,20 +20,24 @@
 export type PageArgs<Params extends unknown[]> = { [K in keyof Params]: Params[K] };
 
 export interface ImportPage {
+  /**
+   * Resolves once navigation settles. Puppeteer resolves with the main response (or `null`), a
+   * stand-in may resolve with nothing; the import never reads the value either way.
+   */
   goto: (
     url: string,
     options?: {
       waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
       timeout?: number;
     },
-  ) => Promise<unknown>;
-  setViewport: (viewport: { width: number; height: number }) => Promise<unknown>;
+  ) => Promise<object | null> | Promise<void>;
+  setViewport: (viewport: { width: number; height: number }) => Promise<void>;
   evaluate: <Params extends unknown[], R>(
     fn: (...params: PageArgs<Params>) => R,
     ...args: Params
   ) => Promise<Awaited<R>>;
   screenshot: (options?: { fullPage?: boolean; type?: "png" }) => Promise<Uint8Array>;
-  close: () => Promise<unknown>;
+  close: () => Promise<void>;
 }
 
 export interface ImportBrowser {
@@ -126,9 +130,11 @@ export async function capturePage(
 
     const links: string[] = [];
     const { origin } = location;
-    for (const a of document.querySelectorAll("a[href]")) {
+    /* The selector names HTML anchors, whose `href` is the resolved URL string. An SVG `<a href>`
+       also matches and is read the same way; that has always been the case here. */
+    for (const a of document.querySelectorAll<HTMLAnchorElement>("a[href]")) {
       try {
-        const { href } = new URL((a as HTMLAnchorElement).href, location.href);
+        const { href } = new URL(a.href, location.href);
         if (href.startsWith(origin) && !href.includes("#")) {
           links.push(href);
         }

package/src/cli.ts

@@ -179,11 +179,12 @@ if (maxDepth > 0) {
 
 // The interactive flow runs inside an async function rather than via top-level await so a test can
 // Dynamic-import this entry and await the same sequence (see create/index.ts for the rationale).
-async function main() {
+// The URL is passed in because a hoisted declaration cannot see the module-level check above.
+async function main(siteUrl: string) {
   try {
     const result = await importSite(
       {
-        url: url as string,
+        url: siteUrl,
         outDir,
         breakpoints,
         maxDepth,
@@ -254,4 +255,4 @@ async function main() {
 }
 
 // oxlint-disable-next-line unicorn/prefer-top-level-await
-export const ready = main();
+export const ready = main(url);