@vertz/ui-server 0.2.0 → 0.2.3

package/dist/bun-plugin/fast-refresh-dom-state.d.ts

@@ -0,0 +1,51 @@
+/**
+* DOM state snapshot/restore utilities for fast refresh.
+*
+* Captures transient DOM state (form values, focus, scroll positions) before
+* a component is replaced, and restores it to the new DOM tree after replacement.
+*
+* Separated from fast-refresh-runtime.ts so it can be tested without
+* import.meta.hot (which only exists in Bun's dev server environment).
+*/
+/** Captured form field value keyed by name attribute. */
+interface FormFieldSnapshot {
+	value: string;
+	checked: boolean;
+	selectedIndex: number;
+	type: string;
+}
+/** Captured focus state. */
+interface FocusSnapshot {
+	/** The name or id used to locate the element in the new tree. */
+	matchKey: string;
+	/** Whether matchKey is a name or id attribute. */
+	matchBy: "name" | "id";
+	/** Selection start for input/textarea. -1 if not applicable. */
+	selectionStart: number;
+	/** Selection end for input/textarea. -1 if not applicable. */
+	selectionEnd: number;
+}
+/** Captured scroll position for a single element. */
+interface ScrollSnapshot {
+	/** Key to locate the element: id value or tagName.className */
+	matchKey: string;
+	matchBy: "id" | "selector";
+	scrollTop: number;
+	scrollLeft: number;
+}
+/** Complete DOM state snapshot for a component tree. */
+interface DOMStateSnapshot {
+	formFields: Map<string, FormFieldSnapshot>;
+	focus: FocusSnapshot | null;
+	scrollPositions: ScrollSnapshot[];
+}
+/**
+* Capture transient DOM state from a component's element tree.
+* Returns a snapshot that can be applied to a new tree via restoreDOMState.
+*/
+declare function captureDOMState(element: Element): DOMStateSnapshot;
+/**
+* Restore previously captured DOM state to a new component tree.
+*/
+declare function restoreDOMState(newElement: Element, snapshot: DOMStateSnapshot): void;
+export { restoreDOMState, captureDOMState, ScrollSnapshot, FormFieldSnapshot, FocusSnapshot, DOMStateSnapshot };

package/dist/bun-plugin/fast-refresh-dom-state.js

@@ -0,0 +1,10 @@
+// @bun
+import {
+  captureDOMState,
+  restoreDOMState
+} from "../shared/chunk-2qsqp9xj.js";
+import"../shared/chunk-eb80r8e8.js";
+export {
+  restoreDOMState,
+  captureDOMState
+};

package/dist/bun-plugin/fast-refresh-runtime.d.ts

@@ -0,0 +1,43 @@
+import { getContextScope } from "@vertz/ui/internals";
+/** Disposal cleanup function. */
+type DisposeFn = () => void;
+/** Derive ContextScope from the actual return type of getContextScope. */
+type ContextScope = NonNullable<ReturnType<typeof getContextScope>>;
+/** Signal ref used for state preservation. Has peek() and settable value. */
+interface SignalRef {
+	peek(): unknown;
+	value: unknown;
+}
+/**
+* Register or update a component factory in the registry.
+*
+* Called at module top-level after each component definition.
+* On first load: creates a new record. On HMR re-evaluation: updates
+* the factory reference (instances are preserved for __$refreshPerform).
+*/
+declare function __$refreshReg(moduleId: string, name: string, factory: (...args: unknown[]) => HTMLElement): void;
+/**
+* Track a live component instance for HMR replacement.
+*
+* Called by the wrapper injected around each component. Captures the DOM
+* element, disposal cleanups, and context scope. Returns the element
+* unchanged (transparent to callers).
+*
+* Prunes stale instances (elements no longer in the DOM) on each call
+* to prevent memory leaks from navigated-away pages.
+*/
+declare function __$refreshTrack(moduleId: string, name: string, element: HTMLElement, args: unknown[], cleanups: DisposeFn[], contextScope: ContextScope | null, signals?: SignalRef[]): HTMLElement;
+/**
+* Perform hot replacement for all components in a module.
+*
+* Called from the HMR accept handler after module re-evaluation.
+* For each component with tracked instances:
+* 1. Skip instances whose elements are no longer in the DOM
+* 2. Run old cleanups (LIFO order via runCleanups)
+* 3. Create a new disposal scope + restore context
+* 4. Re-execute the factory to get a new DOM element
+* 5. Replace the old element in the DOM
+* 6. Update the instance record
+*/
+declare function __$refreshPerform(moduleId: string): void;
+export { __$refreshTrack, __$refreshReg, __$refreshPerform };

package/dist/bun-plugin/fast-refresh-runtime.js

@@ -0,0 +1,150 @@
+// @bun
+import {
+  captureDOMState,
+  restoreDOMState
+} from "../shared/chunk-2qsqp9xj.js";
+import"../shared/chunk-eb80r8e8.js";
+
+// src/bun-plugin/fast-refresh-runtime.ts
+import {
+  _tryOnCleanup,
+  getContextScope,
+  popScope,
+  pushScope,
+  runCleanups,
+  setContextScope,
+  startSignalCollection,
+  stopSignalCollection
+} from "@vertz/ui/internals";
+if (undefined)
+  ;
+var REGISTRY_KEY = Symbol.for("vertz:fast-refresh:registry");
+var DIRTY_KEY = Symbol.for("vertz:fast-refresh:dirty");
+var registry = globalThis[REGISTRY_KEY] ??= new Map;
+var dirtyModules = globalThis[DIRTY_KEY] ??= new Set;
+var performingRefresh = false;
+function getModule(moduleId) {
+  let mod = registry.get(moduleId);
+  if (!mod) {
+    mod = new Map;
+    registry.set(moduleId, mod);
+  }
+  return mod;
+}
+function __$refreshReg(moduleId, name, factory) {
+  const mod = getModule(moduleId);
+  const existing = mod.get(name);
+  if (existing) {
+    existing.factory = factory;
+    dirtyModules.add(moduleId);
+  } else {
+    mod.set(name, { factory, instances: [] });
+  }
+}
+function __$refreshTrack(moduleId, name, element, args, cleanups, contextScope, signals = []) {
+  if (performingRefresh)
+    return element;
+  const mod = registry.get(moduleId);
+  if (!mod)
+    return element;
+  const record = mod.get(name);
+  if (!record)
+    return element;
+  record.instances.push({ element, args, cleanups, contextScope, signals });
+  return element;
+}
+function __$refreshPerform(moduleId) {
+  if (!dirtyModules.has(moduleId))
+    return;
+  dirtyModules.delete(moduleId);
+  const mod = registry.get(moduleId);
+  if (!mod)
+    return;
+  performingRefresh = true;
+  for (const [name, record] of mod) {
+    const { factory, instances } = record;
+    const updatedInstances = [];
+    for (const instance of instances) {
+      const { element, args, cleanups, contextScope, signals: oldSignals } = instance;
+      const parent = element.parentNode;
+      if (!parent)
+        continue;
+      const savedValues = oldSignals.map((s) => s.peek());
+      const newCleanups = pushScope();
+      const prevScope = setContextScope(contextScope);
+      let newElement;
+      let newSignals;
+      let newContextScope;
+      try {
+        startSignalCollection();
+        newElement = factory(...args);
+        newSignals = stopSignalCollection();
+        newContextScope = getContextScope();
+      } catch (err) {
+        stopSignalCollection();
+        runCleanups(newCleanups);
+        popScope();
+        setContextScope(prevScope);
+        console.error(`[vertz-hmr] Error re-mounting ${name}:`, err);
+        updatedInstances.push(instance);
+        continue;
+      }
+      if (savedValues.length > 0 && newSignals.length === savedValues.length) {
+        for (let i = 0;i < newSignals.length; i++) {
+          const sig = newSignals[i];
+          if (sig)
+            sig.value = savedValues[i];
+        }
+      } else if (savedValues.length > 0 && newSignals.length !== savedValues.length) {
+        console.warn(`[vertz-hmr] Signal count changed in ${name} ` + `(${savedValues.length} \u2192 ${newSignals.length}). State reset.`);
+      }
+      popScope();
+      runCleanups(cleanups);
+      if (newCleanups.length > 0) {
+        _tryOnCleanup(() => runCleanups(newCleanups));
+      }
+      setContextScope(prevScope);
+      let domSnapshot = null;
+      try {
+        domSnapshot = captureDOMState(element);
+      } catch (_) {}
+      parent.replaceChild(newElement, element);
+      if (domSnapshot) {
+        try {
+          restoreDOMState(newElement, domSnapshot);
+        } catch (_) {
+          console.warn("[vertz-hmr] Failed to restore DOM state");
+        }
+      }
+      updatedInstances.push({
+        element: newElement,
+        args,
+        cleanups: newCleanups,
+        contextScope: newContextScope,
+        signals: newSignals
+      });
+    }
+    record.instances = updatedInstances;
+  }
+  performingRefresh = false;
+  console.log(`[vertz-hmr] Hot updated: ${moduleId}`);
+}
+var FR_KEY = Symbol.for("vertz:fast-refresh");
+globalThis[FR_KEY] = {
+  __$refreshReg,
+  __$refreshTrack,
+  __$refreshPerform,
+  pushScope,
+  popScope,
+  _tryOnCleanup,
+  runCleanups,
+  getContextScope,
+  setContextScope,
+  startSignalCollection,
+  stopSignalCollection
+};
+export {
+  __$refreshTrack,
+  __$refreshReg,
+  __$refreshPerform
+};

package/dist/bun-plugin/index.d.ts

@@ -0,0 +1,44 @@
+import { CSSExtractionResult } from "@vertz/ui-compiler";
+import { BunPlugin as BunPlugin_seob6 } from "bun";
+interface VertzBunPluginOptions {
+	/** Regex filter for files to transform. Defaults to .tsx files. */
+	filter?: RegExp;
+	/** Compilation target. 'dom' (default) or 'tui'. */
+	target?: "dom" | "tui";
+	/**
+	* Directory for CSS sidecar files.
+	* Defaults to `.vertz/css` relative to the project root.
+	*/
+	cssOutDir?: string;
+	/** Enable HMR support (import.meta.hot.accept). Defaults to true. */
+	hmr?: boolean;
+	/**
+	* Enable Fast Refresh (component-level HMR).
+	* When true, components are wrapped with tracking code and re-mounted
+	* on file change instead of doing a full page reload.
+	* Defaults to true when hmr is true.
+	*/
+	fastRefresh?: boolean;
+	/** Project root for computing relative paths. */
+	projectRoot?: string;
+}
+/** CSS extractions tracked across all transformed files (for dead CSS elimination). */
+type FileExtractionsMap = Map<string, CSSExtractionResult>;
+/** Map of source file path to CSS sidecar file path (for debugging). */
+type CSSSidecarMap = Map<string, string>;
+interface VertzBunPluginResult {
+	/** The Bun plugin to pass to Bun.build or bunfig.toml. */
+	plugin: BunPlugin_seob6;
+	/** CSS extractions for all transformed files (for production dead CSS elimination). */
+	fileExtractions: FileExtractionsMap;
+	/** Map of source file to CSS sidecar file path (for debugging). */
+	cssSidecarMap: CSSSidecarMap;
+}
+/**
+* Create a Vertz Bun plugin with CSS sidecar support and optional Fast Refresh.
+*
+* Returns the plugin along with maps for CSS extractions and sidecar paths,
+* which build scripts need for dead CSS elimination.
+*/
+declare function createVertzBunPlugin(options?: VertzBunPluginOptions): VertzBunPluginResult;
+export { createVertzBunPlugin, VertzBunPluginResult, VertzBunPluginOptions, FileExtractionsMap, CSSSidecarMap };

package/dist/bun-plugin/index.js

@@ -0,0 +1,197 @@
+// @bun
+import"../shared/chunk-eb80r8e8.js";
+
+// src/bun-plugin/plugin.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { dirname, relative, resolve } from "path";
+import remapping from "@ampproject/remapping";
+import { ComponentAnalyzer, CSSExtractor, compile, HydrationTransformer } from "@vertz/ui-compiler";
+import MagicString from "magic-string";
+import { Project, ts as ts2 } from "ts-morph";
+
+// src/bun-plugin/context-stable-ids.ts
+import { ts } from "ts-morph";
+function injectContextStableIds(source, sourceFile, relFilePath) {
+  for (const stmt of sourceFile.getStatements()) {
+    if (!ts.isVariableStatement(stmt.compilerNode))
+      continue;
+    for (const decl of stmt.compilerNode.declarationList.declarations) {
+      if (!decl.initializer || !ts.isCallExpression(decl.initializer))
+        continue;
+      const callText = decl.initializer.expression.getText(sourceFile.compilerNode);
+      if (callText !== "createContext")
+        continue;
+      if (!ts.isIdentifier(decl.name))
+        continue;
+      const varName = decl.name.text;
+      const escapedPath = relFilePath.replace(/['\\]/g, "\\$&");
+      const stableId = `${escapedPath}::${varName}`;
+      const callExpr = decl.initializer;
+      const argsArr = callExpr.arguments;
+      if (argsArr.length === 0) {
+        const closeParenPos = callExpr.end - 1;
+        source.appendLeft(closeParenPos, `undefined, '${stableId}'`);
+      } else {
+        const lastArg = argsArr[argsArr.length - 1];
+        if (lastArg)
+          source.appendLeft(lastArg.end, `, '${stableId}'`);
+      }
+    }
+  }
+}
+
+// src/bun-plugin/fast-refresh-codegen.ts
+function generateRefreshPreamble(moduleId) {
+  const escapedId = moduleId.replace(/['\\]/g, "\\$&");
+  return `const __$fr = globalThis[Symbol.for('vertz:fast-refresh')];
+` + `const { __$refreshReg, __$refreshTrack, __$refreshPerform, ` + `pushScope: __$pushScope, popScope: __$popScope, ` + `_tryOnCleanup: __$tryCleanup, runCleanups: __$runCleanups, ` + `getContextScope: __$getCtx, setContextScope: __$setCtx, ` + `startSignalCollection: __$startSigCol, stopSignalCollection: __$stopSigCol } = __$fr;
+` + `const __$moduleId = '${escapedId}';
+`;
+}
+function generateRefreshWrapper(componentName) {
+  return `
+const __$orig_${componentName} = ${componentName};
+` + `${componentName} = function(...__$args) {
+` + `  const __$scope = __$pushScope();
+` + `  const __$ctx = __$getCtx();
+` + `  __$startSigCol();
+` + `  const __$ret = __$orig_${componentName}.apply(this, __$args);
+` + `  const __$sigs = __$stopSigCol();
+` + `  __$popScope();
+` + `  if (__$scope.length > 0) {
+` + `    __$tryCleanup(() => __$runCleanups(__$scope));
+` + `  }
+` + `  return __$refreshTrack(__$moduleId, '${componentName}', __$ret, __$args, __$scope, __$ctx, __$sigs);
+` + `};
+` + `__$refreshReg(__$moduleId, '${componentName}', ${componentName});
+`;
+}
+function generateRefreshPerform() {
+  return `__$refreshPerform(__$moduleId);
+`;
+}
+function generateRefreshCode(moduleId, components) {
+  if (components.length === 0)
+    return null;
+  const preamble = generateRefreshPreamble(moduleId);
+  let epilogue = "";
+  for (const comp of components) {
+    epilogue += generateRefreshWrapper(comp.name);
+  }
+  epilogue += generateRefreshPerform();
+  return { preamble, epilogue };
+}
+
+// src/bun-plugin/file-path-hash.ts
+function filePathHash(filePath) {
+  let hash = 5381;
+  for (let i = 0;i < filePath.length; i++) {
+    hash = (hash << 5) + hash + filePath.charCodeAt(i) >>> 0;
+  }
+  return hash.toString(36);
+}
+
+// src/bun-plugin/plugin.ts
+function createVertzBunPlugin(options) {
+  const filter = options?.filter ?? /\.tsx$/;
+  const hmr = options?.hmr ?? true;
+  const fastRefresh = options?.fastRefresh ?? hmr;
+  const projectRoot = options?.projectRoot ?? process.cwd();
+  const cssOutDir = options?.cssOutDir ?? resolve(projectRoot, ".vertz", "css");
+  const cssExtractor = new CSSExtractor;
+  const componentAnalyzer = new ComponentAnalyzer;
+  const fileExtractions = new Map;
+  const cssSidecarMap = new Map;
+  mkdirSync(cssOutDir, { recursive: true });
+  const plugin = {
+    name: "vertz-bun-plugin",
+    setup(build) {
+      build.onLoad({ filter }, async (args) => {
+        try {
+          const source = await Bun.file(args.path).text();
+          const hydrationS = new MagicString(source);
+          const hydrationProject = new Project({
+            useInMemoryFileSystem: true,
+            compilerOptions: {
+              jsx: ts2.JsxEmit.Preserve,
+              strict: true
+            }
+          });
+          const hydrationSourceFile = hydrationProject.createSourceFile(args.path, source);
+          const hydrationTransformer = new HydrationTransformer;
+          hydrationTransformer.transform(hydrationS, hydrationSourceFile);
+          if (fastRefresh) {
+            const relFilePath = relative(projectRoot, args.path);
+            injectContextStableIds(hydrationS, hydrationSourceFile, relFilePath);
+          }
+          const hydratedCode = hydrationS.toString();
+          const hydrationMap = hydrationS.generateMap({
+            source: args.path,
+            includeContent: true
+          });
+          const compileResult = compile(hydratedCode, {
+            filename: args.path,
+            target: options?.target
+          });
+          const remapped = remapping([compileResult.map, hydrationMap], () => null);
+          const extraction = cssExtractor.extract(source, args.path);
+          let cssImportLine = "";
+          if (extraction.css.length > 0) {
+            fileExtractions.set(args.path, extraction);
+            if (hmr) {
+              const hash = filePathHash(args.path);
+              const cssFileName = `${hash}.css`;
+              const cssFilePath = resolve(cssOutDir, cssFileName);
+              writeFileSync(cssFilePath, extraction.css);
+              cssSidecarMap.set(args.path, cssFilePath);
+              const relPath = relative(dirname(args.path), cssFilePath);
+              const importPath = relPath.startsWith(".") ? relPath : `./${relPath}`;
+              cssImportLine = `import '${importPath}';
+`;
+            }
+          }
+          let refreshPreamble = "";
+          let refreshEpilogue = "";
+          if (fastRefresh) {
+            const components = componentAnalyzer.analyze(hydrationSourceFile);
+            const refreshCode = generateRefreshCode(args.path, components);
+            if (refreshCode) {
+              refreshPreamble = refreshCode.preamble;
+              refreshEpilogue = refreshCode.epilogue;
+            }
+          }
+          const mapBase64 = Buffer.from(remapped.toString()).toString("base64");
+          const sourceMapComment = `
+//# sourceMappingURL=data:application/json;base64,${mapBase64}`;
+          let contents = "";
+          if (cssImportLine) {
+            contents += cssImportLine;
+          }
+          if (refreshPreamble) {
+            contents += refreshPreamble;
+          }
+          contents += compileResult.code;
+          if (refreshEpilogue) {
+            contents += refreshEpilogue;
+          }
+          if (hmr) {
+            contents += `
+import.meta.hot.accept();
+`;
+          }
+          contents += sourceMapComment;
+          return { contents, loader: "tsx" };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          const relPath = relative(projectRoot, args.path);
+          console.error(`[vertz-bun-plugin] Failed to process ${relPath}:`, message);
+          throw err;
+        }
+      });
+    }
+  };
+  return { plugin, fileExtractions, cssSidecarMap };
+}
+export {
+  createVertzBunPlugin
+};

package/dist/dom-shim/index.d.ts

@@ -22,6 +22,18 @@ declare class SSRNode {
 	replaceChild(newNode: SSRNode, oldNode: SSRNode): SSRNode;
 }
 /**
+* SSR comment node — serialized as `<!-- text -->` in HTML output.
+*
+* Used by __conditional to emit anchor comment nodes that the client-side
+* hydration cursor can claim during mount.
+*/
+declare class SSRComment extends SSRNode {
+	text: string;
+	constructor(text: string);
+	get data(): string;
+	set data(value: string);
+}
+/**
 * SSR text node
 */
 declare class SSRTextNode extends SSRNode {
@@ -43,16 +55,23 @@ declare class SSRDocumentFragment extends SSRNode {
 declare class SSRElement extends SSRNode {
 	tag: string;
 	attrs: Record<string, string>;
-	children: (SSRElement | string)[];
+	children: (SSRElement | SSRComment | string)[];
 	_classList: Set<string>;
 	_textContent: string | null;
 	_innerHTML: string | null;
-	style: Record<string, any>;
+	style: {
+		display: string;
+		[key: string]: any;
+	};
 	constructor(tag: string);
 	setAttribute(name: string, value: string): void;
 	getAttribute(name: string): string | null;
 	removeAttribute(name: string): void;
-	appendChild(child: SSRElement | SSRTextNode | SSRDocumentFragment): void;
+	appendChild(child: SSRElement | SSRTextNode | SSRComment | SSRDocumentFragment): void;
+	insertBefore(newNode: SSRNode, referenceNode: SSRNode | null): SSRNode;
+	replaceChild(newNode: SSRNode, oldNode: SSRNode): SSRNode;
+	/** Find a node's index in the children array via childNodes identity lookup. */
+	private _findChildIndex;
 	removeChild(child: SSRNode): SSRNode;
 	get classList(): {
 		add: (cls: string) => void;
@@ -70,15 +89,27 @@ declare class SSRElement extends SSRNode {
 	toVNode(): VNode;
 }
 /**
-* Create and install the DOM shim
+* Create and install the DOM shim.
+*
+* @deprecated Use `setAdapter(createSSRAdapter())` instead.
+* This function is kept for backward compatibility — it installs the
+* SSR adapter and the global DOM shim. New code should use the adapter
+* directly via `setAdapter()`.
 */
 declare function installDomShim(): void;
 /**
-* Remove the DOM shim
+* Remove the DOM shim.
+*
+* @deprecated Use `setAdapter(null)` instead.
+* This function is kept for backward compatibility.
+*
+* If globals existed before installDomShim() (e.g., happydom in a test runner),
+* they are restored instead of deleted. This prevents contamination in
+* single-process test runners like `bun test`.
 */
 declare function removeDomShim(): void;
 /**
 * Convert an SSRElement to a VNode
 */
 declare function toVNode2(element: any): VNode;
-export { toVNode2 as toVNode, removeDomShim, installDomShim, SSRTextNode, SSRNode, SSRElement, SSRDocumentFragment };
+export { toVNode2 as toVNode, removeDomShim, installDomShim, SSRTextNode, SSRNode, SSRElement, SSRDocumentFragment, SSRComment };