tungsten 0.3.1 → 0.3.2

package/dist/hydrate/hydrate.sxyt.js

@@ -0,0 +1,302 @@
+function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+import { expect } from 'chai';
+import { Window } from 'happy-dom';
+import { describe } from 'sxy-test-runner';
+import { TungstenSimpleComponent } from "../Components.js";
+import { Instance } from "../Instance/Instance.js";
+import { initStores } from "../Servers/initStores.js";
+import { UpdateScheduler } from "../update/UpdateScheduler.js";
+import { contentTreeToRenderingTree } from "../render/contentTreeToRenderingTree.js";
+import { renderingNodeToHtml } from "../render/renderingTreeToHtml.js";
+import { DomPointer } from "../DomPointer.js";
+import { hydrateRootComponent } from "./hydrate.js";
+import { WideRenderedContentNodeIsComponent } from "../RenderedContentNode.js";
+import { AnyComponentIsFunctionComponentStandIn } from "../AnyComponent.js";
+import { hotSwapFunctionComponent } from "../update/integrateUpdateVdom.js";
+import { setCurrentInstance } from "../hmr/instanceRegistry.js";
+import { applyHmrModule } from "../hmr/applyHmrModule.js";
+import { jsxs as _jsxs, jsx as _jsx } from "tungsten/jsxRuntime.js";
+const Greeting = ({
+  name
+}) => {
+  return _jsxs("button", {
+    children: ["Hello ", name]
+  });
+};
+Greeting.style = {
+  moduleName: 'Greeting',
+  tags: {
+    button: 'greeting-button'
+  },
+  classes: {}
+};
+class Root extends TungstenSimpleComponent {
+  constructor(...args) {
+    super(...args);
+    _defineProperty(this, "content", () => _jsx(Greeting, {
+      name: "Ada"
+    }));
+  }
+}
+function makeInstance(document, runtimeContext) {
+  const location = '/';
+  const globalData = {};
+  const matchedRouteInfo = {
+    key: null,
+    params: {},
+    content: null
+  };
+  const {
+    internalStore,
+    stores,
+    storeSubscriptions
+  } = initStores(location, null, globalData, matchedRouteInfo);
+  const instanceConfig = {
+    prod: false,
+    useRootComponent: true,
+    clientSideNav: false,
+    siteBasePath: '/',
+    staticSite: false
+  };
+  const emptyRoutes = {}; // eslint-disable-line no-type-assertion/no-type-assertion -- not exercised by this test
+  return new Instance(location, instanceConfig, null, emptyRoutes, emptyRoutes,
+  // eslint-disable-line no-type-assertion/no-type-assertion
+  internalStore, stores, storeSubscriptions, globalData, matchedRouteInfo, runtimeContext);
+}
+describe('hydrateRootComponent() - function component styling', ({
+  it
+}) => {
+  it('keeps the server-rendered class attribute on a styled function component after hydration', async () => {
+    const window = new Window();
+    const document = window.document; // eslint-disable-line no-type-assertion/no-type-assertion -- happy-dom's Document is structurally compatible
+    const bridgedGlobals = globalThis; // eslint-disable-line no-type-assertion/no-type-assertion -- bridging happy-dom's globals onto the global scope
+    bridgedGlobals.Node = window.Node;
+    bridgedGlobals.Text = window.Text;
+    bridgedGlobals.Comment = window.Comment;
+    bridgedGlobals.Element = window.Element;
+    bridgedGlobals.HTMLElement = window.HTMLElement;
+    bridgedGlobals.Document = window.Document;
+    bridgedGlobals.document = document;
+    bridgedGlobals.window = window;
+    // navigation: false on both instances - this test never touches routing, and it sidesteps
+    // Instance's popstate listener setup, which reaches for the process-wide `window` global
+    // when no runtimeContext is given (isClient.ts caches typeof window at first import, and
+    // other test files in this same process import happy-dom, so relying on "no runtimeContext
+    // means server" here is not reliable the way it is in the real server/client bundle split)
+    const ssrScheduler = new UpdateScheduler();
+    const ssrInstance = makeInstance(document, {
+      document,
+      window: document.defaultView,
+      scheduler: ssrScheduler,
+      navigation: false
+    });
+    const tree = await contentTreeToRenderingTree(_jsx(Root, {}), null, ssrInstance, false);
+    const headData = {
+      found: false,
+      instance: ssrInstance,
+      clientImportAliases: {},
+      importAliases: {},
+      compilationLocation: '',
+      dev: false,
+      tungstenPublicEnv: undefined,
+      siteBasePath: '',
+      hmr: true
+    };
+    const html = await renderingNodeToHtml(tree, false, headData, null);
+    // styleContentSxy prefixes every tag match with componentBumpClass ('__c__')
+    expect(html).to.contain('class="__c__ greeting-button"');
+    document.body.innerHTML = html;
+    // hydrate exactly the way the client does
+    const scheduler = new UpdateScheduler();
+    const runtimeContext = {
+      document,
+      window: document.defaultView,
+      scheduler,
+      navigation: false
+    };
+    const hydrateInstance = makeInstance(document, runtimeContext);
+    const domPointer = new DomPointer(document.body, 0);
+    await hydrateRootComponent(hydrateInstance, Root, domPointer, {
+      insideForm: false
+    });
+    const button = document.body.querySelector('button');
+    expect(button?.getAttribute('class')).to.equal('__c__ greeting-button');
+    scheduler.dispose();
+    ssrScheduler.dispose();
+  });
+  it('sets __renderedNode during hydration, so a hot-swap can find and replace it', async () => {
+    // hydrateFunctionComponent builds its own wrapper independently of the reconciler's
+    // equivalent functions in integrateUpdateVdom.ts - those set element.__renderedNode, but
+    // hydration never did, so hotSwapPrepare() (which requires it) silently bailed out on
+    // every hydrated component in the real client, and applyHmrModule() counted the swap as
+    // successful anyway because it didn't check the swap functions' return value. Both are
+    // fixed; this reproduces the full round trip end to end.
+    const window = new Window();
+    const document = window.document; // eslint-disable-line no-type-assertion/no-type-assertion -- happy-dom's Document is structurally compatible
+    const bridgedGlobals = globalThis; // eslint-disable-line no-type-assertion/no-type-assertion -- bridging happy-dom's globals onto the global scope
+    bridgedGlobals.Node = window.Node;
+    bridgedGlobals.Text = window.Text;
+    bridgedGlobals.Comment = window.Comment;
+    bridgedGlobals.Element = window.Element;
+    bridgedGlobals.HTMLElement = window.HTMLElement;
+    bridgedGlobals.Document = window.Document;
+    bridgedGlobals.document = document;
+    bridgedGlobals.window = window;
+    const ssrScheduler = new UpdateScheduler();
+    const ssrInstance = makeInstance(document, {
+      document,
+      window: document.defaultView,
+      scheduler: ssrScheduler,
+      navigation: false
+    });
+    const tree = await contentTreeToRenderingTree(_jsx(Root, {}), null, ssrInstance, false);
+    const headData = {
+      found: false,
+      instance: ssrInstance,
+      clientImportAliases: {},
+      importAliases: {},
+      compilationLocation: '',
+      dev: false,
+      tungstenPublicEnv: undefined,
+      siteBasePath: '',
+      hmr: true
+    };
+    const html = await renderingNodeToHtml(tree, false, headData, null);
+    document.body.innerHTML = html;
+    const scheduler = new UpdateScheduler();
+    const runtimeContext = {
+      document,
+      window: document.defaultView,
+      scheduler,
+      navigation: false
+    };
+    const hydrateInstance = makeInstance(document, runtimeContext);
+    const domPointer = new DomPointer(document.body, 0);
+    const rootElement = await hydrateRootComponent(hydrateInstance, Root, domPointer, {
+      insideForm: false
+    });
+    const wrapper = rootElement.__currentContent;
+    if (!WideRenderedContentNodeIsComponent(wrapper) || !AnyComponentIsFunctionComponentStandIn(wrapper.element)) {
+      throw new Error('expected the hydrated root to directly wrap a single function component');
+    }
+    const hydratedElement = wrapper.element;
+    expect(hydratedElement.__renderedNode).to.not.equal(undefined);
+    const NewGreeting = ({
+      name
+    }) => {
+      return _jsxs("button", {
+        children: ["Hi there ", name]
+      });
+    };
+    NewGreeting.style = {
+      moduleName: 'Greeting',
+      tags: {
+        button: 'greeting-button'
+      },
+      classes: {}
+    };
+    const swapped = await hotSwapFunctionComponent(hydratedElement, NewGreeting);
+    expect(swapped).to.not.equal(null);
+    expect(document.body.innerHTML).to.contain('Hi there Ada');
+    expect(document.body.innerHTML).to.not.contain('Hello Ada');
+    scheduler.dispose();
+    ssrScheduler.dispose();
+  });
+  it('end-to-end: SSR -> hydrate -> a real dev-mode edit applies without a full reload', async () => {
+    // This is the high-level test for the actual, user-visible bug ("editing a component
+    // always triggers a full page reload instead of an in-place swap"). It goes through the
+    // real hydrate() -> applyHmrModule() pipeline exactly as the dev-mode reload script does
+    // (setCurrentInstance() + applyHmrModule(), not a lower-level helper like
+    // hotSwapFunctionComponent() called directly), so it catches applyHmrModule()
+    // miscounting a failed swap as successful and hydration never setting __renderedNode in
+    // one broad assertion (DOM shows the edited content) rather than two narrow ones.
+    //
+    // It does NOT cover the third cause (the registration gate checking
+    // runtimeContext !== undefined instead of isClient) - this test, like the others in this
+    // file, deliberately passes a real runtimeContext to sidestep isClient.ts's module-load-
+    // order flakiness in a shared test process, so runtimeContext is always defined here
+    // regardless of which gate the source uses. FunctionComponentStandIn.sxyt.ts covers that
+    // cause specifically, by forcing isClient directly instead of relying on either detection
+    // path.
+    const window = new Window();
+    const document = window.document; // eslint-disable-line no-type-assertion/no-type-assertion -- happy-dom's Document is structurally compatible
+    const bridgedGlobals = globalThis; // eslint-disable-line no-type-assertion/no-type-assertion -- bridging happy-dom's globals onto the global scope
+    bridgedGlobals.Node = window.Node;
+    bridgedGlobals.Text = window.Text;
+    bridgedGlobals.Comment = window.Comment;
+    bridgedGlobals.Element = window.Element;
+    bridgedGlobals.HTMLElement = window.HTMLElement;
+    bridgedGlobals.Document = window.Document;
+    bridgedGlobals.document = document;
+    bridgedGlobals.window = window;
+    const ssrScheduler = new UpdateScheduler();
+    const ssrInstance = makeInstance(document, {
+      document,
+      window: document.defaultView,
+      scheduler: ssrScheduler,
+      navigation: false
+    });
+    const tree = await contentTreeToRenderingTree(_jsx(Root, {}), null, ssrInstance, false);
+    const headData = {
+      found: false,
+      instance: ssrInstance,
+      clientImportAliases: {},
+      importAliases: {},
+      compilationLocation: '',
+      dev: false,
+      tungstenPublicEnv: undefined,
+      siteBasePath: '',
+      hmr: true
+    };
+    const html = await renderingNodeToHtml(tree, false, headData, null);
+    document.body.innerHTML = html;
+    const scheduler = new UpdateScheduler();
+    const runtimeContext = {
+      document,
+      window: document.defaultView,
+      scheduler,
+      navigation: false
+    };
+    const hydrateInstance = makeInstance(document, runtimeContext);
+    // exactly what hydrate.tsx's real hydrate() does right after constructing its Instance
+    setCurrentInstance(hydrateInstance);
+    const domPointer = new DomPointer(document.body, 0);
+    await hydrateRootComponent(hydrateInstance, Root, domPointer, {
+      insideForm: false
+    });
+    // stands in for "the file was edited and the browser re-imported it fresh" - a
+    // same-named export with different markup, exactly like applyHmrModule() receives from
+    // the dev-mode reload script
+    const EditedGreeting = ({
+      name
+    }) => {
+      return _jsxs("button", {
+        children: ["Edited ", name]
+      });
+    };
+    // identity matching is by name, and a const's inferred .name is its own variable name
+    // ("EditedGreeting") - force it to match the export name the real dev-mode reload script
+    // would see when re-importing the edited file (the export is still called "Greeting")
+    Object.defineProperty(EditedGreeting, 'name', {
+      value: 'Greeting'
+    });
+    EditedGreeting.style = {
+      moduleName: 'Greeting',
+      tags: {
+        button: 'greeting-button'
+      },
+      classes: {}
+    };
+    const result = await applyHmrModule({
+      Greeting: EditedGreeting
+    }, '/test/end-to-end-Greeting.tsx');
+    expect(result.matched).to.equal(true);
+    expect(result.orphaned).to.equal(false);
+    expect(document.body.innerHTML).to.contain('Edited Ada');
+    expect(document.body.innerHTML).to.not.contain('Hello Ada');
+    scheduler.dispose();
+    ssrScheduler.dispose();
+  });
+});

package/dist/hydrate/reconcileHydratedAttributes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reconcileHydratedAttributes.d.ts","sourceRoot":"","sources":["../../src/hydrate/reconcileHydratedAttributes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAIxD,MAAM,MAAM,iBAAiB,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,gFAAgF;IAChF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,CAAA;AA6BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2BAA2B,CACvC,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,WAAW,EACpB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,GACnD,IAAI,CAkCN"}
+{"version":3,"file":"reconcileHydratedAttributes.d.ts","sourceRoot":"","sources":["../../src/hydrate/reconcileHydratedAttributes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAIxD,MAAM,MAAM,iBAAiB,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,gFAAgF;IAChF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,CAAA;AA6BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2BAA2B,CACvC,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,WAAW,EACpB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,GACnD,IAAI,CAuCN"}

package/dist/hydrate/reconcileHydratedAttributes.js

@@ -40,9 +40,17 @@ function setAttribute(domNode, name, value) {
  */
 export function reconcileHydratedAttributes(node, domNode, onMismatch) {
   // A copy: processProps() rewrites what it is given, and these props stay in
-  // the content tree for the next update to diff against.
+  // the content tree for the next update to diff against. children is pulled out
+  // first, same as the server renderer (renderingTreeToHtml.ts) and the client
+  // update path (integrateUpdateVdom.ts's processAttributes()) both do - it is
+  // rendered content, not an HTML attribute, and processProps() was never meant
+  // to receive it.
+  const {
+    children: _children,
+    ...restProps
+  } = node[$props]; // eslint-disable-line @typescript-eslint/no-unused-vars
   const expected = processProps({
-    ...node[$props]
+    ...restProps
   });
   const handled = new Set();
   for (const name in expected) {

package/dist/hydrate/reconcileHydratedAttributes.sxyt.js

@@ -142,6 +142,23 @@ describe('reconcileHydratedAttributes()', ({
     });
     expect(mismatches).to.deep.equal([]);
   });
+  // children is rendered content, not an attribute - the server renderer and the client
+  // update path both strip it before comparing/writing attributes, and hydration has to
+  // match or it writes the stringified child list (e.g. "[object Object],[object Object]")
+  // onto every element in the page as a literal "children" attribute.
+  it('does not write children as an attribute', () => {
+    const {
+      attributes,
+      mismatches
+    } = reconcile('div', {
+      id: 'd',
+      children: ['a', 'b']
+    }, '<div id="d"></div>');
+    expect(attributes).to.deep.equal({
+      id: 'd'
+    });
+    expect(mismatches).to.deep.equal([]);
+  });
   it('reports what changed, for a dev-mode warning', () => {
     const {
       mismatches

package/dist/importDevModuleWithRetry.d.ts

@@ -0,0 +1,3 @@
+export declare function isTransientDevModuleError(e: unknown): boolean;
+export declare function importDevModuleWithRetry(url: string, attempts?: number, delayMs?: number): Promise<any>;
+//# sourceMappingURL=importDevModuleWithRetry.d.ts.map

package/dist/importDevModuleWithRetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"importDevModuleWithRetry.d.ts","sourceRoot":"","sources":["../src/importDevModuleWithRetry.ts"],"names":[],"mappings":"AAuBA,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAU7D;AAMD,wBAAsB,wBAAwB,CAC1C,GAAG,EAAE,MAAM,EACX,QAAQ,SAAK,EACb,OAAO,SAAM,GACd,OAAO,CAAC,GAAG,CAAC,CAUd"}

package/dist/importDevModuleWithRetry.js

@@ -0,0 +1,46 @@
+// importDevModuleWithRetry
+// exports importDevModuleWithRetry (function)
+//
+// Dev-mode dynamic import wrapper. tsc's own --watch mode emits a multi-file
+// edit (e.g. a rename spanning two files) one recompiled file at a time, so
+// there's a real window where one file has landed and the other hasn't yet.
+// A dev-server request for a component in that window hits a genuine (but
+// self-resolving within a few hundred ms) module-shape error - without this,
+// that's a scary SSR error page for what is, from the developer's
+// perspective, a completely normal edit. Retrying a few times with a fresh
+// cache-busting query per attempt rides out the window; a real, permanent
+// error still surfaces (just slightly slower) once attempts are exhausted.
+// A two-file edit's compile cycle runs tsc's incremental emit followed by a
+// separate downstream babel recompile, sequentially - observed live to take
+// several seconds under load, so the default budget below is generous rather
+// than tuned to a happy-path guess. There's no precise "compile cycle
+// finished" signal plumbed through to here to await instead; this is a
+// bounded heuristic, not a proper synchronization fix.
+// Exported so other dev-only tools (the error page's auto-retry script - see
+// devErrorPageAutoRetry.ts) can recognize the same transient shape without
+// duplicating the heuristic.
+export function isTransientDevModuleError(e) {
+  if (!(e instanceof Error)) return false;
+  if (e.code === 'ERR_MODULE_NOT_FOUND') return true;
+  if (/does not provide an export named/.test(e.message)) return true;
+  // A within-file version of the same race: a multi-step edit can transiently save a file
+  // whose import line was updated but whose JSX/body still references the old local name -
+  // that's a plain runtime ReferenceError, not an ESM linking error, but self-resolves the same
+  // way once the file's own recompile catches up. Kept narrow (a bare identifier only) so it
+  // doesn't swallow other ReferenceError shapes that are more likely to be genuine bugs.
+  return e instanceof ReferenceError && /^\w+ is not defined$/.test(e.message);
+}
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+export async function importDevModuleWithRetry(url, attempts = 30, delayMs = 250) {
+  for (let attempt = 0;; attempt++) {
+    try {
+      const attemptUrl = attempt === 0 ? url : `${url}${url.includes('?') ? '&' : '?'}retryAttempt=${attempt}`;
+      return await import(attemptUrl); // eslint-disable-line @typescript-eslint/no-unsafe-return
+    } catch (e) {
+      if (attempt >= attempts - 1 || !isTransientDevModuleError(e)) throw e;
+      await delay(delayMs);
+    }
+  }
+}

package/dist/importDevModuleWithRetry.sxyt.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=importDevModuleWithRetry.sxyt.d.ts.map

package/dist/importDevModuleWithRetry.sxyt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"importDevModuleWithRetry.sxyt.d.ts","sourceRoot":"","sources":["../src/importDevModuleWithRetry.sxyt.ts"],"names":[],"mappings":""}

package/dist/importDevModuleWithRetry.sxyt.js

@@ -0,0 +1,104 @@
+import { expect } from 'chai';
+import { describe } from 'sxy-test-runner';
+import { mkdtemp, rm, writeFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { importDevModuleWithRetry, isTransientDevModuleError } from "./importDevModuleWithRetry.js";
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+async function makeFixture() {
+  const dir = await mkdtemp(join(tmpdir(), 'tungsten-import-dev-module-retry-'));
+  const depPath = join(dir, 'dep.mjs');
+  const entryPath = join(dir, 'entry.mjs');
+  // dep.mjs never changes - it's the entry file itself that's momentarily
+  // stale on disk, exactly like Home.js briefly still reading its
+  // pre-rename import statement while Button.js has already been rewritten
+  await writeFile(depPath, `export const NewName = 2\n`);
+  await writeFile(entryPath, `export { OldName as NewName } from './dep.mjs'\n`);
+  return {
+    dir,
+    depPath,
+    entryPath
+  };
+}
+describe('importDevModuleWithRetry()', ({
+  it
+}) => {
+  it(`rides out a transient module-shape mismatch, succeeding once the entry file itself catches up`, async () => {
+    const {
+      dir,
+      entryPath
+    } = await makeFixture();
+    try {
+      // simulate the entry file's own recompile (e.g. babel finishing
+      // its pass over Home.tsx) landing a little after this request
+      // started - the exact race this helper exists for
+      void delay(150).then(() => writeFile(entryPath, `export { NewName } from './dep.mjs'\n`));
+      const module = await importDevModuleWithRetry(`file://${entryPath}`, 10, 50);
+      expect(module.NewName).to.equal(2);
+    } finally {
+      await rm(dir, {
+        recursive: true,
+        force: true
+      });
+    }
+  });
+  it(`gives up and throws the real error once attempts are exhausted`, async () => {
+    const {
+      dir,
+      entryPath
+    } = await makeFixture();
+    try {
+      let threw = false;
+      try {
+        await importDevModuleWithRetry(`file://${entryPath}`, 3, 20);
+      } catch (e) {
+        threw = true;
+        expect(String(e)).to.contain('does not provide an export');
+      }
+      expect(threw).to.equal(true);
+    } finally {
+      await rm(dir, {
+        recursive: true,
+        force: true
+      });
+    }
+  });
+  it(`does not retry a genuine, unrelated error - so real bugs still surface immediately`, async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'tungsten-import-dev-module-retry-real-error-'));
+    try {
+      const brokenPath = join(dir, 'broken.mjs');
+      await writeFile(brokenPath, `this is not valid javascript {{{\n`);
+      const start = Date.now();
+      let threw = false;
+      try {
+        await importDevModuleWithRetry(`file://${brokenPath}`, 10, 200);
+      } catch {
+        threw = true;
+      }
+      expect(threw).to.equal(true);
+      // a real syntax error must not be retried - if it were, this would
+      // take multiple * 200ms delays instead of failing on the first attempt
+      expect(Date.now() - start).to.be.lessThan(200);
+    } finally {
+      await rm(dir, {
+        recursive: true,
+        force: true
+      });
+    }
+  });
+});
+describe('isTransientDevModuleError()', ({
+  it
+}) => {
+  it(`recognizes a bare "X is not defined" ReferenceError - the within-file version of the same race, seen live when a file's JSX still referenced a just-renamed import mid-multi-step-edit`, () => {
+    expect(isTransientDevModuleError(new ReferenceError('Button is not defined'))).to.equal(true);
+  });
+  it('does not match a differently-shaped ReferenceError, to stay a narrow signal', () => {
+    expect(isTransientDevModuleError(new ReferenceError('Cannot access X before initialization'))).to.equal(false);
+  });
+  it('does not match an unrelated TypeError', () => {
+    expect(isTransientDevModuleError(new TypeError(`Cannot read properties of undefined (reading 'foo')`))).to.equal(false);
+  });
+});

package/dist/render/HeadData.d.ts

@@ -11,5 +11,6 @@ export type HeadData = {
     dev: boolean;
     tungstenPublicEnv: TungstenEnvOrUndefined;
     siteBasePath: SiteBasePath;
+    hmr: boolean | 'reload';
 };
 //# sourceMappingURL=HeadData.d.ts.map

package/dist/render/HeadData.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HeadData.d.ts","sourceRoot":"","sources":["../../src/render/HeadData.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAE9D,MAAM,MAAM,YAAY,GAAG,EAAE,GAAG,IAAI,MAAM,EAAE,CAAA;AAE5C,MAAM,MAAM,QAAQ,GAAG;IACnB,KAAK,EAAE,OAAO,CAAA;IACd,QAAQ,EAAE,QAAQ,CAAC;IACnB,mBAAmB,EAAE,aAAa,CAAC;IACnC,aAAa,EAAE,aAAa,CAAC;IAC7B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,GAAG,EAAE,OAAO,CAAC;IACb,iBAAiB,EAAE,sBAAsB,CAAC;IAC1C,YAAY,EAAE,YAAY,CAAA;CAC7B,CAAA"}
+{"version":3,"file":"HeadData.d.ts","sourceRoot":"","sources":["../../src/render/HeadData.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAE9D,MAAM,MAAM,YAAY,GAAG,EAAE,GAAG,IAAI,MAAM,EAAE,CAAA;AAE5C,MAAM,MAAM,QAAQ,GAAG;IACnB,KAAK,EAAE,OAAO,CAAA;IACd,QAAQ,EAAE,QAAQ,CAAC;IACnB,mBAAmB,EAAE,aAAa,CAAC;IACnC,aAAa,EAAE,aAAa,CAAC;IAC7B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,GAAG,EAAE,OAAO,CAAC;IACb,iBAAiB,EAAE,sBAAsB,CAAC;IAC1C,YAAY,EAAE,YAAY,CAAC;IAC3B,GAAG,EAAE,OAAO,GAAG,QAAQ,CAAA;CAC1B,CAAA"}

package/dist/render/contentToHtml.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contentToHtml.d.ts","sourceRoot":"","sources":["../../src/render/contentToHtml.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,eAAe,CAAA;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAMvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAI9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAA;AAGrE,wBAAsB,aAAa,CAC/B,eAAe,EAAE,eAAe,EAAE,mBAAmB,EAAE,aAAa,EACpE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EACxC,MAAM,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,YAAY,EACnE,iBAAiB,GAAE,sBAAkC,EAAE,GAAG,UAAQ,GACnE,OAAO,CAAC,MAAM,CAAC,CAoDjB"}
+{"version":3,"file":"contentToHtml.d.ts","sourceRoot":"","sources":["../../src/render/contentToHtml.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,eAAe,CAAA;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAMvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAI9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAA;AAGrE,wBAAsB,aAAa,CAC/B,eAAe,EAAE,eAAe,EAAE,mBAAmB,EAAE,aAAa,EACpE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EACxC,MAAM,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,YAAY,EACnE,iBAAiB,GAAE,sBAAkC,EAAE,GAAG,UAAQ,GACnE,OAAO,CAAC,MAAM,CAAC,CAqDjB"}

package/dist/render/contentToHtml.js

@@ -22,7 +22,8 @@ export async function contentToHtml(compilationInfo, clientImportAliases, conten
     compilationLocation: compilationInfo.buildCodeLocation,
     dev,
     tungstenPublicEnv,
-    siteBasePath: siteBasePathOverride
+    siteBasePath: siteBasePathOverride,
+    hmr: config.hmr
   };
   //console.log('rendering tree', inspect(tree, { depth: 99 } ))
   let html = await renderingNodeToHtml(tree, false, headData, null);

package/dist/render/processHead.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"processHead.d.ts","sourceRoot":"","sources":["../../src/render/processHead.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAK7C,OAAO,EAAE,oBAAoB,EAAqB,MAAM,qBAAqB,CAAA;AAO7E,wBAAgB,WAAW,CACvB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,EAAE,QAAQ,QAmHrB"}
+{"version":3,"file":"processHead.d.ts","sourceRoot":"","sources":["../../src/render/processHead.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAK7C,OAAO,EAAE,oBAAoB,EAAqB,MAAM,qBAAqB,CAAA;AAS7E,wBAAgB,WAAW,CACvB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,EAAE,QAAQ,QAwLrB"}

package/dist/render/processHead.js

@@ -3,6 +3,8 @@ import { clientFolder, componentCssFolder, componentCssFile } from "../settings.
 import { addImportMap } from "./addImportMap.js";
 import { $props, $type } from "../contentNodeSymbols.js";
 import { windowGlobalEnvStatement } from 'tungsten/env/windowGlobalEnvStatement.js';
+import { frameworkDestLocation } from "../build/frameworkDestLocation.js";
+import { devErrorPageClearRetryScript } from "../Servers/devErrorPageAutoRetry.js";
 // process the tree returned by the root component
 // doing things like ensuring there is are html and head elements,
 // and adding necessary style and script tags
@@ -12,7 +14,8 @@ export function processHead(headNode, headData) {
     importAliases,
     clientImportAliases,
     dev,
-    siteBasePath
+    siteBasePath,
+    hmr
   } = headData;
   //console.log('processing head. dev is', dev)
   if (headNode[$props].children === undefined) headNode[$props].children = [];else if (!Array.isArray(headNode[$props].children)) headNode[$props].children = [headNode[$props].children];
@@ -59,16 +62,54 @@ export function processHead(headNode, headData) {
     };
     cjsHelpersScriptNode[$props].type = 'module';
     headNode[$props].children.unshift(cjsHelpersScriptNode);
-    // auto-reload the page whenever the dev build finishes recompiling.
-    // this is a plain full-page reload signal, not module-level hot patching.
-    const liveReloadScriptNode = {
+    // A successful render means whatever the error page's auto-retry script (see
+    // devErrorPageAutoRetry.ts) may have been counting is over - clear it so a later,
+    // unrelated transient error gets its own full retry budget instead of inheriting a
+    // stale count.
+    const clearErrorRetryScriptNode = {
       [$type]: 'script',
       [$props]: {
         'data--t-internal': undefined,
-        children: `(function(){` + `var es=new EventSource('${siteBasePath}/__tungsten_live_reload__');` + `es.addEventListener('js',function(){location.reload()});` + `es.addEventListener('css',function(){location.reload()});` + `})();`
+        children: devErrorPageClearRetryScript
       }
     };
-    headNode[$props].children.unshift(liveReloadScriptNode);
+    headNode[$props].children.unshift(clearErrorRetryScriptNode);
+    // Auto-reload / HMR. This has to stay a raw inline script rather than a real imported
+    // module: it fetches whichever file just recompiled via a computed, cache-busted
+    // import() call, and any dynamic import() with a non-literal argument anywhere in the
+    // framework's traced dependency graph makes the package-copying step that serves
+    // framework code to the browser throw (it requires every import specifier to be
+    // statically known so it can be rewritten/copied). Keeping this logic as untraced text
+    // sidesteps that. applyHmrModule.js itself has no dynamic imports, so it's safely
+    // reachable via a normal static import elsewhere (see hydrate.tsx) and gets copied
+    // there, then loaded here by computed URL. See tungsten/docs/hmr.md.
+    // Tier 1 (hmr: 'reload', or nothing left for Tier 2 to do): always full-reload. A
+    // simple, independent branch from Tier 2's logic - restored as an explicit config value
+    // so it's available as a one-line escape hatch if Tier 2 itself is misbehaving.
+    const tier1OnlyScript = `(function(){` + `var es=new EventSource('${siteBasePath}/__tungsten_live_reload__');` + `es.addEventListener('css',function(){location.reload()});` + `es.addEventListener('js',function(){location.reload()});` + `})();`;
+    // Tier 2: attempt an in-place component/CSS hot-swap before falling back to a full
+    // reload. See tungsten/docs/hmr.md.
+    const tier2Script = `(function(){` + `var es=new EventSource('${siteBasePath}/__tungsten_live_reload__');` + `function fullReload(reason){console.info('[tungsten-hmr] full reload:',reason);location.reload()}` + `function loadHmr(){return import('${frameworkDestLocation}/hmr/applyHmrModule.js')}`
+    // CSS has no state to preserve, so re-applying it is always safe: refreshStylesheets()
+    // inserts the new link and only removes the old one once it's loaded, so there's no
+    // gap where nothing is applied (a plain href swap can produce a visible flash).
+    + `es.addEventListener('css',function(){` + `console.info('[tungsten-hmr] css change, refreshing stylesheets');` + `loadHmr().then(function(hmr){return Promise.all(hmr.refreshStylesheets())})` + `.catch(function(e){console.error('[tungsten-hmr] stylesheet refresh failed',e)});` + `});` + `es.addEventListener('js',function(ev){` + `var payload;` + `try{payload=JSON.parse(ev.data)}catch(e){fullReload('bad payload');return}` + `var files=(payload&&payload.files)||[];` + `if(files.length===0){fullReload('no files in payload');return}` + `console.info('[tungsten-hmr] fetching',files);` + `loadHmr().then(function(hmr){`
+    // a component's own inline style block piggybacks on this same JS pipeline (it
+    // lives in the .tsx/.jsx source, not a separate .css file), so refresh stylesheets
+    // here too rather than only on a dedicated 'css' event - independently of the
+    // component swap below, so a stylesheet load error doesn't force a full reload.
+    + `Promise.all(hmr.refreshStylesheets())` + `.catch(function(e){console.error('[tungsten-hmr] stylesheet refresh failed',e)});` + `return Promise.all(files.map(function(f){return import(f+'?t='+Date.now())}))` + `.then(function(modules){` + `return Promise.all(modules.map(function(m,i){return hmr.applyHmrModule(m,files[i])}))` + `})` + `})` + `.then(function(results){` + `console.info('[tungsten-hmr] results',results);` + `if(results.some(function(r){return r&&r.orphaned})){fullReload('a component export was renamed or removed');return}` + `if(!results.some(function(r){return r&&r.matched}))fullReload('no matching live component found')` + `})` + `.catch(function(e){console.error('[tungsten-hmr] swap failed',e);fullReload('error during swap')});` + `});` + `})();`;
+    // hmr === false: no live-reload script at all (auto-refresh fully disabled).
+    if (hmr !== false) {
+      const liveReloadScriptNode = {
+        [$type]: 'script',
+        [$props]: {
+          'data--t-internal': undefined,
+          children: hmr === true ? tier2Script : tier1OnlyScript
+        }
+      };
+      headNode[$props].children.unshift(liveReloadScriptNode);
+    }
   }
   const {
     content: _,

package/dist/render/processHead.sxyt.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=processHead.sxyt.d.ts.map

package/dist/render/processHead.sxyt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processHead.sxyt.d.ts","sourceRoot":"","sources":["../../src/render/processHead.sxyt.ts"],"names":[],"mappings":""}