partial-solidjs 0.0.0 → 0.0.1

package/README.md

@@ -0,0 +1,55 @@
+# partial-solidjs
+
+State-preserving renderer for prefix-growing streaming Solid/TSX. Solid ships neither an HMR runtime nor a cross-render
+reconciler, so this package owns both gaps: a `createSignal` shim that survives recompiles, and an in-place DOM reconcile
+for append-only streamed frames.
+
+## Input
+
+```ts
+import { SolidRenderer } from "partial-solidjs";
+
+const renderer = await SolidRenderer.create(document.getElementById("preview"));
+renderer.pushCode('import { createSignal } from "solid-js";\nexport default function App() {\n  const [count, setCount] = createSignal(0);\n  return <button onClick={() => setCount(count() + 1)}>{count()}');
+```
+
+## Output
+
+- `createSolidTsxCompiler()` (Node, `@babel/core`) and `createBrowserSolidTsxCompiler()` (`@babel/standalone`) strip
+  TypeScript and run the Solid JSX transform in a single pass; `partial: true` completes the prefix through `partial-tsx`'s
+  `normalizeGeneratedTsx` first.
+- `SolidRenderer` mounts via `solid-js/web`. `pushCode` appends a streaming frame, `render` replaces the buffer, and
+  `finish` installs one clean reactive root.
+
+## State preservation
+
+`SolidStatePreserver` re-binds `createSignal` through a Blob-URL shim of `solid-js`, so the app's signals are created by
+the renderer and a recompile reattaches them instead of resetting.
+
+- Cells are indexed by source-order `createSignal(` call. A frame with the same signature reuses the previous cells; a
+  changed signature resets them.
+- A cell is `touched` once the app calls its setter. Only touched cells keep their value — an untouched cell re-seeds
+  from the newest frame's initializer on every pass, so a truncated `createSignal("")` converges to the final value.
+- Signals created after commit (lazy children) fall through to the real `createSignal` so they cannot alias a preserved
+  cell.
+
+## Corner Cases
+
+- **Streaming reconcile.** Solid's effects capture their own fresh nodes, so swapping trees every token destroys hover,
+  focus and in-flight clicks. `patchFrame` reconciles instead: keep the committed nodes, patch their text/attributes, and
+  adopt the newly streamed-in tail. Gated on `isFramePatchable` (committed children are a structural prefix of the staged
+  ones) and on the frame reusing the same signal cells. `finish()` drops the kept root.
+- **Visible-regression hold.** A streamed frame that drops text length or structural element count versus the committed
+  one is held back. Only a setter running inside a DOM interaction releases the hold — a timer or fetch callback cannot
+  commit a shorter partial.
+- **Focus.** A full-swap commit replays focus via `captureFocusWithin` / `restoreFocusWithin` (child-index path plus text
+  selection). A structure-shifting frame can land the caret on a different element; that positional limit is accepted.
+- **Signature blind spots.** `getSolidSignalSignature` masks comments/strings/templates first, but JSX text is lexed like
+  code (an apostrophe can open a phantom string and swallow a later `createSignal(`) and template literals are opaque
+  backtick-to-backtick. Tracked in #1208.
+
+## Test
+
+```sh
+bun test lib/partial-solidjs
+```

package/package.json

@@ -1,11 +1,35 @@
 {
   "name": "partial-solidjs",
-  "version": "0.0.0",
-  "description": "Placeholder for partial-solidjs",
-  "main": "index.js",
-  "scripts": {},
-  "keywords": [],
-  "author": "muspi-merol (https://www.npmjs.com/~muspi-merol)",
-  "license": "UNLICENSED",
-  "private": false
-}
+  "description": "A state-preserving renderer for prefix-growing streaming Solid/TSX.",
+  "version": "0.0.1",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MindLab-Research/macaron-genui-demo",
+    "directory": "lib/partial-solidjs"
+  },
+  "exports": {
+    ".": "./src/runtime.ts",
+    "./compiler": "./src/compiler.ts",
+    "./browser-compiler": "./src/browser-compiler.ts"
+  },
+  "browser": {
+    "./src/nodeWasm.ts": false
+  },
+  "files": [
+    "src/**/*",
+    "!src/**/*.test.*"
+  ],
+  "dependencies": {
+    "@babel/core": "^7.29.7",
+    "@babel/preset-typescript": "^7.29.7",
+    "@babel/standalone": "^7.29.10",
+    "@esm.sh/tsx": "^1.5.3",
+    "babel-preset-solid": "^1.9.16",
+    "partial-tsx": "~0.0.5"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.9.15"
+  },
+  "sideEffects": false
+}

package/src/babel.d.ts

@@ -0,0 +1,18 @@
+declare module "@babel/core" {
+  export function transformAsync(code: string, options: Record<string, unknown>): Promise<{ code?: string | null } | null>;
+}
+
+declare module "@babel/preset-typescript" {
+  const preset: unknown;
+  export default preset;
+}
+
+declare module "babel-preset-solid" {
+  const preset: unknown;
+  export default preset;
+}
+
+declare module "@babel/standalone" {
+  export const availablePresets: Record<string, unknown>;
+  export function transform(code: string, options: Record<string, unknown>): { code?: string | null };
+}

package/src/browser-compiler.ts

@@ -0,0 +1,42 @@
+import { createSolidTsxCompilerWithTransform, SOLID_JSX_PRESET_OPTIONS, SOLID_TYPESCRIPT_PRESET_OPTIONS, type SolidTsxCompiler } from "./compilerCore";
+
+type BabelStandalone = typeof import("@babel/standalone");
+
+let babelPromise: Promise<BabelStandalone> | null = null;
+let solidPresetPromise: Promise<unknown> | null = null;
+// Null the cached promise on failure so a transient chunk-load error (deploy skew, flaky network) doesn't wedge the
+// browser compiler for the whole session — same retry contract as compilerCore's initPromise.
+const loadBabel = () =>
+  (babelPromise ??= import("@babel/standalone").catch((error) => {
+    babelPromise = null;
+    throw error;
+  }));
+const loadSolidPreset = async () => {
+  const runtime = globalThis as { process?: { env?: Record<string, string | undefined> } };
+  // Babel 7 helper packages still read process.env at module init after Vite wraps the CJS preset for browsers.
+  runtime.process ??= { env: {} };
+  runtime.process.env ??= {};
+  const preset = (solidPresetPromise ??= import("babel-preset-solid").catch((error) => {
+    solidPresetPromise = null;
+    throw error;
+  }));
+  const module = (await preset) as { default?: unknown };
+  return module.default ?? module;
+};
+const transformSolidTsx = async (code: string, filename: string) => {
+  // compilerCore restores Error.prepareStackTrace around this call (@babel/standalone installs a global stack rewriter under Node).
+  const [Babel, solidPreset] = await Promise.all([loadBabel(), loadSolidPreset()]);
+  const result = Babel.transform(code, {
+    filename,
+    presets: [
+      [Babel.availablePresets.typescript, SOLID_TYPESCRIPT_PRESET_OPTIONS],
+      [solidPreset, SOLID_JSX_PRESET_OPTIONS],
+    ],
+    sourceType: "module",
+  });
+  return result.code;
+};
+
+export function createBrowserSolidTsxCompiler(): SolidTsxCompiler {
+  return createSolidTsxCompilerWithTransform(transformSolidTsx);
+}

package/src/browserAssert.cjs

@@ -0,0 +1,9 @@
+function assert(value, message) {
+  if (!value) throw new Error(message || "Assertion failed.");
+}
+
+assert.fail = function fail(message) {
+  throw new Error(message || "Assertion failed.");
+};
+
+module.exports = assert;

package/src/compiler.ts

@@ -0,0 +1,23 @@
+import { transformAsync } from "@babel/core";
+import typescriptPreset from "@babel/preset-typescript";
+import solidPreset from "babel-preset-solid";
+import { createSolidTsxCompilerWithTransform, SOLID_JSX_PRESET_OPTIONS, SOLID_TYPESCRIPT_PRESET_OPTIONS, type SolidTsxCompiler } from "./compilerCore";
+
+const transformSolidTsx = async (code: string, filename: string) => {
+  // compilerCore restores Error.prepareStackTrace around this call (Babel installs a global stack rewriter under Node).
+  const result = await transformAsync(code, {
+    filename,
+    presets: [
+      [typescriptPreset, SOLID_TYPESCRIPT_PRESET_OPTIONS],
+      [solidPreset, SOLID_JSX_PRESET_OPTIONS],
+    ],
+    sourceType: "module",
+  });
+  return result?.code;
+};
+
+export function createSolidTsxCompiler(): SolidTsxCompiler {
+  return createSolidTsxCompilerWithTransform(transformSolidTsx);
+}
+
+export type { CompileOptions, CompileResult, SolidTsxCompiler, RendererImportMap } from "./compilerCore";

package/src/compilerCore.ts

@@ -0,0 +1,57 @@
+import initTsx, { transform as transformTsx } from "@esm.sh/tsx";
+import { normalizeGeneratedTsx } from "partial-tsx";
+
+export type RendererImportMap = { imports?: Record<string, string>; scopes?: Record<string, Record<string, string>>; styles?: string[] };
+export type CompileOptions = { importMap?: RendererImportMap; partial?: boolean; previousCode?: string; filename?: string };
+export type CompileResult = { code: string; source: string; changed: boolean };
+export type SolidTsxCompiler = { compile: (code: string, options?: CompileOptions) => Promise<CompileResult> };
+export type SolidTsxTransform = (code: string, filename: string) => Promise<string | null | undefined>;
+// Shared so the Node (compiler.ts, tested) and browser (@babel/standalone) transform paths stay byte-identical; a
+// one-sided edit to these options would make the two emit different output for the same source.
+export const SOLID_TYPESCRIPT_PRESET_OPTIONS = { isTSX: true, allExtensions: true, onlyRemoveTypeImports: true };
+export const SOLID_JSX_PRESET_OPTIONS = { generate: "dom" };
+const textDecoder = new TextDecoder();
+
+let initPromise: Promise<unknown> | null = null;
+// A DOM shim in a Node test process still needs the on-disk WASM, not a browser asset URL.
+const isNodeLike = typeof process !== "undefined" && Boolean((process as { versions?: { node?: string } }).versions?.node);
+const initCompiler = () =>
+  (initPromise ??= (async () => {
+    try {
+      if (isNodeLike) return initTsx(await (await import("./nodeWasm")).loadNodeWasm());
+    } catch {
+      // Environments without a filesystem (e.g. web workers) fall back to wasm-bindgen's asset resolution below.
+    }
+    // No argument: wasm-bindgen resolves the neighboring .wasm asset without a Vite-only ?url import. #1690
+    return initTsx();
+  })().catch((error) => {
+    initPromise = null;
+    throw error;
+  }));
+// Babel installs a process-global Error.prepareStackTrace rewriter. Under Node restore the native hook so Vite/Rollup error
+// formatting and later standalone tests aren't polluted; in the browser (window defined) keep Babel's hook untouched.
+const withNodeStackTraceRestored = async <T>(run: () => Promise<T>) => {
+  if (typeof window !== "undefined") return run();
+  const previous = Error.prepareStackTrace;
+  try {
+    return await run();
+  } finally {
+    if (previous === undefined) delete (Error as { prepareStackTrace?: typeof Error.prepareStackTrace }).prepareStackTrace;
+    else Error.prepareStackTrace = previous;
+  }
+};
+
+export function createSolidTsxCompilerWithTransform(transformSolidTsx: SolidTsxTransform): SolidTsxCompiler {
+  return {
+    async compile(code, options = {}) {
+      const filename = options.filename ?? "_.tsx";
+      const source = options.partial ? normalizeGeneratedTsx(code) : code;
+      // WASM init and the Solid/Babel transform are independent; overlap them so first compile doesn't serialize the two.
+      const [solidCode] = await Promise.all([withNodeStackTraceRestored(() => transformSolidTsx(source, filename)), initCompiler()]);
+      if (!solidCode) throw new Error("Solid JSX transform produced no code.");
+      const result = transformTsx({ filename: filename.replace(/\.tsx$/, ".ts"), code: solidCode, target: "es2022", importMap: options.importMap });
+      const compiled = textDecoder.decode(result.code);
+      return { code: compiled, source, changed: compiled !== options.previousCode };
+    },
+  };
+}

package/src/focusBridge.ts

@@ -0,0 +1,45 @@
+// commitFrame swaps the host's children wholesale (replaceChildren), so any focused input inside the preview loses focus
+// and caret even though its Solid signal value is preserved. captureFocusWithin records the focused node by its child-index
+// path from the host plus its text selection, and restoreFocusWithin replays it onto the freshly committed tree. This
+// element-index path is a separate axis from SolidStatePreserver's createSignal-call-order keying — the two only coincide
+// while structure is stable. A structure-shifting frame (a new sibling element before the focused node) can land the caret
+// on a different element; that is the accepted limit of positional identity here.
+type TextSelection = { start: number; end: number; direction: "forward" | "backward" | "none" };
+export type CapturedFocus = { path: number[]; selection: TextSelection | null };
+
+const isTextEntry = (node: Element): node is HTMLInputElement | HTMLTextAreaElement => {
+  if (node.tagName === "TEXTAREA") return true;
+  if (node.tagName !== "INPUT") return false;
+  // selectionStart throws on number/email/etc.; only these input types expose a text selection.
+  return /^(?:text|search|url|tel|password)$/.test((node as HTMLInputElement).type);
+};
+const readSelection = (node: Element): TextSelection | null => {
+  if (!isTextEntry(node) || node.selectionStart === null || node.selectionEnd === null) return null;
+  return { start: node.selectionStart, end: node.selectionEnd, direction: node.selectionDirection ?? "none" };
+};
+
+export const captureFocusWithin = (host: Element): CapturedFocus | null => {
+  const active = host.ownerDocument.activeElement;
+  if (!active || active === host || !host.contains(active)) return null;
+  const path: number[] = [];
+  for (let node: Element | null = active; node && node !== host; node = node.parentElement) {
+    const parent = node.parentElement;
+    if (!parent) return null;
+    path.unshift(Array.prototype.indexOf.call(parent.children, node));
+  }
+  return { path, selection: readSelection(active) };
+};
+
+const resolvePath = (host: Element, path: number[]): Element | null => {
+  let node: Element | null = host;
+  for (const index of path) node = node?.children[index] ?? null;
+  return node;
+};
+
+export const restoreFocusWithin = (host: Element, captured: CapturedFocus | null) => {
+  if (!captured) return;
+  const target = resolvePath(host, captured.path);
+  if (!(target instanceof host.ownerDocument.defaultView!.HTMLElement)) return;
+  target.focus();
+  if (captured.selection && isTextEntry(target)) target.setSelectionRange(captured.selection.start, captured.selection.end, captured.selection.direction);
+};

package/src/morph.ts

@@ -0,0 +1,158 @@
+// In-place DOM reconcile for streaming Solid frames.
+//
+// Solid has no cross-render reconciliation: each recompiled frame is a brand-new component whose fine-grained effects
+// capture *its own* fresh nodes. Committing a frame by swapping in that fresh tree (`replaceChildren`) therefore
+// destroys and recreates every node each token — so a tab the user is hovering loses its :hover ring on every frame
+// (the flicker) and a mid-stream click lands on a node that was just replaced.
+//
+// Streaming is append-only: the source only grows, so each frame's DOM is the previous frame's DOM plus new trailing
+// nodes and completed tails. That lets us *reconcile* instead of swap — pair existing nodes by index/tag, patch their
+// text and attributes, adopt the newly streamed-in tail nodes, and discard the fresh frame's now-empty root. Existing
+// nodes keep their identity (hover, focus, in-flight clicks, running CSS transitions all survive) while still tracking
+// the stream. The kept live root keeps driving reactivity for the nodes it owns; adopted tail nodes are refreshed by
+// the next frame's reconcile, and the final full render (on `finish`) installs one clean reactive root. This is the
+// reconciliation partial-react gets for free from React's persistent root.
+
+const isElement = (node: Node): node is HTMLElement => node.nodeType === 1;
+
+const trackedEventListeners = Symbol("partial-solidjs:tracked-event-listeners");
+type TrackedEventListener = {
+  type: string;
+  listener: EventListenerOrEventListenerObject;
+  options?: boolean | AddEventListenerOptions;
+  capture: boolean;
+};
+type TrackedEventTarget = EventTarget & { [trackedEventListeners]?: TrackedEventListener[] };
+type EventTargetPrototype = {
+  addEventListener: EventTarget["addEventListener"];
+  removeEventListener: EventTarget["removeEventListener"];
+};
+
+// Native event listeners cannot be enumerated from a DOM node. A streaming frame is rendered into a temporary tree,
+// then its kept nodes are reconciled against the previous tree; delegated Solid handlers are visible as `$$` expandos,
+// but `on:click`/imperative listeners live only in the browser's listener table. Capture listeners while Solid stages
+// a frame so morphing can transfer just those frame-owned listeners onto the reused node without touching listeners an
+// embedding host attached itself (for example a test harness click probe).
+let activeListenerCapture: object | null = null;
+
+const hasEventListenerNodeShape = (value: EventTarget): value is TrackedEventTarget & HTMLElement => (value as Node).nodeType === 1;
+const listenerCapture = (options: boolean | AddEventListenerOptions | undefined) => options === true || (typeof options === "object" && Boolean(options?.capture));
+const getEventTargetPrototype = (target: EventTarget): EventTargetPrototype | null => {
+  let prototype = Object.getPrototypeOf(target) as EventTargetPrototype | null;
+  while (prototype && !Object.prototype.hasOwnProperty.call(prototype, "addEventListener")) prototype = Object.getPrototypeOf(prototype) as EventTargetPrototype | null;
+  return prototype;
+};
+
+const getTrackedListeners = (target: EventTarget) => (target as TrackedEventTarget)[trackedEventListeners];
+const setTrackedListeners = (target: EventTarget, listeners: TrackedEventListener[] | undefined) => {
+  const node = target as TrackedEventTarget;
+  if (listeners?.length) node[trackedEventListeners] = listeners;
+  else delete node[trackedEventListeners];
+};
+
+/** Run a staged Solid render while recording native (non-delegated) listeners added by that frame. */
+export const captureEventListeners = <T>(target: EventTarget, run: () => T) => {
+  const prototype = getEventTargetPrototype(target);
+  if (!prototype) return run();
+  const previousCapture = activeListenerCapture;
+  const originalAdd = prototype.addEventListener;
+  const originalRemove = prototype.removeEventListener;
+  const add = function (this: EventTarget, type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions) {
+    originalAdd.call(this, type, listener, options);
+    if (!activeListenerCapture || !listener || !hasEventListenerNodeShape(this)) return;
+    const listeners = getTrackedListeners(this) ?? [];
+    listeners.push({ type, listener, options, capture: listenerCapture(options) });
+    setTrackedListeners(this, listeners);
+  } as EventTarget["addEventListener"];
+  const remove = function (this: EventTarget, type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions) {
+    originalRemove.call(this, type, listener, options);
+    if (!activeListenerCapture || !listener || !hasEventListenerNodeShape(this)) return;
+    const capture = listenerCapture(options);
+    const listeners = getTrackedListeners(this)?.filter((entry) => !(entry.type === type && entry.listener === listener && entry.capture === capture));
+    setTrackedListeners(this, listeners);
+  } as EventTarget["removeEventListener"];
+  prototype.addEventListener = add;
+  prototype.removeEventListener = remove;
+  activeListenerCapture = {};
+  try {
+    return run();
+  } finally {
+    activeListenerCapture = previousCapture;
+    // A nested capture may have installed its own wrapper. Restore only this layer's wrapper, preserving any outer one.
+    if (prototype.addEventListener === add) prototype.addEventListener = originalAdd;
+    if (prototype.removeEventListener === remove) prototype.removeEventListener = originalRemove;
+  }
+};
+
+const syncNativeEventListeners = (from: HTMLElement, to: HTMLElement) => {
+  const previous = getTrackedListeners(from);
+  const next = getTrackedListeners(to);
+  if (!previous?.length && !next?.length) return;
+  for (const entry of previous ?? []) from.removeEventListener(entry.type, entry.listener, entry.capture);
+  for (const entry of next ?? []) from.addEventListener(entry.type, entry.listener, entry.options);
+  setTrackedListeners(
+    from,
+    next?.map((entry) => ({ ...entry })),
+  );
+};
+
+const sameShape = (a: Node, b: Node) => a.nodeType === b.nodeType && (!isElement(a) || a.tagName === (b as HTMLElement).tagName);
+
+// A frame is reconcilable when the committed children are a structural prefix of the staged ones at every level:
+// matching nodes pair up by index (append-only streams never reorder), and staged extras are newly streamed nodes we
+// adopt. A committed level that is *longer* than the staged one means normalization retracted content; that needs the
+// full-swap path (and its visible-regression gate) instead, so identity reuse only ever extends, never truncates.
+const isNodePatchable = (current: Node, next: Node): boolean => {
+  if (!sameShape(current, next)) return false;
+  if (current.childNodes.length > next.childNodes.length) return false;
+  for (let i = 0; i < current.childNodes.length; i++) if (!isNodePatchable(current.childNodes[i], next.childNodes[i])) return false;
+  return true;
+};
+export const isFramePatchable = (current: ParentNode, next: ChildNode[]): boolean => {
+  if (current.childNodes.length > next.length) return false;
+  for (let i = 0; i < current.childNodes.length; i++) if (!isNodePatchable(current.childNodes[i], next[i])) return false;
+  return true;
+};
+
+const patchAttributes = (from: Element, to: Element) => {
+  for (const attr of to.attributes) if (from.getAttribute(attr.name) !== attr.value) from.setAttribute(attr.name, attr.value);
+  // Snapshot `from`'s attributes: the loop mutates it via removeAttribute, which would disturb a live iteration.
+  for (const attr of Array.from(from.attributes)) if (!to.hasAttribute(attr.name)) from.removeAttribute(attr.name);
+};
+
+// Solid delegates events by stashing the handler as a `$$event` expando on the node and reading it back at dispatch
+// time through one document-level listener. A reused node keeps the handler from the frame that created it, so once a
+// streamed tail *completes* a handler (e.g. an `onClick` that was mid-token last frame), we must copy the newest
+// frame's expandos onto the kept node or the click fires nothing / a stale closure. All frames' handlers close over the
+// same preserved signal cells, so the copied closure targets the right state.
+// `Object.keys`, not `for...in`: Solid assigns these expandos directly onto the node, so they are always own
+// properties, while `for...in` would additionally walk the whole `HTMLElement`/`Element`/`Node` prototype chain.
+const syncDelegatedHandlers = (from: Record<string, unknown>, to: Record<string, unknown>) => {
+  for (const key of Object.keys(from)) if (key.startsWith("$$") && !(key in to)) delete from[key];
+  for (const key of Object.keys(to)) if (key.startsWith("$$")) from[key] = to[key];
+};
+
+const patchNode = (from: ChildNode, to: ChildNode) => {
+  if (!isElement(from) || !isElement(to)) {
+    if (from.nodeValue !== to.nodeValue) from.nodeValue = to.nodeValue; // text or comment marker
+    return;
+  }
+  // Attributes and delegated handlers sync; DOM properties like input.value are left alone — controlled state belongs
+  // to the live root's own effects (over the same cells as the staged frame) and uncontrolled edits must survive.
+  patchAttributes(from, to);
+  syncDelegatedHandlers(from as unknown as Record<string, unknown>, to as unknown as Record<string, unknown>);
+  syncNativeEventListeners(from, to);
+  patchChildren(from, Array.from(to.childNodes));
+};
+
+// Appending moves a staged node out of its staging container into the live tree. That's safe: the moved node survives
+// its origin root's disposal (only nodes still in staging are cleaned up), and until the stream ends the next frame's
+// reconcile keeps it current.
+const patchChildren = (current: ParentNode, next: ChildNode[]) => {
+  const paired = current.childNodes.length;
+  for (let i = 0; i < paired; i++) patchNode(current.childNodes[i], next[i]);
+  for (let i = paired; i < next.length; i++) current.appendChild(next[i]);
+};
+
+// Callers must have confirmed `isFramePatchable` first; the walk assumes every paired node lines up by index and tag.
+export const patchFrame = patchChildren;

package/src/nodeWasm.ts

@@ -0,0 +1,10 @@
+// Keep import.meta.resolve in a Node-only module: a CJS-emitting browser bundler cannot parse that syntax even when
+// a runtime guard would skip it. The package's browser field excludes this module from browser builds. #1717
+// Typed off globalThis so consumers of the raw .ts package do not need @types/bun.
+const bun = (globalThis as { Bun?: { file(path: URL): { arrayBuffer(): Promise<ArrayBuffer> } } }).Bun;
+
+export const loadNodeWasm = async () => {
+  const wasmUrl = new URL(import.meta.resolve("@esm.sh/tsx/pkg/tsx_bg.wasm"));
+  if (bun) return bun.file(wasmUrl).arrayBuffer();
+  return (await import("node:fs/promises")).readFile(wasmUrl);
+};

package/src/preserve.ts

@@ -0,0 +1,190 @@
+import { createSignal as solidCreateSignal } from "solid-js";
+import type { RendererImportMap } from "./compilerCore";
+
+type SignalSetter<T> = (value: T | ((previous: T) => T)) => T;
+// `setter` is the app-facing setter (marks the cell touched); `rawSetter` is Solid's underlying setter used to re-seed an
+// untouched cell from a fuller streamed initializer without flipping `touched`.
+type SignalCell<T = unknown> = { getter: () => T; setter: SignalSetter<T>; rawSetter: SignalSetter<T>; touched: boolean };
+type SolidSignalRuntime = { createSignal<T>(value: T, options?: unknown): [() => T, SignalSetter<T>] };
+type MutationInteractionTracker = () => boolean;
+
+let scopeSerial = 0;
+const runtimeByScope = new Map<string, SolidSignalRuntime>();
+
+const createScope = () => `solid-renderer:${(++scopeSerial).toString(36)}`;
+const defineGlobalRuntime = () => {
+  const runtime = globalThis as typeof globalThis & { __partialSolidSignalRuntime?: Map<string, SolidSignalRuntime> };
+  runtime.__partialSolidSignalRuntime ??= runtimeByScope;
+  return runtime.__partialSolidSignalRuntime;
+};
+
+const skipQuotedString = (code: string, index: number) => {
+  const quote = code[index++];
+  while (index < code.length) {
+    if (code[index] === "\\") index += 2;
+    else if (code[index] === quote) return index + 1;
+    else index += 1;
+  }
+  return code.length;
+};
+// Replace comment / string / template spans with equal-length whitespace so a stray createSignal( token inside them cannot
+// perturb the signal-count fingerprint. Regex-literal bodies stay as-is: telling them apart from division needs full
+// expression context, and a createSignal( inside a regex effectively never appears in a generated component.
+// Two more accepted blind spots of this token-level scan (tracked in #1208): JSX text is lexed like code, so an apostrophe
+// in rendered copy (`<p>Don't…</p>`) opens a phantom string span that can swallow a later createSignal(; and template
+// literals are opaque backtick-to-backtick, so a quote or backtick inside a `${}` interpolation shifts where the mask ends.
+const maskNonCodeSpans = (code: string) => {
+  let out = "";
+  let runStart = 0;
+  const flushRun = (index: number) => {
+    if (index > runStart) out += code.slice(runStart, index);
+  };
+  for (let index = 0; index < code.length;) {
+    const char = code[index];
+    let stop: number;
+    if (char === "/" && code[index + 1] === "/") {
+      const end = code.indexOf("\n", index + 2);
+      stop = end === -1 ? code.length : end;
+    } else if (char === "/" && code[index + 1] === "*") {
+      const end = code.indexOf("*/", index + 2);
+      stop = end === -1 ? code.length : end + 2;
+    } else if (char === '"' || char === "'" || char === "`") {
+      stop = skipQuotedString(code, index);
+    } else {
+      // Ordinary code chars are copied verbatim in runs; only break the run at a comment/string/template opener.
+      index += 1;
+      continue;
+    }
+    flushRun(index);
+    out += " ".repeat(stop - index);
+    runStart = stop;
+    index = stop;
+  }
+  flushRun(code.length);
+  return out;
+};
+// Fingerprints a frame by its ordered createSignal(...) call count; beginRender keeps preserved cells while it holds and
+// resets them when it changes. String#match has no lastIndex state, so one shared /g instance is safe across renders.
+// Match the call-or-generic open `(` / `<` rather than a full `<…>`: a regex can't balance nested angle brackets, so
+// spelling out the type argument would miscount createSignal<Map<K,V>> / createSignal<() => void> as zero.
+const SOLID_SIGNAL_SIGNATURE_PATTERN = /\bcreateSignal\s*[(<]/g;
+export const getSolidSignalSignature = (code: string) => String(maskNonCodeSpans(code).match(SOLID_SIGNAL_SIGNATURE_PATTERN)?.length ?? 0);
+
+export class SolidStatePreserver {
+  private activeCells: SignalCell[] | null = null;
+  private cells: SignalCell[] = [];
+  private cursor = 0;
+  private mutationSerial = 0;
+  private mutationInteractionTracker: MutationInteractionTracker | null = null;
+  private renderingSignature = "";
+  private scope = createScope();
+  private shimSolidUrl = "";
+  private shimUrl: string | null = null;
+  private signature = "";
+
+  beginRender(sourceCode: string) {
+    const signature = getSolidSignalSignature(sourceCode);
+    this.activeCells = this.signature && this.signature !== signature ? [] : this.cells;
+    this.renderingSignature = signature;
+    this.cursor = 0;
+    defineGlobalRuntime().set(this.scope, this);
+  }
+
+  // True while the in-progress render reuses the committed signal cells (signature unchanged). The streaming DOM
+  // reconcile gates on this: reusing the live nodes is only safe when the frame binds the same cells. If a streamed
+  // token adds a createSignal, the signature changes and the cell array is rebuilt — the reconcile must then fall back
+  // to a full remount so the new cells drive fresh nodes instead of being stranded on the old tree.
+  isActiveCellsReused() {
+    return this.activeCells === this.cells;
+  }
+
+  // Monotonic count of app-facing setter calls that landed *between* renders during a DOM interaction. The streaming
+  // commit gate reads this: once the user has mutated state, a shorter next frame is no longer a bad partial but the
+  // legitimately smaller view of the new state, so the visible-regression hold must release instead of freezing the
+  // preview until the stream catches up. Background setters (timers, fetch callbacks, effects) do not release the gate.
+  getMutationSerial() {
+    return this.mutationSerial;
+  }
+
+  setMutationInteractionTracker(tracker: MutationInteractionTracker | null) {
+    this.mutationInteractionTracker = tracker;
+  }
+
+  commitRender() {
+    if (this.activeCells) this.cells = this.activeCells;
+    this.signature = this.renderingSignature;
+    this.activeCells = null;
+    this.renderingSignature = "";
+    this.cursor = 0;
+  }
+
+  abortRender() {
+    this.activeCells = null;
+    this.renderingSignature = "";
+    this.cursor = 0;
+  }
+
+  createSignal<T>(value: T, options?: unknown): [() => T, SignalSetter<T>] {
+    // Lazily mounted children can create signals after the frame commits. Those signals are outside the positional
+    // render cells; reusing this.cells[0] would alias the first preserved signal and overwrite its value.
+    if (!this.activeCells) return solidCreateSignal(value, options as never) as [() => T, SignalSetter<T>];
+    const index = this.cursor++;
+    const cells = this.activeCells;
+    let cell = cells[index] as SignalCell<T> | undefined;
+    if (!cell) {
+      const [getter, rawSetter] = solidCreateSignal(value, options as never) as [() => T, SignalSetter<T>];
+      const setter: SignalSetter<T> = (next) => {
+        cell!.touched = true;
+        // A setter call outside beginRender/commitRender only releases the visible-regression gate when it is running in
+        // a DOM interaction handler. Timers/fetch callbacks may update state too, but they do not make a shorter partial
+        // frame safe to commit while the source is still streaming.
+        if (!this.activeCells && this.mutationInteractionTracker?.()) this.mutationSerial += 1;
+        return rawSetter(next);
+      };
+      cell = { getter, setter, rawSetter, touched: false };
+      cells[index] = cell as SignalCell;
+    } else if (!cell.touched) {
+      // The initial value is part of the still-streaming template, not user state. A cell first seen mid-stream was seeded
+      // from a truncated initializer (e.g. `createSignal("")` before the string literal finished), so re-seed an untouched
+      // cell from the newest source each frame — the seed converges to the final value. Once the app calls the setter the
+      // cell is `touched` and its value is preserved across recompiles, keeping mid-stream edits alive.
+      cell.rawSetter(() => value);
+    }
+    return [cell.getter, cell.setter];
+  }
+
+  reset() {
+    this.activeCells = null;
+    this.cells = [];
+    this.cursor = 0;
+    this.renderingSignature = "";
+    this.signature = "";
+  }
+
+  dispose() {
+    defineGlobalRuntime().delete(this.scope);
+    this.reset();
+    if (this.shimUrl) URL.revokeObjectURL(this.shimUrl);
+    this.shimSolidUrl = "";
+    this.shimUrl = null;
+    this.scope = createScope();
+  }
+
+  patchImportMap(importmap?: RendererImportMap): RendererImportMap | undefined {
+    const solidUrl = importmap?.imports?.["solid-js"];
+    if (!solidUrl) return importmap;
+    return { ...importmap, imports: { ...importmap.imports, "solid-js": this.getShimUrl(solidUrl) } };
+  }
+
+  private getShimUrl(solidUrl: string) {
+    if (this.shimUrl && this.shimSolidUrl === solidUrl) return this.shimUrl;
+    if (this.shimUrl) URL.revokeObjectURL(this.shimUrl);
+    defineGlobalRuntime().set(this.scope, this);
+    const source = [`import * as solid from ${JSON.stringify(solidUrl)};`, `export * from ${JSON.stringify(solidUrl)};`, `const runtime = globalThis.__partialSolidSignalRuntime?.get(${JSON.stringify(this.scope)});`, `export const createSignal = runtime ? runtime.createSignal.bind(runtime) : solid.createSignal;`].join(
+      "\n",
+    );
+    this.shimSolidUrl = solidUrl;
+    this.shimUrl = URL.createObjectURL(new Blob([source], { type: "text/javascript" }));
+    return this.shimUrl;
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,578 @@
+import type { JSX } from "solid-js";
+import type { CompileResult, SolidTsxCompiler } from "./compiler";
+import { captureEventListeners, isFramePatchable, patchFrame } from "./morph";
+import { SolidStatePreserver } from "./preserve";
+import { captureFocusWithin, restoreFocusWithin } from "./focusBridge";
+import type { RendererImportMap } from "./compilerCore";
+
+export type SolidRenderPhase = "transform" | "compile" | "render";
+export type SolidRendererCallbacks = { onRendered?: (component: unknown, code: string, serial?: number) => void; onError?: (error: Error, phase: SolidRenderPhase) => void };
+export type SolidRendererClearOptions = { preserveVisualState?: boolean; preserveState?: boolean };
+export type SolidRendererFlushMode = "microtask" | "immediate";
+export type SolidRendererOptions = { importmap?: RendererImportMap; callbacks?: SolidRendererCallbacks; compiler?: SolidTsxCompiler; flushMode?: SolidRendererFlushMode };
+export type SolidRendererUpdateMode = "push" | "render";
+type SolidWebRuntime = { render: (code: () => JSX.Element, element: Element | Document | ShadowRoot | DocumentFragment | Node) => () => void };
+type VisibleFrameMetrics = { structureCount: number; textLength: number };
+type SolidPendingCommit = { target: HTMLElement; dispose: () => void; nodes: ChildNode[]; component: unknown; code: string; serial: number | undefined; compileSerial: number; sourceCode: string; cellsReused: boolean };
+
+const attachedRenderer = Symbol.for("@macaron/partial-solidjs:attached-renderer");
+type AttachableHost = HTMLElement & { [attachedRenderer]?: SolidRenderer };
+const VISIBLE_FRAME_TAGS = ["input", "button", "select", "textarea", "img", "svg", "canvas", "video", "iframe"] as const;
+// Capture user-facing events before Solid's delegated handlers run so only setters inside that dispatch release the
+// visible-regression hold. A timer/fetch/effect setter runs after dispatch and must not turn a bad streamed frame into a
+// committed one. The scope is `eventPhase !== NONE`, not a flag cleared by a microtask: for real (trusted) input the
+// browser drains microtasks between listeners, so such a flag is already cleared when Solid's `document` handler runs.
+const MUTATION_INTERACTION_EVENTS = [
+  "beforeinput",
+  "blur",
+  "change",
+  "click",
+  "compositionend",
+  "compositionstart",
+  "compositionupdate",
+  "contextmenu",
+  "copy",
+  "cut",
+  "dblclick",
+  "dragstart",
+  "drop",
+  "focus",
+  "input",
+  "keydown",
+  "keypress",
+  "keyup",
+  "mousedown",
+  "mouseup",
+  "paste",
+  "pointercancel",
+  "pointerdown",
+  "pointerup",
+  "reset",
+  "submit",
+  "touchcancel",
+  "touchend",
+  "touchstart",
+  "wheel",
+] as const;
+// Links, ARIA widgets and editable hosts count as interactive too — a tab strip built from `[role=tab]` or an anchor-only
+// nav would otherwise score structureCount 0, disabling the regression gate for exactly the markup it protects.
+const visibleFrameSelector = `${VISIBLE_FRAME_TAGS.join(",")},a[href],[role=button],[role=tab],[contenteditable]:not([contenteditable="false"])`;
+const structuralFrameSelector = `h1,h2,h3,h4,h5,h6,${visibleFrameSelector}`;
+const normalizeError = (error: unknown) => (error instanceof Error ? error : new Error(String(error)));
+const loadBundledSolidWeb = async () => import("solid-js/web");
+const hasVisibleFrameContent = (target: Element) => Boolean(target.textContent?.trim() || target.querySelector(visibleFrameSelector));
+const getVisibleFrameMetrics = (target: Element): VisibleFrameMetrics => ({ structureCount: target.querySelectorAll(structuralFrameSelector).length, textLength: target.textContent?.trim().replace(/\s+/g, " ").length ?? 0 });
+// A streamed prefix should never render *less* than the frame already committed: with initial state fixed during
+// streaming, a longer prefix is a superset of a shorter one, so any drop is a transient bad partial. Hold the committed
+// frame when EITHER metric regresses — an `&&` here would commit a frame that kept its text but dropped all interactive
+// structure (structureCount 3→0), yanking the button out from under a mid-stream click.
+const isVisibleFrameRegression = (next: VisibleFrameMetrics, current: VisibleFrameMetrics) => current.textLength > 0 && current.structureCount > 0 && (next.textLength < current.textLength || next.structureCount < current.structureCount);
+const createDefaultCompiler = async () => {
+  if (typeof window !== "undefined") return (await import("./browser-compiler")).createBrowserSolidTsxCompiler();
+  return (await import(/* @vite-ignore */ "./compiler")).createSolidTsxCompiler();
+};
+// LRU cap on compiled components. Each entry pins a Blob-imported module the browser can't unload, so the bound keeps
+// long streaming/playback sessions (one distinct frame per token) from growing memory without limit.
+const COMPILED_COMPONENT_CACHE_LIMIT = 256;
+const compiledComponentCache = new Map<string, unknown>();
+const getCompiledComponent = (code: string) => {
+  const cached = compiledComponentCache.get(code);
+  if (cached) {
+    compiledComponentCache.delete(code);
+    compiledComponentCache.set(code, cached);
+  }
+  return cached;
+};
+const rememberCompiledComponent = (code: string, component: unknown) => {
+  compiledComponentCache.delete(code);
+  compiledComponentCache.set(code, component);
+  if (compiledComponentCache.size > COMPILED_COMPONENT_CACHE_LIMIT) compiledComponentCache.delete(compiledComponentCache.keys().next().value!);
+};
+
+export class SolidRenderer {
+  private callbacks: SolidRendererCallbacks;
+  private compiler?: SolidTsxCompiler;
+  private compilerPromise?: Promise<SolidTsxCompiler>;
+  private compileSerial = 0;
+  private committedMutationSerial = 0;
+  private currentBuffer = "";
+  private compileInFlight = false;
+  private queuedCompile: { partial: boolean; serial: number | undefined } | null = null;
+  private scheduledCompile: { partial: boolean; serial: number | undefined } | null = null;
+  private disposeSolid: (() => void) | null = null;
+  private flushMode: SolidRendererFlushMode;
+  private importmap?: RendererImportMap;
+  private lastComponentRendered = false;
+  private lastCommitReconciled = false;
+  private lastCompiledCode = "";
+  private lastComponent: unknown;
+  private moduleUrl: string | null = null;
+  private preserver = new SolidStatePreserver();
+  private pendingCommit: SolidPendingCommit | null = null;
+  private pointerClickFlushQueued = false;
+  private pointerClickSettling = false;
+  private pointerIds = new Set<number>();
+  private pointerSettleCancel: (() => void) | null = null;
+  private pointerTarget: HTMLElement | null = null;
+  private mutationInteractionEvent: Event | null = null;
+  private solidWebPromise?: Promise<SolidWebRuntime>;
+  private target: HTMLElement | null = null;
+  private updateMode: SolidRendererUpdateMode = "render";
+
+  private constructor(target: HTMLElement | null | undefined, options: SolidRendererOptions) {
+    this.callbacks = options.callbacks ?? {};
+    this.compiler = options.compiler;
+    this.flushMode = options.flushMode ?? "microtask";
+    this.importmap = options.importmap;
+    this.preserver.setMutationInteractionTracker(() => !!this.mutationInteractionEvent?.eventPhase);
+    if (target) this.attach(target);
+  }
+
+  static async create(target?: HTMLElement | null, options: SolidRendererOptions = {}) {
+    return new SolidRenderer(target, options);
+  }
+
+  attach(target: HTMLElement) {
+    const element = target as AttachableHost;
+    if (element[attachedRenderer] && element[attachedRenderer] !== this) element[attachedRenderer].detach();
+    const previous = this.target as AttachableHost | null;
+    if (previous && previous[attachedRenderer] === this) delete previous[attachedRenderer];
+    this.target = target;
+    element[attachedRenderer] = this;
+    this.bindPointerGuards(target);
+    return this;
+  }
+
+  detach() {
+    this.compileSerial += 1;
+    this.cancelScheduledCompile();
+    const previous = this.target as AttachableHost | null;
+    if (previous && previous[attachedRenderer] === this) delete previous[attachedRenderer];
+    this.unmount();
+    this.target = null;
+    this.unbindPointerGuards();
+    this.preserver.dispose();
+    this.revokeModuleUrl();
+    return this;
+  }
+
+  setFlushMode(value: SolidRendererFlushMode) {
+    this.flushMode = value;
+    return this;
+  }
+
+  setImportMap(importmap: RendererImportMap) {
+    this.importmap = importmap;
+    this.solidWebPromise = undefined;
+    this.lastComponentRendered = false;
+    return this;
+  }
+
+  render(code: string, serial?: number) {
+    this.currentBuffer = code;
+    this.updateMode = "render";
+    this.scheduleCompile(false, serial);
+  }
+
+  pushCode(code: string, serial?: number) {
+    this.currentBuffer += code;
+    this.updateMode = "push";
+    this.scheduleCompile(true, serial);
+  }
+
+  finish(code?: string, serial?: number) {
+    this.updateMode = "render";
+    if (code !== undefined) this.currentBuffer = code;
+    this.scheduleCompile(false, serial);
+  }
+
+  clear(options: SolidRendererClearOptions = {}) {
+    this.compileSerial += 1;
+    this.currentBuffer = "";
+    this.updateMode = "render";
+    this.cancelScheduledCompile();
+    this.lastCompiledCode = "";
+    this.lastComponent = undefined;
+    this.lastComponentRendered = false;
+    // preserveState is an opt-in for keeping generated createSignal cells across a stream restart, while
+    // preserveVisualState keeps the visible DOM. Keeping the full prior tree as the commit baseline can freeze a new
+    // stream: every smaller partial frame reads as a regression and gets held. Mock playback uses neither option so it
+    // starts from initial state; interactions within that run still survive subsequent push/replace-push frames.
+    if (!options.preserveState && !options.preserveVisualState) this.preserver.reset();
+    this.cancelPendingCommit();
+    if (!options.preserveVisualState) this.unmount();
+    this.revokeModuleUrl();
+    return this;
+  }
+
+  getCurrentBuffer() {
+    return this.currentBuffer;
+  }
+
+  getUpdateMode() {
+    return this.updateMode;
+  }
+
+  private unmount() {
+    this.cancelPendingCommit();
+    this.disposeSolid?.();
+    this.disposeSolid = null;
+    this.lastComponentRendered = false;
+    if (this.target) this.target.textContent = "";
+  }
+
+  private bindPointerGuards(target: HTMLElement) {
+    if (this.pointerTarget === target) return;
+    this.unbindPointerGuards();
+    this.pointerTarget = target;
+    target.addEventListener("pointerdown", this.handlePointerDown, true);
+    target.ownerDocument.addEventListener("pointerup", this.handlePointerEnd, true);
+    target.ownerDocument.addEventListener("pointercancel", this.handlePointerEnd, true);
+    target.ownerDocument.addEventListener("click", this.handleClickAfterPointer, true);
+    for (const type of MUTATION_INTERACTION_EVENTS) target.addEventListener(type, this.handleMutationInteraction, { capture: true, passive: true });
+  }
+
+  private unbindPointerGuards() {
+    const target = this.pointerTarget;
+    if (!target) return;
+    target.removeEventListener("pointerdown", this.handlePointerDown, true);
+    target.ownerDocument.removeEventListener("pointerup", this.handlePointerEnd, true);
+    target.ownerDocument.removeEventListener("pointercancel", this.handlePointerEnd, true);
+    target.ownerDocument.removeEventListener("click", this.handleClickAfterPointer, true);
+    for (const type of MUTATION_INTERACTION_EVENTS) target.removeEventListener(type, this.handleMutationInteraction, true);
+    this.pointerIds.clear();
+    this.endPointerClickSettle(false);
+    this.pointerTarget = null;
+  }
+
+  private handleMutationInteraction = (event: Event) => {
+    this.mutationInteractionEvent = event;
+  };
+
+  private handlePointerDown = (event: PointerEvent) => {
+    this.endPointerClickSettle(false);
+    this.pointerIds.add(event.pointerId);
+  };
+
+  private handlePointerEnd = (event: PointerEvent) => {
+    this.pointerIds.delete(event.pointerId);
+    if (this.pointerIds.size > 0) return;
+    this.beginPointerClickSettle();
+  };
+
+  private handleClickAfterPointer = () => {
+    if (!this.pointerClickSettling || this.pointerClickFlushQueued) return;
+    this.pointerClickFlushQueued = true;
+    this.clearPointerSettleFallback();
+    queueMicrotask(() => this.endPointerClickSettle(true));
+  };
+
+  private hasActivePointerInteraction() {
+    return this.pointerIds.size > 0 || this.pointerClickSettling;
+  }
+
+  private beginPointerClickSettle() {
+    this.pointerClickSettling = true;
+    this.pointerClickFlushQueued = false;
+    this.clearPointerSettleFallback();
+    const window = this.pointerTarget?.ownerDocument.defaultView;
+    if (window?.requestAnimationFrame && window.cancelAnimationFrame) {
+      // Prefer the click event as the ack. The frame fallback covers pointerup paths that do not synthesize a click.
+      const id = window.requestAnimationFrame(() => this.endPointerClickSettle(true));
+      this.pointerSettleCancel = () => window.cancelAnimationFrame(id);
+      return;
+    }
+    let cancelled = false;
+    queueMicrotask(() => {
+      if (!cancelled) this.endPointerClickSettle(true);
+    });
+    this.pointerSettleCancel = () => {
+      cancelled = true;
+    };
+  }
+
+  private clearPointerSettleFallback() {
+    this.pointerSettleCancel?.();
+    this.pointerSettleCancel = null;
+  }
+
+  private endPointerClickSettle(flush: boolean) {
+    this.clearPointerSettleFallback();
+    this.pointerClickFlushQueued = false;
+    this.pointerClickSettling = false;
+    if (flush) this.flushPendingCommit();
+  }
+
+  private cancelPendingCommit() {
+    this.pendingCommit?.dispose();
+    this.pendingCommit = null;
+  }
+
+  private commitFrame(frame: SolidPendingCommit) {
+    if (frame.compileSerial !== this.compileSerial || this.target !== frame.target) {
+      frame.dispose();
+      return;
+    }
+    // The freshly committed DOM now reflects any interaction that fired before this frame, so re-baseline the mutation
+    // serial: later frames of the same interaction resume normal regression gating instead of each re-triggering the
+    // release above.
+    this.committedMutationSerial = this.preserver.getMutationSerial();
+    // Element-reuse fast path for streaming frames. Append-only streaming means each partial frame's DOM is the last
+    // one extended, so instead of swapping in the fresh tree (which recreates every node — the source of the hover
+    // flicker and the mid-stream click miss) we reconcile: keep the committed nodes, patch their text/attributes, and
+    // adopt the newly streamed-in tail. A hovered tab keeps its :hover ring, focus/caret stay put with no focusBridge
+    // replay, an in-flight click keeps its target, and CSS transitions don't replay. Gated on the committed tree being
+    // a structural prefix of the fresh one and on the frame reusing the same signal cells — a cell-signature change (a
+    // new createSignal streamed in) needs the fresh root, so it takes the full-swap path below to re-establish a
+    // coherent reactive root. The kept root keeps driving its own nodes; adopted tail nodes are refreshed by the next
+    // frame's reconcile, and `finish` installs one clean full render. (partial-react never flickered because React's
+    // persistent reconciler reuses nodes; Solid has none, so we reconcile here.)
+    if (this.disposeSolid && this.updateMode === "push" && frame.cellsReused && isFramePatchable(frame.target, frame.nodes)) {
+      patchFrame(frame.target, frame.nodes);
+      frame.dispose();
+      this.lastComponentRendered = true;
+      this.lastCommitReconciled = true;
+      this.scheduleRenderedCallback(frame.component, frame.code, frame.serial, frame.compileSerial);
+      return;
+    }
+    const previousDispose = this.disposeSolid;
+    const capturedFocus = captureFocusWithin(frame.target);
+    previousDispose?.();
+    frame.target.replaceChildren(...frame.nodes);
+    restoreFocusWithin(frame.target, capturedFocus);
+    this.disposeSolid = () => {
+      frame.dispose();
+      frame.target.textContent = "";
+    };
+    this.lastComponentRendered = true;
+    this.lastCommitReconciled = false;
+    this.scheduleRenderedCallback(frame.component, frame.code, frame.serial, frame.compileSerial);
+  }
+
+  private flushPendingCommit() {
+    if (this.hasActivePointerInteraction()) return;
+    const frame = this.pendingCommit;
+    if (!frame) return;
+    this.pendingCommit = null;
+    // The staged DOM was rendered before the target click handler ran. Re-render from the preserved signal cells so the
+    // post-click state is what gets committed, instead of swapping in a stale pre-click frame.
+    frame.dispose();
+    void this.renderComponent(frame.component, frame.code, frame.serial, frame.compileSerial, frame.sourceCode);
+  }
+
+  private shouldCommitFrame(staged: HTMLElement, committed: HTMLElement) {
+    // Only the streaming append path gates on visible content; render()/finish() frames commit unconditionally, so the
+    // querySelectorAll/text scans below stay off the full-render hot path.
+    if (this.updateMode !== "push") return true;
+    if (!hasVisibleFrameContent(staged)) return false;
+    // The visible-regression hold assumes streaming state is fixed, so a shorter frame must be a transient bad partial.
+    // A user interaction (tab switch, toggle) breaks that: the committed DOM is a dead adopted tree that can't react, so
+    // the click's new — legitimately smaller — view arrives only through the next staged frame. Holding it would freeze
+    // the preview until the stream grew past the pre-click snapshot. Release once mutated so that frame commits (it takes
+    // the full-swap path, re-rooting a live interactive tree), then resume regression gating from the new baseline.
+    if (this.preserver.getMutationSerial() !== this.committedMutationSerial) return true;
+    // Partial TSX can briefly normalize to an earlier visible shell while the source is still append-only. Keep the
+    // fuller interactive DOM until the next frame catches up, otherwise clicks land on a regressed subtree.
+    return !isVisibleFrameRegression(getVisibleFrameMetrics(staged), getVisibleFrameMetrics(committed));
+  }
+
+  private cancelScheduledCompile() {
+    this.scheduledCompile = null;
+    this.queuedCompile = null;
+  }
+
+  private startCompile(partial: boolean, serial?: number) {
+    this.compileInFlight = true;
+    void this.compile(partial, serial).finally(() => {
+      this.compileInFlight = false;
+      const queued = this.queuedCompile;
+      this.queuedCompile = null;
+      if (queued) this.scheduleCompile(queued.partial, queued.serial);
+    });
+  }
+
+  private scheduleCompile(partial: boolean, serial?: number) {
+    if (this.compileInFlight) {
+      // Token streams can outrun the Solid compiler. Let append-only streaming commits land as intermediate frames,
+      // but keep only the latest queued buffer so we never stack one compile per token.
+      if (!partial) this.compileSerial += 1;
+      this.queuedCompile = { partial, serial };
+      return;
+    }
+    if (this.flushMode === "immediate") {
+      this.cancelScheduledCompile();
+      this.startCompile(partial, serial);
+      return;
+    }
+    if (this.scheduledCompile) {
+      this.scheduledCompile.partial = partial;
+      this.scheduledCompile.serial = serial;
+      return;
+    }
+    const scheduled = { partial, serial };
+    this.scheduledCompile = scheduled;
+    queueMicrotask(() => {
+      if (this.scheduledCompile !== scheduled) return;
+      this.scheduledCompile = null;
+      this.startCompile(scheduled.partial, scheduled.serial);
+    });
+  }
+
+  private async compile(partial: boolean, renderSerial?: number) {
+    const serial = (this.compileSerial += 1);
+    const code = this.currentBuffer;
+    let result: CompileResult;
+    try {
+      const compiler = this.compiler ?? (await this.getDefaultCompiler());
+      result = await compiler.compile(code, { importMap: this.preserver.patchImportMap(this.importmap), partial: partial && this.updateMode === "push", previousCode: this.lastCompiledCode });
+    } catch (error) {
+      if (serial !== this.compileSerial) return;
+      this.callbacks.onError?.(normalizeError(error), "transform");
+      return;
+    }
+    if (serial !== this.compileSerial) return;
+    // The streaming reconcile leaves controlled DOM properties (input/textarea `.value`, checkbox `.checked`) unsynced by
+    // design — it patches attributes/handlers but not properties, so uncontrolled edits survive. `finish` is meant to land
+    // one clean full render that re-establishes them. But when the final source compiles identically to the last streamed
+    // frame, `result.changed` is false; the callback-only branch would then skip that render and leave a textarea reading
+    // `value={draft()}` stuck on the reconcile's empty `.value`. Re-render from the same component when the last commit was
+    // a reconcile so the properties get re-established.
+    if (!result.changed && this.lastComponent) {
+      if (this.lastComponentRendered && !this.lastCommitReconciled) this.scheduleRenderedCallback(this.lastComponent, code, renderSerial, serial);
+      else await this.renderComponent(this.lastComponent, code, renderSerial, serial, result.source);
+      return;
+    }
+    try {
+      const { component, moduleUrl } = await this.importCompiledComponent(result.code);
+      if (serial !== this.compileSerial) {
+        if (moduleUrl) URL.revokeObjectURL(moduleUrl);
+        return;
+      }
+      this.lastCompiledCode = result.code;
+      this.lastComponent = component;
+      if (moduleUrl) this.adoptModuleUrl(moduleUrl);
+      else this.revokeModuleUrl();
+      await this.renderComponent(component, code, renderSerial, serial, result.source);
+    } catch (error) {
+      if (serial !== this.compileSerial) return;
+      this.callbacks.onError?.(normalizeError(error), "compile");
+    }
+  }
+
+  private async getDefaultCompiler() {
+    // Null the cached promise on failure so a transient compiler-chunk load error doesn't wedge this renderer until detach.
+    this.compilerPromise ??= createDefaultCompiler().catch((error) => {
+      this.compilerPromise = undefined;
+      throw error;
+    });
+    return this.compilerPromise;
+  }
+
+  private async getSolidWebRuntime() {
+    this.solidWebPromise ??= this.importmap?.imports?.["solid-js/web"] ? (import(/* @vite-ignore */ this.importmap.imports["solid-js/web"]) as Promise<SolidWebRuntime>) : loadBundledSolidWeb();
+    return this.solidWebPromise;
+  }
+
+  private async importCompiledComponent(code: string) {
+    const cached = getCompiledComponent(code);
+    if (cached) return { component: cached };
+    const moduleUrl = URL.createObjectURL(new Blob([code], { type: "text/javascript" }));
+    try {
+      const module = (await import(/* @vite-ignore */ moduleUrl)) as { default?: unknown };
+      if (!module.default) throw new Error("No default export found in compiled module.");
+      rememberCompiledComponent(code, module.default);
+      return { component: module.default, moduleUrl };
+    } catch (error) {
+      URL.revokeObjectURL(moduleUrl);
+      throw error;
+    }
+  }
+
+  private adoptModuleUrl(moduleUrl: string) {
+    if (this.moduleUrl && this.moduleUrl !== moduleUrl) URL.revokeObjectURL(this.moduleUrl);
+    this.moduleUrl = moduleUrl;
+  }
+
+  private revokeModuleUrl() {
+    if (!this.moduleUrl) return;
+    URL.revokeObjectURL(this.moduleUrl);
+    this.moduleUrl = null;
+  }
+
+  private async renderComponent(component: unknown, code: string, serial: number | undefined, compileSerial: number, sourceCode = code) {
+    const target = this.target;
+    if (!target) return;
+    const Component = component as () => JSX.Element;
+    const stagingTarget = target.ownerDocument.createElement("div");
+    // Solid's top-level `insert` captures the render target as its parent. Keep that parent attached after commit by
+    // committing this div as a transparent wrapper; moving its children alone strands top-level reactive insertions
+    // on a detached div. `display: contents` keeps the wrapper out of layout while retaining the live parent node.
+    stagingTarget.style.display = "contents";
+    let nextDispose: (() => void) | null = null;
+    try {
+      const { render } = await this.getSolidWebRuntime();
+      if (compileSerial !== this.compileSerial || this.target !== target) return;
+      this.preserver.beginRender(sourceCode);
+      nextDispose = captureEventListeners(stagingTarget, () => render(() => Component(), stagingTarget));
+      if (compileSerial !== this.compileSerial || this.target !== target) {
+        nextDispose();
+        this.preserver.abortRender();
+        return;
+      }
+      const committedDispose = nextDispose;
+      const frame = {
+        target,
+        dispose: () => {
+          committedDispose();
+          stagingTarget.textContent = "";
+        },
+        nodes: [stagingTarget],
+        component,
+        code,
+        serial,
+        compileSerial,
+        sourceCode,
+        cellsReused: this.preserver.isActiveCellsReused(),
+      };
+      this.lastComponentRendered = false;
+      if (!this.shouldCommitFrame(stagingTarget, target)) {
+        frame.dispose();
+        this.preserver.abortRender();
+        this.scheduleRenderedCallback(component, code, serial, compileSerial);
+        return;
+      }
+      if (this.hasActivePointerInteraction()) {
+        this.preserver.abortRender();
+        this.cancelPendingCommit();
+        this.pendingCommit = frame;
+        // Defer the visual swap so an in-flight click keeps its target, but still ack. Ack-paced playback advances the
+        // stream on onRendered; withholding it here froze the whole stream until the pointer released — clicking a tab
+        // mid-stream made every tab look dead. flushPendingCommit lands the real commit on settle.
+        this.scheduleRenderedCallback(component, code, serial, compileSerial);
+        return;
+      }
+      this.preserver.commitRender();
+      this.cancelPendingCommit();
+      this.commitFrame(frame);
+    } catch (error) {
+      nextDispose?.();
+      this.preserver.abortRender();
+      if (compileSerial !== this.compileSerial) return;
+      this.callbacks.onError?.(normalizeError(error), "render");
+    }
+  }
+
+  private scheduleRenderedCallback(component: unknown, code: string, renderSerial: number | undefined, compileSerial: number) {
+    const notify = () => {
+      if (compileSerial === this.compileSerial) this.callbacks.onRendered?.(component, code, renderSerial);
+    };
+    // rAF is throttled/paused on a backgrounded tab, so ack-paced playback (onRendered drives the next chunk) would stall
+    // until refocus. Fire synchronously when hidden.
+    if (typeof document !== "undefined" && document.hidden) {
+      notify();
+      return;
+    }
+    if (typeof requestAnimationFrame === "function") requestAnimationFrame(notify);
+    else queueMicrotask(notify);
+  }
+}

package/index.js

@@ -1 +0,0 @@
-// Placeholder