@noego/wood 0.4.8 → 0.4.10

package/dist/automation/target_registry.cjs

@@ -0,0 +1,148 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var target_registry_exports = {};
+__export(target_registry_exports, {
+  WOOD_INTERNAL_BRIDGE_KEY: () => WOOD_INTERNAL_BRIDGE_KEY,
+  discoverTargets: () => discoverTargets,
+  selectTarget: () => selectTarget
+});
+module.exports = __toCommonJS(target_registry_exports);
+var import_errors = require("./errors.cjs");
+var import_introspection_reader = require("./introspection_reader.cjs");
+const WOOD_INTERNAL_BRIDGE_KEY = "__NOEGO_WOOD_BRIDGE__";
+async function readBridgeWindow(page) {
+  try {
+    const current = await page.evaluate(async (bridgeKey) => {
+      const bridge = globalThis[bridgeKey];
+      if (!bridge || typeof bridge !== "object") {
+        return null;
+      }
+      const windowApi = bridge.__window;
+      if (!windowApi || typeof windowApi.current !== "function") {
+        return null;
+      }
+      return await windowApi.current();
+    }, WOOD_INTERNAL_BRIDGE_KEY);
+    if (!current) {
+      return { windowId: null, defaultRoute: null, present: false };
+    }
+    return {
+      windowId: current.ok ? current.windowId ?? null : null,
+      defaultRoute: current.ok ? current.defaultRoute ?? null : null,
+      present: true
+    };
+  } catch {
+    return { windowId: null, defaultRoute: null, present: false };
+  }
+}
+async function readCdpIdentity(page) {
+  try {
+    const session = await page.context().newCDPSession(page);
+    try {
+      const info = await session.send("Target.getTargetInfo");
+      return {
+        targetId: info.targetInfo.targetId,
+        browserContextId: info.targetInfo.browserContextId
+      };
+    } finally {
+      await session.detach().catch(() => void 0);
+    }
+  } catch {
+    return { targetId: null, browserContextId: void 0 };
+  }
+}
+async function discoverTargets(browser) {
+  const entries = [];
+  let fallbackIndex = 0;
+  for (const context of browser.contexts()) {
+    for (const page of context.pages()) {
+      const [bridge, identity, snapshot] = await Promise.all([
+        readBridgeWindow(page),
+        readCdpIdentity(page),
+        (0, import_introspection_reader.readAutomationSnapshot)(page)
+      ]);
+      const title = await page.title().catch(() => "");
+      entries.push({
+        page,
+        target: {
+          targetId: identity.targetId ?? `unstable:page-${fallbackIndex}`,
+          windowId: snapshot?.windowId ?? bridge.windowId,
+          browserContextId: identity.browserContextId,
+          pageGeneration: 1,
+          url: page.url(),
+          title,
+          currentRoute: (0, import_introspection_reader.formatRoute)(snapshot?.currentRoute ?? null),
+          configuredDefaultRoute: bridge.defaultRoute ?? void 0,
+          woodBridgePresent: bridge.present,
+          eligible: bridge.present
+        }
+      });
+      fallbackIndex += 1;
+    }
+  }
+  return entries;
+}
+function selectTarget(entries, requestedWindowId) {
+  if (entries.length === 0) {
+    return (0, import_errors.automationError)("NO_ELIGIBLE_TARGETS", "No renderer targets found in the running Wood app.", {
+      requiredAction: 'Verify the app is running under "wood dev" and has at least one window.'
+    });
+  }
+  if (requestedWindowId) {
+    const matches = entries.filter((entry) => entry.target.windowId === requestedWindowId);
+    if (matches.length === 0) {
+      return (0, import_errors.automationError)("TARGET_NOT_FOUND", `No Wood window target found for "${requestedWindowId}".`, {
+        details: { candidates: entries.map((entry) => entry.target.windowId).filter(Boolean) },
+        requiredAction: 'Run "axe targets" and pass an existing windowId via --window.'
+      });
+    }
+    if (matches.length > 1) {
+      return (0, import_errors.automationError)("TARGET_AMBIGUOUS", `Multiple targets match windowId "${requestedWindowId}".`, {
+        details: { matchCount: matches.length },
+        requiredAction: "Close duplicate windows or report this as a window-identity bug."
+      });
+    }
+    return (0, import_errors.automationOk)(matches[0]);
+  }
+  const eligible = entries.filter((entry) => entry.target.eligible);
+  if (eligible.length === 0) {
+    return (0, import_errors.automationError)("NO_ELIGIBLE_TARGETS", "No Wood-bridged renderer targets found.", {
+      details: { discovered: entries.length },
+      requiredAction: "Only pages exposing the Wood bridge are automatable; check the app booted correctly."
+    });
+  }
+  if (eligible.length > 1) {
+    return (0, import_errors.automationError)(
+      "TARGET_AMBIGUOUS",
+      `${eligible.length} eligible Wood windows found; an explicit target is required.`,
+      {
+        details: { candidates: eligible.map((entry) => entry.target.windowId) },
+        requiredAction: 'Pass --window <windowId> (see "axe targets").'
+      }
+    );
+  }
+  return (0, import_errors.automationOk)(eligible[0]);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WOOD_INTERNAL_BRIDGE_KEY,
+  discoverTargets,
+  selectTarget
+});
+//# sourceMappingURL=target_registry.cjs.map

package/dist/automation/target_registry.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/automation/target_registry.ts"],"sourcesContent":["/**\n * Target discovery and deterministic selection (AXE-WP-01, AXE-002).\n *\n * Selection rules:\n * - pages without a Wood bridge are ineligible by default;\n * - an explicit windowId must match exactly one target;\n * - without a windowId, exactly one eligible target must exist —\n *   multiple eligible windows are an explicit ambiguity error, never\n *   a silent \"first page wins\".\n */\n\nimport type { Browser, Page } from 'playwright';\nimport { automationError, automationOk, type WoodAutomationResult } from './errors.cjs';\nimport { formatRoute, readAutomationSnapshot } from './introspection_reader.cjs';\nimport type { WoodLiveTarget } from './target_identity.cjs';\n\nexport const WOOD_INTERNAL_BRIDGE_KEY = '__NOEGO_WOOD_BRIDGE__';\n\nexport interface WoodTargetEntry {\n  target: WoodLiveTarget;\n  page: Page;\n}\n\ninterface BridgeWindowInfo {\n  windowId: string | null;\n  defaultRoute: string | null;\n  present: boolean;\n}\n\nasync function readBridgeWindow(page: Page): Promise<BridgeWindowInfo> {\n  try {\n    const current = await page.evaluate(async (bridgeKey) => {\n      const bridge = (globalThis as Record<string, unknown>)[bridgeKey];\n      if (!bridge || typeof bridge !== 'object') {\n        return null;\n      }\n      const windowApi = (bridge as { __window?: { current?: () => Promise<unknown> } }).__window;\n      if (!windowApi || typeof windowApi.current !== 'function') {\n        return null;\n      }\n      return (await windowApi.current()) as { ok?: boolean; windowId?: string; defaultRoute?: string };\n    }, WOOD_INTERNAL_BRIDGE_KEY);\n\n    if (!current) {\n      return { windowId: null, defaultRoute: null, present: false };\n    }\n    return {\n      windowId: current.ok ? current.windowId ?? null : null,\n      defaultRoute: current.ok ? current.defaultRoute ?? null : null,\n      present: true,\n    };\n  } catch {\n    return { windowId: null, defaultRoute: null, present: false };\n  }\n}\n\nasync function readCdpIdentity(\n  page: Page,\n): Promise<{ targetId: string | null; browserContextId: string | undefined }> {\n  try {\n    const session = await page.context().newCDPSession(page);\n    try {\n      const info = await session.send('Target.getTargetInfo');\n      return {\n        targetId: info.targetInfo.targetId,\n        browserContextId: info.targetInfo.browserContextId,\n      };\n    } finally {\n      await session.detach().catch(() => undefined);\n    }\n  } catch {\n    return { targetId: null, browserContextId: undefined };\n  }\n}\n\n/**\n * Enumerate all renderer pages with Wood identity attached.\n * `pageGeneration` starts at 1 per discovery; persistent generation tracking\n * arrives with scenario mode (AXE-WP-04).\n */\nexport async function discoverTargets(browser: Browser): Promise<WoodTargetEntry[]> {\n  const entries: WoodTargetEntry[] = [];\n  let fallbackIndex = 0;\n\n  for (const context of browser.contexts()) {\n    for (const page of context.pages()) {\n      const [bridge, identity, snapshot] = await Promise.all([\n        readBridgeWindow(page),\n        readCdpIdentity(page),\n        readAutomationSnapshot(page),\n      ]);\n      const title = await page.title().catch(() => '');\n\n      entries.push({\n        page,\n        target: {\n          targetId: identity.targetId ?? `unstable:page-${fallbackIndex}`,\n          windowId: snapshot?.windowId ?? bridge.windowId,\n          browserContextId: identity.browserContextId,\n          pageGeneration: 1,\n          url: page.url(),\n          title,\n          currentRoute: formatRoute(snapshot?.currentRoute ?? null),\n          configuredDefaultRoute: bridge.defaultRoute ?? undefined,\n          woodBridgePresent: bridge.present,\n          eligible: bridge.present,\n        },\n      });\n      fallbackIndex += 1;\n    }\n  }\n\n  return entries;\n}\n\n/**\n * Deterministic target selection (pure; unit-tested without a browser).\n */\nexport function selectTarget(\n  entries: WoodTargetEntry[],\n  requestedWindowId?: string | null,\n): WoodAutomationResult<WoodTargetEntry> {\n  if (entries.length === 0) {\n    return automationError('NO_ELIGIBLE_TARGETS', 'No renderer targets found in the running Wood app.', {\n      requiredAction: 'Verify the app is running under \"wood dev\" and has at least one window.',\n    });\n  }\n\n  if (requestedWindowId) {\n    const matches = entries.filter((entry) => entry.target.windowId === requestedWindowId);\n    if (matches.length === 0) {\n      return automationError('TARGET_NOT_FOUND', `No Wood window target found for \"${requestedWindowId}\".`, {\n        details: { candidates: entries.map((entry) => entry.target.windowId).filter(Boolean) },\n        requiredAction: 'Run \"axe targets\" and pass an existing windowId via --window.',\n      });\n    }\n    if (matches.length > 1) {\n      return automationError('TARGET_AMBIGUOUS', `Multiple targets match windowId \"${requestedWindowId}\".`, {\n        details: { matchCount: matches.length },\n        requiredAction: 'Close duplicate windows or report this as a window-identity bug.',\n      });\n    }\n    return automationOk(matches[0]);\n  }\n\n  const eligible = entries.filter((entry) => entry.target.eligible);\n  if (eligible.length === 0) {\n    return automationError('NO_ELIGIBLE_TARGETS', 'No Wood-bridged renderer targets found.', {\n      details: { discovered: entries.length },\n      requiredAction: 'Only pages exposing the Wood bridge are automatable; check the app booted correctly.',\n    });\n  }\n  if (eligible.length > 1) {\n    return automationError(\n      'TARGET_AMBIGUOUS',\n      `${eligible.length} eligible Wood windows found; an explicit target is required.`,\n      {\n        details: { candidates: eligible.map((entry) => entry.target.windowId) },\n        requiredAction: 'Pass --window <windowId> (see \"axe targets\").',\n      },\n    );\n  }\n\n  return automationOk(eligible[0]);\n}\n"],"mappings":"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","names":[]}

package/dist/automation/target_registry.d.cts

@@ -0,0 +1,32 @@
+import { Page, Browser } from 'playwright';
+import { WoodAutomationResult } from './errors.cjs';
+import { WoodLiveTarget } from './target_identity.cjs';
+
+/**
+ * Target discovery and deterministic selection (AXE-WP-01, AXE-002).
+ *
+ * Selection rules:
+ * - pages without a Wood bridge are ineligible by default;
+ * - an explicit windowId must match exactly one target;
+ * - without a windowId, exactly one eligible target must exist —
+ *   multiple eligible windows are an explicit ambiguity error, never
+ *   a silent "first page wins".
+ */
+
+declare const WOOD_INTERNAL_BRIDGE_KEY = "__NOEGO_WOOD_BRIDGE__";
+interface WoodTargetEntry {
+    target: WoodLiveTarget;
+    page: Page;
+}
+/**
+ * Enumerate all renderer pages with Wood identity attached.
+ * `pageGeneration` starts at 1 per discovery; persistent generation tracking
+ * arrives with scenario mode (AXE-WP-04).
+ */
+declare function discoverTargets(browser: Browser): Promise<WoodTargetEntry[]>;
+/**
+ * Deterministic target selection (pure; unit-tested without a browser).
+ */
+declare function selectTarget(entries: WoodTargetEntry[], requestedWindowId?: string | null): WoodAutomationResult<WoodTargetEntry>;
+
+export { WOOD_INTERNAL_BRIDGE_KEY, type WoodTargetEntry, discoverTargets, selectTarget };

package/dist/automation/target_registry.d.ts

@@ -0,0 +1,32 @@
+import { Page, Browser } from 'playwright';
+import { WoodAutomationResult } from './errors.js';
+import { WoodLiveTarget } from './target_identity.js';
+
+/**
+ * Target discovery and deterministic selection (AXE-WP-01, AXE-002).
+ *
+ * Selection rules:
+ * - pages without a Wood bridge are ineligible by default;
+ * - an explicit windowId must match exactly one target;
+ * - without a windowId, exactly one eligible target must exist —
+ *   multiple eligible windows are an explicit ambiguity error, never
+ *   a silent "first page wins".
+ */
+
+declare const WOOD_INTERNAL_BRIDGE_KEY = "__NOEGO_WOOD_BRIDGE__";
+interface WoodTargetEntry {
+    target: WoodLiveTarget;
+    page: Page;
+}
+/**
+ * Enumerate all renderer pages with Wood identity attached.
+ * `pageGeneration` starts at 1 per discovery; persistent generation tracking
+ * arrives with scenario mode (AXE-WP-04).
+ */
+declare function discoverTargets(browser: Browser): Promise<WoodTargetEntry[]>;
+/**
+ * Deterministic target selection (pure; unit-tested without a browser).
+ */
+declare function selectTarget(entries: WoodTargetEntry[], requestedWindowId?: string | null): WoodAutomationResult<WoodTargetEntry>;
+
+export { WOOD_INTERNAL_BRIDGE_KEY, type WoodTargetEntry, discoverTargets, selectTarget };

package/dist/automation/target_registry.js

@@ -0,0 +1,122 @@
+import { automationError, automationOk } from "./errors.js";
+import { formatRoute, readAutomationSnapshot } from "./introspection_reader.js";
+const WOOD_INTERNAL_BRIDGE_KEY = "__NOEGO_WOOD_BRIDGE__";
+async function readBridgeWindow(page) {
+  try {
+    const current = await page.evaluate(async (bridgeKey) => {
+      const bridge = globalThis[bridgeKey];
+      if (!bridge || typeof bridge !== "object") {
+        return null;
+      }
+      const windowApi = bridge.__window;
+      if (!windowApi || typeof windowApi.current !== "function") {
+        return null;
+      }
+      return await windowApi.current();
+    }, WOOD_INTERNAL_BRIDGE_KEY);
+    if (!current) {
+      return { windowId: null, defaultRoute: null, present: false };
+    }
+    return {
+      windowId: current.ok ? current.windowId ?? null : null,
+      defaultRoute: current.ok ? current.defaultRoute ?? null : null,
+      present: true
+    };
+  } catch {
+    return { windowId: null, defaultRoute: null, present: false };
+  }
+}
+async function readCdpIdentity(page) {
+  try {
+    const session = await page.context().newCDPSession(page);
+    try {
+      const info = await session.send("Target.getTargetInfo");
+      return {
+        targetId: info.targetInfo.targetId,
+        browserContextId: info.targetInfo.browserContextId
+      };
+    } finally {
+      await session.detach().catch(() => void 0);
+    }
+  } catch {
+    return { targetId: null, browserContextId: void 0 };
+  }
+}
+async function discoverTargets(browser) {
+  const entries = [];
+  let fallbackIndex = 0;
+  for (const context of browser.contexts()) {
+    for (const page of context.pages()) {
+      const [bridge, identity, snapshot] = await Promise.all([
+        readBridgeWindow(page),
+        readCdpIdentity(page),
+        readAutomationSnapshot(page)
+      ]);
+      const title = await page.title().catch(() => "");
+      entries.push({
+        page,
+        target: {
+          targetId: identity.targetId ?? `unstable:page-${fallbackIndex}`,
+          windowId: snapshot?.windowId ?? bridge.windowId,
+          browserContextId: identity.browserContextId,
+          pageGeneration: 1,
+          url: page.url(),
+          title,
+          currentRoute: formatRoute(snapshot?.currentRoute ?? null),
+          configuredDefaultRoute: bridge.defaultRoute ?? void 0,
+          woodBridgePresent: bridge.present,
+          eligible: bridge.present
+        }
+      });
+      fallbackIndex += 1;
+    }
+  }
+  return entries;
+}
+function selectTarget(entries, requestedWindowId) {
+  if (entries.length === 0) {
+    return automationError("NO_ELIGIBLE_TARGETS", "No renderer targets found in the running Wood app.", {
+      requiredAction: 'Verify the app is running under "wood dev" and has at least one window.'
+    });
+  }
+  if (requestedWindowId) {
+    const matches = entries.filter((entry) => entry.target.windowId === requestedWindowId);
+    if (matches.length === 0) {
+      return automationError("TARGET_NOT_FOUND", `No Wood window target found for "${requestedWindowId}".`, {
+        details: { candidates: entries.map((entry) => entry.target.windowId).filter(Boolean) },
+        requiredAction: 'Run "axe targets" and pass an existing windowId via --window.'
+      });
+    }
+    if (matches.length > 1) {
+      return automationError("TARGET_AMBIGUOUS", `Multiple targets match windowId "${requestedWindowId}".`, {
+        details: { matchCount: matches.length },
+        requiredAction: "Close duplicate windows or report this as a window-identity bug."
+      });
+    }
+    return automationOk(matches[0]);
+  }
+  const eligible = entries.filter((entry) => entry.target.eligible);
+  if (eligible.length === 0) {
+    return automationError("NO_ELIGIBLE_TARGETS", "No Wood-bridged renderer targets found.", {
+      details: { discovered: entries.length },
+      requiredAction: "Only pages exposing the Wood bridge are automatable; check the app booted correctly."
+    });
+  }
+  if (eligible.length > 1) {
+    return automationError(
+      "TARGET_AMBIGUOUS",
+      `${eligible.length} eligible Wood windows found; an explicit target is required.`,
+      {
+        details: { candidates: eligible.map((entry) => entry.target.windowId) },
+        requiredAction: 'Pass --window <windowId> (see "axe targets").'
+      }
+    );
+  }
+  return automationOk(eligible[0]);
+}
+export {
+  WOOD_INTERNAL_BRIDGE_KEY,
+  discoverTargets,
+  selectTarget
+};
+//# sourceMappingURL=target_registry.js.map

package/dist/automation/target_registry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/automation/target_registry.ts"],"sourcesContent":["/**\n * Target discovery and deterministic selection (AXE-WP-01, AXE-002).\n *\n * Selection rules:\n * - pages without a Wood bridge are ineligible by default;\n * - an explicit windowId must match exactly one target;\n * - without a windowId, exactly one eligible target must exist —\n *   multiple eligible windows are an explicit ambiguity error, never\n *   a silent \"first page wins\".\n */\n\nimport type { Browser, Page } from 'playwright';\nimport { automationError, automationOk, type WoodAutomationResult } from './errors.js';\nimport { formatRoute, readAutomationSnapshot } from './introspection_reader.js';\nimport type { WoodLiveTarget } from './target_identity.js';\n\nexport const WOOD_INTERNAL_BRIDGE_KEY = '__NOEGO_WOOD_BRIDGE__';\n\nexport interface WoodTargetEntry {\n  target: WoodLiveTarget;\n  page: Page;\n}\n\ninterface BridgeWindowInfo {\n  windowId: string | null;\n  defaultRoute: string | null;\n  present: boolean;\n}\n\nasync function readBridgeWindow(page: Page): Promise<BridgeWindowInfo> {\n  try {\n    const current = await page.evaluate(async (bridgeKey) => {\n      const bridge = (globalThis as Record<string, unknown>)[bridgeKey];\n      if (!bridge || typeof bridge !== 'object') {\n        return null;\n      }\n      const windowApi = (bridge as { __window?: { current?: () => Promise<unknown> } }).__window;\n      if (!windowApi || typeof windowApi.current !== 'function') {\n        return null;\n      }\n      return (await windowApi.current()) as { ok?: boolean; windowId?: string; defaultRoute?: string };\n    }, WOOD_INTERNAL_BRIDGE_KEY);\n\n    if (!current) {\n      return { windowId: null, defaultRoute: null, present: false };\n    }\n    return {\n      windowId: current.ok ? current.windowId ?? null : null,\n      defaultRoute: current.ok ? current.defaultRoute ?? null : null,\n      present: true,\n    };\n  } catch {\n    return { windowId: null, defaultRoute: null, present: false };\n  }\n}\n\nasync function readCdpIdentity(\n  page: Page,\n): Promise<{ targetId: string | null; browserContextId: string | undefined }> {\n  try {\n    const session = await page.context().newCDPSession(page);\n    try {\n      const info = await session.send('Target.getTargetInfo');\n      return {\n        targetId: info.targetInfo.targetId,\n        browserContextId: info.targetInfo.browserContextId,\n      };\n    } finally {\n      await session.detach().catch(() => undefined);\n    }\n  } catch {\n    return { targetId: null, browserContextId: undefined };\n  }\n}\n\n/**\n * Enumerate all renderer pages with Wood identity attached.\n * `pageGeneration` starts at 1 per discovery; persistent generation tracking\n * arrives with scenario mode (AXE-WP-04).\n */\nexport async function discoverTargets(browser: Browser): Promise<WoodTargetEntry[]> {\n  const entries: WoodTargetEntry[] = [];\n  let fallbackIndex = 0;\n\n  for (const context of browser.contexts()) {\n    for (const page of context.pages()) {\n      const [bridge, identity, snapshot] = await Promise.all([\n        readBridgeWindow(page),\n        readCdpIdentity(page),\n        readAutomationSnapshot(page),\n      ]);\n      const title = await page.title().catch(() => '');\n\n      entries.push({\n        page,\n        target: {\n          targetId: identity.targetId ?? `unstable:page-${fallbackIndex}`,\n          windowId: snapshot?.windowId ?? bridge.windowId,\n          browserContextId: identity.browserContextId,\n          pageGeneration: 1,\n          url: page.url(),\n          title,\n          currentRoute: formatRoute(snapshot?.currentRoute ?? null),\n          configuredDefaultRoute: bridge.defaultRoute ?? undefined,\n          woodBridgePresent: bridge.present,\n          eligible: bridge.present,\n        },\n      });\n      fallbackIndex += 1;\n    }\n  }\n\n  return entries;\n}\n\n/**\n * Deterministic target selection (pure; unit-tested without a browser).\n */\nexport function selectTarget(\n  entries: WoodTargetEntry[],\n  requestedWindowId?: string | null,\n): WoodAutomationResult<WoodTargetEntry> {\n  if (entries.length === 0) {\n    return automationError('NO_ELIGIBLE_TARGETS', 'No renderer targets found in the running Wood app.', {\n      requiredAction: 'Verify the app is running under \"wood dev\" and has at least one window.',\n    });\n  }\n\n  if (requestedWindowId) {\n    const matches = entries.filter((entry) => entry.target.windowId === requestedWindowId);\n    if (matches.length === 0) {\n      return automationError('TARGET_NOT_FOUND', `No Wood window target found for \"${requestedWindowId}\".`, {\n        details: { candidates: entries.map((entry) => entry.target.windowId).filter(Boolean) },\n        requiredAction: 'Run \"axe targets\" and pass an existing windowId via --window.',\n      });\n    }\n    if (matches.length > 1) {\n      return automationError('TARGET_AMBIGUOUS', `Multiple targets match windowId \"${requestedWindowId}\".`, {\n        details: { matchCount: matches.length },\n        requiredAction: 'Close duplicate windows or report this as a window-identity bug.',\n      });\n    }\n    return automationOk(matches[0]);\n  }\n\n  const eligible = entries.filter((entry) => entry.target.eligible);\n  if (eligible.length === 0) {\n    return automationError('NO_ELIGIBLE_TARGETS', 'No Wood-bridged renderer targets found.', {\n      details: { discovered: entries.length },\n      requiredAction: 'Only pages exposing the Wood bridge are automatable; check the app booted correctly.',\n    });\n  }\n  if (eligible.length > 1) {\n    return automationError(\n      'TARGET_AMBIGUOUS',\n      `${eligible.length} eligible Wood windows found; an explicit target is required.`,\n      {\n        details: { candidates: eligible.map((entry) => entry.target.windowId) },\n        requiredAction: 'Pass --window <windowId> (see \"axe targets\").',\n      },\n    );\n  }\n\n  return automationOk(eligible[0]);\n}\n"],"mappings":"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","names":[]}

package/dist/automation/waits.cjs

@@ -0,0 +1,17 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var waits_exports = {};
+module.exports = __toCommonJS(waits_exports);
+//# sourceMappingURL=waits.cjs.map

package/dist/automation/waits.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/automation/waits.ts"],"sourcesContent":["/**\n * Wait and stability contract (frozen — Axe.md \"Wait and stability model\").\n * Type surface only in WP-00/01; execution lands in AXE-WP-03.\n */\n\nimport type { WoodLocator } from './locator.cjs';\nimport type { WoodScrollContainer } from './scrolling.cjs';\n\nexport type WoodWaitCondition =\n  | { kind: 'route'; page: string; params?: Record<string, string>; query?: Record<string, string> }\n  | { kind: 'url'; value: string; match?: 'exact' | 'glob' | 'regex' }\n  | { kind: 'target'; windowId: string; state: 'present' | 'active' | 'closed' }\n  | { kind: 'visible' | 'hidden' | 'attached' | 'detached' | 'enabled'; target: WoodLocator }\n  | { kind: 'trace'; type: string; source?: string; count?: number }\n  | { kind: 'scroll_edge'; container: WoodScrollContainer; edge: 'top' | 'bottom' | 'left' | 'right' }\n  | { kind: 'visual_stable'; target?: WoodLocator; frames?: number }\n  | { kind: 'app_idle' };\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/automation/waits.d.cts

@@ -0,0 +1,44 @@
+import { WoodLocator } from './locator.cjs';
+import { WoodScrollContainer } from './scrolling.cjs';
+import 'playwright';
+import './errors.cjs';
+
+/**
+ * Wait and stability contract (frozen — Axe.md "Wait and stability model").
+ * Type surface only in WP-00/01; execution lands in AXE-WP-03.
+ */
+
+type WoodWaitCondition = {
+    kind: 'route';
+    page: string;
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+} | {
+    kind: 'url';
+    value: string;
+    match?: 'exact' | 'glob' | 'regex';
+} | {
+    kind: 'target';
+    windowId: string;
+    state: 'present' | 'active' | 'closed';
+} | {
+    kind: 'visible' | 'hidden' | 'attached' | 'detached' | 'enabled';
+    target: WoodLocator;
+} | {
+    kind: 'trace';
+    type: string;
+    source?: string;
+    count?: number;
+} | {
+    kind: 'scroll_edge';
+    container: WoodScrollContainer;
+    edge: 'top' | 'bottom' | 'left' | 'right';
+} | {
+    kind: 'visual_stable';
+    target?: WoodLocator;
+    frames?: number;
+} | {
+    kind: 'app_idle';
+};
+
+export type { WoodWaitCondition };

package/dist/automation/waits.d.ts

@@ -0,0 +1,44 @@
+import { WoodLocator } from './locator.js';
+import { WoodScrollContainer } from './scrolling.js';
+import 'playwright';
+import './errors.js';
+
+/**
+ * Wait and stability contract (frozen — Axe.md "Wait and stability model").
+ * Type surface only in WP-00/01; execution lands in AXE-WP-03.
+ */
+
+type WoodWaitCondition = {
+    kind: 'route';
+    page: string;
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+} | {
+    kind: 'url';
+    value: string;
+    match?: 'exact' | 'glob' | 'regex';
+} | {
+    kind: 'target';
+    windowId: string;
+    state: 'present' | 'active' | 'closed';
+} | {
+    kind: 'visible' | 'hidden' | 'attached' | 'detached' | 'enabled';
+    target: WoodLocator;
+} | {
+    kind: 'trace';
+    type: string;
+    source?: string;
+    count?: number;
+} | {
+    kind: 'scroll_edge';
+    container: WoodScrollContainer;
+    edge: 'top' | 'bottom' | 'left' | 'right';
+} | {
+    kind: 'visual_stable';
+    target?: WoodLocator;
+    frames?: number;
+} | {
+    kind: 'app_idle';
+};
+
+export type { WoodWaitCondition };

package/dist/automation/waits.js

@@ -0,0 +1 @@
+//# sourceMappingURL=waits.js.map

package/dist/automation/waits.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/automation/waits_executor.cjs

@@ -0,0 +1,104 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var waits_executor_exports = {};
+__export(waits_executor_exports, {
+  awaitCondition: () => awaitCondition,
+  matchesUrl: () => matchesUrl
+});
+module.exports = __toCommonJS(waits_executor_exports);
+var import_errors = require("./errors.cjs");
+var import_introspection_reader = require("./introspection_reader.cjs");
+var import_locator = require("./locator.cjs");
+const DEFAULT_TIMEOUT_MS = 5e3;
+function matchesUrl(actual, expected, match = "exact") {
+  if (match === "exact") return actual === expected;
+  if (match === "regex") {
+    try {
+      return new RegExp(expected).test(actual);
+    } catch {
+      return false;
+    }
+  }
+  const escaped = expected.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  return new RegExp(`^${escaped}$`).test(actual);
+}
+async function awaitCondition(page, condition, options) {
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const started = Date.now();
+  let lastObserved = null;
+  if (condition.kind === "trace" || condition.kind === "target") {
+    return (0, import_errors.automationError)("UNSUPPORTED", `${condition.kind} waits require an unavailable ${condition.kind} observation capability.`, { details: { capability: condition.kind, lastObserved } });
+  }
+  try {
+    if (condition.kind === "visible" || condition.kind === "hidden" || condition.kind === "attached" || condition.kind === "detached") {
+      await (0, import_locator.toPlaywrightLocator)(page, condition.target).waitFor({ state: condition.kind, timeout: timeoutMs });
+    } else if (condition.kind === "enabled") {
+      const locator = (0, import_locator.toPlaywrightLocator)(page, condition.target);
+      await locator.waitFor({ state: "visible", timeout: timeoutMs });
+      await page.waitForFunction((element) => !element.disabled && element.getAttribute("aria-disabled") !== "true", await locator.elementHandle(), { timeout: timeoutMs });
+    } else if (condition.kind === "app_idle") {
+      lastObserved = await (0, import_introspection_reader.readAutomationSnapshot)(page);
+      if (!await (0, import_introspection_reader.waitForRendererIdle)(page, { timeoutMs })) throw new Error("Renderer did not become idle.");
+    } else if (condition.kind === "url") {
+      while (!matchesUrl(lastObserved = page.url(), condition.value, condition.match)) {
+        if (Date.now() - started >= timeoutMs) throw new Error("URL did not match.");
+        await page.waitForTimeout(25);
+      }
+    } else if (condition.kind === "route") {
+      while (true) {
+        const snapshot = await (0, import_introspection_reader.readAutomationSnapshot)(page);
+        lastObserved = snapshot?.currentRoute ?? null;
+        const route = snapshot?.currentRoute;
+        const includes = (wanted, actual) => !wanted || Object.entries(wanted).every(([key, value]) => actual[key] === value);
+        if (route?.page === condition.page && includes(condition.params, route.params) && includes(condition.query, route.query)) break;
+        if (Date.now() - started >= timeoutMs) throw new Error("Route did not match.");
+        await page.waitForTimeout(25);
+      }
+    } else if (condition.kind === "scroll_edge") {
+      const locator = condition.container.kind === "locator" ? (0, import_locator.toPlaywrightLocator)(page, condition.container.target) : null;
+      await page.waitForFunction(({ element, edge }) => {
+        const node = element ?? document.scrollingElement ?? document.documentElement;
+        return edge === "top" ? node.scrollTop <= 0 : edge === "bottom" ? node.scrollTop + node.clientHeight >= node.scrollHeight - 1 : edge === "left" ? node.scrollLeft <= 0 : node.scrollLeft + node.clientWidth >= node.scrollWidth - 1;
+      }, { element: locator ? await locator.elementHandle() : null, edge: condition.edge }, { timeout: timeoutMs });
+    } else {
+      const locator = condition.target ? (0, import_locator.toPlaywrightLocator)(page, condition.target) : null;
+      lastObserved = await page.evaluate(async ({ element, frames }) => {
+        const target = element;
+        let previous = target?.getBoundingClientRect() ?? { x: 0, y: 0, width: innerWidth, height: innerHeight };
+        let stable = 0;
+        while (stable < frames) {
+          await new Promise((resolve) => requestAnimationFrame(() => resolve()));
+          const next = target?.getBoundingClientRect() ?? { x: 0, y: 0, width: innerWidth, height: innerHeight };
+          stable = next.x === previous.x && next.y === previous.y && next.width === previous.width && next.height === previous.height ? stable + 1 : 0;
+          previous = next;
+        }
+        return { x: previous.x, y: previous.y, width: previous.width, height: previous.height, stableFrames: stable };
+      }, { element: locator ? await locator.elementHandle() : null, frames: condition.kind === "visual_stable" ? condition.frames ?? 3 : 3 });
+    }
+    return (0, import_errors.automationOk)({ waitedMs: Date.now() - started });
+  } catch (error) {
+    return (0, import_errors.automationError)("ACTION_FAILED", `Timed out waiting for ${condition.kind} after ${timeoutMs}ms.`, { details: { timeoutMs, lastObserved, cause: error instanceof Error ? error.message : String(error) } });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  awaitCondition,
+  matchesUrl
+});
+//# sourceMappingURL=waits_executor.cjs.map

package/dist/automation/waits_executor.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/automation/waits_executor.ts"],"sourcesContent":["import type { Page } from 'playwright';\nimport { automationError, automationOk, type WoodAutomationResult } from './errors.cjs';\nimport { readAutomationSnapshot, waitForRendererIdle } from './introspection_reader.cjs';\nimport { toPlaywrightLocator } from './locator.cjs';\nimport type { WoodWaitCondition } from './waits.cjs';\n\nconst DEFAULT_TIMEOUT_MS = 5_000;\n\nexport function matchesUrl(actual: string, expected: string, match: 'exact' | 'glob' | 'regex' = 'exact'): boolean {\n  if (match === 'exact') return actual === expected;\n  if (match === 'regex') {\n    try { return new RegExp(expected).test(actual); } catch { return false; }\n  }\n  const escaped = expected.replace(/[.+^${}()|[\\]\\\\]/g, '\\\\$&').replace(/\\*/g, '.*').replace(/\\?/g, '.');\n  return new RegExp(`^${escaped}$`).test(actual);\n}\n\nexport async function awaitCondition(page: Page, condition: WoodWaitCondition, options?: { timeoutMs?: number }): Promise<WoodAutomationResult<{ waitedMs: number }>> {\n  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const started = Date.now();\n  let lastObserved: unknown = null;\n  if (condition.kind === 'trace' || condition.kind === 'target') {\n    return automationError('UNSUPPORTED', `${condition.kind} waits require an unavailable ${condition.kind} observation capability.`, { details: { capability: condition.kind, lastObserved } });\n  }\n  try {\n    if (condition.kind === 'visible' || condition.kind === 'hidden' || condition.kind === 'attached' || condition.kind === 'detached') {\n      await toPlaywrightLocator(page, condition.target).waitFor({ state: condition.kind, timeout: timeoutMs });\n    } else if (condition.kind === 'enabled') {\n      const locator = toPlaywrightLocator(page, condition.target);\n      await locator.waitFor({ state: 'visible', timeout: timeoutMs });\n      await page.waitForFunction((element) => !(element as HTMLInputElement).disabled && element.getAttribute('aria-disabled') !== 'true', await locator.elementHandle(), { timeout: timeoutMs });\n    } else if (condition.kind === 'app_idle') {\n      lastObserved = await readAutomationSnapshot(page);\n      if (!(await waitForRendererIdle(page, { timeoutMs }))) throw new Error('Renderer did not become idle.');\n    } else if (condition.kind === 'url') {\n      while (!matchesUrl(lastObserved = page.url(), condition.value, condition.match)) {\n        if (Date.now() - started >= timeoutMs) throw new Error('URL did not match.');\n        await page.waitForTimeout(25);\n      }\n    } else if (condition.kind === 'route') {\n      while (true) {\n        const snapshot = await readAutomationSnapshot(page);\n        lastObserved = snapshot?.currentRoute ?? null;\n        const route = snapshot?.currentRoute;\n        const includes = (wanted: Record<string, string> | undefined, actual: Record<string, string>) =>\n          !wanted || Object.entries(wanted).every(([key, value]) => actual[key] === value);\n        if (route?.page === condition.page && includes(condition.params, route.params) && includes(condition.query, route.query)) break;\n        if (Date.now() - started >= timeoutMs) throw new Error('Route did not match.');\n        await page.waitForTimeout(25);\n      }\n    } else if (condition.kind === 'scroll_edge') {\n      const locator = condition.container.kind === 'locator' ? toPlaywrightLocator(page, condition.container.target) : null;\n      await page.waitForFunction(({ element, edge }) => {\n        const node = (element as HTMLElement | null) ?? document.scrollingElement ?? document.documentElement;\n        return edge === 'top' ? node.scrollTop <= 0 : edge === 'bottom' ? node.scrollTop + node.clientHeight >= node.scrollHeight - 1 : edge === 'left' ? node.scrollLeft <= 0 : node.scrollLeft + node.clientWidth >= node.scrollWidth - 1;\n      }, { element: locator ? await locator.elementHandle() : null, edge: condition.edge }, { timeout: timeoutMs });\n    } else {\n      const locator = condition.target ? toPlaywrightLocator(page, condition.target) : null;\n      lastObserved = await page.evaluate(async ({ element, frames }) => {\n        const target = element as Element | null;\n        let previous = target?.getBoundingClientRect() ?? { x: 0, y: 0, width: innerWidth, height: innerHeight };\n        let stable = 0;\n        while (stable < frames) {\n          await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));\n          const next = target?.getBoundingClientRect() ?? { x: 0, y: 0, width: innerWidth, height: innerHeight };\n          stable = next.x === previous.x && next.y === previous.y && next.width === previous.width && next.height === previous.height ? stable + 1 : 0;\n          previous = next;\n        }\n        return { x: previous.x, y: previous.y, width: previous.width, height: previous.height, stableFrames: stable };\n      }, { element: locator ? await locator.elementHandle() : null, frames: condition.kind === 'visual_stable' ? condition.frames ?? 3 : 3 });\n    }\n    return automationOk({ waitedMs: Date.now() - started });\n  } catch (error) {\n    return automationError('ACTION_FAILED', `Timed out waiting for ${condition.kind} after ${timeoutMs}ms.`, { details: { timeoutMs, lastObserved, cause: error instanceof Error ? error.message : String(error) } });\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/automation/waits_executor.d.cts

@@ -0,0 +1,14 @@
+import { Page } from 'playwright';
+import { WoodAutomationResult } from './errors.cjs';
+import { WoodWaitCondition } from './waits.cjs';
+import './locator.cjs';
+import './scrolling.cjs';
+
+declare function matchesUrl(actual: string, expected: string, match?: 'exact' | 'glob' | 'regex'): boolean;
+declare function awaitCondition(page: Page, condition: WoodWaitCondition, options?: {
+    timeoutMs?: number;
+}): Promise<WoodAutomationResult<{
+    waitedMs: number;
+}>>;
+
+export { awaitCondition, matchesUrl };

package/dist/automation/waits_executor.d.ts

@@ -0,0 +1,14 @@
+import { Page } from 'playwright';
+import { WoodAutomationResult } from './errors.js';
+import { WoodWaitCondition } from './waits.js';
+import './locator.js';
+import './scrolling.js';
+
+declare function matchesUrl(actual: string, expected: string, match?: 'exact' | 'glob' | 'regex'): boolean;
+declare function awaitCondition(page: Page, condition: WoodWaitCondition, options?: {
+    timeoutMs?: number;
+}): Promise<WoodAutomationResult<{
+    waitedMs: number;
+}>>;
+
+export { awaitCondition, matchesUrl };