@webjsdev/core 0.7.5 → 0.7.7

package/index-browser.js

@@ -48,8 +48,16 @@ export { WebjsFrame } from './src/webjs-frame.js';
 // Signals (TC39 Stage-1 shape), also available via '@webjsdev/core/signals'
 export { signal, computed, effect, batch, isSignal, Signal } from './src/signal.js';
 
-// Directives, also available via '@webjsdev/core/directives'
-export { unsafeHTML, isUnsafeHTML, live, isLive } from './src/directives.js';
+// Directives, also available via '@webjsdev/core/directives'. The full
+// lit-html-parity set is re-exported here so the dist browser bundle (which
+// the `@webjsdev/core/directives` subpath collapses onto in dist mode) carries
+// every directive, matching what src/directives.js exports in dev.
+export {
+  unsafeHTML, isUnsafeHTML, live, isLive, keyed, isKeyed, guard, isGuard,
+  templateContent, isTemplateContent, ref, isRef, createRef, cache, isCache,
+  until, isUntil, asyncAppend, isAsyncAppend, asyncReplace, isAsyncReplace,
+  watch, isWatch,
+} from './src/directives.js';
 
 // Context Protocol, also available via '@webjsdev/core/context'
 export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from './src/context.js';

package/index.js

@@ -30,8 +30,15 @@ export { WebjsFrame } from './src/webjs-frame.js';
 // Signals (TC39 Stage-1 shape), also available via '@webjsdev/core/signals'
 export { signal, computed, effect, batch, isSignal, Signal } from './src/signal.js';
 
-// Directives, also available via '@webjsdev/core/directives'
-export { unsafeHTML, isUnsafeHTML, live, isLive } from './src/directives.js';
+// Directives, also available via '@webjsdev/core/directives'. The full
+// lit-html-parity set is re-exported so the bare specifier exposes the same
+// directive surface in Node as the browser bundle does.
+export {
+  unsafeHTML, isUnsafeHTML, live, isLive, keyed, isKeyed, guard, isGuard,
+  templateContent, isTemplateContent, ref, isRef, createRef, cache, isCache,
+  until, isUntil, asyncAppend, isAsyncAppend, asyncReplace, isAsyncReplace,
+  watch, isWatch,
+} from './src/directives.js';
 
 // Context Protocol, also available via '@webjsdev/core/context'
 export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from './src/context.js';

package/package.json

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

package/src/component.js

@@ -147,8 +147,257 @@ function defaultHasChanged(a, b) {
  * ```
  */
 
-// Base class choice: real HTMLElement on the browser, a dummy on the server.
-const Base = isBrowser ? HTMLElement : /** @type {any} */ (class {});
+/**
+ * Inert `ElementInternals`-shaped object returned by the server shim's
+ * `attachInternals()`. Modeled on `@lit-labs/ssr-dom-shim`'s
+ * `ElementInternalsShim` (lit repo, `packages/labs/ssr-dom-shim/src/lib/
+ * element-internals.ts`): form-association, validity, and custom-state
+ * calls are no-ops at SSR (no form, no constraint validation, no `:state()`
+ * matching server-side), so a component that calls `this.attachInternals()`
+ * in its constructor renders instead of crashing. The browser runs the real
+ * `attachInternals()` on hydration.
+ *
+ * Deliberate deviation from lit: lit's `checkValidity` / `reportValidity`
+ * 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}
+ */
+function makeServerInternals() {
+  return {
+    states: new Set(),
+    shadowRoot: null,
+    form: null,
+    labels: [],
+    role: '',
+    willValidate: true,
+    validity: /** @type {any} */ ({}),
+    validationMessage: '',
+    setFormValue() {},
+    setValidity() {},
+    checkValidity() { return true; },
+    reportValidity() { return true; },
+  };
+}
+
+/**
+ * Server-side stand-in for `HTMLElement`. The SSR pipeline constructs
+ * component instances in Node, where `HTMLElement` does not exist, so the
+ * base class is this shim. It is modeled on `@lit-labs/ssr-dom-shim`'s
+ * `ElementShim` (lit repo, `packages/labs/ssr-dom-shim/src/index.ts`): the
+ * attribute methods (`getAttribute` / `setAttribute` / `hasAttribute` /
+ * `removeAttribute` / `toggleAttribute`, the `attributes` getter) are backed
+ * by a Map, so lit muscle-memory patterns that read attributes in `render()`
+ * or set them while deriving state work server-side; the SSR walker seeds
+ * the Map from the element's source attributes and reads it back to surface
+ * reflected/added attributes in the output. Event methods are no-ops (no
+ * server event loop), and `attachInternals()` returns the inert object
+ * above. The genuinely browser-only surface (`querySelector`, layout reads,
+ * `attachShadow`, `focus`) is deliberately absent and still throws at SSR,
+ * which the `no-browser-globals-in-render` rule and the SSR crash hint flag.
+ *
+ * Deliberate deviation from lit: this shim lowercases attribute names so
+ * `getAttribute('Foo')` after `setAttribute('foo', x)` resolves, matching how
+ * a real browser treats HTML attribute names as case-insensitive. lit's shim
+ * keys the Map by the raw name (a known fidelity gap in lit-labs).
+ */
+class ServerElement {
+  constructor() {
+    /**
+     * Backing store for the attribute methods. Keys are lowercased
+     * attribute names (HTML attributes are case-insensitive). Seeded by the
+     * SSR walker from the element's source attributes.
+     * @type {Map<string, string>}
+     */
+    this.__ssrAttrs = new Map();
+    /** @type {any} */
+    this.__internals = null;
+  }
+
+  /** Mirrors `Element.attributes`: an array of `{ name, value }`. */
+  get attributes() {
+    return [...this.__ssrAttrs].map(([name, value]) => ({ name, value }));
+  }
+
+  /** @param {string} name */
+  getAttribute(name) {
+    const v = this.__ssrAttrs.get(String(name).toLowerCase());
+    return v === undefined ? null : v;
+  }
+
+  /** @param {string} name @param {unknown} value */
+  setAttribute(name, value) {
+    // Emulate the browser casting all values to string (lit does the same).
+    this.__ssrAttrs.set(String(name).toLowerCase(), String(value));
+  }
+
+  /** @param {string} name */
+  removeAttribute(name) {
+    this.__ssrAttrs.delete(String(name).toLowerCase());
+  }
+
+  /** @param {string} name */
+  hasAttribute(name) {
+    return this.__ssrAttrs.has(String(name).toLowerCase());
+  }
+
+  /** @param {string} name @param {boolean} [force] */
+  toggleAttribute(name, force) {
+    // Steps mirror https://dom.spec.whatwg.org/#dom-element-toggleattribute
+    const key = String(name).toLowerCase();
+    const present = this.__ssrAttrs.has(key);
+    const next = force === undefined ? !present : force;
+    if (next) {
+      this.__ssrAttrs.set(key, '');
+      return true;
+    }
+    this.__ssrAttrs.delete(key);
+    return false;
+  }
+
+  /** @returns {string[]} */
+  getAttributeNames() {
+    return [...this.__ssrAttrs.keys()];
+  }
+
+  /**
+   * Minimal `Element.closest()` for SSR. The SSR walker threads the chain
+   * of enclosing custom-element instances into each instance
+   * (`__ssrAncestors`); this walks self-then-ancestors and returns the
+   * nearest whose tag matches. Only bare tag-name selectors are supported
+   * server-side (`closest('ui-tabs')`), which is what compound components
+   * need to read parent state for a correct first paint; anything more
+   * specific (class, attribute, or descendant selectors) returns null,
+   * matching the pre-shim behaviour. The browser runs the real `closest()`
+   * on hydration.
+   * @param {string} selector
+   * @returns {any}
+   */
+  closest(selector) {
+    const sel = String(selector).trim().toLowerCase();
+    // Tag-name selectors only at SSR; bail (null) on anything else.
+    if (!/^[a-z][a-z0-9-]*$/.test(sel)) return null;
+    if (this.__ssrTag === sel) return this;
+    const chain = this.__ssrAncestors;
+    if (!Array.isArray(chain)) return null;
+    for (let i = chain.length - 1; i >= 0; i--) {
+      if (chain[i] && chain[i].__ssrTag === sel) return chain[i];
+    }
+    return null;
+  }
+
+  /**
+   * `HTMLElement.dataset`: a live view over the element's `data-*`
+   * attributes, backed by the SSR attribute Map. Reading / writing
+   * `el.dataset.fooBar` maps to the `data-foo-bar` attribute (camelCase
+   * to kebab-case), so a `render()` that sets `this.dataset.state = 'on'`
+   * surfaces `data-state="on"` in the SSR'd host tag instead of crashing
+   * on an undefined `dataset`.
+   * @returns {Record<string, string>}
+   */
+  get dataset() {
+    if (this.__dataset) return this.__dataset;
+    const el = this;
+    const toAttr = (p) => 'data-' + String(p).replace(/[A-Z]/g, (m) => '-' + m.toLowerCase());
+    this.__dataset = new Proxy(/** @type {Record<string,string>} */ ({}), {
+      get(_t, prop) {
+        if (typeof prop !== 'string') return undefined;
+        const v = el.getAttribute(toAttr(prop));
+        return v === null ? undefined : v;
+      },
+      set(_t, prop, value) {
+        if (typeof prop === 'string') el.setAttribute(toAttr(prop), value);
+        return true;
+      },
+      has(_t, prop) {
+        return typeof prop === 'string' && el.hasAttribute(toAttr(prop));
+      },
+      deleteProperty(_t, prop) {
+        if (typeof prop === 'string') el.removeAttribute(toAttr(prop));
+        return true;
+      },
+      ownKeys() {
+        return el.getAttributeNames()
+          .filter((n) => n.startsWith('data-'))
+          .map((n) => n.slice(5).replace(/-([a-z])/g, (_m, c) => c.toUpperCase()));
+      },
+      getOwnPropertyDescriptor(_t, prop) {
+        if (typeof prop === 'string' && el.hasAttribute(toAttr(prop))) {
+          return { enumerable: true, configurable: true, value: el.getAttribute(toAttr(prop)) };
+        }
+        return undefined;
+      },
+    });
+    return this.__dataset;
+  }
+
+  // IDL properties that reflect to a content attribute. A render() that
+  // mutates these on the host (a light-DOM compound-component pattern, e.g.
+  // `this.className = ...`, `this.hidden = !active`) then surfaces the
+  // matching attribute in the SSR'd host tag, matching the browser.
+  get className() { return this.getAttribute('class') ?? ''; }
+  set className(v) { this.setAttribute('class', v); }
+  get hidden() { return this.hasAttribute('hidden'); }
+  set hidden(v) { this.toggleAttribute('hidden', !!v); }
+  get id() { return this.getAttribute('id') ?? ''; }
+  set id(v) { this.setAttribute('id', v); }
+  get title() { return this.getAttribute('title') ?? ''; }
+  set title(v) { this.setAttribute('title', v); }
+  get slot() { return this.getAttribute('slot') ?? ''; }
+  set slot(v) { this.setAttribute('slot', v); }
+  get role() { return this.getAttribute('role'); }
+  set role(v) { v == null ? this.removeAttribute('role') : this.setAttribute('role', v); }
+  get tabIndex() { const v = this.getAttribute('tabindex'); return v === null ? -1 : (Number.parseInt(v, 10) || 0); }
+  set tabIndex(v) { this.setAttribute('tabindex', String(v)); }
+
+  // No server event loop: listeners never fire at SSR. The no-op keeps a
+  // constructor that wires delegated listeners (a common lit pattern) from
+  // crashing; the browser re-runs the constructor on hydration where the
+  // real HTMLElement methods apply.
+  addEventListener() {}
+  removeEventListener() {}
+  dispatchEvent() { return true; }
+
+  /** @returns {any} */
+  attachInternals() {
+    // Match the browser (and lit's shim): a second attach is an error.
+    if (this.__internals !== null) {
+      throw new Error(
+        "Failed to execute 'attachInternals' on 'HTMLElement': " +
+          'ElementInternals for the specified element was already attached.',
+      );
+    }
+    this.__internals = makeServerInternals();
+    return this.__internals;
+  }
+}
+
+// ARIAMixin IDL reflections (`el.ariaPressed = 'true'` writes aria-pressed).
+// A render() that sets ARIA state via the IDL properties then surfaces the
+// matching aria-* attribute in the SSR'd host tag, matching the browser. The
+// IDL name maps to the content attribute by lowercasing the part after
+// `aria` and prefixing `aria-` (ariaPressed -> aria-pressed).
+const ARIA_IDL_PROPS = [
+  'ariaAtomic', 'ariaAutoComplete', 'ariaBusy', 'ariaChecked', 'ariaColCount',
+  'ariaColIndex', 'ariaColSpan', 'ariaCurrent', 'ariaDescription', 'ariaDisabled',
+  'ariaExpanded', 'ariaHasPopup', 'ariaHidden', 'ariaInvalid', 'ariaKeyShortcuts',
+  'ariaLabel', 'ariaLevel', 'ariaLive', 'ariaModal', 'ariaMultiLine',
+  'ariaMultiSelectable', 'ariaOrientation', 'ariaPlaceholder', 'ariaPosInSet',
+  'ariaPressed', 'ariaReadOnly', 'ariaRequired', 'ariaRoleDescription',
+  'ariaRowCount', 'ariaRowIndex', 'ariaRowSpan', 'ariaSelected', 'ariaSetSize',
+  'ariaSort', 'ariaValueMax', 'ariaValueMin', 'ariaValueNow', 'ariaValueText',
+];
+for (const idl of ARIA_IDL_PROPS) {
+  const attr = 'aria-' + idl.slice(4).toLowerCase();
+  Object.defineProperty(ServerElement.prototype, idl, {
+    configurable: true,
+    get() { return this.getAttribute(attr); },
+    set(v) { v == null ? this.removeAttribute(attr) : this.setAttribute(attr, String(v)); },
+  });
+}
+
+// Base class choice: real HTMLElement on the browser, the shim on the server.
+const Base = isBrowser ? HTMLElement : /** @type {any} */ (ServerElement);
 
 export class WebComponent extends Base {
   /** Whether to use shadow DOM. Default: false (light DOM). @type {boolean} */
@@ -467,6 +716,13 @@ export class WebComponent extends Base {
 
   _activate() {
     this._connected = true;
+    // Reflect declared reflect:true properties from their current value now
+    // that the element is connected. Constructor / willUpdate defaults were
+    // set while disconnected (the setter skips reflection then), so this is
+    // what makes a freshly-created client element carry the same reflected
+    // attributes the SSR walker emitted. Same-value reflects are no-ops, so a
+    // hydrated element (whose attribute already arrived from SSR) is unchanged.
+    this._reflectDeclaredAttributes();
     const Ctor = /** @type any */ (this.constructor);
     if (Ctor.shadow === true) {
       const hadSSRShadow = !!this.shadowRoot;
@@ -815,6 +1071,67 @@ export class WebComponent extends Base {
     }
   }
 
+  /**
+   * Run the pre-render half of the update cycle synchronously for SSR.
+   *
+   * The SSR walker constructs the instance, applies attributes/props, then
+   * calls this BEFORE `render()`. It mirrors how lit drives the update
+   * lifecycle server-side: `willUpdate` runs so derived state computed there
+   * is correct in the SSR'd HTML, then reactive controllers' `hostUpdate`
+   * runs, then reflect:true properties are written to attributes so they
+   * appear in the serialized output. It deliberately does NOT run
+   * `shouldUpdate` (SSR always produces the first paint, there is no prior
+   * render to skip), `update` (the walker commits by calling `render`
+   * itself), or the post-commit hooks `firstUpdated` / `updated` (browser-only
+   * DOM work).
+   *
+   * `_isUpdating` is set so a property assignment inside `willUpdate` folds
+   * into the current `changedProperties` snapshot instead of scheduling a
+   * fresh cycle (the SSR scheduler short-circuits anyway, since the element
+   * is not connected). Hook throws propagate to the walker's per-component
+   * try/catch, which logs an actionable hint and skips DSD for that element,
+   * the same as a throwing `render()`.
+   */
+  performServerUpdate() {
+    const changedProperties = this._changedProperties;
+    this._isUpdating = true;
+    try {
+      this.willUpdate(changedProperties);
+      for (const c of this.__controllers) {
+        if (c.hostUpdate) c.hostUpdate();
+      }
+      this._reflectDeclaredAttributes();
+    } finally {
+      this._isUpdating = false;
+    }
+  }
+
+  /**
+   * Reflect every reflect:true (non-state) property to its attribute from its
+   * CURRENT value, regardless of whether the value arrived via the setter.
+   *
+   * The property setter only reflects on a connected change, so a value set
+   * in the constructor (a default) or in `willUpdate` is not reflected by the
+   * setter alone. This syncs those: the SSR walker calls it in
+   * `performServerUpdate` (writing into the server attribute shim, which the
+   * walker reads back into the rendered HTML), and `_activate` calls it on
+   * the client's first connected render. Running it on both sides is what
+   * keeps a server-rendered element and a freshly-created client element
+   * agree on their reflected attributes (matching lit, which reflects during
+   * the first update). `_reflectAttribute`'s re-entrancy guard makes a
+   * same-value reflect a no-op, so re-reflecting an attribute that already
+   * arrived from SSR does not churn.
+   * @private
+   */
+  _reflectDeclaredAttributes() {
+    const props = /** @type {any} */ (this.constructor).properties || {};
+    for (const name of Object.keys(props)) {
+      const decl = props[name];
+      if (!decl || !decl.reflect || decl.state) continue;
+      this._reflectAttribute(name, this[name], decl);
+    }
+  }
+
   // ---------------------------------------------------------------------------
   // Lifecycle hooks: override in subclasses
   // ---------------------------------------------------------------------------

package/src/directives.js

@@ -12,11 +12,17 @@
  * } from '@webjsdev/core/directives';
  * ```
  *
- * `repeat()` lives in `./repeat.js` (re-exported from the package root).
+ * `repeat()` is implemented in `./repeat.js`; it is re-exported here so the
+ * `@webjsdev/core/directives` subpath exposes the whole documented directive
+ * table in src/dev mode too (the dist browser bundle already carries it).
  *
  * @module directives
  */
 
+// Re-export so the `/directives` subpath surface matches the documented table
+// in both src and dist mode. The implementation stays in repeat.js.
+export { repeat, isRepeat } from './repeat.js';
+
 /* ================================================================
  * unsafeHTML
  * ================================================================ */

package/src/render-server.js

@@ -322,9 +322,13 @@ const SSR_BROWSER_GLOBALS = new Set([
   'matchMedia', 'requestAnimationFrame', 'getComputedStyle',
   'IntersectionObserver', 'MutationObserver', 'ResizeObserver',
 ]);
+// Attribute methods (get/set/has/remove/toggleAttribute), the event methods
+// (add/removeEventListener, dispatchEvent), and attachInternals are backed by
+// the server-side element shim and work at SSR, so they are NOT listed here.
+// What remains is the genuinely browser-only HTMLElement surface that still
+// has no server stand-in and throws at SSR.
 const SSR_HTMLELEMENT_METHODS = new Set([
-  'attachShadow', 'setAttribute', 'getAttribute', 'removeAttribute',
-  'hasAttribute', 'dispatchEvent', 'querySelector', 'querySelectorAll',
+  'attachShadow', 'querySelector', 'querySelectorAll',
   'getBoundingClientRect', 'focus', 'blur', 'scrollIntoView',
 ]);
 
@@ -358,7 +362,7 @@ function browserMemberHint(e) {
  * @param {SuspenseCtx} [ctx]
  * @returns {Promise<string>}
  */
-async function injectDSD(html, ctx) {
+async function injectDSD(html, ctx, ancestors = []) {
   const tags = allTags();
   if (!tags.length) return html;
   // Sort longest tag name first so the regex alternation tries the most
@@ -383,10 +387,16 @@ async function injectDSD(html, ctx) {
     // Track which custom elements actually appeared: used by SSR to emit
     // `<link rel="modulepreload">` hints for their module URLs.
     if (ctx && ctx.usedComponents) ctx.usedComponents.add(tag);
-    const opening = selfClose ? `<${tag}${attrs}>` : match;
+    let opening = selfClose ? `<${tag}${attrs}>` : match;
     try {
       const isShadow = /** @type any */ (Cls).shadow === true;
       const instance = new /** @type any */ (Cls)();
+      // Thread the ancestor chain (the enclosing custom-element instances)
+      // so the server element shim's closest() can resolve a parent at SSR.
+      // Set before performServerUpdate so a willUpdate() that reads a parent
+      // via closest() sees the chain. Each child recursion below extends it.
+      instance.__ssrTag = tag;
+      instance.__ssrAncestors = ancestors;
       const attrMap = parseAttrs(attrs);
       // Decode `data-webjs-prop-*` attributes first (rich-typed values
       // emitted for `.prop=${val}` bindings in the parent template),
@@ -394,10 +404,34 @@ async function injectDSD(html, ctx) {
       // properties` type. Property bindings take priority on a name
       // collision because they preserve the original JS reference.
       const propValues = consumePropAttrs(attrMap);
+      // Names already present in the source opening tag (including the
+      // data-webjs-prop-* bindings, which were stripped from attrMap above
+      // but remain in the emitted `attrs` string). Reflected/added
+      // attributes are appended only when their name is NOT already here, so
+      // existing output stays byte-identical when nothing reflects.
+      const presentAttrNames = new Set(Object.keys(parseAttrs(attrs)).map((n) => n.toLowerCase()));
+      // Seed the server attribute shim so `this.getAttribute(...)` /
+      // `this.hasAttribute(...)` in willUpdate / render read the source
+      // attributes (a lit muscle-memory pattern) instead of reading empty.
+      seedServerAttrs(instance, attrMap);
       applyAttrsToInstance(instance, attrMap, Cls);
       for (const [k, v] of Object.entries(propValues)) instance[k] = v;
+      // Run the pre-render lifecycle (willUpdate, controllers' hostUpdate,
+      // then reflect reflect:true props) so derived state computed there is
+      // correct in the SSR'd HTML, matching how lit runs the update cycle at
+      // SSR. WebComponent instances expose performServerUpdate; bare
+      // Base-extending kit components (no lifecycle) do not, so it is guarded.
+      if (typeof instance.performServerUpdate === 'function') instance.performServerUpdate();
       let tpl = instance.render ? instance.render() : '';
       if (tpl && typeof tpl.then === 'function') tpl = await tpl;
+      // Surface attributes the component set up to and including render()
+      // that were not already in the source tag: reflected reflect:true
+      // props, an explicit this.setAttribute in the constructor / willUpdate,
+      // or a host-attribute mutation inside render() itself (a light-DOM
+      // compound-component pattern, e.g. this.dataset.state / this.className /
+      // this.hidden on the host). Reading after render() captures all three.
+      // Appending keeps the original tag byte-identical when nothing changed.
+      opening = appendReflectedAttrs(opening, instance, presentAttrNames);
       // Render the template to HTML. injectDSD recurses on the result so
       // nested custom elements (e.g. <theme-toggle> inside <blog-shell>)
       // get their own DSD pass.
@@ -407,7 +441,7 @@ async function injectDSD(html, ctx) {
         // Shadow DOM: native <slot> stays as-is in the DSD template. The
         // browser handles projection from the host's light-DOM children
         // into the shadow tree natively. No framework substitution here.
-        const innerProcessed = await injectDSD(rawInner, ctx);
+        const innerProcessed = await injectDSD(rawInner, ctx, [...ancestors, instance]);
         const rawStyles = /** @type any */ (Cls).styles;
         const styleList = Array.isArray(rawStyles) ? rawStyles : rawStyles && isCSS(rawStyles) ? [rawStyles] : [];
         const styleStr = stylesToString(styleList);
@@ -470,7 +504,7 @@ async function injectDSD(html, ctx) {
         }
         const partitioned = partitionAuthoredBySlot(authoredInner);
         const innerWithSlots = substituteSlotsInRender(rawInner, partitioned);
-        const innerProcessed = await injectDSD(innerWithSlots, ctx);
+        const innerProcessed = await injectDSD(innerWithSlots, ctx, [...ancestors, instance]);
         edits.push({
           start: m.index,
           end: closeEnd,
@@ -498,6 +532,11 @@ async function injectDSD(html, ctx) {
   // independently against the original html, but those inner elements
   // are processed by the recursive injectDSD call on innerWithSlots.
   // Keeping both edits would double-process them and corrupt the output.
+  // A consequence: a nested instance's render() runs once per chain depth
+  // (the discarded top-level pass sees an empty ancestor chain, so its
+  // closest() reads null; the kept recursive pass has the real chain). The
+  // kept pass is the only output, and closest() is a read, so render() must
+  // stay pure at SSR (the standard SSR contract), not branch on side effects.
   edits.sort((a, b) => a.start - b.start);
   /** @type {{start:number, end:number, text:string}[]} */
   const filtered = [];
@@ -764,6 +803,55 @@ function parseAttrs(attrStr) {
   return out;
 }
 
+/**
+ * Seed the element's attributes from the source opening tag so reads like
+ * `this.getAttribute(name)` / `this.hasAttribute(name)` inside willUpdate /
+ * render return the real value during SSR. Goes through `setAttribute`, which
+ * both the server element shim (Node SSR) and a real `HTMLElement`
+ * (renderToString called in a browser, e.g. tests) implement, so the path
+ * does not depend on the shim's internal store. A bare Base-extending kit
+ * component without `setAttribute` is skipped.
+ *
+ * @param {any} instance
+ * @param {Record<string,string>} attrs  parsed source attributes (data-webjs-prop-* already removed)
+ */
+function seedServerAttrs(instance, attrs) {
+  if (!instance || typeof instance.setAttribute !== 'function') return;
+  for (const [name, raw] of Object.entries(attrs)) {
+    instance.setAttribute(name, unescapeAttr(raw));
+  }
+}
+
+/**
+ * Append attributes the component set before render (reflected reflect:true
+ * properties, or an explicit `this.setAttribute` in the constructor /
+ * willUpdate) to the element's opening tag, skipping any name already present
+ * in the source tag. Reads via the standard `getAttributeNames` /
+ * `getAttribute` API so it works whether the instance is the server shim or a
+ * real `HTMLElement`. Returns the opening tag unchanged when there is nothing
+ * to add, so existing SSR output stays byte-identical when no component
+ * reflects, which preserves the elision on-vs-off differential invariant.
+ *
+ * @param {string} opening  the element's opening tag, ending in `>`
+ * @param {any} instance
+ * @param {Set<string>} presentAttrNames  lowercased names already in the source tag
+ * @returns {string}
+ */
+function appendReflectedAttrs(opening, instance, presentAttrNames) {
+  if (!instance || typeof instance.getAttributeNames !== 'function') return opening;
+  let extra = '';
+  for (const rawName of instance.getAttributeNames()) {
+    const name = String(rawName).toLowerCase();
+    if (presentAttrNames.has(name)) continue;
+    const value = instance.getAttribute(rawName);
+    extra += value === '' ? ` ${name}` : ` ${name}="${escapeAttr(String(value))}"`;
+  }
+  if (!extra) return opening;
+  // Insert before the closing `>` (the opening tag is normalised to end in
+  // `>`; a self-closing source tag was already rewritten without the slash).
+  return `${opening.slice(0, -1)}${extra}>`;
+}
+
 /**
  * Coerce attribute strings to typed properties on a component instance
  * based on its static `properties` declaration.
@@ -780,7 +868,12 @@ function applyAttrsToInstance(instance, attrs, Cls) {
     if (def.type === Number) instance[propName] = Number(raw);
     else if (def.type === Boolean) instance[propName] = raw !== 'false';
     else if (def.type === Object || def.type === Array) {
-      try { instance[propName] = JSON.parse(raw); } catch { instance[propName] = raw; }
+      // `raw` is the entity-encoded attribute text (parseAttrs returns the
+      // literal characters between the quotes), so decode the HTML entities
+      // before JSON.parse. A JSON attribute carries `&quot;` for every `"`;
+      // parsing it raw throws and would silently fall back to the string,
+      // leaving an Object/Array prop holding a string at SSR.
+      try { instance[propName] = JSON.parse(unescapeAttr(raw)); } catch { instance[propName] = raw; }
     } else instance[propName] = raw;
   }
 }

package/src/task.js

@@ -93,6 +93,16 @@
  * @readonly
  * @enum {number}
  */
+// The SSR walker now runs controllers' hostUpdate during the pre-render pass
+// (issue #217). A Task must NOT invoke its task function server-side (that
+// would fire a fetch during SSR); the browser runs it on hydration. Read live
+// (not cached) so the auto-run gate reflects the current environment: SSR
+// ships the task's INITIAL state, unchanged from before hostUpdate fired at
+// SSR, and the browser runs it on connect.
+function inBrowser() {
+  return typeof window !== 'undefined';
+}
+
 export const TaskStatus = /** @type {const} */ ({
   INITIAL: 0,
   PENDING: 1,
@@ -326,6 +336,9 @@ export class Task {
    */
   hostUpdate() {
     if (!this._autoRun) return;
+    // Never auto-run server-side: SSR ships the INITIAL state and the task
+    // function (typically a fetch) runs only in the browser on hydration.
+    if (!inBrowser()) return;
 
     const nextArgs = this._argsFn();