@akanjs/devkit 3.0.0-beta.22 → 3.0.0-beta.24

package/cloud/globalConfig.ts

@@ -39,12 +39,27 @@ export class GlobalConfig {
     const temp = `${configPath}.${process.pid}.${crypto.randomUUID()}.tmp`;
     try {
       await writeFile(temp, JSON.stringify(akanConfig, null, 2), { mode: 0o600 });
-      await rename(temp, configPath);
+      await GlobalConfig.#replace(temp, configPath);
     } catch (error) {
       await rm(temp, { force: true });
       throw error;
     }
   }
+  static readonly #replaceAttempts = 100;
+  // Windows refuses to rename over a file another process has open (EPERM, or EACCES/EBUSY), and every CLI reads this
+  // one outside the lock. A reader holds it for one read, so the rename is retried for a few seconds instead of failing.
+  static async #replace(temp: string, target: string) {
+    for (let attempt = 1; ; attempt++) {
+      try {
+        return await rename(temp, target);
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        const busy = process.platform === "win32" && (code === "EPERM" || code === "EACCES" || code === "EBUSY");
+        if (!busy || attempt >= GlobalConfig.#replaceAttempts) throw error;
+        await Bun.sleep(Math.min(10 * attempt, 50));
+      }
+    }
+  }
   static readonly #lockPath = `${configPath}.lock`;
   // Every write re-reads under the lock: one built on an earlier read could restore a rotated-away refresh token.
   static async #update(mutate: (akanConfig: AkanGlobalConfig) => AkanGlobalConfig) {

package/csrE2e/csrE2eHarness.fixture.ts

@@ -0,0 +1,400 @@
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+
+export interface CsrE2eOptions {
+  app: string;
+  /** An `akan start` that is already running; without it the harness starts one on `port`. */
+  url?: string;
+  port?: number;
+  /** Extra env for the `akan start` it spawns, e.g. `{ AKAN_DEV_CSR: "registry" }`. */
+  env?: Record<string, string>;
+  lang?: string;
+  mobileTarget?: string;
+  workspaceRoot?: string;
+  startTimeoutMs?: number;
+  viewport?: { width: number; height: number };
+  /** `webkit` is macOS only; elsewhere, or with `AKAN_CSR_E2E_BACKEND=chrome`, an installed Chrome is driven. */
+  backend?: "webkit" | "chrome";
+}
+
+export interface CsrE2ePageContainer {
+  key: string;
+  path: string;
+  hidden: boolean;
+  inert: boolean;
+  ariaHidden: boolean;
+}
+
+export interface CsrE2eProbe {
+  renders: number;
+  ticks: number;
+  mountId: string;
+  mounted: boolean;
+  activity: string;
+  focused: boolean;
+  focusCount: number;
+}
+
+interface CsrE2eServer {
+  proc: ReturnType<typeof Bun.spawn>;
+  logPath: string;
+}
+
+const DEFAULT_PORT = 8391;
+const RELOAD_MARKER = "__akanE2eBootMarker";
+//? Longer than the frame's navigation lock (360ms after a transition commits, `webkit/useCsrValues.ts`).
+const SETTLE_MS = 450;
+
+/** Drives a CSR page (`?csr=true` + a mobile target) of a running `akan start` in a headless `Bun.WebView`. */
+export class CsrE2eHarness {
+  readonly origin: string;
+  readonly #view: Bun.WebView;
+  readonly #server: CsrE2eServer | null;
+  readonly #lang: string;
+  readonly #mobileTarget: string;
+  readonly #edited = new Map<string, string>();
+  #marker = "";
+
+  private constructor(options: {
+    origin: string;
+    view: Bun.WebView;
+    server: CsrE2eServer | null;
+    lang: string;
+    mobileTarget: string;
+  }) {
+    this.origin = options.origin;
+    this.#view = options.view;
+    this.#server = options.server;
+    this.#lang = options.lang;
+    this.#mobileTarget = options.mobileTarget;
+  }
+
+  /** E2E suites run only with `AKAN_CSR_E2E=1`: they boot a dev server and a browser. */
+  static get enabled() {
+    return process.env.AKAN_CSR_E2E === "1";
+  }
+
+  static async start(options: CsrE2eOptions): Promise<CsrE2eHarness> {
+    const workspaceRoot = options.workspaceRoot ?? CsrE2eHarness.#findWorkspaceRoot();
+    const url = options.url ?? process.env.AKAN_CSR_E2E_URL;
+    const port = options.port ?? Number(process.env.AKAN_CSR_E2E_PORT ?? DEFAULT_PORT);
+    const server = url ? null : await CsrE2eHarness.#startServer({ ...options, workspaceRoot, port });
+    const origin = new URL(url ?? `http://localhost:${port}`).origin;
+    try {
+      await CsrE2eHarness.#waitForHealth(origin, server, options.startTimeoutMs ?? 180_000);
+      const { width, height } = { width: 390, height: 844, ...options.viewport };
+      const backend = options.backend ?? CsrE2eHarness.#defaultBackend();
+      //? `url: false` spawns a fresh Chrome instead of attaching to one the developer runs with remote debugging on.
+      const view = new Bun.WebView({
+        width,
+        height,
+        backend: backend === "chrome" ? { type: "chrome", url: false } : backend,
+      });
+      return new CsrE2eHarness({
+        origin,
+        view,
+        server,
+        lang: options.lang ?? "en",
+        mobileTarget: options.mobileTarget ?? "e2e",
+      });
+    } catch (error) {
+      await CsrE2eHarness.#stopServer(server);
+      throw error;
+    }
+  }
+
+  /** Loads `path` (without the locale) as a CSR page and plants the marker `reloaded()` checks. */
+  async open(path: string) {
+    const url = new URL(`/${this.#lang}${path === "/" ? "" : path}`, this.origin);
+    url.searchParams.set("csr", "true");
+    url.searchParams.set("akanMobileTarget", this.#mobileTarget);
+    await this.#view.navigate(url.toString());
+    await this.#markBoot();
+  }
+
+  /** Reloads the page where it is, as a WebView does after its content process died, and marks the new boot. */
+  async reload() {
+    await this.#view.reload();
+    //? On the WebKit backend `reload()` resolves before the old document is gone; its marker going is the reload.
+    await this.waitFor(
+      (key: string, previous: string) => (window as unknown as Record<string, string | undefined>)[key] !== previous,
+      { args: [RELOAD_MARKER, this.#marker], timeout: 30_000 },
+    );
+    await this.#markBoot();
+  }
+
+  async #markBoot() {
+    await this.waitFor(() => document.querySelector('[id^="pageContainer-"]') !== null, { timeout: 30_000 });
+    await Bun.sleep(SETTLE_MS);
+    this.#marker = Math.random().toString(36).slice(2);
+    await this.evaluate(
+      (key: string, value: string) => {
+        (window as unknown as Record<string, string>)[key] = value;
+      },
+      RELOAD_MARKER,
+      this.#marker,
+    );
+  }
+
+  /** Reports the document as `state` and tells the page, as an app moving to or from the background does. */
+  async setVisibility(state: "hidden" | "visible") {
+    await this.evaluate((next: string) => {
+      Object.defineProperty(document, "visibilityState", { value: next, configurable: true });
+      document.dispatchEvent(new Event("visibilitychange"));
+    }, state);
+    await Bun.sleep(50);
+  }
+
+  //? The CSR frame's own dev sync-navigation event: it calls the app router's push/replace, as a click would.
+  //? The frame drops a navigation that starts while a transition runs, so each one waits the transition out.
+  async navigate(href: string, kind: "push" | "replace" = "push", { settleMs = SETTLE_MS } = {}) {
+    const target = new URL(href, this.origin);
+    await this.evaluate(
+      (next: string, how: string) => {
+        window.dispatchEvent(new CustomEvent("akan:sync-navigation", { detail: { href: next, kind: how } }));
+      },
+      href,
+      kind,
+    );
+    await this.waitFor(
+      (pathname: string, search: string) =>
+        location.pathname.endsWith(pathname) &&
+        [...new URLSearchParams(search)].every(
+          ([key, value]) => new URLSearchParams(location.search).get(key) === value,
+        ),
+      { args: [target.pathname, target.search], timeout: 10_000 },
+    );
+    await Bun.sleep(settleMs);
+  }
+
+  /** A history back through popstate, the path a native back button or a browser back takes. */
+  async back({ settleMs = SETTLE_MS } = {}) {
+    await this.go(-1, { settleMs });
+  }
+
+  async go(delta: number, { settleMs = SETTLE_MS } = {}) {
+    const before = await this.currentPath();
+    await this.evaluate((steps: number) => {
+      window.history.go(steps);
+    }, delta);
+    await this.waitFor((path: string) => window.location.pathname + window.location.search !== path, {
+      args: [before],
+      timeout: 10_000,
+    });
+    await Bun.sleep(settleMs);
+  }
+
+  /**
+   * Runs `fn` in the page. Only its source crosses, so it closes over nothing; `args` and the result travel as JSON.
+   */
+  async evaluate<Args extends unknown[], Result>(fn: (...args: Args) => Result, ...args: Args) {
+    return await this.#view.evaluate<Awaited<Result>>(`(${fn.toString()})(...${JSON.stringify(args)})`);
+  }
+
+  //? A poll that lands while the page reloads rejects; it is retried, so a wait spans a reload.
+  async waitFor<Args extends unknown[]>(
+    predicate: (...args: Args) => unknown,
+    { timeout = 5_000, args = [] as unknown as Args }: { timeout?: number; args?: Args } = {},
+  ) {
+    const deadline = Date.now() + timeout;
+    let lastError: unknown = null;
+    for (;;) {
+      try {
+        if (await this.evaluate(predicate, ...args)) return;
+        lastError = null;
+      } catch (error) {
+        lastError = error;
+      }
+      if (Date.now() >= deadline) break;
+      await Bun.sleep(50);
+    }
+    throw new Error(`[csr-e2e] waitFor timed out after ${timeout}ms: ${predicate.toString()}`, { cause: lastError });
+  }
+
+  async currentPath() {
+    return await this.evaluate(() => window.location.pathname + window.location.search);
+  }
+
+  async containers(): Promise<CsrE2ePageContainer[]> {
+    return await this.evaluate(() =>
+      [...document.querySelectorAll<HTMLElement>('[id^="pageContainer-"]')].map((element) => ({
+        key: element.id.slice("pageContainer-".length),
+        path: element.dataset.path ?? element.id.slice("pageContainer-".length),
+        hidden: getComputedStyle(element).display === "none",
+        inert: element.inert || element.closest("[inert]") !== null,
+        ariaHidden: element.closest('[aria-hidden="true"]') !== null,
+      })),
+    );
+  }
+
+  async probe(name: string): Promise<CsrE2eProbe | null> {
+    return await this.evaluate(
+      (probeName: string) =>
+        (window as unknown as { __akanE2eProbes?: Record<string, CsrE2eProbe> }).__akanE2eProbes?.[probeName] ?? null,
+      name,
+    );
+  }
+
+  /** Ticks a probe gained over `ms` — 0 while its page's effects are paused. */
+  async ticksOver(name: string, ms = 400) {
+    const before = (await this.probe(name))?.ticks ?? 0;
+    await Bun.sleep(ms);
+    return ((await this.probe(name))?.ticks ?? 0) - before;
+  }
+
+  /** The tool names the in-page agent is offered right now, built-ins included. */
+  async agentTools(): Promise<string[]> {
+    return await this.evaluate(() => {
+      const holder = globalThis as unknown as {
+        [key: symbol]: { snapshot: () => { tools: { name: string }[] } } | undefined;
+      };
+      return holder[Symbol.for("useAgentic.sharedSurface")]?.snapshot().tools.map((tool) => tool.name) ?? [];
+    });
+  }
+
+  /** Text of every rendered match; `{ mounted: true }` reads hidden ones too, which is how a parked page is seen. */
+  async text(selector: string, { mounted = false }: { mounted?: boolean } = {}) {
+    return await this.evaluate(
+      (target: string, all: boolean) =>
+        [...document.querySelectorAll<HTMLElement>(target)]
+          .filter((element) => all || element.checkVisibility())
+          .map((element) => element.textContent ?? ""),
+      selector,
+      mounted,
+    );
+  }
+
+  /** Waits until the rendered matches read `expected`, for a step whose cost is a mount rather than a transition. */
+  async waitForText(selector: string, expected: string[], { timeout = 5_000 } = {}) {
+    await this.waitFor(
+      (target: string, want: string[]) =>
+        JSON.stringify(
+          [...document.querySelectorAll<HTMLElement>(target)]
+            .filter((element) => element.checkVisibility())
+            .map((element) => element.textContent ?? ""),
+        ) === JSON.stringify(want),
+      { args: [selector, expected], timeout },
+    );
+  }
+
+  async values(selector: string) {
+    return await this.evaluate(
+      (target: string) => [...document.querySelectorAll<HTMLInputElement>(target)].map((element) => element.value),
+      selector,
+    );
+  }
+
+  //? `Bun.WebView.type` inserts into the focused element as a paste does: `input` fires, `keydown` does not.
+  async type(selector: string, text: string) {
+    const focused = await this.evaluate((target: string) => {
+      const element = document.querySelector<HTMLElement>(target);
+      element?.focus();
+      return element !== null && document.activeElement === element;
+    }, selector);
+    if (!focused) throw new Error(`[csr-e2e] type: ${selector} is not a focusable element on the page`);
+    await this.#view.type(text);
+  }
+
+  /** Whether the page reloaded since `open()`: the boot marker lives only in the page `open()` loaded. */
+  async reloaded() {
+    const marker = await this.evaluate(
+      (key: string) => (window as unknown as Record<string, string | undefined>)[key] ?? "",
+      RELOAD_MARKER,
+    ).catch(() => "");
+    return marker !== this.#marker;
+  }
+
+  /** Rewrites a workspace file for the duration of `run`, and always puts the original back. */
+  async editSource<T>(file: string, transform: (source: string) => string, run: () => Promise<T>): Promise<T> {
+    const absolute = path.resolve(file);
+    const original = this.#edited.get(absolute) ?? (await Bun.file(absolute).text());
+    const next = transform(original);
+    if (next === original) throw new Error(`[csr-e2e] editSource left ${file} unchanged`);
+    this.#edited.set(absolute, original);
+    await Bun.write(absolute, next);
+    try {
+      return await run();
+    } finally {
+      await Bun.write(absolute, original);
+      this.#edited.delete(absolute);
+    }
+  }
+
+  async close() {
+    for (const [file, original] of this.#edited) await Bun.write(file, original);
+    this.#edited.clear();
+    this.#view.close();
+    await CsrE2eHarness.#stopServer(this.#server);
+  }
+
+  static #defaultBackend() {
+    const requested = process.env.AKAN_CSR_E2E_BACKEND;
+    if (requested === "webkit" || requested === "chrome") return requested;
+    return process.platform === "darwin" ? "webkit" : "chrome";
+  }
+
+  static #findWorkspaceRoot() {
+    let dir = import.meta.dir;
+    for (;;) {
+      if (existsSync(path.join(dir, "pkgs/@akanjs/cli/build.ts"))) return dir;
+      const parent = path.dirname(dir);
+      if (parent === dir) throw new Error("[csr-e2e] workspace root not found above the harness");
+      dir = parent;
+    }
+  }
+
+  static async #startServer({
+    app,
+    port,
+    env = {},
+    workspaceRoot,
+  }: CsrE2eOptions & { port: number; workspaceRoot: string }): Promise<CsrE2eServer> {
+    const cli = path.join(workspaceRoot, "dist/pkgs/@akanjs/cli/index.js");
+    if (!(await Bun.file(cli).exists()))
+      throw new Error(`[csr-e2e] ${cli} is missing; build the CLI first (bun pkgs/@akanjs/cli/build.ts)`);
+    const logDir = path.join(workspaceRoot, "local", "csr-e2e");
+    await mkdir(logDir, { recursive: true });
+    const logPath = path.join(logDir, `${app}-${port}.log`);
+    //? Its own process group, so stopping it reaches the gateway, the builder and every replica it spawned.
+    const proc = Bun.spawn(["bun", cli, "start", app, "--plain"], {
+      cwd: workspaceRoot,
+      env: { ...process.env, AKAN_DEV_PORT: String(port), ...env },
+      stdout: Bun.file(logPath),
+      stderr: Bun.file(logPath.replace(/\.log$/, ".err.log")),
+      detached: true,
+    });
+    return { proc, logPath };
+  }
+
+  static async #waitForHealth(origin: string, server: CsrE2eServer | null, timeoutMs: number) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (server && server.proc.exitCode !== null)
+        throw new Error(`[csr-e2e] akan start exited with ${server.proc.exitCode}; see ${server.logPath}`);
+      const ok = await fetch(`${origin}/_akan/app/health`)
+        .then((res) => res.ok)
+        .catch(() => false);
+      if (ok) return;
+      await Bun.sleep(500);
+    }
+    throw new Error(
+      `[csr-e2e] ${origin} did not become healthy in ${timeoutMs}ms${server ? `; see ${server.logPath}` : ""}`,
+    );
+  }
+
+  static async #stopServer(server: CsrE2eServer | null) {
+    if (!server || server.proc.exitCode !== null) return;
+    const group = -server.proc.pid;
+    const signal = (name: NodeJS.Signals) => {
+      try {
+        process.kill(group, name);
+      } catch {
+        // The group is already gone.
+      }
+    };
+    signal("SIGINT");
+    const exited = await Promise.race([server.proc.exited.then(() => true), Bun.sleep(15_000).then(() => false)]);
+    if (!exited) signal("SIGKILL");
+  }
+}

package/csrE2e/csrFastRefresh.e2e.test.ts

@@ -0,0 +1,233 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import path from "node:path";
+import { CsrE2eHarness } from "./csrE2eHarness.fixture";
+
+const TAB_A = "/e2e/stack/tab-a";
+const workspaceRoot = path.resolve(import.meta.dir, "../../../..");
+const probeFile = path.join(workspaceRoot, "apps/minimal/ui/StackProbe.tsx");
+const tabAFile = path.join(workspaceRoot, "apps/minimal/page/(home)/e2e/stack/tab-a.tsx");
+const tabBFile = path.join(workspaceRoot, "apps/minimal/page/(home)/e2e/stack/tab-b.tsx");
+const itemFile = path.join(workspaceRoot, "apps/minimal/page/(home)/e2e/stack/item.tsx");
+const layoutFile = path.join(workspaceRoot, "apps/minimal/page/(home)/e2e/_layout.tsx");
+const storeFile = path.join(workspaceRoot, "apps/minimal/lib/_minimal/minimal.store.ts");
+const port = Number(process.env.AKAN_CSR_E2E_FAST_REFRESH_PORT ?? 8491);
+
+interface CsrWindow {
+  __akan?: { generation: number; inspect(): { modules: number } };
+  __AKAN_CSR_LAST_UPDATE__?: { generation: number; executed: string[] };
+}
+
+const markProbe = (source: string) =>
+  source.replace("data-e2e-probe={name}>", 'data-e2e-probe={name} data-e2e-hot="1">');
+const ownSources = (executed: string[] = []) => executed.filter((id) => !id.includes("/.akan/generated/"));
+
+describe.skipIf(!CsrE2eHarness.enabled)("CSR Fast Refresh (minimal, AKAN_DEV_CSR=registry)", () => {
+  let csr: CsrE2eHarness;
+
+  beforeAll(async () => {
+    csr = await CsrE2eHarness.start({ app: "minimal", port, env: { AKAN_DEV_CSR: "registry" } });
+  }, 240_000);
+
+  afterAll(async () => {
+    // biome-ignore lint/suspicious/noUnnecessaryConditions: unassigned when beforeAll threw before the harness started
+    await csr?.close();
+  }, 60_000);
+
+  const lastUpdate = async () =>
+    await csr.evaluate(() => (window as unknown as CsrWindow).__AKAN_CSR_LAST_UPDATE__ ?? null);
+  const generation = async () => await csr.evaluate(() => (window as unknown as CsrWindow).__akan?.generation);
+  const generationPasses = async (previous: number) =>
+    await csr.waitFor((last: number) => ((window as unknown as CsrWindow).__akan?.generation ?? 0) > last, {
+      args: [previous],
+      timeout: 20_000,
+    });
+  const inputValue = async () =>
+    await csr.evaluate(
+      () => (document.querySelector('[data-e2e-probe="tab-a"] input') as HTMLInputElement | null)?.value,
+    );
+  const tabAItemIdIs = async (itemId: string) =>
+    await csr.waitFor(
+      (expected: string) =>
+        document.querySelector('[data-e2e-probe="tab-a"] [data-e2e="item-id"]')?.textContent === expected,
+      { args: [itemId], timeout: 30_000 },
+    );
+
+  test("the page boots from the registry dev bundle", async () => {
+    await csr.open(TAB_A);
+    const booted = await csr.evaluate(() => {
+      const runtime = (window as unknown as CsrWindow).__akan;
+      return { generation: runtime?.generation, modules: runtime?.inspect().modules ?? 0 };
+    });
+    expect(booted.generation).toBeGreaterThan(0);
+    expect(booted.modules).toBeGreaterThan(100);
+  }, 60_000);
+
+  test("a component edit applies in place, keeping hook state and the DOM", async () => {
+    await csr.open(TAB_A);
+    await csr.type('[data-e2e-probe="tab-a"] input', "typed");
+    const mountId = (await csr.probe("tab-a"))?.mountId;
+    await csr.editSource(probeFile, markProbe, async () => {
+      await csr.waitFor(() => document.querySelector('[data-e2e-hot="1"]') !== null, { timeout: 20_000 });
+      expect(await csr.reloaded()).toBe(false);
+      expect((await csr.probe("tab-a"))?.mountId).toBe(mountId);
+      expect(await inputValue()).toBe("typed");
+      expect((await lastUpdate())?.executed).toEqual(["apps/minimal/ui/StackProbe.tsx"]);
+    });
+    await csr.waitFor(() => document.querySelector('[data-e2e-hot="1"]') === null, { timeout: 20_000 });
+    expect(await csr.reloaded()).toBe(false);
+  }, 90_000);
+
+  test("a store edit re-runs the store root and nothing above it", async () => {
+    await csr.open(TAB_A);
+    await csr.type('[data-e2e-probe="tab-a"] input', "kept");
+    const before = (await generation()) ?? 0;
+    const edited = await csr.editSource(
+      storeFile,
+      (source) => source.replace("  // action\n", "  // action\n  touchForE2e() {\n    this.set({});\n  }\n"),
+      async () => {
+        await generationPasses(before);
+        expect(await csr.reloaded()).toBe(false);
+        expect(((await lastUpdate())?.executed ?? []).sort()).toEqual([
+          "apps/minimal/lib/_minimal/minimal.store.ts",
+          "apps/minimal/lib/st.ts",
+        ]);
+        expect(await inputValue()).toBe("kept");
+        return (await generation()) ?? 0;
+      },
+    );
+    await generationPasses(edited);
+  }, 90_000);
+
+  test("a build error shows the overlay without reloading, and the fix applies in place", async () => {
+    await csr.open(TAB_A);
+    await csr.editSource(
+      probeFile,
+      (source) => source.replace("  return (\n", "  return ((\n"),
+      async () => {
+        await csr.waitFor(() => document.querySelector('.__akan_hmr_overlay[data-status="error"]') !== null, {
+          timeout: 20_000,
+        });
+        expect(await csr.reloaded()).toBe(false);
+      },
+    );
+    await csr.editSource(probeFile, markProbe, async () => {
+      await csr.waitFor(() => document.querySelector('[data-e2e-hot="1"]') !== null, { timeout: 20_000 });
+      expect(await csr.reloaded()).toBe(false);
+    });
+    await csr.waitFor(() => document.querySelector('[data-e2e-hot="1"]') === null, { timeout: 20_000 });
+  }, 90_000);
+
+  test("a page edit swaps the route in place, keeping the page's state", async () => {
+    await csr.open(TAB_A);
+    await csr.type('[data-e2e-probe="tab-a"] input', "kept");
+    const mountId = (await csr.probe("tab-a"))?.mountId;
+    await csr.editSource(
+      tabAFile,
+      (source) => source.replace('name="tab-a"', 'name="tab-a" itemId="edited"'),
+      async () => {
+        await tabAItemIdIs("edited");
+        expect(await csr.reloaded()).toBe(false);
+        expect((await csr.probe("tab-a"))?.mountId).toBe(mountId);
+        expect(await inputValue()).toBe("kept");
+        expect((await lastUpdate())?.executed).toEqual(["apps/minimal/page/(home)/e2e/stack/tab-a.tsx"]);
+      },
+    );
+    await tabAItemIdIs("");
+    expect(await csr.reloaded()).toBe(false);
+  }, 90_000);
+
+  test("an edit to another page leaves the current page's render alone", async () => {
+    await csr.open(TAB_A);
+    const before = (await generation()) ?? 0;
+    const renders = (await csr.probe("tab-a"))?.renders;
+    const edited = await csr.editSource(
+      tabBFile,
+      (source) => source.replace('name="tab-b"', 'name="tab-b" itemId="edited"'),
+      async () => {
+        await generationPasses(before);
+        await Bun.sleep(300);
+        expect((await lastUpdate())?.executed).toEqual(["apps/minimal/page/(home)/e2e/stack/tab-b.tsx"]);
+        expect((await csr.probe("tab-a"))?.renders).toBe(renders);
+        expect(await csr.reloaded()).toBe(false);
+        return (await generation()) ?? 0;
+      },
+    );
+    await generationPasses(edited);
+  }, 90_000);
+
+  test("a layout edit swaps the layout in place, keeping the page under it", async () => {
+    await csr.open(TAB_A);
+    await csr.type('[data-e2e-probe="tab-a"] input', "kept");
+    const mountId = (await csr.probe("tab-a"))?.mountId;
+    await csr.editSource(
+      layoutFile,
+      (source) => source.replace("<>{children}</>", '<>{children}<span data-e2e-layout="edited" /></>'),
+      async () => {
+        await csr.waitFor(() => document.querySelector('[data-e2e-layout="edited"]') !== null, { timeout: 30_000 });
+        expect(await csr.reloaded()).toBe(false);
+        expect((await csr.probe("tab-a"))?.mountId).toBe(mountId);
+        expect(await inputValue()).toBe("kept");
+        //? A layout reaches the entry through the root-layout wrapper route discovery generates around it.
+        expect(ownSources((await lastUpdate())?.executed)).toEqual(["apps/minimal/page/(home)/e2e/_layout.tsx"]);
+      },
+    );
+    await csr.waitFor(() => document.querySelector('[data-e2e-layout="edited"]') === null, { timeout: 30_000 });
+    expect(await csr.reloaded()).toBe(false);
+  }, 90_000);
+
+  test("a page edit keeps the stack: the page it covers comes back with its state", async () => {
+    await csr.open(TAB_A);
+    await csr.type('[data-e2e-probe="tab-a"] input', "under");
+    const mountId = (await csr.probe("tab-a"))?.mountId;
+    await csr.navigate("/e2e/stack/item?id=1");
+    const currentItemId = async () =>
+      await csr.text('[id^="pageContainer-"]:not([aria-hidden="true"]) [data-e2e-probe="item"] [data-e2e="item-id"]');
+    await csr.editSource(
+      itemFile,
+      (source) => source.replace('itemId={id ?? ""}', 'itemId={"edited-" + (id ?? "")}'),
+      async () => {
+        await csr.waitFor(
+          () =>
+            [...document.querySelectorAll('[data-e2e-probe="item"] [data-e2e="item-id"]')].some(
+              (element) => element.textContent === "edited-1",
+            ),
+          { timeout: 30_000 },
+        );
+        expect(await currentItemId()).toEqual(["edited-1"]);
+        expect((await lastUpdate())?.executed).toEqual(["apps/minimal/page/(home)/e2e/stack/item.tsx"]);
+      },
+    );
+    await csr.waitFor(
+      () =>
+        [...document.querySelectorAll('[data-e2e-probe="item"] [data-e2e="item-id"]')].some(
+          (element) => element.textContent === "1",
+        ),
+      { timeout: 30_000 },
+    );
+    await csr.back();
+    expect(await inputValue()).toBe("under");
+    expect((await csr.probe("tab-a"))?.mountId).toBe(mountId);
+    expect(await csr.reloaded()).toBe(false);
+  }, 90_000);
+});
+
+describe.skipIf(!CsrE2eHarness.enabled)("CSR single-file artifact (minimal, AKAN_DEV_CSR=artifact)", () => {
+  let csr: CsrE2eHarness;
+
+  beforeAll(async () => {
+    csr = await CsrE2eHarness.start({ app: "minimal", port, env: { AKAN_DEV_CSR: "artifact" } });
+  }, 240_000);
+
+  afterAll(async () => {
+    // biome-ignore lint/suspicious/noUnnecessaryConditions: unassigned when beforeAll threw before the harness started
+    await csr?.close();
+  }, 60_000);
+
+  test("a component edit reloads the tab onto the rebuilt artifact", async () => {
+    await csr.open(TAB_A);
+    await csr.editSource(probeFile, markProbe, async () => {
+      await csr.waitFor(() => document.querySelector('[data-e2e-hot="1"]') !== null, { timeout: 30_000 });
+      expect(await csr.reloaded()).toBe(true);
+    });
+  }, 90_000);
+});