@reticular/speakable 1.6.0 → 1.8.0

package/dist/harness/index.d.ts

@@ -0,0 +1,57 @@
+import { I as InteractionSequence, a as AnalysisResult, A as AccessibilityTimeline } from '../types-Blh0EnZF.js';
+
+/**
+ * Shared message protocol for the iframe harness.
+ *
+ * The parent-page controller and the in-iframe agent exchange these
+ * request/response envelopes over `postMessage`. Every request carries a
+ * unique `id` so responses can be correlated.
+ */
+
+/** Serializable subset of CaptureOptions safe to send over postMessage. */
+interface SerializableCaptureOptions {
+    componentName: string;
+    storyName?: string;
+    sequence: InteractionSequence;
+    settlePeriod?: number;
+    awaitUpgrade?: boolean;
+    upgradeTimeoutMs?: number;
+}
+
+/**
+ * Iframe harness — parent-page controller.
+ *
+ * Runs in a parent page, mounts a component (URL or HTML string) into an
+ * iframe, injects the browser bundle, and drives analysis/capture over
+ * `postMessage`. This is the Storybook-independent runtime testing surface.
+ */
+
+interface HarnessOptions {
+    /** An existing iframe to drive, or a container to create one inside. */
+    target: HTMLIFrameElement | {
+        container: HTMLElement;
+    };
+    /** Load + inject + request timeout in ms (default: 10000). */
+    timeoutMs?: number;
+    /** Origins allowed for postMessage. Defaults to same-origin only. */
+    allowedOrigins?: string[];
+    /**
+     * URL to the injectable IIFE bundle. When omitted, the harness assumes the
+     * bundle is already present in the iframe (e.g. bundled into the page).
+     */
+    bundleUrl?: string;
+}
+type LoadSource = {
+    url: string;
+} | {
+    html: string;
+};
+interface Harness {
+    load(source: LoadSource): Promise<void>;
+    analyze(selector?: string): Promise<AnalysisResult>;
+    captureTimeline(options: SerializableCaptureOptions): Promise<AccessibilityTimeline>;
+    destroy(): void;
+}
+declare function createHarness(options: HarnessOptions): Harness;
+
+export { type Harness, type HarnessOptions, type LoadSource, type SerializableCaptureOptions, createHarness };

package/dist/harness/index.js

@@ -0,0 +1,176 @@
+// src/harness/protocol.ts
+var HARNESS_CHANNEL = "speakable-harness";
+function isHarnessResponse(data) {
+  if (!data || typeof data !== "object") return false;
+  const d = data;
+  return d.channel === HARNESS_CHANNEL && typeof d.id === "string" && typeof d.ok === "boolean";
+}
+function isHarnessReady(data) {
+  if (!data || typeof data !== "object") return false;
+  const d = data;
+  return d.channel === HARNESS_CHANNEL && d.kind === "ready";
+}
+
+// src/harness/index.ts
+var DEFAULT_TIMEOUT = 1e4;
+var idCounter = 0;
+function nextId() {
+  idCounter += 1;
+  return `req-${Date.now()}-${idCounter}`;
+}
+function isCrossOrigin(url) {
+  try {
+    const resolved = new URL(url, window.location.href);
+    return resolved.origin !== window.location.origin;
+  } catch {
+    return false;
+  }
+}
+function createHarness(options) {
+  const { timeoutMs = DEFAULT_TIMEOUT, allowedOrigins, bundleUrl } = options;
+  let ownsIframe = false;
+  let iframe;
+  if (options.target instanceof HTMLIFrameElement) {
+    iframe = options.target;
+  } else {
+    iframe = document.createElement("iframe");
+    iframe.setAttribute("title", "speakable-harness");
+    options.target.container.appendChild(iframe);
+    ownsIframe = true;
+  }
+  const pending = /* @__PURE__ */ new Map();
+  function onMessage(event) {
+    if (event.source !== iframe.contentWindow) return;
+    if (allowedOrigins && allowedOrigins.length > 0 && !allowedOrigins.includes("*")) {
+      if (!allowedOrigins.includes(event.origin)) return;
+    }
+    const data = event.data;
+    if (!isHarnessResponse(data)) return;
+    const entry = pending.get(data.id);
+    if (!entry) return;
+    clearTimeout(entry.timer);
+    pending.delete(data.id);
+    entry.resolve(data);
+  }
+  window.addEventListener("message", onMessage);
+  function targetOrigin() {
+    if (allowedOrigins && allowedOrigins.includes("*")) return "*";
+    try {
+      return iframe.contentWindow ? new URL(iframe.src || window.location.href).origin : "*";
+    } catch {
+      return "*";
+    }
+  }
+  function request(payload) {
+    const id = nextId();
+    const win = iframe.contentWindow;
+    if (!win) {
+      return Promise.reject(new Error("Harness iframe has no content window; call load() first."));
+    }
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error(`Harness request "${payload.kind}" timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      pending.set(id, { resolve, reject, timer });
+      win.postMessage({ channel: HARNESS_CHANNEL, id, ...payload }, targetOrigin());
+    });
+  }
+  function waitForReady() {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        window.removeEventListener("message", onReady);
+        reject(new Error(`Harness bundle did not signal ready within ${timeoutMs}ms`));
+      }, timeoutMs);
+      function onReady(event) {
+        if (event.source !== iframe.contentWindow) return;
+        if (!isHarnessReady(event.data)) return;
+        clearTimeout(timer);
+        window.removeEventListener("message", onReady);
+        resolve();
+      }
+      window.addEventListener("message", onReady);
+    });
+  }
+  function waitForLoad() {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        iframe.removeEventListener("load", onLoad);
+        reject(new Error(`Harness iframe failed to load within ${timeoutMs}ms`));
+      }, timeoutMs);
+      function onLoad() {
+        clearTimeout(timer);
+        iframe.removeEventListener("load", onLoad);
+        resolve();
+      }
+      iframe.addEventListener("load", onLoad);
+    });
+  }
+  function injectBundle() {
+    const doc = iframe.contentDocument;
+    if (!doc) {
+      throw new Error(
+        "Cannot access iframe document for bundle injection. Cross-origin content is not supported; use { html } (srcdoc) or a same-origin URL."
+      );
+    }
+    const script = doc.createElement("script");
+    if (bundleUrl) {
+      script.src = bundleUrl;
+    } else {
+      const injected = iframe.contentWindow?.__SPEAKABLE__;
+      if (!injected) {
+        throw new Error(
+          "No bundleUrl provided and the iframe does not already include the Speakable bundle. Pass options.bundleUrl."
+        );
+      }
+      return;
+    }
+    doc.head?.appendChild(script) ?? doc.documentElement.appendChild(script);
+  }
+  return {
+    async load(source) {
+      if ("url" in source && isCrossOrigin(source.url)) {
+        throw new Error(
+          `Cannot inject into cross-origin URL "${source.url}". Use { html } (srcdoc) or a same-origin URL.`
+        );
+      }
+      const loaded = waitForLoad();
+      if ("url" in source) {
+        iframe.src = source.url;
+      } else {
+        iframe.srcdoc = source.html;
+      }
+      await loaded;
+      const ready = waitForReady();
+      injectBundle();
+      const alreadyPresent = iframe.contentWindow?.__SPEAKABLE__;
+      if (alreadyPresent) return;
+      await ready;
+    },
+    async analyze(selector) {
+      const res = await request({ kind: "analyze", ...selector && { selector } });
+      if (res.ok && res.kind === "analyze") return res.result;
+      throw new Error(res.ok ? "Unexpected response kind" : res.error);
+    },
+    async captureTimeline(opts) {
+      const res = await request({ kind: "capture", options: opts });
+      if (res.ok && res.kind === "capture") return res.result;
+      throw new Error(res.ok ? "Unexpected response kind" : res.error);
+    },
+    destroy() {
+      window.removeEventListener("message", onMessage);
+      for (const [, entry] of pending) {
+        clearTimeout(entry.timer);
+        entry.reject(new Error("Harness destroyed"));
+      }
+      pending.clear();
+      if (ownsIframe && iframe.parentNode) {
+        iframe.parentNode.removeChild(iframe);
+      }
+    }
+  };
+}
+export {
+  createHarness
+};
+//# sourceMappingURL=index.js.map

package/dist/harness/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/harness/protocol.ts","../../src/harness/index.ts"],"sourcesContent":["/**\n * Shared message protocol for the iframe harness.\n *\n * The parent-page controller and the in-iframe agent exchange these\n * request/response envelopes over `postMessage`. Every request carries a\n * unique `id` so responses can be correlated.\n */\n\nimport type { AnalysisResult } from '../browser/analyze.js';\nimport type { AccessibilityTimeline, InteractionSequence } from '../runtime/types.js';\n\n/** Namespace tag stamped on every harness message to avoid collisions. */\nexport const HARNESS_CHANNEL = 'speakable-harness';\n\n/** Serializable subset of CaptureOptions safe to send over postMessage. */\nexport interface SerializableCaptureOptions {\n  componentName: string;\n  storyName?: string;\n  sequence: InteractionSequence;\n  settlePeriod?: number;\n  awaitUpgrade?: boolean;\n  upgradeTimeoutMs?: number;\n}\n\nexport type HarnessRequest =\n  | { channel: typeof HARNESS_CHANNEL; id: string; kind: 'analyze'; selector?: string }\n  | { channel: typeof HARNESS_CHANNEL; id: string; kind: 'capture'; options: SerializableCaptureOptions };\n\nexport type HarnessResponse =\n  | { channel: typeof HARNESS_CHANNEL; id: string; ok: true; kind: 'analyze'; result: AnalysisResult }\n  | { channel: typeof HARNESS_CHANNEL; id: string; ok: true; kind: 'capture'; result: AccessibilityTimeline }\n  | { channel: typeof HARNESS_CHANNEL; id: string; ok: false; error: string };\n\n/** Sent by the agent once it has installed its message listener. */\nexport interface HarnessReadyMessage {\n  channel: typeof HARNESS_CHANNEL;\n  kind: 'ready';\n}\n\nexport function isHarnessRequest(data: unknown): data is HarnessRequest {\n  if (!data || typeof data !== 'object') return false;\n  const d = data as Record<string, unknown>;\n  return d.channel === HARNESS_CHANNEL && typeof d.id === 'string' &&\n    (d.kind === 'analyze' || d.kind === 'capture');\n}\n\nexport function isHarnessResponse(data: unknown): data is HarnessResponse {\n  if (!data || typeof data !== 'object') return false;\n  const d = data as Record<string, unknown>;\n  return d.channel === HARNESS_CHANNEL && typeof d.id === 'string' && typeof d.ok === 'boolean';\n}\n\nexport function isHarnessReady(data: unknown): data is HarnessReadyMessage {\n  if (!data || typeof data !== 'object') return false;\n  const d = data as Record<string, unknown>;\n  return d.channel === HARNESS_CHANNEL && d.kind === 'ready';\n}\n","/**\n * Iframe harness — parent-page controller.\n *\n * Runs in a parent page, mounts a component (URL or HTML string) into an\n * iframe, injects the browser bundle, and drives analysis/capture over\n * `postMessage`. This is the Storybook-independent runtime testing surface.\n */\n\nimport type { AnalysisResult } from '../browser/analyze.js';\nimport type { AccessibilityTimeline } from '../runtime/types.js';\nimport {\n  HARNESS_CHANNEL,\n  isHarnessReady,\n  isHarnessResponse,\n  type HarnessResponse,\n  type SerializableCaptureOptions,\n} from './protocol.js';\n\nexport interface HarnessOptions {\n  /** An existing iframe to drive, or a container to create one inside. */\n  target: HTMLIFrameElement | { container: HTMLElement };\n  /** Load + inject + request timeout in ms (default: 10000). */\n  timeoutMs?: number;\n  /** Origins allowed for postMessage. Defaults to same-origin only. */\n  allowedOrigins?: string[];\n  /**\n   * URL to the injectable IIFE bundle. When omitted, the harness assumes the\n   * bundle is already present in the iframe (e.g. bundled into the page).\n   */\n  bundleUrl?: string;\n}\n\nexport type LoadSource = { url: string } | { html: string };\n\nexport interface Harness {\n  load(source: LoadSource): Promise<void>;\n  analyze(selector?: string): Promise<AnalysisResult>;\n  captureTimeline(options: SerializableCaptureOptions): Promise<AccessibilityTimeline>;\n  destroy(): void;\n}\n\nconst DEFAULT_TIMEOUT = 10000;\n\nlet idCounter = 0;\nfunction nextId(): string {\n  idCounter += 1;\n  return `req-${Date.now()}-${idCounter}`;\n}\n\nfunction isCrossOrigin(url: string): boolean {\n  try {\n    const resolved = new URL(url, window.location.href);\n    return resolved.origin !== window.location.origin;\n  } catch {\n    // Relative or malformed — treat as same-origin.\n    return false;\n  }\n}\n\nexport function createHarness(options: HarnessOptions): Harness {\n  const { timeoutMs = DEFAULT_TIMEOUT, allowedOrigins, bundleUrl } = options;\n\n  // Resolve or create the iframe.\n  let ownsIframe = false;\n  let iframe: HTMLIFrameElement;\n  if (options.target instanceof HTMLIFrameElement) {\n    iframe = options.target;\n  } else {\n    iframe = document.createElement('iframe');\n    iframe.setAttribute('title', 'speakable-harness');\n    options.target.container.appendChild(iframe);\n    ownsIframe = true;\n  }\n\n  const pending = new Map<\n    string,\n    { resolve: (r: HarnessResponse) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }\n  >();\n\n  function onMessage(event: MessageEvent) {\n    // Only accept messages originating from our iframe's window.\n    if (event.source !== iframe.contentWindow) return;\n    if (allowedOrigins && allowedOrigins.length > 0 && !allowedOrigins.includes('*')) {\n      if (!allowedOrigins.includes(event.origin)) return;\n    }\n    const data = event.data;\n    if (!isHarnessResponse(data)) return;\n    const entry = pending.get(data.id);\n    if (!entry) return;\n    clearTimeout(entry.timer);\n    pending.delete(data.id);\n    entry.resolve(data);\n  }\n\n  window.addEventListener('message', onMessage);\n\n  function targetOrigin(): string {\n    if (allowedOrigins && allowedOrigins.includes('*')) return '*';\n    try {\n      return iframe.contentWindow ? new URL(iframe.src || window.location.href).origin : '*';\n    } catch {\n      return '*';\n    }\n  }\n\n  function request(payload: Record<string, unknown>): Promise<HarnessResponse> {\n    const id = nextId();\n    const win = iframe.contentWindow;\n    if (!win) {\n      return Promise.reject(new Error('Harness iframe has no content window; call load() first.'));\n    }\n    return new Promise<HarnessResponse>((resolve, reject) => {\n      const timer = setTimeout(() => {\n        pending.delete(id);\n        reject(new Error(`Harness request \"${payload.kind}\" timed out after ${timeoutMs}ms`));\n      }, timeoutMs);\n      pending.set(id, { resolve, reject, timer });\n      win.postMessage({ channel: HARNESS_CHANNEL, id, ...payload }, targetOrigin());\n    });\n  }\n\n  function waitForReady(): Promise<void> {\n    return new Promise<void>((resolve, reject) => {\n      const timer = setTimeout(() => {\n        window.removeEventListener('message', onReady);\n        reject(new Error(`Harness bundle did not signal ready within ${timeoutMs}ms`));\n      }, timeoutMs);\n      function onReady(event: MessageEvent) {\n        if (event.source !== iframe.contentWindow) return;\n        if (!isHarnessReady(event.data)) return;\n        clearTimeout(timer);\n        window.removeEventListener('message', onReady);\n        resolve();\n      }\n      window.addEventListener('message', onReady);\n    });\n  }\n\n  function waitForLoad(): Promise<void> {\n    return new Promise<void>((resolve, reject) => {\n      const timer = setTimeout(() => {\n        iframe.removeEventListener('load', onLoad);\n        reject(new Error(`Harness iframe failed to load within ${timeoutMs}ms`));\n      }, timeoutMs);\n      function onLoad() {\n        clearTimeout(timer);\n        iframe.removeEventListener('load', onLoad);\n        resolve();\n      }\n      iframe.addEventListener('load', onLoad);\n    });\n  }\n\n  function injectBundle(): void {\n    const doc = iframe.contentDocument;\n    if (!doc) {\n      throw new Error(\n        'Cannot access iframe document for bundle injection. Cross-origin content is not supported; use { html } (srcdoc) or a same-origin URL.'\n      );\n    }\n    const script = doc.createElement('script');\n    if (bundleUrl) {\n      script.src = bundleUrl;\n    } else {\n      // No bundle URL provided and no bundle detected — surface a clear error\n      // rather than hanging on waitForReady.\n      const injected = (iframe.contentWindow as unknown as { __SPEAKABLE__?: unknown })?.__SPEAKABLE__;\n      if (!injected) {\n        throw new Error(\n          'No bundleUrl provided and the iframe does not already include the Speakable bundle. Pass options.bundleUrl.'\n        );\n      }\n      return;\n    }\n    doc.head?.appendChild(script) ?? doc.documentElement.appendChild(script);\n  }\n\n  return {\n    async load(source: LoadSource): Promise<void> {\n      // Validate before starting any timers so we don't leak a pending\n      // load-wait rejection when we bail out synchronously.\n      if ('url' in source && isCrossOrigin(source.url)) {\n        throw new Error(\n          `Cannot inject into cross-origin URL \"${source.url}\". Use { html } (srcdoc) or a same-origin URL.`\n        );\n      }\n\n      const loaded = waitForLoad();\n      if ('url' in source) {\n        iframe.src = source.url;\n      } else {\n        iframe.srcdoc = source.html;\n      }\n      await loaded;\n\n      const ready = waitForReady();\n      injectBundle();\n      // If the bundle was already present, it may have signaled ready before we\n      // attached the listener; fall back to a short probe.\n      const alreadyPresent = (iframe.contentWindow as unknown as { __SPEAKABLE__?: unknown })?.__SPEAKABLE__;\n      if (alreadyPresent) return;\n      await ready;\n    },\n\n    async analyze(selector?: string): Promise<AnalysisResult> {\n      const res = await request({ kind: 'analyze', ...(selector && { selector }) });\n      if (res.ok && res.kind === 'analyze') return res.result;\n      throw new Error(res.ok ? 'Unexpected response kind' : res.error);\n    },\n\n    async captureTimeline(opts: SerializableCaptureOptions): Promise<AccessibilityTimeline> {\n      const res = await request({ kind: 'capture', options: opts });\n      if (res.ok && res.kind === 'capture') return res.result;\n      throw new Error(res.ok ? 'Unexpected response kind' : res.error);\n    },\n\n    destroy(): void {\n      window.removeEventListener('message', onMessage);\n      for (const [, entry] of pending) {\n        clearTimeout(entry.timer);\n        entry.reject(new Error('Harness destroyed'));\n      }\n      pending.clear();\n      if (ownsIframe && iframe.parentNode) {\n        iframe.parentNode.removeChild(iframe);\n      }\n    },\n  };\n}\n\nexport type { SerializableCaptureOptions } from './protocol.js';\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -16,7 +16,7 @@ interface ModelVersion {
  * Accessible role following ARIA specification.
  * V1 supports common interactive and structural roles.
  */
-type AccessibleRole = 'button' | 'link' | 'heading' | 'textbox' | 'checkbox' | 'radio' | 'combobox' | 'listbox' | 'option' | 'list' | 'listitem' | 'article' | 'generic' | 'navigation' | 'main' | 'banner' | 'contentinfo' | 'region' | 'img' | 'complementary' | 'form' | 'search' | 'paragraph' | 'blockquote' | 'code' | 'staticText' | 'table' | 'row' | 'cell' | 'columnheader' | 'rowheader' | 'term' | 'definition' | 'figure' | 'caption' | 'group' | 'dialog' | 'meter' | 'progressbar' | 'status' | 'document' | 'application' | 'separator';
+type AccessibleRole = 'button' | 'link' | 'heading' | 'textbox' | 'checkbox' | 'radio' | 'combobox' | 'listbox' | 'option' | 'list' | 'listitem' | 'article' | 'generic' | 'navigation' | 'main' | 'banner' | 'contentinfo' | 'region' | 'img' | 'complementary' | 'form' | 'search' | 'paragraph' | 'blockquote' | 'code' | 'staticText' | 'table' | 'row' | 'cell' | 'columnheader' | 'rowheader' | 'term' | 'definition' | 'figure' | 'caption' | 'group' | 'dialog' | 'meter' | 'progressbar' | 'status' | 'switch' | 'slider' | 'spinbutton' | 'tab' | 'tablist' | 'tabpanel' | 'document' | 'application' | 'separator';
 /**
  * Accessible states and properties.
  * Only includes properties relevant to the element's role.

package/dist/index.js

@@ -48,6 +48,12 @@ var SUPPORTED_ROLES = [
   "meter",
   "progressbar",
   "status",
+  "switch",
+  "slider",
+  "spinbutton",
+  "tab",
+  "tablist",
+  "tabpanel",
   "document",
   "application",
   "separator"
@@ -968,8 +974,45 @@ function renderNodeVoiceOver(node, announcements, c) {
     renderNodeVoiceOver(child, announcements, c);
   }
 }
+function isValueFirstWidget(role) {
+  return role === "slider" || role === "spinbutton" || role === "combobox";
+}
+function isValueBeforeRoleWidget(role) {
+  return role === "progressbar" || role === "meter";
+}
+function isSilentContainerVoiceOver(node) {
+  if (node.role !== "list" && node.role !== "status") return false;
+  if (node.name) return false;
+  return node.children.length > 0;
+}
 function formatNodeVoiceOver(node, c) {
+  if (isSilentContainerVoiceOver(node)) {
+    return "";
+  }
   const parts = [];
+  const valueFirst = isValueFirstWidget(node.role) && node.value !== void 0;
+  if (valueFirst) {
+    const valueText = node.value.text || String(node.value.current);
+    if (valueText) parts.push(valueText);
+    if (node.name) parts.push(c.elementName(node.name));
+    const roleText = formatRoleVoiceOver(node);
+    if (roleText) parts.push(c.roleName(roleText));
+    const stateText2 = formatStatesVoiceOver(node);
+    if (stateText2) parts.push(c.stateName(stateText2));
+    if (node.description) parts.push(c.description(node.description));
+    return parts.join(", ");
+  }
+  if (isValueBeforeRoleWidget(node.role) && node.value !== void 0) {
+    if (node.name) parts.push(c.elementName(node.name));
+    const valueText = node.value.text || String(node.value.current);
+    if (valueText) parts.push(valueText);
+    const roleText = formatRoleVoiceOver(node);
+    if (roleText) parts.push(c.roleName(roleText));
+    const stateText2 = formatStatesVoiceOver(node);
+    if (stateText2) parts.push(c.stateName(stateText2));
+    if (node.description) parts.push(c.description(node.description));
+    return parts.join(", ");
+  }
   const roleFirst = shouldAnnounceRoleFirst(node.role);
   if (roleFirst) {
     const roleText = formatRoleVoiceOver(node);
@@ -998,6 +1041,9 @@ function formatNodeVoiceOver(node, c) {
       parts.push(valueText);
     }
   }
+  if (node.state.posinset !== void 0 && node.state.setsize !== void 0) {
+    parts.push(`${node.state.posinset} of ${node.state.setsize}`);
+  }
   if (node.description) {
     parts.push(c.description(node.description));
   }
@@ -1033,7 +1079,7 @@ function formatRoleVoiceOver(node) {
     case "list":
       return "list";
     case "listitem":
-      return "item";
+      return "";
     case "navigation":
       return "navigation";
     case "main":
@@ -1089,6 +1135,18 @@ function formatRoleVoiceOver(node) {
       return "progress indicator";
     case "status":
       return "status";
+    case "switch":
+      return "switch";
+    case "slider":
+      return "slider";
+    case "spinbutton":
+      return "stepper";
+    case "tab":
+      return "tab";
+    case "tablist":
+      return node.name ? "tab group" : "tab group";
+    case "tabpanel":
+      return "tab panel";
     case "group":
       return node.name ? "group" : "";
     case "document":
@@ -1109,6 +1167,10 @@ function formatStatesVoiceOver(node) {
   if (node.state.checked !== void 0) {
     if (node.state.checked === "mixed") {
       states.push("mixed");
+    } else if (node.role === "switch") {
+      states.push(node.state.checked ? "on" : "off");
+    } else if (node.role === "radio") {
+      if (node.state.checked) states.push("selected");
     } else {
       states.push(node.state.checked ? "checked" : "unchecked");
     }
@@ -1117,10 +1179,10 @@ function formatStatesVoiceOver(node) {
     if (node.state.pressed === "mixed") {
       states.push("mixed");
     } else {
-      states.push(node.state.pressed ? "pressed" : "not pressed");
+      states.push(node.state.pressed ? "selected" : "unselected");
     }
   }
-  if (node.state.selected !== void 0) {
+  if (node.state.selected !== void 0 && node.role !== "tab") {
     states.push(node.state.selected ? "selected" : "unselected");
   }
   if (node.state.disabled) {
@@ -2069,7 +2131,10 @@ var INPUT_TYPE_ROLE_MAP = {
   "search": "textbox",
   "tel": "textbox",
   "url": "textbox",
-  "number": "textbox"
+  // Per ARIA, <input type="number"> has an implicit role of spinbutton
+  // (VoiceOver announces it as "stepper").
+  "number": "spinbutton",
+  "range": "slider"
 };
 function computeRole(element) {
   const warnings = [];
@@ -2102,6 +2167,11 @@ function computeImplicitRole(element, _warnings) {
   if (tagName === "input") {
     return computeInputRole(element);
   }
+  if (tagName === "select") {
+    const multiple = element.hasAttribute("multiple");
+    const size = parseInt(element.getAttribute("size") || "0", 10);
+    return multiple || size > 1 ? "listbox" : "combobox";
+  }
   if (tagName === "a") {
     return element.hasAttribute("href") ? "link" : null;
   }
@@ -2511,6 +2581,7 @@ function processChildNode(node, children, warnings) {
   if (node.nodeType === 1) {
     const element = node;
     if (isHidden(element)) return;
+    if (isConsumedLabel(element)) return;
     if (!isAccessible(element)) {
       const grandchildren = collectChildrenFromRolelessElement(element, warnings);
       children.push(...grandchildren);
@@ -2520,18 +2591,74 @@ function processChildNode(node, children, warnings) {
     if (childNode) children.push(childNode);
   }
 }
+function isConsumedLabel(element) {
+  if (element.tagName.toLowerCase() !== "label") return false;
+  const forId = element.getAttribute("for");
+  if (forId) {
+    const doc = element.ownerDocument;
+    const target = doc?.getElementById(forId);
+    if (target && isLabelableControl(target)) return true;
+  }
+  const wrapped = element.querySelector("input, select, textarea, button, meter, progress");
+  if (wrapped && isLabelableControl(wrapped)) return true;
+  return false;
+}
+function isLabelableControl(element) {
+  const tag = element.tagName.toLowerCase();
+  if (tag === "input") {
+    return (element.getAttribute("type") || "text").toLowerCase() !== "hidden";
+  }
+  return tag === "select" || tag === "textarea" || tag === "button" || tag === "meter" || tag === "progress";
+}
 function collectChildrenFromRolelessElement(element, warnings) {
+  return collectAccessibleChildren(element, warnings);
+}
+function collectAccessibleChildren(element, warnings) {
   const children = [];
   if (element.shadowRoot) {
     for (const child of Array.from(element.shadowRoot.childNodes)) {
-      processChildNode(child, children, warnings);
+      processShadowNode(child, children, warnings);
     }
+    return children;
+  }
+  if (element.localName && element.localName.includes("-") && element.childNodes.length === 0) {
+    warnings.push({
+      message: `Custom element <${element.localName}> has no accessible children and may have a closed shadow root; its content could not be analyzed.`,
+      element
+    });
   }
   for (const child of Array.from(element.childNodes)) {
     processChildNode(child, children, warnings);
   }
   return children;
 }
+function processShadowNode(node, children, warnings) {
+  if (node.nodeType === 1) {
+    const element = node;
+    if (element.localName === "slot") {
+      const slot = element;
+      let assigned = [];
+      if (typeof slot.assignedNodes === "function") {
+        try {
+          assigned = Array.from(slot.assignedNodes({ flatten: true }));
+        } catch {
+          assigned = [];
+        }
+      }
+      if (assigned.length > 0) {
+        for (const assignedNode of assigned) {
+          processChildNode(assignedNode, children, warnings);
+        }
+      } else {
+        for (const child of Array.from(slot.childNodes)) {
+          processShadowNode(child, children, warnings);
+        }
+      }
+      return;
+    }
+  }
+  processChildNode(node, children, warnings);
+}
 function buildAccessibilityTree(rootElement, sourceHash) {
   const warnings = [];
   if (isHidden(rootElement)) {
@@ -2588,6 +2715,30 @@ function buildAccessibilityTreeWithSelector(rootElement, selector, sourceHash) {
   }
   return results;
 }
+var SET_MEMBER_ROLES = /* @__PURE__ */ new Set([
+  "radio",
+  "option",
+  "listitem",
+  "tab"
+]);
+function assignImplicitSetPosition(children) {
+  const totals = /* @__PURE__ */ new Map();
+  for (const child of children) {
+    if (SET_MEMBER_ROLES.has(child.role)) {
+      totals.set(child.role, (totals.get(child.role) ?? 0) + 1);
+    }
+  }
+  const seen = /* @__PURE__ */ new Map();
+  for (const child of children) {
+    if (!SET_MEMBER_ROLES.has(child.role)) continue;
+    const total = totals.get(child.role);
+    if (total < 2) continue;
+    const pos = (seen.get(child.role) ?? 0) + 1;
+    seen.set(child.role, pos);
+    if (child.state.posinset === void 0) child.state.posinset = pos;
+    if (child.state.setsize === void 0) child.state.setsize = total;
+  }
+}
 function buildNodeRecursive(element, warnings) {
   if (isHidden(element)) {
     return null;
@@ -2624,15 +2775,15 @@ function buildNodeRecursive(element, warnings) {
     element: w.element
   })));
   const focusInfo = extractFocusInfo(element);
-  const children = [];
-  if (element.shadowRoot) {
-    for (const child of Array.from(element.shadowRoot.childNodes)) {
-      processChildNode(child, children, warnings);
+  let children = collectAccessibleChildren(element, warnings);
+  const isNativeSelect = element.tagName.toLowerCase() === "select";
+  if (isNativeSelect && roleResult.role === "combobox") {
+    children = [];
+    if (stateResult.state.expanded === void 0) {
+      stateResult.state.expanded = false;
     }
   }
-  for (const child of Array.from(element.childNodes)) {
-    processChildNode(child, children, warnings);
-  }
+  assignImplicitSetPosition(children);
   const node = {
     role: roleResult.role,
     name: nameResult.name,
@@ -2645,15 +2796,7 @@ function buildNodeRecursive(element, warnings) {
   return node;
 }
 function createGenericContainer(rootElement, warnings) {
-  const children = [];
-  if (rootElement.shadowRoot) {
-    for (const child of Array.from(rootElement.shadowRoot.childNodes)) {
-      processChildNode(child, children, warnings);
-    }
-  }
-  for (const child of Array.from(rootElement.childNodes)) {
-    processChildNode(child, children, warnings);
-  }
+  const children = collectAccessibleChildren(rootElement, warnings);
   return {
     role: "generic",
     name: "",
@@ -4365,8 +4508,10 @@ function createHeuristicAnalyzer(config) {
   };
 }
 
+// src/version.ts
+var SPEAKABLE_VERSION = "1.7.0" ? "1.7.0" : "dev";
+
 // src/runtime/timeline-generator.ts
-var SPEAKABLE_VERSION = "1.3.0";
 var TIMELINE_FORMAT_VERSION = "1.0";
 var DEFAULT_SETTLE_PERIOD = 500;
 var DEFAULT_LOAD_TIMEOUT = 1e4;
@@ -5123,7 +5268,6 @@ function classifyModified(entry) {
 // src/runtime/baseline-storage.ts
 import { readFile, writeFile, mkdir, access } from "fs/promises";
 import { join, dirname } from "path";
-var SPEAKABLE_VERSION2 = "1.3.0";
 function createBaselineStorage(baseDir) {
   function sanitize(name) {
     return name.toLowerCase().replace(/[/\\]/g, "-").replace(/[^a-z0-9._-]/g, "-");
@@ -5143,7 +5287,7 @@ function createBaselineStorage(baseDir) {
       const baselineFile = {
         baseline: {
           createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-          speakableVersion: SPEAKABLE_VERSION2,
+          speakableVersion: SPEAKABLE_VERSION,
           storybookUrl: meta?.storybookUrl,
           interactionSequence: timeline.interactionSequence
         },