@webjsdev/core 0.8.0 → 0.9.0

package/src/render-server/expand.js

@@ -1,7 +1,7 @@
-import { stylesToString, isCSS } from '../css.js';
+import { stylesToString, finalizeStyles, lightDomStylesMessage } from '../css.js';
 import { unsafeHTML } from '../directives.js';
 import { escapeAttr } from '../escape.js';
-import { defaultSSRErrorTemplate, browserMemberHint } from './errors.js';
+import { defaultSSRErrorTemplate, browserMemberHint, isProd } from './errors.js';
 import {
   applyAttrsToInstance, consumePropAttrs, parseAttrs, seedServerAttrs,
   withHostMarker,
@@ -45,6 +45,7 @@ const NON_BLANK = /\S/;
 export function beginComponent(w, tag, Cls, opening, attrs) {
   if (w.ctx && w.ctx.usedComponents) w.ctx.usedComponents.add(tag);
   const isShadow = Cls.shadow === true;
+  if (!isShadow) reportLightDomStyles(w, tag, Cls);
   const frame = {
     kind: 'component', tag, Cls, isShadow, instance: null, opening, tpl: undefined,
     pending: /** @type {Promise<unknown> | null} */ (null), presentAttrNames: /** @type {Set<string> | null} */ (null),
@@ -142,7 +143,7 @@ export async function finishComponent(w, frame, children) {
         // Native <slot> stays as-is in the DSD template: the browser projects
         // the host's light children natively. The authored children stay in
         // place after the template, and the source end tag is kept.
-        return `${frame.opening}<template shadowrootmode="open">${styleString(Cls)}${inner}</template>${children}${frame.closeText}`;
+        return `${frame.opening}${dsdOpenTag(Cls)}${styleString(Cls)}${inner}</template>${children}${frame.closeText}`;
       }
       if (!NON_BLANK.test(inner)) {
         // An empty rendered template (a decorator component with no render(),
@@ -169,10 +170,12 @@ export async function finishComponent(w, frame, children) {
 async function renderOwnTemplate(w, frame, children) {
   const owner = w.owner;
   w.owner = frame.isShadow ? null : { tag: frame.tag, partition: partitionChildren(children, frame.segments), consumed: null };
+  w.componentDepth = (w.componentDepth || 0) + 1;
   try {
     return await w.capture(() => w.value(frame.tpl));
   } finally {
     w.owner = owner;
+    w.componentDepth -= 1;
   }
 }
 
@@ -204,12 +207,54 @@ function partitionChildren(children, segments) {
   return groups;
 }
 
+/**
+ * The Declarative Shadow DOM opening tag for a shadow component, carrying
+ * Lit's `static shadowRootOptions` as the template attributes the HTML parser
+ * maps onto `attachShadow()`: the mode, `delegatesFocus`, `clonable` and
+ * `serializable`. The common case (no options) is the constant open tag.
+ * @param {any} Cls
+ * @returns {string}
+ */
+export function dsdOpenTag(Cls) {
+  const o = Cls.shadowRootOptions;
+  if (!o) return OPEN_DSD;
+  const mode = o.mode === 'closed' ? 'closed' : 'open';
+  if (mode === 'open' && !o.delegatesFocus && !o.clonable && !o.serializable) return OPEN_DSD;
+  return `<template shadowrootmode="${mode}"` +
+    (o.delegatesFocus ? ' shadowrootdelegatesfocus' : '') +
+    (o.clonable ? ' shadowrootclonable' : '') +
+    (o.serializable ? ' shadowrootserializable' : '') + '>';
+}
+const OPEN_DSD = '<template shadowrootmode="open">';
+
 function styleString(Cls) {
-  const rawStyles = Cls.styles;
-  const styleList = Array.isArray(rawStyles) ? rawStyles : rawStyles && isCSS(rawStyles) ? [rawStyles] : [];
-  return stylesToString(styleList);
+  // `elementStyles` is the class's finalized list (Lit's `finalizeStyles`);
+  // a class not built on WebComponent has none, so flatten its styles here.
+  return stylesToString(Cls.elementStyles ?? finalizeStyles(Cls.styles));
+}
+
+/** Light-DOM classes already reported for `static styles`. @type {WeakSet<Function>} */
+const REPORTED_LIGHT_STYLES = new WeakSet();
+
+/**
+ * A light-DOM component's `static styles` never apply (there is no shadow
+ * root to adopt them into). Report it once per class in dev, on the server,
+ * so the cause shows up in the terminal as well as the browser console.
+ * @param {import('./walk.js').Walker} w
+ * @param {string} tag
+ * @param {any} Cls
+ */
+function reportLightDomStyles(w, tag, Cls) {
+  if (!Cls.styles || REPORTED_LIGHT_STYLES.has(Cls)) return;
+  const dev = w.dev === undefined ? !isProd() : !!w.dev;
+  if (!dev) return;
+  REPORTED_LIGHT_STYLES.add(Cls);
+  console.error(lightDomStylesMessage(tag));
 }
 
+/** Key of the hook the server installs to hear about isolated component failures. */
+const COMPONENT_ERROR_HOOK = Symbol.for('webjs.ssr.componentError');
+
 /**
  * Per-component error isolation (#469). The element renders a
  * component-scoped error state in its place (renderError() customises it;
@@ -230,20 +275,28 @@ async function errorState(w, frame) {
   } else {
     console.error(`[webjs] SSR failed for <${tag}>:`, e);
   }
+  // The page still renders (the failure is isolated to this element), so the
+  // server hears about it only through this hook: @webjsdev/server installs it
+  // and routes it to the current request's dev status.
+  const report = /** @type {any} */ (globalThis)[COMPONENT_ERROR_HOOK];
+  if (typeof report === 'function') {
+    try { report(tag, e); } catch { /* a reporting failure must not affect the render */ }
+  }
   const err = e instanceof Error ? e : new Error(String(e));
   let errorInner = '';
   try {
     let errTpl;
     if (instance && typeof instance.renderError === 'function') errTpl = instance.renderError(err);
     if (errTpl === undefined) errTpl = defaultSSRErrorTemplate(tag, err, w.dev);
-    errorInner = await w.capture(() => w.value(errTpl));
+    w.componentDepth = (w.componentDepth || 0) + 1;
+    try { errorInner = await w.capture(() => w.value(errTpl)); } finally { w.componentDepth -= 1; }
   } catch (renderErrorThrew) {
     console.error(`[webjs] renderError() for <${tag}> also threw:`, renderErrorThrew);
     errorInner = '';
   }
   let opening = frame.opening;
   if (!isShadow) opening = withHostMarker(opening);
-  if (isShadow) return `${opening}<template shadowrootmode="open">${styleString(Cls)}${errorInner}</template>`;
+  if (isShadow) return `${opening}${dsdOpenTag(Cls)}${styleString(Cls)}${errorInner}</template>`;
   return `${opening}<!--webjs-hydrate-->${errorInner}</${tag}>`;
 }
 

package/src/render-server/served-attrs.js

@@ -16,8 +16,7 @@ import { appendReflectedAttrs } from './attrs.js';
  *   - one the element REMOVED is dropped from the tag.
  * An attribute the element left alone keeps its source text BYTE FOR BYTE
  * (its quoting, its entity spelling, its position), so a page whose
- * components touch nothing renders exactly as before, which the elision
- * on-versus-off differential relies on.
+ * components touch nothing renders exactly as before.
  *
  * What stays as written, and why each is safe:
  *   - `data-webjs-prop-*`: a parent's `.prop=${value}` binding, consumed into

package/src/render-server/walk.js

@@ -12,6 +12,8 @@ import {
   isSubmitterReflectedProp, FORM_ACTION_FIELD,
 } from '../form-action.js';
 import { isRepeat } from '../repeat.js';
+import { isDirectiveResult, PartType } from '../directive.js';
+import { isSignal } from '../signal.js';
 import { isSuspense } from '../suspense.js';
 import { isUnsafeHTML, isLive, isKeyed, isGuard, isTemplateContent, isRef, isCache, isUntil, isAsyncAppend, isAsyncReplace, isWatch } from '../directives.js';
 import { stringify } from '../serialize.js';
@@ -83,6 +85,8 @@ export class Walker {
     this.defer = 0;
     /** @type {any} */
     this.tagState = null;
+    /** How many component templates (render / renderError) are being walked. */
+    this.componentDepth = 0;
   }
 
   // -------------------------------------------------------------------------
@@ -165,6 +169,10 @@ export class Walker {
    * @param {unknown} value
    */
   async value(value) {
+    if (isDirectiveResult(value)) value = resolveDirective(value, CHILD_PART);
+    // A bare `${signal}` renders its current value (the client binds the hole
+    // to the signal so it updates in place, as `watch()` does).
+    if (isSignal(value)) value = /** @type any */ (value).get();
     if (value == null || value === nothing || value === noChange) return;
     if (typeof (/** @type any */ (value).then) === 'function') {
       return this.value(await value);
@@ -175,6 +183,14 @@ export class Walker {
       for (const v of value) await this.value(v);
       return;
     }
+    // Any other iterable renders like an array, as in lit: a generator from
+    // `map()` / `join()` / `range()`, a Set, a Map's values. A string is
+    // iterable too and was handled above, and every directive marker is a
+    // plain object with no iterator, so none of them reaches this branch.
+    if (typeof value === 'object' && typeof (/** @type any */ (value))[Symbol.iterator] === 'function') {
+      for (const v of /** @type {Iterable<unknown>} */ (value)) await this.value(v);
+      return;
+    }
     // An unsafeHTML value is raw markup. With expansion on, the components it
     // carries render too (the output rescan used to find them), through the
     // same tokenizer the template went through, so a tag written inside one
@@ -244,6 +260,12 @@ export class Walker {
 
   /** @param {import('../html.js').TemplateResult} tr */
   async template(tr) {
+    // Only a tagged template's strings carry `raw`, so a result that arrived as
+    // data (JSON with the `_$webjs` brand) is refused rather than rendered as
+    // markup, as the client renderer and lit's `trustFromTemplateString` do.
+    if (!Array.isArray(tr.strings) || !Object.prototype.hasOwnProperty.call(tr.strings, 'raw')) {
+      throw new Error("[webjs] refusing to render a template result whose strings are not a tagged template's (a TemplateResult built from data, not by html``).");
+    }
     await this.ops(compile(tr.strings), tr.values);
     this.flush();
   }
@@ -317,6 +339,9 @@ export class Walker {
                       if (piece && typeof piece.then === 'function') piece = await piece;
                       if (isLive(piece)) piece = piece.value;
                     }
+                    piece = await attrValueOf(piece);
+                    if (isDirectiveResult(piece)) piece = resolveDirective(piece, { type: PartType.ATTRIBUTE, name: op.name, tagName: op.tag?.toUpperCase() });
+                    if (isSignal(piece) || isWatch(piece)) piece = signalValue(piece);
                     if (isAttributeMap(piece)) piece = attributeMapText(piece, op.name);
                     assertNotFunctionActionAttr(piece, op.name, op.tag);
                     if (piece === nothing) omitted = true;
@@ -336,6 +361,9 @@ export class Walker {
               }
               // A hole inside a quoted/unquoted value, the `action="${fn}"` and
               // mixed `action="/x/${fn}"` shapes (#1154).
+              val = await attrValueOf(val);
+              if (isDirectiveResult(val)) val = resolveDirective(val, { type: PartType.ATTRIBUTE, name: op.name, tagName: op.tag?.toUpperCase() });
+              if (isSignal(val) || isWatch(val)) val = signalValue(val);
               assertNotFunctionActionAttr(val, op.name, op.tag);
               this.buf += escapeAttr(String(val ?? ''));
               break;
@@ -351,6 +379,8 @@ export class Walker {
   // -------------------------------------------------------------------------
   // Start tags
   // -------------------------------------------------------------------------
+  // (attrValueOf, the attribute-position unwrap of the value-carrying
+  // built-in directives, is a module function below.)
 
   /** @param {string} tag */
   open(tag) {
@@ -400,6 +430,18 @@ export class Walker {
    * @param {unknown} val
    */
   async attr(op, val) {
+    if (op.kind !== 'event') val = await attrValueOf(val);
+    // A custom directive renders its `render()` result at SSR (lit's server
+    // rule: `update()` needs a DOM). An event part is client-only, so its
+    // directive never runs here.
+    if (isDirectiveResult(val) && op.kind !== 'event') {
+      const type = op.kind === 'prop' ? PartType.PROPERTY : op.kind === 'bool' ? PartType.BOOLEAN_ATTRIBUTE : PartType.ATTRIBUTE;
+      val = resolveDirective(val, { type, name: op.name, tagName: op.tag?.toUpperCase() });
+    }
+    // A bare signal in an attribute or boolean hole renders its current value;
+    // a `.prop` hole hands the signal object itself to the property, as lit's
+    // signals package does.
+    if ((isSignal(val) || isWatch(val)) && (op.kind === 'plain' || op.kind === 'bool')) val = signalValue(val);
     if (isAttributeMap(val)) {
       if (op.kind !== 'plain') throw new Error('classMap/styleMap require an attribute binding.');
       val = attributeMapText(val, op.name);
@@ -410,7 +452,10 @@ export class Walker {
     const name = /** @type string */ (op.name);
     const tag = /** @type string */ (op.tag);
     if (op.kind === 'event') {
-      // An event listener is client-only behaviour, dropped at SSR.
+      // An event listener is client-only behaviour, dropped at SSR. Outside
+      // any component template it can never run either: a page or layout
+      // never hydrates. Dev makes that a render error naming the fix.
+      if (this.dev && this.componentDepth === 0) throw new Error(pageBindingError(true, name, tag));
       return;
     }
     if (op.kind === 'prop') {
@@ -424,6 +469,9 @@ export class Walker {
         return;
       }
       if (!tag.includes('-')) {
+        if (this.dev && this.componentDepth === 0 && !isReflectedFormProp(name, tag)) {
+          throw new Error(pageBindingError(false, name, tag));
+        }
         // A native element's `.prop` is dropped at SSR. It still refuses a
         // function where the property is a REFLECTED IDL attribute (`.action`
         // on a form, `.formAction` on a button or input), and records the
@@ -464,7 +512,7 @@ export class Walker {
         // page's own url; the identity is remembered for the `>`. Trailing
         // whitespace goes with the attribute, since every injected attribute
         // carries its own leading space.
-        if (ts) ts.actionId = assertIdentifiableAction(await resolveFormActionId(val), tag);
+        if (ts) ts.actionId = assertIdentifiableAction(await resolveFormActionId(val), tag, val);
         this.buf = this.buf.replace(/\s+$/, '');
       } else {
         // #1207, the submitter binding. The identity replaces the
@@ -475,7 +523,7 @@ export class Walker {
         if (attrs.has('name')) assertSubmitterHasNoName(attrs.get('name') || '', tag, false);
         if (attrs.has('value')) assertSubmitterHasNoValue(tag);
         if (attrs.has('form')) assertSubmitterHasNoFormAttribute(tag);
-        const subId = assertIdentifiableAction(await resolveFormActionId(val), tag);
+        const subId = assertIdentifiableAction(await resolveFormActionId(val), tag, val);
         if (ts) ts.submitterTag = tag;
         this.buf += `name="${FORM_ACTION_FIELD}" value="${escapeAttr(subId)}"`;
       }
@@ -726,6 +774,37 @@ export class Walker {
 
 const EMPTY = Object.freeze([]);
 
+/**
+ * The current value of a bare signal or a `watch(signal)` marker in an
+ * attribute-shaped hole (SSR reads it once; the client binds the hole).
+ * @param {any} v
+ */
+function signalValue(v) {
+  return isWatch(v) ? v.signal.get() : v.get();
+}
+
+/** The part info every child-position directive is constructed with. */
+const CHILD_PART = Object.freeze({ type: PartType.CHILD });
+
+/**
+ * Resolve a custom directive result (`directive(C)(...values)`) to the value
+ * it renders, lit's server rule: construct the class with the part info and
+ * call `render(...values)` (never `update()`, which needs a DOM). A directive
+ * that returns another directive resolves in turn. A fresh instance per
+ * render is right here, since an SSR render is one shot.
+ * @param {any} value
+ * @param {{ type: number, name?: string, tagName?: string }} partInfo
+ * @returns {unknown}
+ */
+function resolveDirective(value, partInfo) {
+  for (let depth = 0; isDirectiveResult(value); depth++) {
+    if (depth > 100) throw new Error('[webjs] a custom directive kept returning directives (more than 100 levels deep).');
+    const instance = new value.ctor(partInfo);
+    value = instance.render(...value.values);
+  }
+  return value;
+}
+
 /**
  * #1155: a `.method` / `.enctype` / `.encoding` prop on a form is dropped at
  * SSR but applied for real in the browser, where all three are reflected IDL
@@ -796,3 +875,56 @@ export async function streamValue(value, ctx, controller) {
   await w.value(value);
   w.flush();
 }
+
+/**
+ * A form-shape property the dedicated form guards judge (and refuse with a
+ * more specific message), so the page-binding error leaves it to them.
+ * @param {string} name
+ * @param {string} tag
+ */
+function isReflectedFormProp(name, tag) {
+  return /^(?:action|method|enctype|encoding|formaction|formmethod|formenctype)$/i.test(name)
+    && /^(?:form|button|input)$/.test(tag);
+}
+
+/**
+ * The dev error for an `@event` or native `.prop` binding in a template no
+ * component renders (a page or layout, which never hydrates).
+ * @param {boolean} isEvent an `@event` listener (else a `.prop` binding)
+ * @param {string} name
+ * @param {string} tag
+ */
+function pageBindingError(isEvent, name, tag) {
+  const what = isEvent ? `an \`@${name}\` event listener` : `a \`.${name}\` property binding`;
+  return `webjs: ${what} on <${tag}> in a page or layout template. Pages and layouts render only on the server and never hydrate, so it is dropped and never runs. `
+    + `Move the interactive markup into a WebComponent and render its tag from the page (its render() hydrates in the browser)`
+    + (!isEvent ? ', or write a plain attribute (\`' + name.toLowerCase() + '=${value}\`) when the value only needs to reach the HTML' : '')
+    + '. This check runs in dev only. See https://webjs.dev/docs/troubleshooting#binding-in-page-template';
+}
+
+/**
+ * The value a value-carrying built-in directive stands for in an ATTRIBUTE,
+ * property or boolean position, as in Lit (#1686): `guard` renders its
+ * callback's result, `until` its first non-promise argument (else the first
+ * promise to settle, a rejection reading as no value), `keyed` and `cache`
+ * their value. A child position unwraps these in `value()`; an attribute hole
+ * used to stringify the directive object to "[object Object]".
+ * @param {unknown} v
+ * @returns {Promise<unknown>}
+ */
+async function attrValueOf(v) {
+  for (let depth = 0; depth < 8; depth++) {
+    /** @type any */
+    const d = v;
+    if (isGuard(d)) v = d.fn();
+    else if (isKeyed(d) || isCache(d)) v = d.value;
+    else if (isLive(d)) v = d.value;
+    else if (isUntil(d)) {
+      const sync = d.args.find((a) => !a || typeof a.then !== 'function');
+      if (sync !== undefined || d.args.some((a) => !a || typeof a.then !== 'function')) v = sync;
+      else if (d.args.length) v = await Promise.race(d.args.map((p) => Promise.resolve(p).catch(() => undefined)));
+      else v = undefined;
+    } else return v;
+  }
+  return v;
+}

package/src/render-server.d.ts

@@ -12,3 +12,6 @@ export function renderToStream(
   value: unknown,
   opts?: { ssr?: boolean; suspenseCtx?: SuspenseContext },
 ): ReadableStream;
+/** A React-ism in an html template's static strings: `className=` / `htmlFor=` or a capitalised tag. */
+export function findJsxIsm(strings: readonly string[]): { kind: 'attr' | 'tag'; name: string } | null;
+export function jsxIsmMessage(ism: { kind: 'attr' | 'tag'; name: string }): string;

package/src/render-server.js

@@ -4,3 +4,5 @@
 // backs the published `@webjsdev/core/server` subpath, so re-exporting it would
 // widen the package's public API for a helper no consumer asked for.
 export { renderToString, renderToStream } from './render-server/stream.js';
+// The JSX-in-template scan, shared with `webjs check` (`no-jsx-attributes`).
+export { findJsxIsm, jsxIsmMessage } from './jsx-guard.js';

package/src/repeat.d.ts

@@ -3,13 +3,18 @@
 // exported, so it cannot be named, and no consumer constructs one by hand.
 export interface RepeatDirective<T> {
   items: T[];
-  keyFn: (item: T, i: number) => string | number;
+  keyFn: (item: T, i: number) => unknown;
   templateFn: (item: T, i: number) => unknown;
 }
 
 export function repeat<T>(
   items: Iterable<T>,
-  keyFn: (item: T, i: number) => string | number,
+  keyFn: (item: T, i: number) => unknown,
+  templateFn: (item: T, i: number) => unknown,
+): RepeatDirective<T>;
+/** lit's two-argument form: no key function, so each item is keyed by its index. */
+export function repeat<T>(
+  items: Iterable<T>,
   templateFn: (item: T, i: number) => unknown,
 ): RepeatDirective<T>;
 export function isRepeat(x: unknown): x is RepeatDirective<unknown>;

package/src/repeat.js

@@ -7,8 +7,10 @@
  * html`<ul>${repeat(items, (it) => it.id, (it) => html`<li>${it.title}</li>`)}</ul>`;
  * ```
  *
- * Without `repeat()`, an array re-render rebuilds every child (losing focus,
- * selection, and scroll). With `repeat()`, the client renderer maintains a
+ * Without `repeat()`, an array updates positionally: the DOM for item N is
+ * reused for whatever is now at index N, so focus, selection and component
+ * state follow the position, not the item. With `repeat()`, the client
+ * renderer maintains a
  * `Map<key, TemplateInstance>`: matched items update in place, new items
  * mount fresh, removed items unmount, and the surviving DOM nodes are moved
  * (not recreated) when the order changes.
@@ -16,19 +18,31 @@
  * Keys must be stable and unique within the call. Bad keys (array indices)
  * defeat the purpose; prefer a stable id from the data.
  *
+ * The two-argument form, `repeat(items, (it) => html`...`)`, is lit's too: with
+ * no key function each item is keyed by its INDEX, which makes it a plain
+ * positional list (no DOM moves on reorder). Pass a key function whenever item
+ * identity has to follow the data.
+ *
  * On the server this marker is just iterated: order matters, keys don't.
  */
 
 const REPEAT = Symbol.for('webjs.repeat');
 
+/** The key of an item `repeat(items, template)` was given no key function for. */
+const indexKey = (/** @type {unknown} */ _item, /** @type {number} */ i) => i;
+
 /**
  * @template T
  * @param {Iterable<T>} items
- * @param {(item: T, i: number) => string | number} keyFn
- * @param {(item: T, i: number) => unknown} templateFn
+ * @param {((item: T, i: number) => unknown)} keyFnOrTemplate the key function,
+ *   or, when `templateFn` is omitted, the template function (lit's two-argument form)
+ * @param {(item: T, i: number) => unknown} [templateFn]
  */
-export function repeat(items, keyFn, templateFn) {
-  return { [REPEAT]: true, items: [...items], keyFn, templateFn };
+export function repeat(items, keyFnOrTemplate, templateFn) {
+  if (templateFn === undefined) {
+    return { [REPEAT]: true, items: [...items], keyFn: indexKey, templateFn: keyFnOrTemplate };
+  }
+  return { [REPEAT]: true, items: [...items], keyFn: keyFnOrTemplate, templateFn };
 }
 
 /** @param {unknown} x */

package/src/router-client/dom-differ.js

@@ -224,9 +224,25 @@ export function diffElementInPlace(dst, src) {
   }
   // Update attributes from src; remove ones not in src.
   const srcAttrs = new Set();
+  // A server-passed `.prop` binding on a reused, upgraded component (#1686):
+  // its `data-webjs-prop-*` attribute was read once at upgrade and stripped,
+  // so writing the new value as an attribute changed nothing and the property
+  // stayed stale after a same-page update. A binding whose value changed is
+  // handed to the component to decode; an unchanged one is left alone, so a
+  // value the component changed locally survives, as in Lit.
+  const hydrated = isHydratedComponent(dst) && typeof (/** @type any */ (dst))._hydratePropAttrs === 'function';
+  let propsChanged = false;
   for (const attr of src.attributes) {
     srcAttrs.add(attr.name);
     if (LIVE_ATTRS.has(attr.name)) continue;
+    if (hydrated && attr.name.startsWith('data-webjs-prop-')) {
+      const seen = /** @type any */ (dst).__webjsPropAttrValues;
+      if (!seen || seen.get(attr.name) !== attr.value) {
+        dst.setAttribute(attr.name, attr.value);
+        propsChanged = true;
+      }
+      continue;
+    }
     // The serialized-restore stamp is a message to a NOT-YET-UPGRADED
     // element's connectedCallback; copying it onto a live reused host would
     // leave a consume-once marker lingering in the live DOM forever. Note
@@ -243,6 +259,7 @@ export function diffElementInPlace(dst, src) {
     if (LIVE_ATTRS.has(attr.name)) continue;
     if (!srcAttrs.has(attr.name)) dst.removeAttribute(attr.name);
   }
+  if (propsChanged) /** @type any */ (dst)._hydratePropAttrs();
   // For form-control-like elements, preserve live IDL state.
   // (`value`, `checked`, `open`, etc.: see LIVE_ATTRS below for full list.)
   // The attribute version is skipped above; we deliberately do nothing

package/src/router-client/fetch-apply.js

@@ -15,7 +15,8 @@ import { restoreOptimistic } from './dom-differ.js';
 import { parseHTML } from './dom-parse.js';
 import { clearFrameBusy, markFrameBusy } from './frames.js';
 import { handleNavigationError } from './nav-error.js';
-import { navigate } from './navigator.js';
+import { navigate, revalidate } from './navigator.js';
+import { parseRefreshHeader } from '../refresh-header.js';
 import { prefetchTake } from './prefetch.js';
 import { currentNavigationToken } from './state.js';
 import { readStreamedShell, streamBoundariesProgressively } from './stream.js';
@@ -53,7 +54,7 @@ import { _swapCommit, applySwap } from './swap.js';
  *   top on a forward navigation (#1436), from `data-preserve-scroll` on the
  *   link or form, or from `navigate(url, { scroll: false })`. It suppresses only
  *   the scroll-to-top writes, never the hash-anchor scroll.
- * @returns {Promise<{ ok: boolean, status: number | null, aborted: boolean, applied: boolean }>}
+ * @returns {Promise<{ ok: boolean, status: number | null, aborted: boolean, applied: boolean, devError?: boolean }>}
  *   The fetch outcome, so a caller (the form-submission busy/event lifecycle)
  *   can report whether the submission settled as a success, an error, or an
  *   abort. `ok` mirrors `response.ok` for an HTTP response (a 422 validation
@@ -72,7 +73,62 @@ import { _swapCommit, applySwap } from './swap.js';
  *   degradation to a hard navigation from an importmap mismatch or a poisoned
  *   boundary scan). A caller deciding whether to fall back to a full page load
  *   wants `applied`; one reporting the submission's success wants `ok`.
+ *
+ *   `devError` is set for a `refresh` answered with `X-Webjs-Dev-Error: 1`
+ *   (#1689): the dev render failed, nothing was applied, and the page on
+ *   screen is meant to stay as it is under the dev overlay.
+ */
+/**
+ * Whether two urls name the same document (origin, path and query; the hash
+ * is a position within it).
+ * @param {string} a @param {string} b
+ */
+function sameDocumentUrl(a, b) {
+  try {
+    const x = new URL(a, location.href);
+    const y = new URL(b, location.href);
+    return x.origin === y.origin && x.pathname === y.pathname && x.search === y.search;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The focused element and its text selection, for a same-page update.
+ * @returns {{ el: Element, start: number | null, end: number | null } | null}
  */
+function captureFocus() {
+  const el = document.activeElement;
+  if (!el || el === document.body || el === document.documentElement) return null;
+  /** @type any */
+  const input = el;
+  let start = null;
+  let end = null;
+  try { start = input.selectionStart ?? null; end = input.selectionEnd ?? null; } catch { /* not a text control */ }
+  return { el, start, end };
+}
+
+/**
+ * Give focus back to the element that had it, when the morph kept the node.
+ * @param {{ el: Element, start: number | null, end: number | null }} state
+ */
+function restoreFocus(state) {
+  const { el, start, end } = state;
+  if (!el.isConnected || document.activeElement === el) return;
+  /** @type any */
+  const target = el;
+  if (typeof target.focus !== 'function') return;
+  // WebKit scrolls a text control into view on setSelectionRange even after a
+  // preventScroll focus, so the window offset is put back afterwards.
+  const x = window.scrollX;
+  const y = window.scrollY;
+  target.focus({ preventScroll: true });
+  if (start !== null && end !== null) {
+    try { target.setSelectionRange(start, end); } catch { /* not a text control */ }
+  }
+  if (window.scrollX !== x || window.scrollY !== y) window.scrollTo({ left: x, top: y, behavior: 'instant' });
+}
+
 export async function fetchAndApply(href, frameId, recordHistory, optimisticState, method, body, signal, token, revalidating, opts) {
   method = method || 'GET';
   const refresh = (opts && opts.refresh) || undefined;
@@ -176,11 +232,27 @@ export async function fetchAndApply(href, frameId, recordHistory, optimisticStat
     const resp = await fetch(href, init);
     respStatus = resp.status;
     respOk = resp.ok;
+    // A dev render that reported an error (#1689). The server marks it, and
+    // the dev overlay is already up describing it. A refresh leaves the page
+    // that last rendered on screen under the overlay, as Next does, so the
+    // edit that fixes the error refreshes it in place; applying the error page
+    // would share no boundary with it and hard-navigate, and so would the fix.
+    // Only `webjs dev` sends the header.
+    if (refresh && resp.headers.get('x-webjs-dev-error') === '1') {
+      try { await resp.body?.cancel(); } catch (_) { /* already consumed */ }
+      return { ok: false, status: respStatus, aborted: false, applied: false, devError: true };
+    }
     // `fetch` follows a 303 transparently and its headers are then unreadable,
     // so this lands on a non-redirect response: the 422 failure re-render, or
     // any form response that answers in place.
     const invalidated = parseTagHeader(resp.headers.get('x-webjs-invalidate'));
     if (invalidated.length) markStale(invalidated);
+    // `revalidatePath()` in a form action (a 422 re-render, or any response
+    // answered in place): drop the router's cached copies of those paths.
+    for (const e of parseRefreshHeader(resp.headers.get('x-webjs-refresh'))) {
+      if (e.layout || e.path.includes('[')) revalidate();
+      else revalidate(e.path);
+    }
     const ctype = resp.headers.get('content-type') || '';
     const isHTML = /^text\/html\b/i.test(ctype);
     const isStream = ctype.toLowerCase().indexOf(STREAM_MIME) === 0;
@@ -342,14 +414,22 @@ export async function fetchAndApply(href, frameId, recordHistory, optimisticStat
   // (see the `applied` comment below). Keeping the tail call preserves them byte
   // for byte, so this commit changes the ORDER on committing swaps and nothing
   // else.
+  // A write that lands back on the page it was submitted from (a validation
+  // re-render, or a PRG redirect to the same url) updates that page in place,
+  // the way a Next.js server action does after revalidatePath (#1686): the
+  // history entry is replaced rather than duplicated, the scroll position is
+  // kept, and the focused control keeps focus when it survives the morph.
+  const samePage = mutation && !refresh && sameDocumentUrl(finalUrl, location.href);
   let historyRecorded = false;
   const recordHistoryNow = recordHistory
     ? () => {
       if (historyRecorded) return;
       historyRecorded = true;
-      history.pushState(null, '', finalUrl);
+      if (samePage) history.replaceState(history.state, '', finalUrl);
+      else history.pushState(null, '', finalUrl);
     }
     : null;
+  const focusState = samePage ? captureFocus() : null;
 
   const disposition = applySwap(doc, frameId, !!revalidating, finalUrl, incomingBuild, incomingSrc, refresh || (mutation ? 'layouts' : undefined), recordHistoryNow);
   // The temporary stylesheet copies are released once the swap has COMMITTED:
@@ -357,6 +437,7 @@ export async function fetchAndApply(href, frameId, recordHistory, optimisticStat
   // lands a frame later. A copy with no twin in the result (a discarded or
   // uncommitted swap) goes as soon as the commit settles.
   if (sheets) _swapCommit.then(() => releaseIncomingStylesheets(sheets), () => releaseIncomingStylesheets(sheets));
+  if (focusState) _swapCommit.then(() => { if (myToken === currentNavigationToken) restoreFocus(focusState); }, () => {});
   // `'none'` means applySwap returned WITHOUT committing anything: the frame the
   // response was for is missing, or it degraded to a hard navigation (an
   // importmap/build mismatch, a poisoned boundary scan). The page is not left
@@ -427,7 +508,7 @@ export async function fetchAndApply(href, frameId, recordHistory, optimisticStat
       // `#section` link is exactly where an app's `scroll-behavior: smooth`
       // is wanted, and native browsers animate it too.
       target.scrollIntoView();
-    } else if (!preserveScroll) {
+    } else if (!preserveScroll && !samePage) {
       // Scroll-to-top on a forward nav. behavior:'instant' so an app-level
       // `scroll-behavior: smooth` does not animate it (match native nav).
       warnIfSmoothScrollOnHtml();
@@ -454,7 +535,7 @@ export async function fetchAndApply(href, frameId, recordHistory, optimisticStat
   }
 
   document.dispatchEvent(new CustomEvent('webjs:navigate', { detail: { url: finalUrl, frameId, from: 'navigate' } }));
-  return { ok: respOk, status: respStatus, aborted: false, applied };
+  return { ok: respOk, status: respStatus, aborted: false, applied, samePage };
   } finally {
     // Clear the frame's busy state on every exit path (the early returns
     // above all unwind through here). No-op when this was not a frame nav.