@streetui/testing 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StreetUI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# @streetui/testing
+
+StreetUI testing utilities — test renderer, query helpers, assertions
+
+Part of [StreetUI](https://github.com/streetui/streetui) — a semantic,
+signal-based UI framework with its own reactivity and keyed DOM reconciler
+(no virtual DOM).
+
+## Install
+
+```sh
+npm install @streetui/testing
+```
+
+## Usage
+
+```ts
+import * as pkg from '@streetui/testing';
+```
+
+Both ESM (`import`) and CommonJS (`require`) entry points are shipped, with
+matching TypeScript declarations.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,240 @@
+"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);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  findAllByRole: () => findAllByRole,
+  findByRole: () => findByRole,
+  findByText: () => findByText,
+  flushUpdates: () => flushUpdates,
+  render: () => render,
+  renderOnce: () => renderOnce,
+  renderServerThenHydrate: () => renderServerThenHydrate,
+  waitFor: () => waitFor
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/test-renderer.ts
+var import_core = require("@streetui/core");
+var import_compiler = require("@streetui/compiler");
+var import_dom = require("@streetui/dom");
+var import_renderer = require("@streetui/renderer");
+function render(app) {
+  const compiled = (0, import_compiler.compile)(app);
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const renderer = (0, import_renderer.createRenderer)({ domAdapter: new import_dom.BrowserDOMAdapter() });
+  const handle = renderer.mount(compiled, container);
+  return {
+    container,
+    handle,
+    unmount() {
+      handle.unmount();
+      if (container.parentNode !== null) {
+        container.parentNode.removeChild(container);
+      }
+    },
+    flush() {
+      handle.flush();
+    },
+    getByTag(tag) {
+      const el = container.querySelector(tag);
+      if (el === null) {
+        throw new Error(`[StreetUI Testing] Element <${tag}> not found in render output`);
+      }
+      return el;
+    },
+    getAllByTag(tag) {
+      return Array.from(container.querySelectorAll(tag));
+    },
+    getByText(text) {
+      const all = Array.from(container.querySelectorAll("*"));
+      const match = all.find(
+        (el) => el.children.length === 0 && el.textContent?.includes(text)
+      );
+      if (match === void 0) {
+        throw new Error(`[StreetUI Testing] No element with text "${text}" found`);
+      }
+      return match;
+    },
+    getAllByText(text) {
+      return Array.from(container.querySelectorAll("*")).filter(
+        (el) => el.textContent?.includes(text)
+      );
+    },
+    query(selector) {
+      return container.querySelector(selector);
+    },
+    queryAll(selector) {
+      return Array.from(container.querySelectorAll(selector));
+    },
+    find(selector) {
+      const el = container.querySelector(selector);
+      if (el === null) {
+        throw new Error(`[StreetUI Testing] Selector "${selector}" matched nothing`);
+      }
+      return el;
+    }
+  };
+}
+function renderOnce(app, testFn) {
+  const result = render(app);
+  return Promise.resolve(testFn(result)).finally(() => {
+    result.unmount();
+    (0, import_core.resetIdCounter)();
+  });
+}
+
+// src/helpers.ts
+var import_core2 = require("@streetui/core");
+var import_scheduler = require("@streetui/scheduler");
+var import_compiler2 = require("@streetui/compiler");
+var import_dom2 = require("@streetui/dom");
+var import_renderer2 = require("@streetui/renderer");
+async function flushUpdates() {
+  (0, import_scheduler.flushSync)();
+  await Promise.resolve();
+  (0, import_scheduler.flushSync)();
+}
+async function waitFor(check, options = {}) {
+  const timeout = options.timeout ?? 1e3;
+  const interval = options.interval ?? 10;
+  const deadline = Date.now() + timeout;
+  let lastError;
+  for (; ; ) {
+    await flushUpdates();
+    try {
+      const result = check();
+      if (result) return result;
+      lastError = new Error("[StreetUI Testing] waitFor: condition was falsy");
+    } catch (err) {
+      lastError = err;
+    }
+    if (Date.now() >= deadline) {
+      throw lastError instanceof Error ? lastError : new Error(String(lastError));
+    }
+    await new Promise((resolve) => setTimeout(resolve, interval));
+  }
+}
+function findByText(container, text) {
+  const match = Array.from(container.querySelectorAll("*")).find(
+    (el) => el.children.length === 0 && (el.textContent?.includes(text) ?? false)
+  );
+  if (match === void 0) {
+    throw new Error(`[StreetUI Testing] No element with text "${text}" found`);
+  }
+  return match;
+}
+function implicitRole(el) {
+  const tag = el.tagName.toLowerCase();
+  switch (tag) {
+    case "button":
+      return "button";
+    case "a":
+      return el.hasAttribute("href") ? "link" : null;
+    case "nav":
+      return "navigation";
+    case "h1":
+    case "h2":
+    case "h3":
+    case "h4":
+    case "h5":
+    case "h6":
+      return "heading";
+    case "input": {
+      const type = (el.getAttribute("type") ?? "text").toLowerCase();
+      if (type === "checkbox") return "checkbox";
+      if (type === "radio") return "radio";
+      if (type === "button" || type === "submit") return "button";
+      return "textbox";
+    }
+    case "form":
+      return "form";
+    default:
+      return null;
+  }
+}
+function accessibleName(el) {
+  return (el.getAttribute("aria-label") ?? el.textContent ?? "").trim();
+}
+function findAllByRole(container, role, options = {}) {
+  const all = Array.from(container.querySelectorAll("*"));
+  return all.filter((el) => {
+    const explicit = el.getAttribute("role");
+    const matches = explicit === role || explicit === null && implicitRole(el) === role;
+    if (!matches) return false;
+    if (options.name !== void 0) {
+      return accessibleName(el).includes(options.name);
+    }
+    return true;
+  });
+}
+function findByRole(container, role, options = {}) {
+  const matches = findAllByRole(container, role, options);
+  if (matches.length === 0) {
+    const named = options.name !== void 0 ? ` with name "${options.name}"` : "";
+    throw new Error(`[StreetUI Testing] No element with role "${role}"${named} found`);
+  }
+  if (matches.length > 1) {
+    throw new Error(
+      `[StreetUI Testing] Found ${matches.length} elements with role "${role}" \u2014 refine with { name }`
+    );
+  }
+  return matches[0];
+}
+function renderServerThenHydrate(build, options = {}) {
+  (0, import_core2.resetIdCounter)();
+  const serverHtml = (0, import_renderer2.renderToString)((0, import_compiler2.compile)(build()));
+  const container = document.createElement("div");
+  container.innerHTML = serverHtml;
+  document.body.appendChild(container);
+  const collector = options.collectDiagnostics === true ? (0, import_renderer2.createHydrationDiagnosticCollector)() : void 0;
+  (0, import_core2.resetIdCounter)();
+  const renderer = (0, import_renderer2.createRenderer)({
+    domAdapter: new import_dom2.BrowserDOMAdapter(),
+    ...collector !== void 0 ? { hydrationDiagnostics: collector.sink } : {}
+  });
+  const handle = renderer.hydrate((0, import_compiler2.compile)(build()), container);
+  return {
+    container,
+    serverHtml,
+    handle,
+    diagnostics: collector?.diagnostics ?? [],
+    flush() {
+      handle.flush();
+    },
+    unmount() {
+      handle.unmount();
+      if (container.parentNode !== null) container.parentNode.removeChild(container);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  findAllByRole,
+  findByRole,
+  findByText,
+  flushUpdates,
+  render,
+  renderOnce,
+  renderServerThenHydrate,
+  waitFor
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/test-renderer.ts","../src/helpers.ts"],"sourcesContent":["export * from './test-renderer.js';\nexport * from './helpers.js';\n","/**\n * StreetUI Test Renderer.\n *\n * Renders a StreetApp into a real (happy-dom / jsdom) DOM container\n * and exposes query helpers so tests can assert on structure/content\n * without importing the browser renderer directly.\n */\n\nimport { resetIdCounter } from '@streetui/core';\nimport { compile } from '@streetui/compiler';\nimport type { StreetApp } from '@streetui/dsl';\nimport { BrowserDOMAdapter } from '@streetui/dom';\nimport { createRenderer } from '@streetui/renderer';\nimport type { RenderHandle } from '@streetui/runtime';\n\nexport interface RenderResult {\n  /** The root container element that was rendered into. */\n  readonly container: HTMLElement;\n  /** Unmount and clean up the render. */\n  unmount(): void;\n  /** Query a single element (throws if missing). */\n  getByTag<K extends keyof HTMLElementTagNameMap>(tag: K): HTMLElementTagNameMap[K];\n  /** Query all elements by tag. */\n  getAllByTag<K extends keyof HTMLElementTagNameMap>(tag: K): Array<HTMLElementTagNameMap[K]>;\n  /** Query by text content (partial match). */\n  getByText(text: string): Element;\n  /** Query all elements whose text content includes the given string. */\n  getAllByText(text: string): Element[];\n  /** Raw querySelector. */\n  query(selector: string): Element | null;\n  /** Raw querySelectorAll. */\n  queryAll(selector: string): Element[];\n  /** Assert element exists; return it. */\n  find(selector: string): Element;\n  /** Force a flush of any pending scheduler work. */\n  flush(): void;\n  /** The underlying render handle. */\n  readonly handle: RenderHandle;\n}\n\n/**\n * Render a StreetApp into a detached DOM container.\n * Uses the real StreetUI renderer backed by happy-dom/jsdom.\n */\nexport function render(app: StreetApp): RenderResult {\n  const compiled = compile(app);\n  const container = document.createElement('div');\n  document.body.appendChild(container);\n\n  const renderer = createRenderer({ domAdapter: new BrowserDOMAdapter() });\n  const handle = renderer.mount(compiled, container);\n\n  return {\n    container,\n    handle,\n    unmount() {\n      handle.unmount();\n      if (container.parentNode !== null) {\n        container.parentNode.removeChild(container);\n      }\n    },\n    flush() {\n      handle.flush();\n    },\n    getByTag<K extends keyof HTMLElementTagNameMap>(tag: K): HTMLElementTagNameMap[K] {\n      const el = container.querySelector(tag);\n      if (el === null) {\n        throw new Error(`[StreetUI Testing] Element <${tag}> not found in render output`);\n      }\n      return el as HTMLElementTagNameMap[K];\n    },\n    getAllByTag<K extends keyof HTMLElementTagNameMap>(tag: K): Array<HTMLElementTagNameMap[K]> {\n      return Array.from(container.querySelectorAll(tag)) as Array<HTMLElementTagNameMap[K]>;\n    },\n    getByText(text: string): Element {\n      const all = Array.from(container.querySelectorAll('*'));\n      const match = all.find(el =>\n        el.children.length === 0 && el.textContent?.includes(text),\n      );\n      if (match === undefined) {\n        throw new Error(`[StreetUI Testing] No element with text \"${text}\" found`);\n      }\n      return match;\n    },\n    getAllByText(text: string): Element[] {\n      return Array.from(container.querySelectorAll('*')).filter(el =>\n        el.textContent?.includes(text),\n      );\n    },\n    query(selector: string): Element | null {\n      return container.querySelector(selector);\n    },\n    queryAll(selector: string): Element[] {\n      return Array.from(container.querySelectorAll(selector));\n    },\n    find(selector: string): Element {\n      const el = container.querySelector(selector);\n      if (el === null) {\n        throw new Error(`[StreetUI Testing] Selector \"${selector}\" matched nothing`);\n      }\n      return el;\n    },\n  };\n}\n\n/** Render and automatically clean up after the test. */\nexport function renderOnce(\n  app: StreetApp,\n  testFn: (result: RenderResult) => void | Promise<void>,\n): Promise<void> {\n  const result = render(app);\n  return Promise.resolve(testFn(result)).finally(() => {\n    result.unmount();\n    resetIdCounter();\n  });\n}\n","/**\n * Higher-level testing helpers: role/text queries, update flushing, async\n * waiting, and a first-class SSR → hydrate → assert workflow.\n *\n * These build on the same real renderer the app uses — no private-graph access,\n * no second assertion framework. They exist so a test does not have to\n * reimplement server-render/hydrate plumbing or poll for async resource state\n * by hand.\n */\n\nimport { resetIdCounter } from '@streetui/core';\nimport { flushSync } from '@streetui/scheduler';\nimport { compile } from '@streetui/compiler';\nimport type { StreetApp } from '@streetui/dsl';\nimport { BrowserDOMAdapter } from '@streetui/dom';\nimport {\n  createRenderer,\n  renderToString,\n  type HydrationDiagnostic,\n  createHydrationDiagnosticCollector,\n} from '@streetui/renderer';\nimport type { RenderHandle } from '@streetui/runtime';\n\n// ── Update flushing & async waiting ─────────────────────────────────────────\n\n/**\n * Flush all pending scheduler work, then yield once to the microtask queue so\n * promise-driven updates (e.g. a resolved `resource` loader) are applied. Await\n * this after triggering a change that schedules a DOM patch.\n */\nexport async function flushUpdates(): Promise<void> {\n  flushSync();\n  await Promise.resolve();\n  flushSync();\n}\n\nexport interface WaitForOptions {\n  /** Give up after this many milliseconds (default 1000). */\n  readonly timeout?: number;\n  /** Delay between attempts in milliseconds (default 10). */\n  readonly interval?: number;\n}\n\n/**\n * Poll `check` until it returns a truthy value (or stops throwing), flushing\n * updates between attempts. Rejects with the last error/tiemout after the\n * deadline. Use for assertions that become true only after async work settles.\n */\nexport async function waitFor<T>(\n  check: () => T,\n  options: WaitForOptions = {},\n): Promise<T> {\n  const timeout = options.timeout ?? 1000;\n  const interval = options.interval ?? 10;\n  const deadline = Date.now() + timeout;\n  let lastError: unknown;\n\n  for (;;) {\n    await flushUpdates();\n    try {\n      const result = check();\n      if (result) return result;\n      lastError = new Error('[StreetUI Testing] waitFor: condition was falsy');\n    } catch (err) {\n      lastError = err;\n    }\n    if (Date.now() >= deadline) {\n      throw lastError instanceof Error\n        ? lastError\n        : new Error(String(lastError));\n    }\n    await new Promise((resolve) => setTimeout(resolve, interval));\n  }\n}\n\n// ── Text / role queries (container-scoped) ──────────────────────────────────\n\n/** Find the first leaf element whose text content includes `text`. */\nexport function findByText(container: Element, text: string): Element {\n  const match = Array.from(container.querySelectorAll('*')).find(\n    (el) => el.children.length === 0 && (el.textContent?.includes(text) ?? false),\n  );\n  if (match === undefined) {\n    throw new Error(`[StreetUI Testing] No element with text \"${text}\" found`);\n  }\n  return match;\n}\n\nexport interface ByRoleOptions {\n  /** Restrict to elements whose accessible name includes this string. */\n  readonly name?: string;\n}\n\n/** The implicit ARIA role for a plain HTML element, when it has one. */\nfunction implicitRole(el: Element): string | null {\n  const tag = el.tagName.toLowerCase();\n  switch (tag) {\n    case 'button':\n      return 'button';\n    case 'a':\n      return el.hasAttribute('href') ? 'link' : null;\n    case 'nav':\n      return 'navigation';\n    case 'h1':\n    case 'h2':\n    case 'h3':\n    case 'h4':\n    case 'h5':\n    case 'h6':\n      return 'heading';\n    case 'input': {\n      const type = (el.getAttribute('type') ?? 'text').toLowerCase();\n      if (type === 'checkbox') return 'checkbox';\n      if (type === 'radio') return 'radio';\n      if (type === 'button' || type === 'submit') return 'button';\n      return 'textbox';\n    }\n    case 'form':\n      return 'form';\n    default:\n      return null;\n  }\n}\n\n/** The accessible name approximation for an element (aria-label or text). */\nfunction accessibleName(el: Element): string {\n  return (el.getAttribute('aria-label') ?? el.textContent ?? '').trim();\n}\n\n/**\n * Find all elements matching an ARIA `role` — explicit `role=\"…\"` first, then\n * the element's implicit role. Optionally filter by accessible name.\n */\nexport function findAllByRole(\n  container: Element,\n  role: string,\n  options: ByRoleOptions = {},\n): Element[] {\n  const all = Array.from(container.querySelectorAll('*'));\n  return all.filter((el) => {\n    const explicit = el.getAttribute('role');\n    const matches = explicit === role || (explicit === null && implicitRole(el) === role);\n    if (!matches) return false;\n    if (options.name !== undefined) {\n      return accessibleName(el).includes(options.name);\n    }\n    return true;\n  });\n}\n\n/** Find the single element matching a role (throws if none/ambiguous). */\nexport function findByRole(\n  container: Element,\n  role: string,\n  options: ByRoleOptions = {},\n): Element {\n  const matches = findAllByRole(container, role, options);\n  if (matches.length === 0) {\n    const named = options.name !== undefined ? ` with name \"${options.name}\"` : '';\n    throw new Error(`[StreetUI Testing] No element with role \"${role}\"${named} found`);\n  }\n  if (matches.length > 1) {\n    throw new Error(\n      `[StreetUI Testing] Found ${matches.length} elements with role \"${role}\" — refine with { name }`,\n    );\n  }\n  return matches[0]!;\n}\n\n// ── First-class SSR → hydrate → assert workflow ─────────────────────────────\n\nexport interface HydrateTestOptions {\n  /** Collect hydration mismatch diagnostics (dev-style) during hydration. */\n  readonly collectDiagnostics?: boolean;\n}\n\nexport interface HydrateTestResult {\n  /** The container holding the server HTML, now hydrated live. */\n  readonly container: HTMLElement;\n  /** The server-produced HTML string (before hydration). */\n  readonly serverHtml: string;\n  /** The live render handle from hydration. */\n  readonly handle: RenderHandle;\n  /** Hydration mismatch diagnostics (empty unless collectDiagnostics + a real mismatch). */\n  readonly diagnostics: readonly HydrationDiagnostic[];\n  /** Flush pending scheduler work. */\n  flush(): void;\n  /** Unmount and detach the container. */\n  unmount(): void;\n}\n\n/**\n * Render `build` on the \"server\" to HTML, mount that HTML into a container,\n * then hydrate the SAME app against it — exactly the production SSR path. The\n * builder is invoked twice (server then client) with `resetIdCounter` between,\n * so deterministic ids line up. Assert node identity, behavior, and (optionally)\n * that hydration reported no mismatches.\n */\nexport function renderServerThenHydrate(\n  build: () => StreetApp,\n  options: HydrateTestOptions = {},\n): HydrateTestResult {\n  resetIdCounter();\n  const serverHtml = renderToString(compile(build()));\n\n  const container = document.createElement('div');\n  container.innerHTML = serverHtml;\n  document.body.appendChild(container);\n\n  const collector = options.collectDiagnostics === true\n    ? createHydrationDiagnosticCollector()\n    : undefined;\n\n  resetIdCounter();\n  const renderer = createRenderer({\n    domAdapter: new BrowserDOMAdapter(),\n    ...(collector !== undefined ? { hydrationDiagnostics: collector.sink } : {}),\n  });\n  const handle = renderer.hydrate(compile(build()), container);\n\n  return {\n    container,\n    serverHtml,\n    handle,\n    diagnostics: collector?.diagnostics ?? [],\n    flush() {\n      handle.flush();\n    },\n    unmount() {\n      handle.unmount();\n      if (container.parentNode !== null) container.parentNode.removeChild(container);\n    },\n  };\n}\n"],"mappings":"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","names":["import_core","import_compiler","import_dom","import_renderer"]}

package/dist/index.d.cts

@@ -0,0 +1,113 @@
+import { StreetApp } from '@streetui/dsl';
+import { RenderHandle } from '@streetui/runtime';
+import { HydrationDiagnostic } from '@streetui/renderer';
+
+/**
+ * StreetUI Test Renderer.
+ *
+ * Renders a StreetApp into a real (happy-dom / jsdom) DOM container
+ * and exposes query helpers so tests can assert on structure/content
+ * without importing the browser renderer directly.
+ */
+
+interface RenderResult {
+    /** The root container element that was rendered into. */
+    readonly container: HTMLElement;
+    /** Unmount and clean up the render. */
+    unmount(): void;
+    /** Query a single element (throws if missing). */
+    getByTag<K extends keyof HTMLElementTagNameMap>(tag: K): HTMLElementTagNameMap[K];
+    /** Query all elements by tag. */
+    getAllByTag<K extends keyof HTMLElementTagNameMap>(tag: K): Array<HTMLElementTagNameMap[K]>;
+    /** Query by text content (partial match). */
+    getByText(text: string): Element;
+    /** Query all elements whose text content includes the given string. */
+    getAllByText(text: string): Element[];
+    /** Raw querySelector. */
+    query(selector: string): Element | null;
+    /** Raw querySelectorAll. */
+    queryAll(selector: string): Element[];
+    /** Assert element exists; return it. */
+    find(selector: string): Element;
+    /** Force a flush of any pending scheduler work. */
+    flush(): void;
+    /** The underlying render handle. */
+    readonly handle: RenderHandle;
+}
+/**
+ * Render a StreetApp into a detached DOM container.
+ * Uses the real StreetUI renderer backed by happy-dom/jsdom.
+ */
+declare function render(app: StreetApp): RenderResult;
+/** Render and automatically clean up after the test. */
+declare function renderOnce(app: StreetApp, testFn: (result: RenderResult) => void | Promise<void>): Promise<void>;
+
+/**
+ * Higher-level testing helpers: role/text queries, update flushing, async
+ * waiting, and a first-class SSR → hydrate → assert workflow.
+ *
+ * These build on the same real renderer the app uses — no private-graph access,
+ * no second assertion framework. They exist so a test does not have to
+ * reimplement server-render/hydrate plumbing or poll for async resource state
+ * by hand.
+ */
+
+/**
+ * Flush all pending scheduler work, then yield once to the microtask queue so
+ * promise-driven updates (e.g. a resolved `resource` loader) are applied. Await
+ * this after triggering a change that schedules a DOM patch.
+ */
+declare function flushUpdates(): Promise<void>;
+interface WaitForOptions {
+    /** Give up after this many milliseconds (default 1000). */
+    readonly timeout?: number;
+    /** Delay between attempts in milliseconds (default 10). */
+    readonly interval?: number;
+}
+/**
+ * Poll `check` until it returns a truthy value (or stops throwing), flushing
+ * updates between attempts. Rejects with the last error/tiemout after the
+ * deadline. Use for assertions that become true only after async work settles.
+ */
+declare function waitFor<T>(check: () => T, options?: WaitForOptions): Promise<T>;
+/** Find the first leaf element whose text content includes `text`. */
+declare function findByText(container: Element, text: string): Element;
+interface ByRoleOptions {
+    /** Restrict to elements whose accessible name includes this string. */
+    readonly name?: string;
+}
+/**
+ * Find all elements matching an ARIA `role` — explicit `role="…"` first, then
+ * the element's implicit role. Optionally filter by accessible name.
+ */
+declare function findAllByRole(container: Element, role: string, options?: ByRoleOptions): Element[];
+/** Find the single element matching a role (throws if none/ambiguous). */
+declare function findByRole(container: Element, role: string, options?: ByRoleOptions): Element;
+interface HydrateTestOptions {
+    /** Collect hydration mismatch diagnostics (dev-style) during hydration. */
+    readonly collectDiagnostics?: boolean;
+}
+interface HydrateTestResult {
+    /** The container holding the server HTML, now hydrated live. */
+    readonly container: HTMLElement;
+    /** The server-produced HTML string (before hydration). */
+    readonly serverHtml: string;
+    /** The live render handle from hydration. */
+    readonly handle: RenderHandle;
+    /** Hydration mismatch diagnostics (empty unless collectDiagnostics + a real mismatch). */
+    readonly diagnostics: readonly HydrationDiagnostic[];
+    /** Flush pending scheduler work. */
+    flush(): void;
+    /** Unmount and detach the container. */
+    unmount(): void;
+}
+/**
+ * Render `build` on the "server" to HTML, mount that HTML into a container,
+ * then hydrate the SAME app against it — exactly the production SSR path. The
+ * builder is invoked twice (server then client) with `resetIdCounter` between,
+ * so deterministic ids line up. Assert node identity, behavior, and (optionally)
+ * that hydration reported no mismatches.
+ */
+declare function renderServerThenHydrate(build: () => StreetApp, options?: HydrateTestOptions): HydrateTestResult;
+
+export { type ByRoleOptions, type HydrateTestOptions, type HydrateTestResult, type RenderResult, type WaitForOptions, findAllByRole, findByRole, findByText, flushUpdates, render, renderOnce, renderServerThenHydrate, waitFor };

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+import { StreetApp } from '@streetui/dsl';
+import { RenderHandle } from '@streetui/runtime';
+import { HydrationDiagnostic } from '@streetui/renderer';
+
+/**
+ * StreetUI Test Renderer.
+ *
+ * Renders a StreetApp into a real (happy-dom / jsdom) DOM container
+ * and exposes query helpers so tests can assert on structure/content
+ * without importing the browser renderer directly.
+ */
+
+interface RenderResult {
+    /** The root container element that was rendered into. */
+    readonly container: HTMLElement;
+    /** Unmount and clean up the render. */
+    unmount(): void;
+    /** Query a single element (throws if missing). */
+    getByTag<K extends keyof HTMLElementTagNameMap>(tag: K): HTMLElementTagNameMap[K];
+    /** Query all elements by tag. */
+    getAllByTag<K extends keyof HTMLElementTagNameMap>(tag: K): Array<HTMLElementTagNameMap[K]>;
+    /** Query by text content (partial match). */
+    getByText(text: string): Element;
+    /** Query all elements whose text content includes the given string. */
+    getAllByText(text: string): Element[];
+    /** Raw querySelector. */
+    query(selector: string): Element | null;
+    /** Raw querySelectorAll. */
+    queryAll(selector: string): Element[];
+    /** Assert element exists; return it. */
+    find(selector: string): Element;
+    /** Force a flush of any pending scheduler work. */
+    flush(): void;
+    /** The underlying render handle. */
+    readonly handle: RenderHandle;
+}
+/**
+ * Render a StreetApp into a detached DOM container.
+ * Uses the real StreetUI renderer backed by happy-dom/jsdom.
+ */
+declare function render(app: StreetApp): RenderResult;
+/** Render and automatically clean up after the test. */
+declare function renderOnce(app: StreetApp, testFn: (result: RenderResult) => void | Promise<void>): Promise<void>;
+
+/**
+ * Higher-level testing helpers: role/text queries, update flushing, async
+ * waiting, and a first-class SSR → hydrate → assert workflow.
+ *
+ * These build on the same real renderer the app uses — no private-graph access,
+ * no second assertion framework. They exist so a test does not have to
+ * reimplement server-render/hydrate plumbing or poll for async resource state
+ * by hand.
+ */
+
+/**
+ * Flush all pending scheduler work, then yield once to the microtask queue so
+ * promise-driven updates (e.g. a resolved `resource` loader) are applied. Await
+ * this after triggering a change that schedules a DOM patch.
+ */
+declare function flushUpdates(): Promise<void>;
+interface WaitForOptions {
+    /** Give up after this many milliseconds (default 1000). */
+    readonly timeout?: number;
+    /** Delay between attempts in milliseconds (default 10). */
+    readonly interval?: number;
+}
+/**
+ * Poll `check` until it returns a truthy value (or stops throwing), flushing
+ * updates between attempts. Rejects with the last error/tiemout after the
+ * deadline. Use for assertions that become true only after async work settles.
+ */
+declare function waitFor<T>(check: () => T, options?: WaitForOptions): Promise<T>;
+/** Find the first leaf element whose text content includes `text`. */
+declare function findByText(container: Element, text: string): Element;
+interface ByRoleOptions {
+    /** Restrict to elements whose accessible name includes this string. */
+    readonly name?: string;
+}
+/**
+ * Find all elements matching an ARIA `role` — explicit `role="…"` first, then
+ * the element's implicit role. Optionally filter by accessible name.
+ */
+declare function findAllByRole(container: Element, role: string, options?: ByRoleOptions): Element[];
+/** Find the single element matching a role (throws if none/ambiguous). */
+declare function findByRole(container: Element, role: string, options?: ByRoleOptions): Element;
+interface HydrateTestOptions {
+    /** Collect hydration mismatch diagnostics (dev-style) during hydration. */
+    readonly collectDiagnostics?: boolean;
+}
+interface HydrateTestResult {
+    /** The container holding the server HTML, now hydrated live. */
+    readonly container: HTMLElement;
+    /** The server-produced HTML string (before hydration). */
+    readonly serverHtml: string;
+    /** The live render handle from hydration. */
+    readonly handle: RenderHandle;
+    /** Hydration mismatch diagnostics (empty unless collectDiagnostics + a real mismatch). */
+    readonly diagnostics: readonly HydrationDiagnostic[];
+    /** Flush pending scheduler work. */
+    flush(): void;
+    /** Unmount and detach the container. */
+    unmount(): void;
+}
+/**
+ * Render `build` on the "server" to HTML, mount that HTML into a container,
+ * then hydrate the SAME app against it — exactly the production SSR path. The
+ * builder is invoked twice (server then client) with `resetIdCounter` between,
+ * so deterministic ids line up. Assert node identity, behavior, and (optionally)
+ * that hydration reported no mismatches.
+ */
+declare function renderServerThenHydrate(build: () => StreetApp, options?: HydrateTestOptions): HydrateTestResult;
+
+export { type ByRoleOptions, type HydrateTestOptions, type HydrateTestResult, type RenderResult, type WaitForOptions, findAllByRole, findByRole, findByText, flushUpdates, render, renderOnce, renderServerThenHydrate, waitFor };

package/dist/index.js

@@ -0,0 +1,210 @@
+// src/test-renderer.ts
+import { resetIdCounter } from "@streetui/core";
+import { compile } from "@streetui/compiler";
+import { BrowserDOMAdapter } from "@streetui/dom";
+import { createRenderer } from "@streetui/renderer";
+function render(app) {
+  const compiled = compile(app);
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const renderer = createRenderer({ domAdapter: new BrowserDOMAdapter() });
+  const handle = renderer.mount(compiled, container);
+  return {
+    container,
+    handle,
+    unmount() {
+      handle.unmount();
+      if (container.parentNode !== null) {
+        container.parentNode.removeChild(container);
+      }
+    },
+    flush() {
+      handle.flush();
+    },
+    getByTag(tag) {
+      const el = container.querySelector(tag);
+      if (el === null) {
+        throw new Error(`[StreetUI Testing] Element <${tag}> not found in render output`);
+      }
+      return el;
+    },
+    getAllByTag(tag) {
+      return Array.from(container.querySelectorAll(tag));
+    },
+    getByText(text) {
+      const all = Array.from(container.querySelectorAll("*"));
+      const match = all.find(
+        (el) => el.children.length === 0 && el.textContent?.includes(text)
+      );
+      if (match === void 0) {
+        throw new Error(`[StreetUI Testing] No element with text "${text}" found`);
+      }
+      return match;
+    },
+    getAllByText(text) {
+      return Array.from(container.querySelectorAll("*")).filter(
+        (el) => el.textContent?.includes(text)
+      );
+    },
+    query(selector) {
+      return container.querySelector(selector);
+    },
+    queryAll(selector) {
+      return Array.from(container.querySelectorAll(selector));
+    },
+    find(selector) {
+      const el = container.querySelector(selector);
+      if (el === null) {
+        throw new Error(`[StreetUI Testing] Selector "${selector}" matched nothing`);
+      }
+      return el;
+    }
+  };
+}
+function renderOnce(app, testFn) {
+  const result = render(app);
+  return Promise.resolve(testFn(result)).finally(() => {
+    result.unmount();
+    resetIdCounter();
+  });
+}
+
+// src/helpers.ts
+import { resetIdCounter as resetIdCounter2 } from "@streetui/core";
+import { flushSync } from "@streetui/scheduler";
+import { compile as compile2 } from "@streetui/compiler";
+import { BrowserDOMAdapter as BrowserDOMAdapter2 } from "@streetui/dom";
+import {
+  createRenderer as createRenderer2,
+  renderToString,
+  createHydrationDiagnosticCollector
+} from "@streetui/renderer";
+async function flushUpdates() {
+  flushSync();
+  await Promise.resolve();
+  flushSync();
+}
+async function waitFor(check, options = {}) {
+  const timeout = options.timeout ?? 1e3;
+  const interval = options.interval ?? 10;
+  const deadline = Date.now() + timeout;
+  let lastError;
+  for (; ; ) {
+    await flushUpdates();
+    try {
+      const result = check();
+      if (result) return result;
+      lastError = new Error("[StreetUI Testing] waitFor: condition was falsy");
+    } catch (err) {
+      lastError = err;
+    }
+    if (Date.now() >= deadline) {
+      throw lastError instanceof Error ? lastError : new Error(String(lastError));
+    }
+    await new Promise((resolve) => setTimeout(resolve, interval));
+  }
+}
+function findByText(container, text) {
+  const match = Array.from(container.querySelectorAll("*")).find(
+    (el) => el.children.length === 0 && (el.textContent?.includes(text) ?? false)
+  );
+  if (match === void 0) {
+    throw new Error(`[StreetUI Testing] No element with text "${text}" found`);
+  }
+  return match;
+}
+function implicitRole(el) {
+  const tag = el.tagName.toLowerCase();
+  switch (tag) {
+    case "button":
+      return "button";
+    case "a":
+      return el.hasAttribute("href") ? "link" : null;
+    case "nav":
+      return "navigation";
+    case "h1":
+    case "h2":
+    case "h3":
+    case "h4":
+    case "h5":
+    case "h6":
+      return "heading";
+    case "input": {
+      const type = (el.getAttribute("type") ?? "text").toLowerCase();
+      if (type === "checkbox") return "checkbox";
+      if (type === "radio") return "radio";
+      if (type === "button" || type === "submit") return "button";
+      return "textbox";
+    }
+    case "form":
+      return "form";
+    default:
+      return null;
+  }
+}
+function accessibleName(el) {
+  return (el.getAttribute("aria-label") ?? el.textContent ?? "").trim();
+}
+function findAllByRole(container, role, options = {}) {
+  const all = Array.from(container.querySelectorAll("*"));
+  return all.filter((el) => {
+    const explicit = el.getAttribute("role");
+    const matches = explicit === role || explicit === null && implicitRole(el) === role;
+    if (!matches) return false;
+    if (options.name !== void 0) {
+      return accessibleName(el).includes(options.name);
+    }
+    return true;
+  });
+}
+function findByRole(container, role, options = {}) {
+  const matches = findAllByRole(container, role, options);
+  if (matches.length === 0) {
+    const named = options.name !== void 0 ? ` with name "${options.name}"` : "";
+    throw new Error(`[StreetUI Testing] No element with role "${role}"${named} found`);
+  }
+  if (matches.length > 1) {
+    throw new Error(
+      `[StreetUI Testing] Found ${matches.length} elements with role "${role}" \u2014 refine with { name }`
+    );
+  }
+  return matches[0];
+}
+function renderServerThenHydrate(build, options = {}) {
+  resetIdCounter2();
+  const serverHtml = renderToString(compile2(build()));
+  const container = document.createElement("div");
+  container.innerHTML = serverHtml;
+  document.body.appendChild(container);
+  const collector = options.collectDiagnostics === true ? createHydrationDiagnosticCollector() : void 0;
+  resetIdCounter2();
+  const renderer = createRenderer2({
+    domAdapter: new BrowserDOMAdapter2(),
+    ...collector !== void 0 ? { hydrationDiagnostics: collector.sink } : {}
+  });
+  const handle = renderer.hydrate(compile2(build()), container);
+  return {
+    container,
+    serverHtml,
+    handle,
+    diagnostics: collector?.diagnostics ?? [],
+    flush() {
+      handle.flush();
+    },
+    unmount() {
+      handle.unmount();
+      if (container.parentNode !== null) container.parentNode.removeChild(container);
+    }
+  };
+}
+export {
+  findAllByRole,
+  findByRole,
+  findByText,
+  flushUpdates,
+  render,
+  renderOnce,
+  renderServerThenHydrate,
+  waitFor
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/test-renderer.ts","../src/helpers.ts"],"sourcesContent":["/**\n * StreetUI Test Renderer.\n *\n * Renders a StreetApp into a real (happy-dom / jsdom) DOM container\n * and exposes query helpers so tests can assert on structure/content\n * without importing the browser renderer directly.\n */\n\nimport { resetIdCounter } from '@streetui/core';\nimport { compile } from '@streetui/compiler';\nimport type { StreetApp } from '@streetui/dsl';\nimport { BrowserDOMAdapter } from '@streetui/dom';\nimport { createRenderer } from '@streetui/renderer';\nimport type { RenderHandle } from '@streetui/runtime';\n\nexport interface RenderResult {\n  /** The root container element that was rendered into. */\n  readonly container: HTMLElement;\n  /** Unmount and clean up the render. */\n  unmount(): void;\n  /** Query a single element (throws if missing). */\n  getByTag<K extends keyof HTMLElementTagNameMap>(tag: K): HTMLElementTagNameMap[K];\n  /** Query all elements by tag. */\n  getAllByTag<K extends keyof HTMLElementTagNameMap>(tag: K): Array<HTMLElementTagNameMap[K]>;\n  /** Query by text content (partial match). */\n  getByText(text: string): Element;\n  /** Query all elements whose text content includes the given string. */\n  getAllByText(text: string): Element[];\n  /** Raw querySelector. */\n  query(selector: string): Element | null;\n  /** Raw querySelectorAll. */\n  queryAll(selector: string): Element[];\n  /** Assert element exists; return it. */\n  find(selector: string): Element;\n  /** Force a flush of any pending scheduler work. */\n  flush(): void;\n  /** The underlying render handle. */\n  readonly handle: RenderHandle;\n}\n\n/**\n * Render a StreetApp into a detached DOM container.\n * Uses the real StreetUI renderer backed by happy-dom/jsdom.\n */\nexport function render(app: StreetApp): RenderResult {\n  const compiled = compile(app);\n  const container = document.createElement('div');\n  document.body.appendChild(container);\n\n  const renderer = createRenderer({ domAdapter: new BrowserDOMAdapter() });\n  const handle = renderer.mount(compiled, container);\n\n  return {\n    container,\n    handle,\n    unmount() {\n      handle.unmount();\n      if (container.parentNode !== null) {\n        container.parentNode.removeChild(container);\n      }\n    },\n    flush() {\n      handle.flush();\n    },\n    getByTag<K extends keyof HTMLElementTagNameMap>(tag: K): HTMLElementTagNameMap[K] {\n      const el = container.querySelector(tag);\n      if (el === null) {\n        throw new Error(`[StreetUI Testing] Element <${tag}> not found in render output`);\n      }\n      return el as HTMLElementTagNameMap[K];\n    },\n    getAllByTag<K extends keyof HTMLElementTagNameMap>(tag: K): Array<HTMLElementTagNameMap[K]> {\n      return Array.from(container.querySelectorAll(tag)) as Array<HTMLElementTagNameMap[K]>;\n    },\n    getByText(text: string): Element {\n      const all = Array.from(container.querySelectorAll('*'));\n      const match = all.find(el =>\n        el.children.length === 0 && el.textContent?.includes(text),\n      );\n      if (match === undefined) {\n        throw new Error(`[StreetUI Testing] No element with text \"${text}\" found`);\n      }\n      return match;\n    },\n    getAllByText(text: string): Element[] {\n      return Array.from(container.querySelectorAll('*')).filter(el =>\n        el.textContent?.includes(text),\n      );\n    },\n    query(selector: string): Element | null {\n      return container.querySelector(selector);\n    },\n    queryAll(selector: string): Element[] {\n      return Array.from(container.querySelectorAll(selector));\n    },\n    find(selector: string): Element {\n      const el = container.querySelector(selector);\n      if (el === null) {\n        throw new Error(`[StreetUI Testing] Selector \"${selector}\" matched nothing`);\n      }\n      return el;\n    },\n  };\n}\n\n/** Render and automatically clean up after the test. */\nexport function renderOnce(\n  app: StreetApp,\n  testFn: (result: RenderResult) => void | Promise<void>,\n): Promise<void> {\n  const result = render(app);\n  return Promise.resolve(testFn(result)).finally(() => {\n    result.unmount();\n    resetIdCounter();\n  });\n}\n","/**\n * Higher-level testing helpers: role/text queries, update flushing, async\n * waiting, and a first-class SSR → hydrate → assert workflow.\n *\n * These build on the same real renderer the app uses — no private-graph access,\n * no second assertion framework. They exist so a test does not have to\n * reimplement server-render/hydrate plumbing or poll for async resource state\n * by hand.\n */\n\nimport { resetIdCounter } from '@streetui/core';\nimport { flushSync } from '@streetui/scheduler';\nimport { compile } from '@streetui/compiler';\nimport type { StreetApp } from '@streetui/dsl';\nimport { BrowserDOMAdapter } from '@streetui/dom';\nimport {\n  createRenderer,\n  renderToString,\n  type HydrationDiagnostic,\n  createHydrationDiagnosticCollector,\n} from '@streetui/renderer';\nimport type { RenderHandle } from '@streetui/runtime';\n\n// ── Update flushing & async waiting ─────────────────────────────────────────\n\n/**\n * Flush all pending scheduler work, then yield once to the microtask queue so\n * promise-driven updates (e.g. a resolved `resource` loader) are applied. Await\n * this after triggering a change that schedules a DOM patch.\n */\nexport async function flushUpdates(): Promise<void> {\n  flushSync();\n  await Promise.resolve();\n  flushSync();\n}\n\nexport interface WaitForOptions {\n  /** Give up after this many milliseconds (default 1000). */\n  readonly timeout?: number;\n  /** Delay between attempts in milliseconds (default 10). */\n  readonly interval?: number;\n}\n\n/**\n * Poll `check` until it returns a truthy value (or stops throwing), flushing\n * updates between attempts. Rejects with the last error/tiemout after the\n * deadline. Use for assertions that become true only after async work settles.\n */\nexport async function waitFor<T>(\n  check: () => T,\n  options: WaitForOptions = {},\n): Promise<T> {\n  const timeout = options.timeout ?? 1000;\n  const interval = options.interval ?? 10;\n  const deadline = Date.now() + timeout;\n  let lastError: unknown;\n\n  for (;;) {\n    await flushUpdates();\n    try {\n      const result = check();\n      if (result) return result;\n      lastError = new Error('[StreetUI Testing] waitFor: condition was falsy');\n    } catch (err) {\n      lastError = err;\n    }\n    if (Date.now() >= deadline) {\n      throw lastError instanceof Error\n        ? lastError\n        : new Error(String(lastError));\n    }\n    await new Promise((resolve) => setTimeout(resolve, interval));\n  }\n}\n\n// ── Text / role queries (container-scoped) ──────────────────────────────────\n\n/** Find the first leaf element whose text content includes `text`. */\nexport function findByText(container: Element, text: string): Element {\n  const match = Array.from(container.querySelectorAll('*')).find(\n    (el) => el.children.length === 0 && (el.textContent?.includes(text) ?? false),\n  );\n  if (match === undefined) {\n    throw new Error(`[StreetUI Testing] No element with text \"${text}\" found`);\n  }\n  return match;\n}\n\nexport interface ByRoleOptions {\n  /** Restrict to elements whose accessible name includes this string. */\n  readonly name?: string;\n}\n\n/** The implicit ARIA role for a plain HTML element, when it has one. */\nfunction implicitRole(el: Element): string | null {\n  const tag = el.tagName.toLowerCase();\n  switch (tag) {\n    case 'button':\n      return 'button';\n    case 'a':\n      return el.hasAttribute('href') ? 'link' : null;\n    case 'nav':\n      return 'navigation';\n    case 'h1':\n    case 'h2':\n    case 'h3':\n    case 'h4':\n    case 'h5':\n    case 'h6':\n      return 'heading';\n    case 'input': {\n      const type = (el.getAttribute('type') ?? 'text').toLowerCase();\n      if (type === 'checkbox') return 'checkbox';\n      if (type === 'radio') return 'radio';\n      if (type === 'button' || type === 'submit') return 'button';\n      return 'textbox';\n    }\n    case 'form':\n      return 'form';\n    default:\n      return null;\n  }\n}\n\n/** The accessible name approximation for an element (aria-label or text). */\nfunction accessibleName(el: Element): string {\n  return (el.getAttribute('aria-label') ?? el.textContent ?? '').trim();\n}\n\n/**\n * Find all elements matching an ARIA `role` — explicit `role=\"…\"` first, then\n * the element's implicit role. Optionally filter by accessible name.\n */\nexport function findAllByRole(\n  container: Element,\n  role: string,\n  options: ByRoleOptions = {},\n): Element[] {\n  const all = Array.from(container.querySelectorAll('*'));\n  return all.filter((el) => {\n    const explicit = el.getAttribute('role');\n    const matches = explicit === role || (explicit === null && implicitRole(el) === role);\n    if (!matches) return false;\n    if (options.name !== undefined) {\n      return accessibleName(el).includes(options.name);\n    }\n    return true;\n  });\n}\n\n/** Find the single element matching a role (throws if none/ambiguous). */\nexport function findByRole(\n  container: Element,\n  role: string,\n  options: ByRoleOptions = {},\n): Element {\n  const matches = findAllByRole(container, role, options);\n  if (matches.length === 0) {\n    const named = options.name !== undefined ? ` with name \"${options.name}\"` : '';\n    throw new Error(`[StreetUI Testing] No element with role \"${role}\"${named} found`);\n  }\n  if (matches.length > 1) {\n    throw new Error(\n      `[StreetUI Testing] Found ${matches.length} elements with role \"${role}\" — refine with { name }`,\n    );\n  }\n  return matches[0]!;\n}\n\n// ── First-class SSR → hydrate → assert workflow ─────────────────────────────\n\nexport interface HydrateTestOptions {\n  /** Collect hydration mismatch diagnostics (dev-style) during hydration. */\n  readonly collectDiagnostics?: boolean;\n}\n\nexport interface HydrateTestResult {\n  /** The container holding the server HTML, now hydrated live. */\n  readonly container: HTMLElement;\n  /** The server-produced HTML string (before hydration). */\n  readonly serverHtml: string;\n  /** The live render handle from hydration. */\n  readonly handle: RenderHandle;\n  /** Hydration mismatch diagnostics (empty unless collectDiagnostics + a real mismatch). */\n  readonly diagnostics: readonly HydrationDiagnostic[];\n  /** Flush pending scheduler work. */\n  flush(): void;\n  /** Unmount and detach the container. */\n  unmount(): void;\n}\n\n/**\n * Render `build` on the \"server\" to HTML, mount that HTML into a container,\n * then hydrate the SAME app against it — exactly the production SSR path. The\n * builder is invoked twice (server then client) with `resetIdCounter` between,\n * so deterministic ids line up. Assert node identity, behavior, and (optionally)\n * that hydration reported no mismatches.\n */\nexport function renderServerThenHydrate(\n  build: () => StreetApp,\n  options: HydrateTestOptions = {},\n): HydrateTestResult {\n  resetIdCounter();\n  const serverHtml = renderToString(compile(build()));\n\n  const container = document.createElement('div');\n  container.innerHTML = serverHtml;\n  document.body.appendChild(container);\n\n  const collector = options.collectDiagnostics === true\n    ? createHydrationDiagnosticCollector()\n    : undefined;\n\n  resetIdCounter();\n  const renderer = createRenderer({\n    domAdapter: new BrowserDOMAdapter(),\n    ...(collector !== undefined ? { hydrationDiagnostics: collector.sink } : {}),\n  });\n  const handle = renderer.hydrate(compile(build()), container);\n\n  return {\n    container,\n    serverHtml,\n    handle,\n    diagnostics: collector?.diagnostics ?? [],\n    flush() {\n      handle.flush();\n    },\n    unmount() {\n      handle.unmount();\n      if (container.parentNode !== null) container.parentNode.removeChild(container);\n    },\n  };\n}\n"],"mappings":";AAQA,SAAS,sBAAsB;AAC/B,SAAS,eAAe;AAExB,SAAS,yBAAyB;AAClC,SAAS,sBAAsB;AAgCxB,SAAS,OAAO,KAA8B;AACnD,QAAM,WAAW,QAAQ,GAAG;AAC5B,QAAM,YAAY,SAAS,cAAc,KAAK;AAC9C,WAAS,KAAK,YAAY,SAAS;AAEnC,QAAM,WAAW,eAAe,EAAE,YAAY,IAAI,kBAAkB,EAAE,CAAC;AACvE,QAAM,SAAS,SAAS,MAAM,UAAU,SAAS;AAEjD,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,UAAU;AACR,aAAO,QAAQ;AACf,UAAI,UAAU,eAAe,MAAM;AACjC,kBAAU,WAAW,YAAY,SAAS;AAAA,MAC5C;AAAA,IACF;AAAA,IACA,QAAQ;AACN,aAAO,MAAM;AAAA,IACf;AAAA,IACA,SAAgD,KAAkC;AAChF,YAAM,KAAK,UAAU,cAAc,GAAG;AACtC,UAAI,OAAO,MAAM;AACf,cAAM,IAAI,MAAM,+BAA+B,GAAG,8BAA8B;AAAA,MAClF;AACA,aAAO;AAAA,IACT;AAAA,IACA,YAAmD,KAAyC;AAC1F,aAAO,MAAM,KAAK,UAAU,iBAAiB,GAAG,CAAC;AAAA,IACnD;AAAA,IACA,UAAU,MAAuB;AAC/B,YAAM,MAAM,MAAM,KAAK,UAAU,iBAAiB,GAAG,CAAC;AACtD,YAAM,QAAQ,IAAI;AAAA,QAAK,QACrB,GAAG,SAAS,WAAW,KAAK,GAAG,aAAa,SAAS,IAAI;AAAA,MAC3D;AACA,UAAI,UAAU,QAAW;AACvB,cAAM,IAAI,MAAM,4CAA4C,IAAI,SAAS;AAAA,MAC3E;AACA,aAAO;AAAA,IACT;AAAA,IACA,aAAa,MAAyB;AACpC,aAAO,MAAM,KAAK,UAAU,iBAAiB,GAAG,CAAC,EAAE;AAAA,QAAO,QACxD,GAAG,aAAa,SAAS,IAAI;AAAA,MAC/B;AAAA,IACF;AAAA,IACA,MAAM,UAAkC;AACtC,aAAO,UAAU,cAAc,QAAQ;AAAA,IACzC;AAAA,IACA,SAAS,UAA6B;AACpC,aAAO,MAAM,KAAK,UAAU,iBAAiB,QAAQ,CAAC;AAAA,IACxD;AAAA,IACA,KAAK,UAA2B;AAC9B,YAAM,KAAK,UAAU,cAAc,QAAQ;AAC3C,UAAI,OAAO,MAAM;AACf,cAAM,IAAI,MAAM,gCAAgC,QAAQ,mBAAmB;AAAA,MAC7E;AACA,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAGO,SAAS,WACd,KACA,QACe;AACf,QAAM,SAAS,OAAO,GAAG;AACzB,SAAO,QAAQ,QAAQ,OAAO,MAAM,CAAC,EAAE,QAAQ,MAAM;AACnD,WAAO,QAAQ;AACf,mBAAe;AAAA,EACjB,CAAC;AACH;;;ACzGA,SAAS,kBAAAA,uBAAsB;AAC/B,SAAS,iBAAiB;AAC1B,SAAS,WAAAC,gBAAe;AAExB,SAAS,qBAAAC,0BAAyB;AAClC;AAAA,EACE,kBAAAC;AAAA,EACA;AAAA,EAEA;AAAA,OACK;AAUP,eAAsB,eAA8B;AAClD,YAAU;AACV,QAAM,QAAQ,QAAQ;AACtB,YAAU;AACZ;AAcA,eAAsB,QACpB,OACA,UAA0B,CAAC,GACf;AACZ,QAAM,UAAU,QAAQ,WAAW;AACnC,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,WAAW,KAAK,IAAI,IAAI;AAC9B,MAAI;AAEJ,aAAS;AACP,UAAM,aAAa;AACnB,QAAI;AACF,YAAM,SAAS,MAAM;AACrB,UAAI,OAAQ,QAAO;AACnB,kBAAY,IAAI,MAAM,iDAAiD;AAAA,IACzE,SAAS,KAAK;AACZ,kBAAY;AAAA,IACd;AACA,QAAI,KAAK,IAAI,KAAK,UAAU;AAC1B,YAAM,qBAAqB,QACvB,YACA,IAAI,MAAM,OAAO,SAAS,CAAC;AAAA,IACjC;AACA,UAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,QAAQ,CAAC;AAAA,EAC9D;AACF;AAKO,SAAS,WAAW,WAAoB,MAAuB;AACpE,QAAM,QAAQ,MAAM,KAAK,UAAU,iBAAiB,GAAG,CAAC,EAAE;AAAA,IACxD,CAAC,OAAO,GAAG,SAAS,WAAW,MAAM,GAAG,aAAa,SAAS,IAAI,KAAK;AAAA,EACzE;AACA,MAAI,UAAU,QAAW;AACvB,UAAM,IAAI,MAAM,4CAA4C,IAAI,SAAS;AAAA,EAC3E;AACA,SAAO;AACT;AAQA,SAAS,aAAa,IAA4B;AAChD,QAAM,MAAM,GAAG,QAAQ,YAAY;AACnC,UAAQ,KAAK;AAAA,IACX,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO,GAAG,aAAa,MAAM,IAAI,SAAS;AAAA,IAC5C,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT,KAAK,SAAS;AACZ,YAAM,QAAQ,GAAG,aAAa,MAAM,KAAK,QAAQ,YAAY;AAC7D,UAAI,SAAS,WAAY,QAAO;AAChC,UAAI,SAAS,QAAS,QAAO;AAC7B,UAAI,SAAS,YAAY,SAAS,SAAU,QAAO;AACnD,aAAO;AAAA,IACT;AAAA,IACA,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO;AAAA,EACX;AACF;AAGA,SAAS,eAAe,IAAqB;AAC3C,UAAQ,GAAG,aAAa,YAAY,KAAK,GAAG,eAAe,IAAI,KAAK;AACtE;AAMO,SAAS,cACd,WACA,MACA,UAAyB,CAAC,GACf;AACX,QAAM,MAAM,MAAM,KAAK,UAAU,iBAAiB,GAAG,CAAC;AACtD,SAAO,IAAI,OAAO,CAAC,OAAO;AACxB,UAAM,WAAW,GAAG,aAAa,MAAM;AACvC,UAAM,UAAU,aAAa,QAAS,aAAa,QAAQ,aAAa,EAAE,MAAM;AAChF,QAAI,CAAC,QAAS,QAAO;AACrB,QAAI,QAAQ,SAAS,QAAW;AAC9B,aAAO,eAAe,EAAE,EAAE,SAAS,QAAQ,IAAI;AAAA,IACjD;AACA,WAAO;AAAA,EACT,CAAC;AACH;AAGO,SAAS,WACd,WACA,MACA,UAAyB,CAAC,GACjB;AACT,QAAM,UAAU,cAAc,WAAW,MAAM,OAAO;AACtD,MAAI,QAAQ,WAAW,GAAG;AACxB,UAAM,QAAQ,QAAQ,SAAS,SAAY,eAAe,QAAQ,IAAI,MAAM;AAC5E,UAAM,IAAI,MAAM,4CAA4C,IAAI,IAAI,KAAK,QAAQ;AAAA,EACnF;AACA,MAAI,QAAQ,SAAS,GAAG;AACtB,UAAM,IAAI;AAAA,MACR,4BAA4B,QAAQ,MAAM,wBAAwB,IAAI;AAAA,IACxE;AAAA,EACF;AACA,SAAO,QAAQ,CAAC;AAClB;AA+BO,SAAS,wBACd,OACA,UAA8B,CAAC,GACZ;AACnB,EAAAH,gBAAe;AACf,QAAM,aAAa,eAAeC,SAAQ,MAAM,CAAC,CAAC;AAElD,QAAM,YAAY,SAAS,cAAc,KAAK;AAC9C,YAAU,YAAY;AACtB,WAAS,KAAK,YAAY,SAAS;AAEnC,QAAM,YAAY,QAAQ,uBAAuB,OAC7C,mCAAmC,IACnC;AAEJ,EAAAD,gBAAe;AACf,QAAM,WAAWG,gBAAe;AAAA,IAC9B,YAAY,IAAID,mBAAkB;AAAA,IAClC,GAAI,cAAc,SAAY,EAAE,sBAAsB,UAAU,KAAK,IAAI,CAAC;AAAA,EAC5E,CAAC;AACD,QAAM,SAAS,SAAS,QAAQD,SAAQ,MAAM,CAAC,GAAG,SAAS;AAE3D,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA,aAAa,WAAW,eAAe,CAAC;AAAA,IACxC,QAAQ;AACN,aAAO,MAAM;AAAA,IACf;AAAA,IACA,UAAU;AACR,aAAO,QAAQ;AACf,UAAI,UAAU,eAAe,KAAM,WAAU,WAAW,YAAY,SAAS;AAAA,IAC/E;AAAA,EACF;AACF;","names":["resetIdCounter","compile","BrowserDOMAdapter","createRenderer"]}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@streetui/testing",
+  "version": "1.0.0",
+  "description": "StreetUI testing utilities — test renderer, query helpers, assertions",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@streetui/core": "1.0.0",
+    "@streetui/graph": "1.0.0",
+    "@streetui/compiler": "1.0.0",
+    "@streetui/dsl": "1.0.0",
+    "@streetui/renderer": "1.0.0",
+    "@streetui/dom": "1.0.0",
+    "@streetui/runtime": "1.0.0",
+    "@streetui/scheduler": "1.0.0",
+    "@streetui/state": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "*",
+    "tsup": "*",
+    "vitest": "*",
+    "happy-dom": "*"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}