@webjsdev/core 0.7.32 → 0.7.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.7.32",
+  "version": "0.7.34",
   "type": "module",
   "description": "webjs core runtime - html/css tags, WebComponent base, isomorphic renderers",
   "types": "./index.d.ts",

package/src/component.js

@@ -159,7 +159,7 @@ function defaultHasChanged(a, b) {
  * `attachInternals()` on hydration.
  *
  * Deliberate deviation from lit: lit's `checkValidity` / `reportValidity`
- * THROW on the server. webjs returns `true` instead, to keep SSR
+ * THROW on the server. WebJs returns `true` instead, to keep SSR
  * progressive-enhancement-safe (a stray validity call in a constructor must
  * not 500 the page); the browser does the real validation.
  * @returns {any}

package/src/context.js

@@ -2,7 +2,7 @@
  * Context Protocol: cross-component data sharing without prop drilling.
  *
  * Implements the W3C Community Group Context Protocol so any web component
- * (not just webjs components) can participate as a provider or consumer.
+ * (not just WebJs components) can participate as a provider or consumer.
  *
  * ## When to use
  *

package/src/metadata.d.ts

@@ -259,7 +259,7 @@ export interface Metadata {
    * `<link rel="preconnect">` hints: warm DNS + TLS + TCP to a cross-origin
    * the page is about to talk to (an API host, a font / image CDN). Each
    * entry is a URL string or `{ url, crossorigin? }` (a font CDN needs
-   * `crossorigin`). A single value or an array. webjs ALSO auto-emits one
+   * `crossorigin`). A single value or an array. WebJs ALSO auto-emits one
    * preconnect to the resolved vendor CDN origin for an unpinned app (deduped
    * against an author-declared one).
    */

package/src/render-server.js

@@ -390,7 +390,7 @@ function isProd() {
  * renders an empty (silent, isolated) element so no internal detail leaks.
  *
  * The prod-silence signal is the SERVER's `dev` flag, threaded through the SSR
- * render context (#483). webjs keys prod on the CLI `dev` flag, not `NODE_ENV`,
+ * render context (#483). WebJs keys prod on the CLI `dev` flag, not `NODE_ENV`,
  * and `webjs start` does not export `NODE_ENV=production`, so a bare prod launch
  * would otherwise leak the message. When `dev` is undefined (a context-free
  * `renderToString` with no server signal, e.g. a bare unit test) it falls back

package/src/rich-fetch.js

@@ -8,14 +8,14 @@ const RPC_CONTENT_TYPE = 'application/vnd.webjs+json';
  * `TypedArray`, `Blob`, `File`, `FormData`, cycles).
  *
  * - Adds `Accept: application/vnd.webjs+json` to the request so a
- *   server-side `json(data)` helper encodes with the webjs serializer.
+ *   server-side `json(data)` helper encodes with the WebJs serializer.
  * - If the response content-type matches, decodes with the webjs
  *   serializer and returns the rich value.
  * - Otherwise decodes with plain `.json()` (so any route you haven't
  *   opted in on still works).
  * - Request bodies: if `init.body` is a plain object (not a string,
  *   FormData/Blob/ArrayBuffer/ReadableStream/URLSearchParams), it is
- *   encoded with the webjs serializer and the request content-type is
+ *   encoded with the WebJs serializer and the request content-type is
  *   set to our vendor type.
  *
  * ```js

package/src/router-client.js

@@ -153,7 +153,7 @@ let currentPageUrl = null;
  * Previous value of `history.scrollRestoration` (so we can restore it
  * when the router is disabled). The browser's default behavior of
  * auto-restoring scroll on popstate races with the SPA's own scroll
- * restoration: disabled here so webjs is the sole authority on scroll
+ * restoration: disabled here so WebJs is the sole authority on scroll
  * during navigation. Same pattern as Turbo Drive's
  * `assumeControlOfScrollRestoration()` (turbo/src/core/drive/history.js).
  *
@@ -1189,7 +1189,7 @@ function prefetchSuppressed(anchor) {
 
 /**
  * Resolve the prefetch strategy for an anchor from a `data-prefetch`
- * attribute. webjs has no Link component (links are plain `<a href>`), so
+ * attribute. WebJs has no Link component (links are plain `<a href>`), so
  * the knob is a valid-HTML `data-*` attribute, the same shape SvelteKit
  * (`data-sveltekit-preload-data`) and Astro (`data-astro-prefetch`) use.
  * Next.js / Nuxt / Remix express the same choice as a component PROP
@@ -1284,9 +1284,34 @@ function prefetch(href) {
       if (!/^text\/html\b/i.test(ctype)) return;
       if (resp.status >= 400) return;
       const build = resp.headers.get('x-webjs-build');
+      const src = resp.headers.get('x-webjs-src');
+      // Deploy detected at PREFETCH time (#899). A prefetch fetch carries the
+      // server's current build id AND app-source id. If EITHER differs from what
+      // the page booted with, a deploy landed, so every earlier snapshot/prefetch
+      // is pre-deploy and stale. Evict them here, well before the click (a
+      // hover/viewport prefetch fires early), so a click on a previously-
+      // prefetched link re-fetches fresh (then applySwap hard-reloads on a build
+      // change or soft-applies on a src-only change). This shrinks the window
+      // where a pre-deploy prefetch, whose stored ids equal the still-old page
+      // ids so applySwap alone cannot tell it is stale, is served. Both ids of a
+      // pair must be present: an empty id is the warmup "version unknown", never
+      // a deploy signal.
+      const pageTag = typeof document !== 'undefined' ? document.querySelector('script[type="importmap"]') : null;
+      const pageBuild = pageTag ? pageTag.getAttribute('data-webjs-build') : null;
+      const pageSrc = pageTag ? pageTag.getAttribute('data-webjs-src') : null;
+      if ((build && pageBuild && build !== pageBuild) || (src && pageSrc && src !== pageSrc)) {
+        snapshotCache.clear();
+        prefetchCache.clear();
+        // Deliberately do NOT advance the page's data-webjs-src here (only the
+        // foreground `applySwap` does). A prefetch is speculative; leaving the
+        // reference id on the old deploy keeps applySwap the single authority
+        // that settles the page on the first real navigation. The cost is small:
+        // repeated prefetches in the pre-first-nav window each re-clear the
+        // (already tiny) caches, which converges the instant the user navigates.
+      }
       const finalUrl = resp.redirected && resp.url ? resp.url : href;
       const html = await resp.text();
-      prefetchStore(key, { html, build, finalUrl, at: nowMs() });
+      prefetchStore(key, { html, build, src, finalUrl, at: nowMs() });
     })
     .catch(() => { /* speculative: swallow */ })
     .finally(() => {
@@ -1608,6 +1633,7 @@ async function fetchAndApply(href, frameId, recordHistory, optimisticState, meth
   // shell swap. Null for a buffered (non-streaming) or prefetched response.
   let streamCtx = null;
   let incomingBuild = null;
+  let incomingSrc = null;
   /** @type {number | null} */
   let respStatus = null;
   /** @type {boolean} */
@@ -1633,6 +1659,7 @@ async function fetchAndApply(href, frameId, recordHistory, optimisticState, meth
     if (prefetched) {
       html = prefetched.html;
       incomingBuild = prefetched.build;
+      incomingSrc = prefetched.src;
       finalUrl = prefetched.finalUrl;
       // A consumed prefetch is a successful 200 GET fragment.
       respStatus = 200;
@@ -1725,6 +1752,7 @@ async function fetchAndApply(href, frameId, recordHistory, optimisticState, meth
     // tag to compare. The applySwap importmap-mismatch guard reads
     // this to detect deploys that bumped the vendor pin.
     incomingBuild = resp.headers.get('x-webjs-build');
+    incomingSrc = resp.headers.get('x-webjs-src');
     // Progressive streaming (#473): read only up to the first streamed Suspense
     // boundary so the shell (with fallbacks) swaps in immediately; the rest
     // streams in after the swap. A body with no boundaries reads to completion,
@@ -1763,7 +1791,7 @@ async function fetchAndApply(href, frameId, recordHistory, optimisticState, meth
   // recover in place rather than a destructive full reload.
   if (!doc) { restoreOptimistic(optimisticState); handleNavigationError(href, null, new Error('navigation response did not parse as HTML')); return { ok: false, status: respStatus, aborted: false }; }
 
-  applySwap(doc, frameId, false, finalUrl, incomingBuild);
+  applySwap(doc, frameId, false, finalUrl, incomingBuild, incomingSrc);
 
   if (recordHistory) history.pushState(null, '', finalUrl);
 
@@ -2234,7 +2262,7 @@ function upgradeCustomElementsInRange(range) {
   }
 }
 
-function applySwap(doc, frameId, revalidating, href, incomingBuild) {
+function applySwap(doc, frameId, revalidating, href, incomingBuild, incomingSrc) {
   // SSR action seeding (#472): ingest any seed payload the incoming page
   // carries BEFORE its components are grafted into the live DOM and upgrade, so
   // a soft-navigated async component resolves from the seed instead of
@@ -2308,6 +2336,14 @@ function applySwap(doc, frameId, revalidating, href, incomingBuild) {
       if (currentSig !== incomingSig) mismatch = true;
     }
     if (mismatch && typeof location !== 'undefined') {
+      // A detected cross-deploy mismatch means every URL-keyed snapshot and
+      // speculative prefetch was captured on the OLD deploy, so it is stale
+      // pre-deploy HTML (#899). Evict both caches so no stale entry is applied
+      // on a later soft nav, even when the infinite-reload guard below bails to
+      // a partial swap instead of a full reload (that partial swap must not then
+      // pull a pre-deploy fragment out of the cache).
+      snapshotCache.clear();
+      prefetchCache.clear();
       // Infinite-reload guard: if the importmap appears to genuinely
       // change EVERY navigation (e.g. a developer is live-editing the
       // pin file in dev, or a misbehaving CDN returns different
@@ -2336,6 +2372,27 @@ function applySwap(doc, frameId, revalidating, href, incomingBuild) {
         return;
       }
     } else if (!mismatch) {
+      // No importmap/build mismatch, so no hard reload. But the app-source
+      // signal (#899) is the SECOND tier: if `data-webjs-src` differs, an
+      // app-source or server-framework deploy changed the SSR output while the
+      // running page's browser code is unchanged. A hard reload would be an
+      // over-correction; instead EVICT the URL-keyed snapshot + prefetch caches
+      // (all captured on the OLD deploy) so a later soft nav re-fetches fresh.
+      // The current nav's already-fetched `doc` still applies normally. Both ids
+      // must be present (an empty id is the warmup "unknown", never a signal),
+      // exactly like the build guard.
+      const currentSrc = currentTag ? currentTag.getAttribute('data-webjs-src') : null;
+      if (incomingSrc && currentSrc && incomingSrc !== currentSrc) {
+        snapshotCache.clear();
+        prefetchCache.clear();
+        // Advance the page's reference id. The importmap <script> is preserved
+        // across soft navs (an importmap cannot be re-registered), so without
+        // this the tag would keep its OLD id and EVERY later nav in the new
+        // deploy would re-detect the same mismatch and evict again, defeating
+        // the caches. Updating the attribute (not the importmap body) settles
+        // the page onto the new deploy: evict once, then cache normally.
+        if (currentTag) currentTag.setAttribute('data-webjs-src', incomingSrc);
+      }
       // A clean swap (no importmap mismatch) means we're back to
       // matching client/server importmaps. Clear the reload flag so
       // a future LEGITIMATE mismatch (e.g. a later deploy) gets a
@@ -2609,12 +2666,42 @@ function diffElementInPlace(dst, src) {
   // The attribute version is skipped above; we deliberately do nothing
   // here so the user's typing / checking is never blown away.
 
+  // A hydrated component OWNS its rendered subtree. The client renderer
+  // stashes the live template instance (lit-html parts holding DIRECT
+  // references to the rendered nodes) on the host under
+  // `Symbol.for('webjs.instance')`. Recursing into those children would
+  // import/remove/reorder the very nodes the parts still point at, so the
+  // component's next reactive update would write into detached nodes and
+  // silently do nothing (a dead click after a soft nav, #906). Treat the
+  // component as opaque: the attribute sync above already drove any reactive
+  // property change through `attributeChangedCallback`, so the component
+  // re-renders ITSELF; the router must not touch its internals. This mirrors
+  // Turbo/morphdom, which leave custom elements alone by default.
+  if (isHydratedComponent(dst)) return;
+
   // Recurse into children: collect both sides, run reconcileSiblings on
   // them with synthetic boundary markers. Cheap implementation: use
   // virtual ranges instead of inserting real comment markers.
   reconcileChildren(dst, src);
 }
 
+/**
+ * True when `el` carries a live client-side render instance, i.e. a webjs
+ * component whose `render()` produced the current children and owns them via
+ * lit-html parts. The router must not reconcile INTO such an element (#906).
+ *
+ * Detected via the render-client instance symbol rather than a `customElements`
+ * lookup so it fires only for elements that have actually rendered client-side:
+ * a not-yet-upgraded or purely display-only custom element (no client render,
+ * no parts to corrupt) stays fully reconcilable.
+ *
+ * @param {Element} el
+ * @returns {boolean}
+ */
+function isHydratedComponent(el) {
+  return /** @type {any} */ (el)[Symbol.for('webjs.instance')] != null;
+}
+
 /**
  * Reconcile dst's children to match src's children, in-place.
  *
@@ -2839,7 +2926,7 @@ function getCspNonce() {
   // because it can be called against script/link elements (where
   // browsers DO expose `.nonce` and additionally clear the
   // `nonce` attribute on document load). The `<meta name="csp-nonce">`
-  // element webjs targets has no `.nonce` IDL (only script + link
+  // element WebJs targets has no `.nonce` IDL (only script + link
   // elements do per HTML spec), so the only viable source is the
   // `content` attribute.
   return meta ? meta.getAttribute('content') || '' : '';
@@ -3220,7 +3307,9 @@ export {
   diffElementInPlace as _diffElementInPlace,
   reconcileChildren as _reconcileChildren,
   onPopState as _onPopState,
+  applySwap as _applySwap,
   snapshotCache as _snapshotCache,
+  prefetchCache as _prefetchCache,
   LIVE_ATTRS as _LIVE_ATTRS,
   blurOutgoingFocus as _blurOutgoingFocus,
   onSubmit as _onSubmit,

package/src/routes.d.ts

@@ -3,7 +3,7 @@
  * opt-in, generated route union that types `navigate()` and catches bad
  * hrefs at tsserver time (#258).
  *
- * webjs identity holds: NO build step, NO runtime cost, types-only, opt-in
+ * WebJs identity holds: NO build step, NO runtime cost, types-only, opt-in
  * for JSDoc apps. The mechanism mirrors Next 15's `typedRoutes` but via
  * interface declaration-merging instead of a bundler.
  *
@@ -86,7 +86,7 @@ export type RouteParams<R extends string> = R extends keyof RouteParamMap
 
 /**
  * A value that is BOTH synchronously usable as `T` and `await`-able to `T`
- * (#848). The webjs runtime hands `params` / `searchParams` as a plain object
+ * (#848). The WebJs runtime hands `params` / `searchParams` as a plain object
  * carrying a non-enumerable `then`, so `params.id` and `await params` both
  * work; this type expresses that dual nature to TypeScript.
  */

package/src/serializable.d.ts

@@ -2,7 +2,7 @@
  * Compile-time serializability typing for server actions (#488).
  *
  * A `'use server'` action's arguments and result cross the RPC wire through the
- * webjs serializer, which round-trips a SPECIFIC set of rich types (`Date`,
+ * WebJs serializer, which round-trips a SPECIFIC set of rich types (`Date`,
  * `Map`, `Set`, `BigInt`, `Error`, `RegExp`, `URL`, typed arrays, `ArrayBuffer`,
  * `Blob`, `File`, `FormData`, registered `Symbol`s, plain objects / arrays, and
  * cycles). It does NOT round-trip a FUNCTION or a class instance's METHODS: a
@@ -17,7 +17,7 @@
  * / `SerializableResult` apply it across an action's parameter tuple and its
  * (possibly promised) return.
  *
- * This is OPT-IN by design: webjs actions stay plain `export async function`s
+ * This is OPT-IN by design: WebJs actions stay plain `export async function`s
  * with no wrapper (the framework rewrites the client import to an RPC stub at
  * runtime, it does not wrap the authored function). An author who wants the
  * guard annotates the action with `SerializableActionFn`, e.g.
@@ -40,7 +40,7 @@ export type NonSerializable<Reason extends string = 'this value is not serializa
 type SerializablePrimitive = string | number | boolean | bigint | null | undefined;
 
 /**
- * Built-in rich types the webjs serializer round-trips as themselves (their
+ * Built-in rich types the WebJs serializer round-trips as themselves (their
  * identity / methods survive because the serializer reconstructs the instance).
  * `Map` / `Set` recurse into their members via the top-level mapper.
  */

package/src/serialize.d.ts

@@ -1,5 +1,5 @@
 /**
- * The webjs wire serializer (rich-type round-trip: Date / Map / Set / BigInt /
+ * The WebJs wire serializer (rich-type round-trip: Date / Map / Set / BigInt /
  * Error / typed arrays / Blob / File / FormData / Symbols / cycles).
  */
 export function stringify(value: unknown): Promise<string>;

package/src/serialize.js

@@ -1,5 +1,5 @@
 /**
- * webjs serializer: JSON-friendly encoding for rich JS types.
+ * WebJs serializer: JSON-friendly encoding for rich JS types.
  *
  * Replaces superjson with a pure-ESM, dependency-free implementation
  * tuned to the wire surface that React Server Actions support, plus a

package/src/signal.js

@@ -493,7 +493,7 @@ class SignalWatcher {
    * to the watcher's producer set automatically. Re-arms on every call.
    *
    * Used by the WebComponent integration and the `watch()` directive
-   * because the natural webjs pattern is "watch everything this render
+   * because the natural WebJs pattern is "watch everything this render
    * touches" rather than enumerating signals up front.
    *
    * @param {() => unknown} fn

package/src/testing.js

@@ -1,5 +1,5 @@
 /**
- * Testing utilities for webjs components.
+ * Testing utilities for WebJs components.
  *
  * **When to use (AI hint):** Import from `'@webjsdev/core/testing'` in test files
  * to create, render, and interact with web components in a Node.js test

package/src/webjs-config.d.ts

@@ -1,5 +1,5 @@
 /**
- * TypeScript overlay for the `webjs` config block in a webjs app's
+ * TypeScript overlay for the `webjs` config block in a WebJs app's
  * package.json.
  *
  *     // package.json is JSON, so author it there, but a typed reference
@@ -95,6 +95,17 @@ export interface WebjsDevTasks {
    * the parent and torn down on exit, so a watcher cannot leak past the server.
    */
   parallel?: string[];
+  /**
+   * Extra directories the dev live-reload watcher follows IN ADDITION to the
+   * appDir (#894). The dev server watches its appDir recursively, but an app
+   * that reads content from OUTSIDE its tree (e.g. blog markdown in a repo-root
+   * `blog/` dir, a sibling of the app) sees no reload when that content changes.
+   * Each entry is resolved relative to the app root and MAY escape it
+   * (`"../blog"`); a change under one triggers the same rebuild + browser reload
+   * as an in-tree edit. Missing / overlapping (ancestor or descendant of the
+   * appDir) entries are skipped. Read by the server (`readDevWatchPathsFromApp`).
+   */
+  watch?: string[];
 }
 
 /** Start task orchestration in `webjs.start` (#550). Read by the CLI, not the server. */
@@ -124,7 +135,7 @@ export interface WebjsCspConfig {
 }
 
 /**
- * The `webjs` object in a webjs app's package.json. Every key is
+ * The `webjs` object in a WebJs app's package.json. Every key is
  * optional. Mirrors what the server readers actually consume, NOT a
  * Next.js superset.
  */

package/src/websocket-client.js

@@ -1,6 +1,6 @@
 /**
  * Tiny client-side WebSocket helper with automatic reconnection, JSON
- * parse/stringify, and the webjs CSRF-style matches-origin wss:// scheme
+ * parse/stringify, and the WebJs CSRF-style matches-origin wss:// scheme
  * rewriting.
  *
  * ```js