@relicloops/cathode 2.0.0 → 2.1.0-0

package/esbuild-plugin.js

@@ -0,0 +1,75 @@
+import { readFileSync } from 'node:fs';
+/**
+ * esbuild plugin that automatically wraps exported JSX components with
+ * cathode's HMR proxy at build time.
+ *
+ * Only activate this plugin in watch / dev mode:
+ *
+ *   plugins: [
+ *     ...(watchMode ? [cathodeHMRPlugin()] : []),
+ *     deployPlugin,
+ *   ]
+ *
+ * The plugin detects top-level exports whose name starts with an uppercase
+ * letter (PascalCase convention for components) and rewrites:
+ *
+ *   export const Foo = ( props ) => { ... };
+ *   export function Bar( props ) { ... }
+ *
+ * into:
+ *
+ *   import { hmr as __cathode_hmr } from '@relicloops/cathode/hmr';
+ *   const _Foo = ( props ) => { ... };
+ *   function _Bar( props ) { ... }
+ *   export const Foo = __cathode_hmr.wrap( _Foo, import.meta.url, 'Foo' );
+ *   export const Bar = __cathode_hmr.wrap( _Bar, import.meta.url, 'Bar' );
+ *
+ * Files that already contain '__cathode_hmr' or 'hmr.wrap' are left
+ * untouched so that explicit wrapping is never doubled.
+ */
+export function cathodeHMRPlugin(options = {}) {
+    const filter = options.filter ?? /\.tsx$/;
+    return {
+        name: 'cathode-hmr',
+        setup(build) {
+            build.onLoad({ filter }, ({ path }) => {
+                const source = readFileSync(path, 'utf8');
+                // Skip files that already opt in to explicit HMR wrapping.
+                if (source.includes('__cathode_hmr') || source.includes('hmr.wrap')) {
+                    return undefined;
+                }
+                const names = [];
+                // Match top-level: export const PascalName
+                const constRe = /^export\s+const\s+([A-Z]\w*)\b/gm;
+                // Match top-level: export function PascalName
+                const fnRe = /^export\s+function\s+([A-Z]\w*)\b/gm;
+                let m;
+                while ((m = constRe.exec(source)) !== null) {
+                    names.push(m[1]);
+                }
+                while ((m = fnRe.exec(source)) !== null) {
+                    names.push(m[1]);
+                }
+                if (names.length === 0) {
+                    return undefined;
+                }
+                // Rename each exported symbol to a private name by stripping
+                // the 'export' keyword and prefixing the identifier with '_'.
+                let transformed = source;
+                for (const name of names) {
+                    transformed = transformed
+                        .replace(new RegExp(`^export\\s+const\\s+${name}\\b`, 'gm'), `const _${name}`)
+                        .replace(new RegExp(`^export\\s+function\\s+${name}\\b`, 'gm'), `function _${name}`);
+                }
+                const hmrImport = `import { hmr as __cathode_hmr } from '@relicloops/cathode/hmr';\n`;
+                const wrapLines = names
+                    .map(name => `export const ${name} = __cathode_hmr.wrap( _${name}, import.meta.url, '${name}' );`)
+                    .join('\n');
+                return {
+                    contents: `${hmrImport}${transformed}\n${wrapLines}\n`,
+                    loader: 'tsx',
+                };
+            });
+        },
+    };
+}

package/hmr.js

@@ -0,0 +1,71 @@
+import { applyUpdate, enableDevMode, isDevMode, refreshModule, registerRoot, useCallback, useEffect, useMemo, useRef, useState, wrapComponent, } from './lib/hmr-runtime.js';
+export const hmr = {
+    wrap: wrapComponent,
+    registerRoot,
+    applyUpdate,
+    refreshModule,
+};
+export { applyUpdate, enableDevMode, refreshModule, registerRoot, useCallback, useEffect, useMemo, useRef, useState, wrapComponent as wrap, };
+export function connectHMR(options = {}) {
+    const isDev = import.meta?.env?.DEV;
+    if (!isDev && !isDevMode()) {
+        console.warn('[hmr] disabled outside dev mode');
+        return () => { };
+    }
+    const endpoint = options.endpoint ?? '/__neon/hmr';
+    const source = new EventSource(endpoint);
+    console.trace('[hmr] connecting', endpoint);
+    source.onopen = () => {
+        console.trace('[hmr] connected', endpoint);
+    };
+    source.onerror = (err) => {
+        console.trace('[hmr] error', err);
+    };
+    source.onmessage = (msg) => {
+        console.trace('[hmr] message', msg.data);
+        let data;
+        try {
+            data = JSON.parse(msg.data);
+        }
+        catch {
+            console.trace('[hmr] parse error', msg.data);
+            return;
+        }
+        if (data.type !== 'hmr') {
+            console.trace('[hmr] ignored event type', data.type);
+            return;
+        }
+        console.trace('[hmr] update received', data);
+        options.onBeforeReload?.(data);
+        void handleHotUpdate(data, options);
+    };
+    return () => {
+        console.trace('[hmr] closing', endpoint);
+        source.close();
+    };
+}
+async function handleHotUpdate(data, options) {
+    const moduleUrl = normalizeModuleUrl(data.path, options.pathTransform);
+    // Skip directories and non-JS paths (CSS, HTML, media, empty string, etc.).
+    // NeonSignal fires a directory-level event in addition to file-level events;
+    // importing a directory URL returns HTML, not a JS module.
+    if (!moduleUrl.endsWith('.js')) {
+        return;
+    }
+    try {
+        const mod = await import(`${moduleUrl}?t=${Date.now()}`);
+        options.onHotUpdate?.(data, moduleUrl, mod);
+    }
+    catch (error) {
+        options.onHotError?.(data, error);
+    }
+}
+function normalizeModuleUrl(path, transform) {
+    const transformed = transform ? transform(path) : path;
+    try {
+        return new URL(transformed, window.location.origin).pathname;
+    }
+    catch {
+        return transformed;
+    }
+}

package/lib/hmr-runtime.js

@@ -0,0 +1,415 @@
+const rootMap = new WeakMap();
+const moduleRegistry = new Map();
+const scheduledRoots = new Set();
+let devMode = false;
+let currentInstance = null;
+let renderNode = null;
+let renderRoot = null;
+export function enableDevMode() {
+    devMode = true;
+}
+export function isDevMode() {
+    return devMode;
+}
+export function setDevRenderers(nodeRenderer, rootRenderer) {
+    renderNode = nodeRenderer;
+    renderRoot = rootRenderer;
+}
+export function prepareRootContext(parent, node) {
+    const existing = rootMap.get(parent);
+    const root = existing ?? {
+        parent,
+        instances: [],
+        cursor: 0,
+        effects: [],
+        lastNode: node,
+    };
+    root.cursor = 0;
+    root.effects = [];
+    root.lastNode = node;
+    rootMap.set(parent, root);
+    return root;
+}
+export function finishRootRender(root) {
+    trimInstances(root.instances, root.cursor);
+    flushEffects(root);
+}
+export function createOrReuseInstance(root, parentInstance, component, props) {
+    const list = parentInstance ? parentInstance.childInstances : root.instances;
+    const index = parentInstance ? parentInstance.childCursor : root.cursor;
+    let instance = list[index];
+    if (!instance) {
+        instance = {
+            component,
+            props,
+            hooks: [],
+            hookIndex: 0,
+            childInstances: [],
+            childCursor: 0,
+            root,
+            domStart: null,
+            domEnd: null,
+        };
+        list[index] = instance;
+    }
+    else if (instance.component !== component) {
+        disposeInstance(instance);
+        instance.component = component;
+        instance.props = props;
+        instance.hooks = [];
+        instance.childInstances = [];
+        instance.childCursor = 0;
+        instance.root = root;
+    }
+    instance.component = component;
+    instance.props = props;
+    instance.hookIndex = 0;
+    instance.childCursor = 0;
+    instance.root = root;
+    if (parentInstance) {
+        parentInstance.childCursor++;
+    }
+    else {
+        root.cursor++;
+    }
+    registerInstanceIfNeeded(instance, component);
+    return instance;
+}
+export function beginInstanceRender(instance) {
+    currentInstance = instance;
+    instance.hookIndex = 0;
+}
+export function endInstanceRender() {
+    currentInstance = null;
+}
+export function finalizeInstance(instance) {
+    trimInstances(instance.childInstances, instance.childCursor);
+}
+export function makeInstanceFragment(instance, content) {
+    const fragment = document.createDocumentFragment();
+    const start = document.createComment('cathode:hmr:start');
+    const end = document.createComment('cathode:hmr:end');
+    instance.domStart = start;
+    instance.domEnd = end;
+    fragment.appendChild(start);
+    fragment.appendChild(content);
+    fragment.appendChild(end);
+    return fragment;
+}
+export function useState(initial) {
+    const instance = requireInstance();
+    const index = instance.hookIndex++;
+    let hook = instance.hooks[index];
+    if (!hook) {
+        const state = typeof initial === 'function' ? initial() : initial;
+        hook = {
+            kind: 'state',
+            state,
+            setState: (value) => {
+                const next = typeof value === 'function'
+                    ? value(hook.state)
+                    : value;
+                if (Object.is(next, hook.state)) {
+                    return;
+                }
+                hook.state = next;
+                scheduleRootRender(instance.root);
+            },
+        };
+        instance.hooks[index] = hook;
+    }
+    return [hook.state, hook.setState];
+}
+export function useEffect(create, deps) {
+    const instance = requireInstance();
+    const index = instance.hookIndex++;
+    let hook = instance.hooks[index];
+    if (!hook) {
+        hook = {
+            kind: 'effect',
+            deps,
+        };
+        instance.hooks[index] = hook;
+        instance.root.effects.push({ instance, index, create, deps });
+        return;
+    }
+    if (!depsEqual(hook.deps, deps)) {
+        hook.deps = deps;
+        instance.root.effects.push({ instance, index, create, deps });
+    }
+}
+export function useMemo(factory, deps) {
+    const instance = requireInstance();
+    const index = instance.hookIndex++;
+    let hook = instance.hooks[index];
+    if (!hook) {
+        const value = factory();
+        hook = {
+            kind: 'memo',
+            deps,
+            value,
+        };
+        instance.hooks[index] = hook;
+        return value;
+    }
+    if (depsEqual(hook.deps, deps)) {
+        return hook.value;
+    }
+    const value = factory();
+    hook.deps = deps;
+    hook.value = value;
+    return value;
+}
+export function useRef(initial) {
+    const instance = requireInstance();
+    const index = instance.hookIndex++;
+    let hook = instance.hooks[index];
+    if (!hook) {
+        hook = {
+            kind: 'ref',
+            ref: { current: initial },
+        };
+        instance.hooks[index] = hook;
+    }
+    return hook.ref;
+}
+export function useCallback(fn, deps) {
+    const instance = requireInstance();
+    const index = instance.hookIndex++;
+    let hook = instance.hooks[index];
+    if (!hook) {
+        hook = {
+            kind: 'callback',
+            deps,
+            value: fn,
+        };
+        instance.hooks[index] = hook;
+        return fn;
+    }
+    if (depsEqual(hook.deps, deps)) {
+        return hook.value;
+    }
+    hook.deps = deps;
+    hook.value = fn;
+    return fn;
+}
+// Strip the esbuild content hash from chunk filenames so that registry keys
+// remain stable across rebuilds.  Works for both full URLs and path strings.
+// 'https://host/Index-DFFMCZIQ.js'  →  '/Index.js'
+// '/Index-DFFMCZIQ.js?t=1234'       →  '/Index.js'
+// '/app.js'                          →  '/app.js'   (no hash — unchanged)
+function normalizeRegistryKey(url) {
+    let pathname;
+    try {
+        pathname = new URL(url, 'http://x').pathname;
+    }
+    catch {
+        pathname = url.split('?')[0];
+    }
+    // esbuild hashes are exactly 8 uppercase-alphanumeric chars before .js
+    return pathname.replace(/-[A-Za-z0-9]{8}(?=\.js$)/, '');
+}
+export function wrapComponent(component, moduleUrl, exportName) {
+    const key = normalizeRegistryKey(moduleUrl);
+    const meta = { moduleUrl: key, exportName };
+    // Reuse the existing proxy across HMR reloads so that instances holding a
+    // reference to the proxy are never disposed due to a reference identity change.
+    // The proxy delegates to __current, which we update in place on each reload.
+    const record = getModuleRecord(key);
+    const existing = record.exports.get(exportName);
+    if (existing) {
+        console.trace('[hmr:registry] wrapComponent:update', { key, exportName });
+        existing.__current = component;
+        return existing;
+    }
+    console.trace('[hmr:registry] wrapComponent:create', { key, exportName });
+    const proxy = ((props) => proxy.__current(props));
+    proxy.__current = component;
+    proxy.__cathode_hmr = meta;
+    registerExport(meta, proxy);
+    return proxy;
+}
+export function registerRoot(moduleUrl, parent, getNode) {
+    const key = normalizeRegistryKey(moduleUrl);
+    console.trace('[hmr:registry] registerRoot', { raw: moduleUrl, key });
+    const record = getModuleRecord(key);
+    record.roots.add({ parent, getNode });
+}
+export function applyUpdate(moduleUrl, mod) {
+    const key = normalizeRegistryKey(moduleUrl);
+    const record = moduleRegistry.get(key);
+    console.trace('[hmr:registry] applyUpdate', {
+        raw: moduleUrl,
+        key,
+        found: !!record,
+        exports: record ? [...record.exports.keys()] : [],
+        instances: record ? record.instances.size : 0,
+        incoming: Object.keys(mod),
+    });
+    // Proxy implementations are already updated by wrapComponent during module
+    // re-import, so there is nothing left to do here.
+}
+export function refreshModule(moduleUrl) {
+    const key = normalizeRegistryKey(moduleUrl);
+    const record = moduleRegistry.get(key);
+    console.trace('[hmr:registry] refreshModule', {
+        raw: moduleUrl,
+        key,
+        found: !!record,
+        instances: record ? record.instances.size : 0,
+        roots: record ? record.roots.size : 0,
+    });
+    if (!record) {
+        return;
+    }
+    if (record.instances.size > 0) {
+        record.instances.forEach((instance) => {
+            rerenderInstance(instance);
+        });
+        return;
+    }
+    record.roots.forEach((root) => {
+        rerenderRoot(root);
+    });
+}
+export function registerInstanceIfNeeded(instance, component) {
+    const meta = component.__cathode_hmr;
+    if (!meta) {
+        if (instance.meta) {
+            unregisterInstance(instance, instance.meta);
+            instance.meta = undefined;
+        }
+        return;
+    }
+    if (instance.meta?.moduleUrl !== meta.moduleUrl || instance.meta?.exportName !== meta.exportName) {
+        if (instance.meta) {
+            unregisterInstance(instance, instance.meta);
+        }
+        instance.meta = meta;
+    }
+    const record = getModuleRecord(meta.moduleUrl);
+    record.instances.add(instance);
+}
+function requireInstance() {
+    if (!currentInstance) {
+        throw new Error('Cathode hooks can only be used inside components.');
+    }
+    return currentInstance;
+}
+function depsEqual(prev, next) {
+    if (prev === next) {
+        return true;
+    }
+    if (!prev || !next) {
+        return false;
+    }
+    if (prev.length !== next.length) {
+        return false;
+    }
+    for (let i = 0; i < prev.length; i++) {
+        if (!Object.is(prev[i], next[i])) {
+            return false;
+        }
+    }
+    return true;
+}
+function flushEffects(root) {
+    root.effects.forEach((record) => {
+        const hook = record.instance.hooks[record.index];
+        if (hook?.cleanup) {
+            hook.cleanup();
+        }
+        const cleanup = record.create();
+        if (hook) {
+            hook.cleanup = typeof cleanup === 'function' ? cleanup : undefined;
+        }
+    });
+    root.effects = [];
+}
+function scheduleRootRender(root) {
+    if (!renderRoot) {
+        return;
+    }
+    if (scheduledRoots.has(root)) {
+        return;
+    }
+    scheduledRoots.add(root);
+    queueMicrotask(() => {
+        scheduledRoots.delete(root);
+        renderRoot?.(root);
+    });
+}
+function rerenderInstance(instance) {
+    if (!renderNode || !instance.domStart || !instance.domEnd) {
+        return;
+    }
+    beginInstanceRender(instance);
+    instance.childCursor = 0;
+    const nextNode = instance.component(instance.props);
+    endInstanceRender();
+    const content = renderNode(nextNode, instance.root, instance);
+    finalizeInstance(instance);
+    replaceBetween(instance.domStart, instance.domEnd, content);
+    flushEffects(instance.root);
+}
+function rerenderRoot(rootRef) {
+    if (!renderRoot) {
+        return;
+    }
+    const root = prepareRootContext(rootRef.parent, rootRef.getNode());
+    renderRoot(root);
+}
+function replaceBetween(start, end, content) {
+    const parent = start.parentNode;
+    if (!parent) {
+        return;
+    }
+    let cursor = start.nextSibling;
+    while (cursor && cursor !== end) {
+        const next = cursor.nextSibling;
+        parent.removeChild(cursor);
+        cursor = next;
+    }
+    parent.insertBefore(content, end);
+}
+function registerExport(meta, component) {
+    const record = getModuleRecord(meta.moduleUrl);
+    record.exports.set(meta.exportName, component);
+}
+function getModuleRecord(moduleUrl) {
+    let record = moduleRegistry.get(moduleUrl);
+    if (!record) {
+        record = {
+            exports: new Map(),
+            instances: new Set(),
+            roots: new Set(),
+        };
+        moduleRegistry.set(moduleUrl, record);
+    }
+    return record;
+}
+function unregisterInstance(instance, meta) {
+    const record = moduleRegistry.get(meta.moduleUrl);
+    if (!record) {
+        return;
+    }
+    record.instances.delete(instance);
+}
+function disposeInstance(instance) {
+    if (instance.meta) {
+        unregisterInstance(instance, instance.meta);
+    }
+    instance.hooks.forEach((hook) => {
+        if (hook.kind === 'effect' && hook.cleanup) {
+            hook.cleanup();
+        }
+    });
+    instance.childInstances.forEach(disposeInstance);
+}
+function trimInstances(list, cursor) {
+    if (list.length <= cursor) {
+        return;
+    }
+    const removed = list.splice(cursor);
+    removed.forEach(disposeInstance);
+}

package/lib/lazy.js

@@ -51,7 +51,7 @@ function createLazyComponent(loader, autoLoad) {
         }
         // console.trace( '[LazyWrapper.awake] Starting loader()' );
         LazyWrapper.__promise = loader()
-            .then(mod => {
+            .then((mod) => {
             let component = null;
             if (mod && typeof mod === 'object' && 'default' in mod && mod.default) {
                 component = mod.default;
@@ -60,7 +60,7 @@ function createLazyComponent(loader, autoLoad) {
                 component = mod;
             }
             else if (mod && typeof mod === 'object') {
-                const candidates = Object.values(mod).filter((value) => typeof value === 'function');
+                const candidates = Object.values(mod).filter(value => typeof value === 'function');
                 if (candidates.length === 1) {
                     component = candidates[0];
                 }
@@ -72,7 +72,7 @@ function createLazyComponent(loader, autoLoad) {
             LazyWrapper.__component = component;
             LazyWrapper.__status = 'resolved';
         })
-            .catch(err => {
+            .catch((err) => {
             LazyWrapper.__error = err;
             LazyWrapper.__status = 'rejected';
         });

package/lib/runtime.js

@@ -1,13 +1,21 @@
+import { beginInstanceRender, createOrReuseInstance, endInstanceRender, finalizeInstance, finishRootRender, isDevMode, makeInstanceFragment, prepareRootContext, setDevRenderers, } from './hmr-runtime.js';
 import { findLazyPending } from './suspense.js';
 export function h(type, props, ...children) {
     return { type, props: props || {}, children };
 }
 export const Fragment = (props) => Array.isArray(props.children) ? props.children : [props.children];
 export function render(node, parent) {
+    if (isDevMode()) {
+        const root = prepareRootContext(parent, node);
+        parent.innerHTML = '';
+        parent.appendChild(toDOM(node, root, null));
+        finishRootRender(root);
+        return;
+    }
     parent.innerHTML = '';
     parent.appendChild(toDOM(node));
 }
-function toDOM(node) {
+function toDOM(node, root, parentInstance) {
     if (node === null || node === undefined) {
         return document.createTextNode('');
     }
@@ -16,7 +24,7 @@ function toDOM(node) {
     }
     if (Array.isArray(node)) {
         const frag = document.createDocumentFragment();
-        node.forEach(child => frag.appendChild(toDOM(child)));
+        node.forEach(child => frag.appendChild(toDOM(child, root, parentInstance ?? null)));
         return frag;
     }
     // Debug: log VNode type
@@ -28,13 +36,13 @@ function toDOM(node) {
         const { fallback, children } = node.props;
         const pending = findLazyPending(children);
         if (pending.length === 0) {
-            return toDOM(children);
+            return toDOM(children, root, parentInstance ?? null);
         }
         const container = document.createElement('div');
         container.setAttribute('data-cathode-suspense', 'true');
         container.appendChild(toDOM(fallback));
         Promise.all(pending.map(lc => lc.awake())).then(() => {
-            const content = toDOM(children);
+            const content = toDOM(children, root, parentInstance ?? null);
             container.innerHTML = '';
             container.appendChild(content);
         });
@@ -47,7 +55,7 @@ function toDOM(node) {
         placeholder.setAttribute('data-cathode-lazy', 'pending');
         wrapper.awake().then(() => {
             if (wrapper.__status === 'resolved') {
-                const resolved = toDOM(h(wrapper.__component, componentProps));
+                const resolved = toDOM(h(wrapper.__component, componentProps), root, parentInstance ?? null);
                 placeholder.replaceWith(resolved);
             }
         });
@@ -87,7 +95,7 @@ function toDOM(node) {
                 wrapper.__promise.then(() => {
                     // console.trace( '[lazy ondemand] Component loaded:', wrapper.__component?.name, 'status:', wrapper.__status, 'connected:', placeholder.isConnected );
                     if (wrapper.__status === 'resolved' && placeholder.isConnected) {
-                        const resolved = toDOM(h(wrapper.__component, componentProps));
+                        const resolved = toDOM(h(wrapper.__component, componentProps), root, parentInstance ?? null);
                         // console.trace( '[lazy ondemand] Replacing placeholder with resolved component' );
                         placeholder.replaceWith(resolved);
                     }
@@ -119,7 +127,7 @@ function toDOM(node) {
                     if (entry.isIntersecting) {
                         component.awake().then(() => {
                             if (component.__status === 'resolved') {
-                                const resolved = toDOM(h(component, componentProps));
+                                const resolved = toDOM(h(component, componentProps), root, parentInstance ?? null);
                                 container.innerHTML = '';
                                 container.appendChild(resolved);
                             }
@@ -147,16 +155,26 @@ function toDOM(node) {
     if (node.type === '__error_boundary__') {
         const { fallback, children } = node.props;
         try {
-            return toDOM(children);
+            return toDOM(children, root, parentInstance ?? null);
         }
         catch (error) {
             if (typeof fallback === 'function') {
-                return toDOM(fallback(error));
+                return toDOM(fallback(error), root, parentInstance ?? null);
             }
-            return toDOM(fallback);
+            return toDOM(fallback, root, parentInstance ?? null);
         }
     }
     if (typeof node.type === 'function') {
+        if (isDevMode() && root) {
+            const props = { ...node.props, children: node.children };
+            const instance = createOrReuseInstance(root, parentInstance ?? null, node.type, props);
+            beginInstanceRender(instance);
+            const nextNode = instance.component(props);
+            endInstanceRender();
+            const content = toDOM(nextNode, root, instance);
+            finalizeInstance(instance);
+            return makeInstanceFragment(instance, content);
+        }
         return toDOM(node.type({ ...node.props, children: node.children }));
     }
     const el = document.createElement(node.type);
@@ -176,7 +194,7 @@ function toDOM(node) {
     });
     if (node.children) {
         node.children.forEach((child) => {
-            el.appendChild(toDOM(child));
+            el.appendChild(toDOM(child, root, parentInstance ?? null));
         });
     }
     return el;
@@ -186,3 +204,8 @@ if (typeof globalThis !== 'undefined') {
     globalThis.h = h;
     globalThis.Fragment = Fragment;
 }
+setDevRenderers((node, root, parentInstance) => toDOM(node, root, parentInstance), (root) => {
+    root.parent.innerHTML = '';
+    root.parent.appendChild(toDOM(root.lastNode, root, null));
+    finishRootRender(root);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relicloops/cathode",
-  "version": "2.0.0",
+  "version": "2.1.0-000",
   "license": "Apache-2.0",
   "description": "Lightweight JSX runtime.",
   "type": "module",
@@ -18,12 +18,22 @@
     "./jsx-dev-runtime": {
       "types": "./types/jsx-dev-runtime.d.ts",
       "default": "./jsx-dev-runtime.js"
+    },
+    "./hmr": {
+      "types": "./types/hmr.d.ts",
+      "default": "./hmr.js"
+    },
+    "./esbuild-plugin": {
+      "types": "./types/esbuild-plugin.d.ts",
+      "default": "./esbuild-plugin.js"
     }
   },
   "files": [
     "index.js",
     "jsx-runtime.js",
     "jsx-dev-runtime.js",
+    "hmr.js",
+    "esbuild-plugin.js",
     "lib/**/*.js",
     "types/**/*.d.ts",
     "README.md",

package/types/esbuild-plugin.d.ts

@@ -0,0 +1,50 @@
+type Build = {
+    onLoad: (options: {
+        filter: RegExp;
+    }, callback: (args: {
+        path: string;
+    }) => {
+        contents: string;
+        loader: string;
+    } | undefined) => void;
+};
+export type CathodeHMRPluginOptions = {
+    /**
+     * Regex that controls which files are transformed.
+     * Default: /\.tsx$/ — all TSX files in the bundle.
+     */
+    filter?: RegExp;
+};
+/**
+ * esbuild plugin that automatically wraps exported JSX components with
+ * cathode's HMR proxy at build time.
+ *
+ * Only activate this plugin in watch / dev mode:
+ *
+ *   plugins: [
+ *     ...(watchMode ? [cathodeHMRPlugin()] : []),
+ *     deployPlugin,
+ *   ]
+ *
+ * The plugin detects top-level exports whose name starts with an uppercase
+ * letter (PascalCase convention for components) and rewrites:
+ *
+ *   export const Foo = ( props ) => { ... };
+ *   export function Bar( props ) { ... }
+ *
+ * into:
+ *
+ *   import { hmr as __cathode_hmr } from '@relicloops/cathode/hmr';
+ *   const _Foo = ( props ) => { ... };
+ *   function _Bar( props ) { ... }
+ *   export const Foo = __cathode_hmr.wrap( _Foo, import.meta.url, 'Foo' );
+ *   export const Bar = __cathode_hmr.wrap( _Bar, import.meta.url, 'Bar' );
+ *
+ * Files that already contain '__cathode_hmr' or 'hmr.wrap' are left
+ * untouched so that explicit wrapping is never doubled.
+ */
+export declare function cathodeHMRPlugin(options?: CathodeHMRPluginOptions): {
+    name: string;
+    setup: (build: Build) => void;
+};
+export {};

package/types/hmr.d.ts

@@ -0,0 +1,21 @@
+import { applyUpdate, enableDevMode, refreshModule, registerRoot, useCallback, useEffect, useMemo, useRef, useState, wrapComponent } from './lib/hmr-runtime.js';
+export type HMREvent = {
+    type: 'hmr';
+    path: string;
+    event: 'created' | 'modified' | 'deleted' | 'renamed';
+};
+export type HMROptions = {
+    endpoint?: string;
+    pathTransform?: (path: string) => string;
+    onBeforeReload?: (event: HMREvent) => void;
+    onHotUpdate?: (event: HMREvent, moduleUrl: string, mod: Record<string, any>) => void;
+    onHotError?: (event: HMREvent, error: unknown) => void;
+};
+export declare const hmr: {
+    wrap: typeof wrapComponent;
+    registerRoot: typeof registerRoot;
+    applyUpdate: typeof applyUpdate;
+    refreshModule: typeof refreshModule;
+};
+export { applyUpdate, enableDevMode, refreshModule, registerRoot, useCallback, useEffect, useMemo, useRef, useState, wrapComponent as wrap, };
+export declare function connectHMR(options?: HMROptions): () => void;

package/types/lib/hmr-runtime.d.ts

@@ -0,0 +1,82 @@
+export type HMRMeta = {
+    moduleUrl: string;
+    exportName: string;
+};
+export type ComponentFn = (props: any) => any;
+export type ComponentInstance = {
+    component: ComponentFn;
+    props: any;
+    hooks: HookEntry[];
+    hookIndex: number;
+    childInstances: ComponentInstance[];
+    childCursor: number;
+    root: RootContext;
+    domStart: Comment | null;
+    domEnd: Comment | null;
+    meta?: HMRMeta;
+};
+export type RootContext = {
+    parent: HTMLElement;
+    instances: ComponentInstance[];
+    cursor: number;
+    effects: EffectRecord[];
+    lastNode: any;
+};
+type EffectRecord = {
+    instance: ComponentInstance;
+    index: number;
+    create: () => void | (() => void);
+    deps?: any[];
+};
+type HookEntry = StateHook | EffectHook | MemoHook | RefHook | CallbackHook;
+type StateHook = {
+    kind: 'state';
+    state: any;
+    setState: (value: any) => void;
+};
+type EffectHook = {
+    kind: 'effect';
+    deps?: any[];
+    cleanup?: () => void;
+};
+type MemoHook = {
+    kind: 'memo';
+    deps?: any[];
+    value: any;
+};
+type RefHook = {
+    kind: 'ref';
+    ref: {
+        current: any;
+    };
+};
+type CallbackHook = {
+    kind: 'callback';
+    deps?: any[];
+    value: any;
+};
+type RootRender = (root: RootContext) => void;
+type NodeRender = (node: any, root: RootContext, parentInstance: ComponentInstance | null) => Node;
+export declare function enableDevMode(): void;
+export declare function isDevMode(): boolean;
+export declare function setDevRenderers(nodeRenderer: NodeRender, rootRenderer: RootRender): void;
+export declare function prepareRootContext(parent: HTMLElement, node: any): RootContext;
+export declare function finishRootRender(root: RootContext): void;
+export declare function createOrReuseInstance(root: RootContext, parentInstance: ComponentInstance | null, component: ComponentFn, props: any): ComponentInstance;
+export declare function beginInstanceRender(instance: ComponentInstance): void;
+export declare function endInstanceRender(): void;
+export declare function finalizeInstance(instance: ComponentInstance): void;
+export declare function makeInstanceFragment(instance: ComponentInstance, content: Node): DocumentFragment;
+export declare function useState<T>(initial: T | (() => T)): [T, (value: T | ((prev: T) => T)) => void];
+export declare function useEffect(create: () => void | (() => void), deps?: any[]): void;
+export declare function useMemo<T>(factory: () => T, deps?: any[]): T;
+export declare function useRef<T>(initial: T): {
+    current: T;
+};
+export declare function useCallback<T extends (...args: any[]) => any>(fn: T, deps?: any[]): T;
+export declare function wrapComponent<T extends ComponentFn>(component: T, moduleUrl: string, exportName: string): T;
+export declare function registerRoot(moduleUrl: string, parent: HTMLElement, getNode: () => any): void;
+export declare function applyUpdate(moduleUrl: string, mod: Record<string, any>): void;
+export declare function refreshModule(moduleUrl: string): void;
+export declare function registerInstanceIfNeeded(instance: ComponentInstance, component: ComponentFn): void;
+export {};

package/types/lib/suspense.d.ts

@@ -1,5 +1,5 @@
-import type { VNode } from './runtime.js';
 import type { LazyComponent } from './lazy.js';
+import type { VNode } from './runtime.js';
 export interface SuspenseProps {
     fallback: VNode | string | number;
     children?: any;