@jxsuite/import 0.40.8 → 0.40.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/import",
-  "version": "0.40.8",
+  "version": "0.40.10",
   "description": "Clone a live website into a Jx project",
   "license": "MIT",
   "repository": {
@@ -36,16 +36,18 @@
   },
   "dependencies": {
     "@jxsuite/markup": "^0.4.12",
+    "@jxsuite/protocol": "^2.6.1",
     "@jxsuite/schema": "^3.0.0",
-    "pixelmatch": "^7.2.0",
+    "pixelmatch": "^8.0.0",
     "pngjs": "^7.0.0",
     "puppeteer-core": "^25.12.0"
   },
   "devDependencies": {
+    "@happy-dom/global-registrator": "^21.0.3",
     "@types/pngjs": "^6.0.5",
-    "happy-dom": "^20.10.6"
+    "happy-dom": "^21.0.3"
   },
   "optionalDependencies": {
-    "@jxsuite/compiler": "^5.1.1"
+    "@jxsuite/compiler": "^5.1.3"
   }
 }

package/src/ai-componentize.ts

@@ -9,7 +9,8 @@
  * Uses the OpenAI-compatible chat completions API (same as the eval harness).
  */
 
-import type { JxElement } from "@jxsuite/schema/types";
+import { isJsonObject, isNonNullObject, isString } from "@jxsuite/schema/guards";
+import type { JsonObject, JsonValue, JxElement } from "@jxsuite/schema/types";
 import type { ExtractedComponent, ComponentizeResult } from "./componentize.ts";
 
 export interface AiComponentizeOptions {
@@ -31,7 +32,8 @@ export interface AiComponentizeOptions {
 interface RenameResult {
   componentName: string;
   tagName: string;
-  props: Record<string, string>;
+  /** The model's proposed renames, unvalidated: a caller keeps only the string values it accepts. */
+  props: Record<string, JsonValue>;
 }
 
 function buildPrompt(component: ExtractedComponent): string {
@@ -87,102 +89,81 @@ async function callLlm(prompt: string, opts: AiComponentizeOptions): Promise<Ren
     return null;
   }
 
-  const data = (await response.json()) as {
-    choices?: { message?: { content?: string } }[];
-  };
-
-  const content = data.choices?.[0]?.message?.content;
-  if (!content) {
+  // The completion body is foreign JSON: walk `choices[0].message.content` one guard at a time.
+  const data: unknown = await response.json();
+  const choices = isJsonObject(data) ? data.choices : undefined;
+  const choice = Array.isArray(choices) ? choices[0] : undefined;
+  const message = isJsonObject(choice) ? choice.message : undefined;
+  const content = isJsonObject(message) ? message.content : undefined;
+  if (!isString(content) || !content) {
     return null;
   }
 
   try {
-    const parsed = JSON.parse(content) as Record<string, unknown>;
-    const { componentName } = parsed;
-    const { tagName } = parsed;
-    const { props } = parsed;
+    // A reply that is not an object has none of the three fields, and fails the check below.
+    const parsed: unknown = JSON.parse(content);
+    const fields: JsonObject = isJsonObject(parsed) ? parsed : {};
+    const { componentName } = fields;
+    const { tagName } = fields;
+    const { props } = fields;
 
     if (
-      typeof componentName !== "string" ||
+      !isString(componentName) ||
       !componentName.includes("-") ||
-      typeof tagName !== "string" ||
-      typeof props !== "object" ||
-      props === null
+      !isString(tagName) ||
+      !isNonNullObject(props)
     ) {
       return null;
     }
 
-    return {
-      componentName: componentName as string,
-      tagName: tagName as string,
-      props: props as Record<string, string>,
-    };
+    /* `Object.entries` reads an array's indices as keys, so an array `props` keeps the by-index
+       lookup it always had while the result gains one honest dictionary type. */
+    return { componentName, tagName, props: Object.fromEntries(Object.entries(props)) };
   } catch {
     return null;
   }
 }
 
-function renamePropsInTree(
-  node: JxElement | string,
-  renames: Record<string, string>,
-): JxElement | string {
-  if (typeof node === "string") {
-    let result = node;
-    for (const [oldName, newName] of Object.entries(renames)) {
-      if (oldName !== newName) {
-        result = result.replaceAll(`\${state.${oldName}}`, `\${state.${newName}}`);
-      }
+/** Rewrites every `${state.<old>}` reference in one template string to its renamed prop. */
+function renameStateRefs(text: string, renames: Record<string, string>): string {
+  let result = text;
+  for (const [oldName, newName] of Object.entries(renames)) {
+    if (oldName !== newName) {
+      result = result.replaceAll(`\${state.${oldName}}`, `\${state.${newName}}`);
     }
-    return result;
   }
+  return result;
+}
 
+function renamePropsInTree(node: JxElement, renames: Record<string, string>): JxElement {
   const out: JxElement = { ...node };
 
-  if (typeof out.textContent === "string") {
-    for (const [oldName, newName] of Object.entries(renames)) {
-      if (oldName !== newName) {
-        out.textContent = (out.textContent as string).replaceAll(
-          `\${state.${oldName}}`,
-          `\${state.${newName}}`,
-        );
-      }
-    }
+  const { textContent } = out;
+  if (isString(textContent)) {
+    out.textContent = renameStateRefs(textContent, renames);
   }
 
   if (out.attributes) {
     out.attributes = { ...out.attributes };
     for (const [attrKey, attrVal] of Object.entries(out.attributes)) {
-      if (typeof attrVal === "string") {
-        let v = attrVal;
-        for (const [oldName, newName] of Object.entries(renames)) {
-          if (oldName !== newName) {
-            v = v.replaceAll(`\${state.${oldName}}`, `\${state.${newName}}`);
-          }
-        }
-        out.attributes[attrKey] = v;
+      if (isString(attrVal)) {
+        out.attributes[attrKey] = renameStateRefs(attrVal, renames);
       }
     }
   }
 
   if (Array.isArray(out.children)) {
     out.children = out.children.map((c) =>
-      renamePropsInTree(c as JxElement | string, renames),
-    ) as JxElement[];
+      isString(c) ? renameStateRefs(c, renames) : renamePropsInTree(c, renames),
+    );
   }
 
   return out;
 }
 
-function renamePropsInState(
-  state: Record<string, unknown>,
-  renames: Record<string, string>,
-): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(state)) {
-    const newKey = renames[k] ?? k;
-    out[newKey] = v;
-  }
-  return out;
+/** Re-keys a state map by the prop renames, keeping each entry's value and its position. */
+function renamePropsInState<V>(state: Record<string, V>, renames: Record<string, string>) {
+  return Object.fromEntries(Object.entries(state).map(([k, v]) => [renames[k] ?? k, v]));
 }
 
 function toPascalCase(str: string): string {
@@ -241,15 +222,12 @@ export async function aiComponentize(
     for (const prop of existingProps) {
       const renamed = result.props[prop];
       propRenames[prop] =
-        typeof renamed === "string" && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(renamed) ? renamed : prop;
+        isString(renamed) && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(renamed) ? renamed : prop;
     }
 
-    const newTemplate = renamePropsInTree(component.template, propRenames) as JxElement;
+    const newTemplate = renamePropsInTree(component.template, propRenames);
     if (newTemplate.state) {
-      newTemplate.state = renamePropsInState(
-        newTemplate.state as Record<string, unknown>,
-        propRenames,
-      ) as Record<string, string>;
+      newTemplate.state = renamePropsInState(newTemplate.state, propRenames);
     }
 
     const newComponent: ExtractedComponent = {
@@ -291,7 +269,7 @@ function rewriteCallSites(
 
   /* Import builds every node from parsed HTML, so a tag here is always a literal — the narrow is
      the type saying so rather than a cast pretending the other shape cannot arrive. */
-  const literalTag = typeof result.tagName === "string" ? result.tagName : null;
+  const literalTag = isString(result.tagName) ? result.tagName : null;
   if (literalTag && tagRenames.has(literalTag)) {
     const oldTag = literalTag;
     result.tagName = tagRenames.get(oldTag)!;
@@ -309,11 +287,11 @@ function rewriteCallSites(
 
   if (Array.isArray(result.children)) {
     result.children = result.children.map((child) => {
-      if (typeof child === "string") {
+      if (isString(child)) {
         return child;
       }
-      return rewriteCallSites(child as JxElement, tagRenames, propRenamesByTag);
-    }) as JxElement[];
+      return rewriteCallSites(child, tagRenames, propRenamesByTag);
+    });
   }
 
   return result;

package/src/apply-accordions.ts

@@ -20,7 +20,8 @@
  * open/closed logic out of attribute values without naming Alpine, Vue or anything else.
  */
 
-import type { JxElement } from "@jxsuite/schema/types";
+import { isString } from "@jxsuite/schema/guards";
+import type { JxAttributeValue, JxElement } from "@jxsuite/schema/types";
 import { roleOfElement } from "./toggle-algebra.ts";
 import type { ToggleRole } from "./toggle-algebra.ts";
 
@@ -43,11 +44,11 @@ const CONCEALING_STYLE = new Set(["display", "height", "maxHeight", "overflow",
 /** Names that must survive whatever else is stripped. */
 const PROTECTED_ATTRIBUTES = new Set(["id", "role", "href", "src", "alt", "class", "title"]);
 
-function isDeadDirective(name: string, value: unknown): boolean {
+function isDeadDirective(name: string, value: JxAttributeValue | undefined): boolean {
   if (PROTECTED_ATTRIBUTES.has(name) || name.startsWith("aria-")) {
     return false;
   }
-  if (name.startsWith("on") && typeof value === "string") {
+  if (name.startsWith("on") && isString(value)) {
     return true;
   }
   return DEAD_DIRECTIVE_PREFIXES.some((prefix) => name.startsWith(prefix));
@@ -62,7 +63,7 @@ function isDeadDirective(name: string, value: unknown): boolean {
  * anyway, and returning nothing makes it fall through untouched.
  */
 function childrenOf(node: JxElement): (JxElement | string)[] {
-  return Array.isArray(node.children) ? (node.children as (JxElement | string)[]) : [];
+  return Array.isArray(node.children) ? node.children : [];
 }
 
 /**
@@ -78,17 +79,17 @@ function childrenOf(node: JxElement): (JxElement | string)[] {
 export function countLeaves(node: JxElement | string): string[] {
   const leaves: string[] = [];
   const visit = (current: JxElement | string): void => {
-    if (typeof current === "string") {
+    if (isString(current)) {
       if (current.trim().length > 0) {
         leaves.push(`t:${current.trim()}`);
       }
       return;
     }
-    if (typeof current.textContent === "string" && current.textContent.trim().length > 0) {
+    if (isString(current.textContent) && current.textContent.trim().length > 0) {
       leaves.push(`t:${current.textContent.trim()}`);
     }
-    const source = (current.attributes as Record<string, unknown> | undefined)?.["src"];
-    if (typeof source === "string") {
+    const source = current.attributes?.["src"];
+    if (isString(source)) {
       leaves.push(`m:${source}`);
     }
     for (const child of childrenOf(current)) {
@@ -101,7 +102,7 @@ export function countLeaves(node: JxElement | string): string[] {
 
 /** Remove dead framework directives and concealment from one node, in place. */
 function cleanNode(node: JxElement, unconceal: boolean): void {
-  const attributes = node.attributes as Record<string, unknown> | undefined;
+  const { attributes } = node;
   if (attributes) {
     for (const name of Object.keys(attributes)) {
       if (isDeadDirective(name, attributes[name])) {
@@ -112,7 +113,7 @@ function cleanNode(node: JxElement, unconceal: boolean): void {
     }
   }
   if (unconceal && node.style) {
-    const style = node.style as Record<string, unknown>;
+    const { style } = node;
     for (const property of Object.keys(style)) {
       if (CONCEALING_STYLE.has(property)) {
         delete style[property];
@@ -123,7 +124,7 @@ function cleanNode(node: JxElement, unconceal: boolean): void {
 
 /** Strip directives from a whole subtree; only the row's own body is unconcealed. */
 function cleanSubtree(node: JxElement | string, unconceal: boolean): void {
-  if (typeof node === "string") {
+  if (isString(node)) {
     return;
   }
   cleanNode(node, unconceal);
@@ -139,18 +140,26 @@ interface RowParts {
   key: string;
 }
 
+/** Whether a role is of the kind asked for, narrowing it to that member of the union. */
+function isRoleOfKind<K extends ToggleRole["kind"]>(
+  role: ToggleRole | null,
+  want: K,
+): role is Extract<ToggleRole, { kind: K }> {
+  return role?.kind === want;
+}
+
 /** The first descendant-or-self whose role matches, depth-first, narrowed to the kind asked for. */
 function findRole<K extends ToggleRole["kind"]>(
   node: JxElement,
   idents: ReadonlySet<string>,
   want: K,
 ): { node: JxElement; role: Extract<ToggleRole, { kind: K }> } | null {
-  const role = roleOfElement(node.attributes as Record<string, unknown> | undefined, idents);
-  if (role?.kind === want) {
-    return { node, role: role as Extract<ToggleRole, { kind: K }> };
+  const role = roleOfElement(node.attributes, idents);
+  if (isRoleOfKind(role, want)) {
+    return { node, role };
   }
   for (const child of childrenOf(node)) {
-    if (typeof child === "string") {
+    if (isString(child)) {
       continue;
     }
     const found = findRole(child, idents, want);
@@ -174,13 +183,13 @@ export function readAccordionRows(root: JxElement, idents: ReadonlySet<string>):
   const seenKeys = new Set<string>();
 
   for (const child of childrenOf(root)) {
-    if (typeof child === "string") {
+    if (isString(child)) {
       if (child.trim().length > 0) {
         return null;
       }
       continue;
     }
-    const row = child as JxElement;
+    const row = child;
     const toggle = findRole(row, idents, "assign");
     const predicate = findRole(row, idents, "compare");
     if (!toggle || !predicate) {
@@ -233,15 +242,13 @@ function rewriteRoot(
     cleanSubtree(row, false);
     cleanNode(body, true);
 
-    const summary: JxElement = { children: [title] as JxElement[], tagName: "summary" };
-    const others = childrenOf(row).filter(
-      (child) => child !== title && child !== body,
-    ) as JxElement[];
+    const summary: JxElement = { children: [title], tagName: "summary" };
+    const others = childrenOf(row).filter((child) => child !== title && child !== body);
 
     rewritten.push({
       ...row,
-      attributes: { ...(row.attributes as Record<string, string>), name },
-      children: [summary, body, ...others] as JxElement[],
+      attributes: { ...row.attributes, name },
+      children: [summary, body, ...others],
       tagName: "details",
     });
   }
@@ -281,7 +288,7 @@ export function applyAccordions(root: JxElement): AccordionResult {
   let index = 0;
 
   const visit = (node: JxElement): void => {
-    const role = roleOfElement(node.attributes as Record<string, unknown> | undefined);
+    const role = roleOfElement(node.attributes);
     if (role?.kind === "declare") {
       const idents = new Set(role.idents.keys());
       const rows = readAccordionRows(node, idents);
@@ -293,7 +300,7 @@ export function applyAccordions(root: JxElement): AccordionResult {
       }
     }
     for (const child of childrenOf(node)) {
-      if (typeof child !== "string") {
+      if (!isString(child)) {
         visit(child);
       }
     }

package/src/apply-disclosures.ts

@@ -21,6 +21,7 @@
  * that would lose a text run or an image is abandoned whole.
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import type { JxElement } from "@jxsuite/schema/types";
 import { countLeaves } from "./apply-accordions.ts";
 
@@ -30,28 +31,22 @@ const CONTROL_ATTRIBUTES = ["aria-expanded", "aria-controls", "role", "tabindex"
 /** A panel lifted out of the flow is an overlay, and belongs to the popover pass instead. */
 const POSITIONED = new Set(["absolute", "fixed"]);
 
-function attributesOf(node: JxElement): Record<string, unknown> | undefined {
-  return node.attributes as Record<string, unknown> | undefined;
-}
-
 function childrenOf(node: JxElement): (JxElement | string)[] {
-  return Array.isArray(node.children) ? (node.children as (JxElement | string)[]) : [];
+  return Array.isArray(node.children) ? node.children : [];
 }
 
 function elementChildren(node: JxElement): JxElement[] {
-  return childrenOf(node).filter((child) => typeof child !== "string") as JxElement[];
+  return childrenOf(node).filter((child): child is JxElement => !isString(child));
 }
 
 /** Whether this control declares that it expands a named panel. */
 export function isDisclosureInvoker(node: JxElement): boolean {
-  const attributes = attributesOf(node);
+  const { attributes } = node;
   if (!attributes) {
     return false;
   }
   const controls = attributes["aria-controls"];
-  return (
-    attributes["aria-expanded"] !== undefined && typeof controls === "string" && controls.length > 0
-  );
+  return attributes["aria-expanded"] !== undefined && isString(controls) && controls.length > 0;
 }
 
 /**
@@ -61,20 +56,19 @@ export function isDisclosureInvoker(node: JxElement): boolean {
  * why a detector looking only at computed style would miss every one of them.
  */
 export function isDisclosurePanel(node: JxElement): boolean {
-  const style = node.style as Record<string, unknown> | undefined;
+  const { style } = node;
   if (POSITIONED.has(String(style?.["position"] ?? ""))) {
     return false;
   }
-  const attributes = attributesOf(node);
-  return attributes?.["hidden"] !== undefined || style?.["display"] === "none";
+  return node.attributes?.["hidden"] !== undefined || style?.["display"] === "none";
 }
 
 /** Every element carrying an `id`, so `aria-controls` can be resolved. */
 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 elementChildren(node)) {
@@ -98,9 +92,7 @@ function contentOf(node: JxElement): (JxElement | string)[] {
   if (children.length > 0) {
     return children;
   }
-  return typeof node.textContent === "string" && node.textContent.length > 0
-    ? [node.textContent]
-    : [];
+  return isString(node.textContent) && node.textContent.length > 0 ? [node.textContent] : [];
 }
 
 /**
@@ -118,15 +110,15 @@ function unwrapInvoker(node: JxElement, invoker: JxElement): JxElement {
   }
   const rebuilt: (JxElement | string)[] = [];
   for (const child of children) {
-    if (child === invoker) {
-      rebuilt.push(...contentOf(child as JxElement));
-    } else if (typeof child === "string") {
+    if (isString(child)) {
       rebuilt.push(child);
+    } else if (child === invoker) {
+      rebuilt.push(...contentOf(child));
     } else {
-      rebuilt.push(unwrapInvoker(child as JxElement, invoker));
+      rebuilt.push(unwrapInvoker(child, invoker));
     }
   }
-  return { ...node, children: rebuilt as JxElement[] };
+  return { ...node, children: rebuilt };
 }
 
 export interface DisclosureResult {
@@ -159,15 +151,16 @@ export function applyDisclosures(root: JxElement): DisclosureResult {
 
       for (let index = 0; index < children.length && !applied; index += 1) {
         const branch = children[index];
-        if (typeof branch === "string") {
+        // The loop bound keeps `index` in range, so `branch` is never the out-of-bounds `undefined`.
+        if (branch === undefined || isString(branch)) {
           continue;
         }
 
-        const invoker = findInvokerIn(branch as JxElement);
+        const invoker = findInvokerIn(branch);
         if (!invoker) {
           continue;
         }
-        const panelId = String(attributesOf(invoker)!["aria-controls"]);
+        const panelId = String(invoker.attributes!["aria-controls"]);
         const panel = byId.get(panelId);
         if (!panel || !isDisclosurePanel(panel)) {
           continue;
@@ -176,7 +169,7 @@ export function applyDisclosures(root: JxElement): DisclosureResult {
           /* A second control for a panel already inside a `<details>` is now a lie to a screen
              reader: it reports a collapsed state it no longer governs. Strip what made it a
              control and leave the text. */
-          const attributes = attributesOf(invoker)!;
+          const attributes = invoker.attributes!;
           for (const name of CONTROL_ATTRIBUTES) {
             delete attributes[name];
           }
@@ -190,7 +183,7 @@ export function applyDisclosures(root: JxElement): DisclosureResult {
         }
 
         const before = countLeaves(parent);
-        const panelAttributes = { ...attributesOf(panel) };
+        const panelAttributes = { ...panel.attributes };
         delete panelAttributes["hidden"];
         delete panelAttributes["aria-hidden"];
 
@@ -198,41 +191,38 @@ export function applyDisclosures(root: JxElement): DisclosureResult {
            its own attributes would ride onto the `<summary>`. Stripping them here covers both
            shapes: `<summary>` is the control now, and a leftover `aria-expanded` on it would report
            a state the element no longer owns. */
-        const summaryBranch = unwrapInvoker(branch as JxElement, invoker);
-        const summaryAttributes = { ...attributesOf(summaryBranch) };
+        const summaryBranch = unwrapInvoker(branch, invoker);
+        const summaryAttributes = { ...summaryBranch.attributes };
         for (const name of CONTROL_ATTRIBUTES) {
           delete summaryAttributes[name];
         }
+        /* An `attributes` key the branch carried keeps its position, and one written only to be
+           deleted leaves no trace, so key order matches the branch it came from. */
         const summary: JxElement = {
           ...summaryBranch,
-          ...(Object.keys(summaryAttributes).length > 0
-            ? { attributes: summaryAttributes as Record<string, string> }
-            : {}),
+          attributes: summaryAttributes,
           tagName: "summary",
         };
         if (Object.keys(summaryAttributes).length === 0) {
           delete summary.attributes;
         }
         const details: JxElement = {
-          children: [summary, { ...panel, attributes: panelAttributes }] as JxElement[],
+          children: [summary, { ...panel, attributes: panelAttributes }],
           tagName: "details",
         };
 
         /* Placed where the FIRST of the pair sat, so the disclosure keeps the position the reader
            already associated with it. `<details>` always renders its summary above its content, so
            a panel that came first moves below the label it was always labelled by. */
-        const rebuilt = children.filter((child) => child !== branch && child !== panel) as (
-          | JxElement
-          | string
-        )[];
+        const rebuilt = children.filter((child) => child !== branch && child !== panel);
         rebuilt.splice(Math.min(index, panelIndex), 0, details);
 
-        const candidate: JxElement = { ...parent, children: rebuilt as JxElement[] };
+        const candidate: JxElement = { ...parent, children: rebuilt };
         if (countLeaves(candidate).join(" ") !== before.join(" ")) {
           continue;
         }
 
-        parent.children = rebuilt as JxElement[];
+        parent.children = rebuilt;
         claimedPanels.add(panel);
         result.converted += 1;
         applied = true;