feat(core): slot lifecycle in WebComponent + per-instance fallback clone

Third slice. Wires the slot runtime into the WebComponent lifecycle and
refines render-client.js's slot bind so fallback content is captured
once at compile time and cloned freshly per instance.

component.js:

- Light-DOM activation now runs in two phases:
    Phase 1 (before _performRender): if not hydrating, call
      captureAuthoredChildren(host) to move authored children into the
      slot state's assignment table. The renderer's replaceChildren()
      call would otherwise destroy them on first render.
    Phase 2 (after _performRender, slots are now live DOM): if the
      host was hydrating, call adoptSSRAssignments(host) to record
      SSR-placed children so the first projection pass is a no-op.
      Then call attachSlotObservers(host) so future authored-child
      mutations and slot-name changes drive incremental projection.

- New __isHydrating() helper inspects this.firstChild for the
  framework's <!--webjs-hydrate--> marker and records the result
  on __hydratedAtActivate so phase two can branch correctly.

- disconnectedCallback now calls detachSlotObservers(host) for
  light-DOM hosts. The per-host slot state (assignment table,
  pending fragments, last snapshots) is preserved across disconnect,
  so a re-attached element picks up where it left off.

render-client.js:

- discoverSlots() now MOVES the slot's authored children into a
  fallbackTemplate DocumentFragment stored on the SLOT
  PartDescriptor. The cached templateEl's slot becomes empty, so
  every clone starts empty too. This eliminates the cloning-the-
  fallback-out-of-the-slot dance the previous bind step did.

- bindPart for slot now clones the descriptor's fallbackTemplate
  into a per-instance holding fragment and stamps it on the slot
  via SLOT_FALLBACK_FRAG for slot.js to swap in. The slot itself
  is left untouched at bind time, which makes hydration trivially
  correct (SSR-projected children stay in place; the slot-part
  just sets up its fallback supply for later transitions).

- PartDescriptor typedef gains an optional fallbackTemplate field.

Verified across 115 existing core unit tests (component, render-client,
render-server, directives, registry, css, html, context, task,
suspense, repeat, testing). All pass.

What remains: render-server.js injectDSD upgrade for SSR slot
substitution (Task #13), then the 62-case test suite (Task #14),
then docs (Task #15).

Author: vivek7405

packages/core/src/component.js

@@ -1,6 +1,13 @@
 import { render as clientRender } from './render-client.js';
 import { isCSS, adoptStyles } from './css.js';
 import { register, tagOf } from './registry.js';
+import {
+  captureAuthoredChildren,
+  adoptSSRAssignments,
+  attachSlotObservers,
+  detachSlotObservers,
+  ensureSlotState,
+} from './slot.js';
 
 const isBrowser = typeof window !== 'undefined' && typeof HTMLElement !== 'undefined';
 
@@ -381,6 +388,22 @@ export class WebComponent extends Base {
           `For light DOM, use global CSS or <style> in render().`
         );
       }
+      // Light-DOM slot lifecycle phase one. Capture authored children
+      // into the slot-state's assignment table BEFORE _performRender
+      // runs, since the renderer's first clientRender call will
+      // replaceChildren() on the host and would otherwise destroy them.
+      //
+      // Detect SSR hydration via the framework's <!--webjs-hydrate-->
+      // marker: in that case the SSR pipeline already placed projected
+      // children inside <slot data-webjs-light data-projection="actual">
+      // elements, so we ensure slot state exists (so findSlotHost
+      // succeeds) and defer to adoptSSRAssignments after the renderer
+      // has hydrated the template. Otherwise capture in place.
+      if (this.__isHydrating()) {
+        ensureSlotState(this);
+      } else {
+        captureAuthoredChildren(this);
+      }
     }
 
     // Notify all controllers that the host is connected.
@@ -393,6 +416,41 @@ export class WebComponent extends Base {
     // light DOM, existing shadow root for shadow DOM) and hydrates
     // instead of replacing: binding events without touching the DOM.
     this._performRender();
+
+    // Light-DOM slot lifecycle phase two. With the rendered template
+    // (and therefore the live <slot> elements) now in the DOM, hook up
+    // the mutation observers so future authored-child mutations and
+    // slot-name changes drive incremental projection. For hydrated
+    // hosts, also adopt the SSR-placed slot assignments so the first
+    // projection pass is a no-op.
+    if (this._renderRoot === this) {
+      if (this.__hydratedAtActivate) {
+        adoptSSRAssignments(this);
+        this.__hydratedAtActivate = false;
+      }
+      attachSlotObservers(this);
+    }
+  }
+
+  /**
+   * True when this host's first child is the framework's hydration
+   * marker, meaning the SSR pipeline already rendered the template's
+   * shape (including <slot data-webjs-light> elements with their
+   * projected children inside) and the client should bind events
+   * without re-creating DOM. Sets __hydratedAtActivate as a side
+   * effect so the post-render path picks up the SSR assignment table.
+   *
+   * @returns {boolean}
+   * @private
+   */
+  __isHydrating() {
+    const first = this.firstChild;
+    const isHydrate =
+      first != null &&
+      first.nodeType === 8 &&
+      /** @type {Comment} */ (first).data === 'webjs-hydrate';
+    if (isHydrate) this.__hydratedAtActivate = true;
+    return isHydrate;
   }
 
 
@@ -411,6 +469,10 @@ export class WebComponent extends Base {
       this.__hydrationObserver.disconnect();
       this.__hydrationObserver = null;
     }
+    // Pause slot observers. The per-host state (assignment table,
+    // pending fragments, last snapshots) is preserved so a subsequent
+    // reconnection picks up where it left off.
+    if (this._renderRoot === this) detachSlotObservers(this);
     for (const c of this.__controllers) {
       if (c.onUnmount) c.onUnmount();
     }

packages/core/src/render-client.js

@@ -50,6 +50,7 @@ const INSTANCE = Symbol.for('webjs.instance');
  *   name?: string,
  *   statics?: string[],
  *   group?: number[],
+ *   fallbackTemplate?: DocumentFragment,
  * }} PartDescriptor
  *
  * @typedef {{
@@ -348,12 +349,18 @@ function compile(tr) {
  *      recognise it as a framework-managed light-DOM slot.
  *   2. Add a sentinel attribute (`data-MARKER<idx>`) so the subsequent
  *      assignPaths walk records the slot's path into the new SLOT part.
- *   3. Push a SLOT part descriptor onto the parts list.
+ *   3. Move the slot's authored children into a `fallbackTemplate`
+ *      DocumentFragment stored on the PartDescriptor. The slot in the
+ *      cached template becomes empty, so every clone starts empty too.
+ *      bindPart clones a fresh fallback fragment per instance from this
+ *      template, giving each instance an independent fallback supply
+ *      that slot.js swaps in via the SLOT_FALLBACK_FRAG symbol.
  *
- * The slot's authored inner content stays in place in the template; it
- * becomes the fallback content cloned along with the rest of the template
- * on every instantiation. The slot-part's bind step at createInstance
- * moves those cloned nodes into a holding fragment owned by the part.
+ *   Fallback content with template holes (`<slot>fallback ${x}</slot>`)
+ *   is captured as a static-HTML snapshot of the template state at
+ *   compile time. Dynamic holes inside fallback content are not
+ *   re-bound per instance in v1; authors should put dynamic content
+ *   outside the slot.
  *
  * @param {DocumentFragment} root
  * @param {PartDescriptor[]} parts
@@ -364,7 +371,9 @@ function discoverSlots(root, parts) {
     slot.setAttribute(LIGHT_SLOT_ATTR, '');
     const partIdx = parts.length;
     slot.setAttribute(`data-${MARKER}${partIdx}`, '');
-    parts.push({ kind: 'slot', path: [] });
+    const fallbackTemplate = document.createDocumentFragment();
+    while (slot.firstChild) fallbackTemplate.appendChild(slot.firstChild);
+    parts.push({ kind: 'slot', path: [], fallbackTemplate });
   }
 }
 
@@ -483,12 +492,24 @@ function bindPart(p, root) {
   if (p.kind === 'bool') return { kind: 'bool', el, name: p.name || '' };
   if (p.kind === 'slot') {
     const slotEl = /** @type {HTMLSlotElement} */ (el);
-    // Move the slot's fallback content (cloned from the template) into a
-    // holding fragment that slot.js can swap back in when the slot
-    // transitions to data-projection="fallback". slot.js looks this up
-    // via the SLOT_FALLBACK_FRAG symbol on the slot element.
+    // Build a per-instance holding fragment by cloning the PartDescriptor's
+    // fallback template (captured once at compile time). slot.js swaps
+    // this fragment in via SLOT_FALLBACK_FRAG when projection state
+    // transitions to "fallback". The cloned slot in `root` starts empty
+    // (discoverSlots() moved the original children to the template), so
+    // there is nothing to extract from the slot itself.
+    //
+    // Hydration case: if the slot already carries data-projection="actual"
+    // from the SSR pipeline, its children are the SSR-projected nodes and
+    // must be left in place. The component lifecycle (component.js) calls
+    // adoptSSRAssignments() to record those children in the host state
+    // so the first projection pass is a no-op.
     const frag = document.createDocumentFragment();
-    while (slotEl.firstChild) frag.appendChild(slotEl.firstChild);
+    if (p.fallbackTemplate) {
+      for (const node of p.fallbackTemplate.childNodes) {
+        frag.appendChild(node.cloneNode(true));
+      }
+    }
     /** @type {any} */ (slotEl)[SLOT_FALLBACK_FRAG] = frag;
     return { kind: 'slot', slotEl, applied: false };
   }