@webjsdev/core 0.7.50 → 0.7.53

package/src/slot/sensors.js

@@ -0,0 +1,303 @@
+/**
+ * MutationObserver sensors that keep a host in sync with post-mount
+ * native writes, plus the renderer-write backstop.
+ *
+ * Moved verbatim out of the pre-split `slot.js`; see that barrel for the
+ * runtime's full contract.
+ *
+ * @module
+ */
+import { isOwnSlot } from './assignment.js';
+import { instanceOwns } from './interception.js';
+import { inBrowser } from './polyfills.js';
+import { applySlotAssignments } from './project.js';
+import { ensureSlotState } from './state.js';
+import { FRAMEWORK_DETACHED, LIGHT_SLOT_ATTR, PARK, RENDERING, SLOT_STATE } from './symbols.js';
+
+// Saved native references, captured once in the browser (Node has no `Node`).
+export let N_appendChild = null;
+export let N_insertBefore = null;
+export let N_removeChild = null;
+export let N_replaceChild = null;
+export let N_append = null;
+export let N_prepend = null;
+export let N_replaceChildren = null;
+export let INNER_HTML_DESC = null;
+export let TEXT_CONTENT_DESC = null;
+
+export function captureNatives() {
+  if (N_appendChild || !inBrowser) return;
+  N_appendChild = Node.prototype.appendChild;
+  N_insertBefore = Node.prototype.insertBefore;
+  N_removeChild = Node.prototype.removeChild;
+  N_replaceChild = Node.prototype.replaceChild;
+  N_append = Element.prototype.append;
+  N_prepend = Element.prototype.prepend;
+  N_replaceChildren = Element.prototype.replaceChildren;
+  INNER_HTML_DESC = Object.getOwnPropertyDescriptor(Element.prototype, 'innerHTML');
+  TEXT_CONTENT_DESC = Object.getOwnPropertyDescriptor(Node.prototype, 'textContent');
+}
+
+/**
+ * Run `fn` with the renderer-write window open on `host`, restoring the prior
+ * flag afterward (re-entrancy safe: nested renderer commits nest cleanly). The
+ * renderer wraps every host-receiver commit in this; a write to a light host
+ * inside the window bypasses the interception and hits the native DOM.
+ *
+ * @template T
+ * @param {any} host
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function withRendererWrites(host, fn) {
+  const prev = host[RENDERING];
+  host[RENDERING] = true;
+  try {
+    return fn();
+  } finally {
+    host[RENDERING] = prev;
+    // When the OUTERMOST window closes, drain the backstop synchronously before
+    // its async callback fires. The drain PROCESSES the records (renderer output
+    // is skipped structurally, a genuine bypass write is folded), so this
+    // commit's own childList churn is absorbed without losing a real author
+    // write that coincided in the same task. (The flip sensor is NOT drained: a
+    // renderer `name=` write on a slot is exactly what re-projects a dynamic
+    // `name=${...}`.)
+    if (!prev) drainRendererBackstop(host);
+  }
+}
+
+/**
+ * Install the two read-only sensors on a light host. Neither moves a node; each
+ * only folds a mutation into `authored` and calls the single renderer-owned
+ * writer. Installed on connect, torn down on disconnect.
+ *   - Bypass backstop (childList, subtree:false): catches raw writes that skip
+ *     the patched methods (`Node.prototype.appendChild.call`, Range ops).
+ *   - Flip sensor (attributes slot/name, subtree:true): catches an `el.slot=`
+ *     flip on a projected child and a slot `name=` change.
+ *
+ * @param {Element} host
+ */
+export function installSlotSensors(host) {
+  if (!inBrowser) return;
+  const h = /** @type {any} */ (host);
+  const state = ensureSlotState(host);
+  if (state.backstop) return;
+
+  state.backstop = new MutationObserver((records) => processBackstop(host, state, records));
+  state.backstop.observe(host, { childList: true, subtree: false });
+
+  state.flipSensor = new MutationObserver((records) => processFlip(host, records));
+  state.flipSensor.observe(host, {
+    attributes: true,
+    attributeFilter: ['slot', 'name'],
+    subtree: true,
+  });
+}
+
+/**
+ * Backstop callback body: fold a raw direct-child add / un-author a raw remove.
+ * A renderer-committed node (the render root and everything between the instance
+ * bookend markers) is SKIPPED structurally, so this is safe to run on the
+ * records drained at a renderer-write window close, not only on genuine
+ * author-bypass records. That is what keeps a real bypass write that happened
+ * to coincide with a commit in the same task from being silently dropped.
+ */
+export function processBackstop(host, state, records) {
+  const h = /** @type {any} */ (host);
+  const park = h[PARK];
+  const inst = h[Symbol.for('webjs.instance')];
+  let dirty = false;
+  // Nodes the AUTHOR touched in THIS pass (any addedNodes appearance): for
+  // them, the latest same-pass author action wins, so a following removal
+  // record splices even a marked node.
+  const touchedThisPass = new Set();
+  for (const r of records) {
+    for (const node of r.addedNodes) {
+      touchedThisPass.add(node);
+      if (node === park) continue;
+      if (inst && instanceOwns(inst, node)) continue; // renderer output, not authored
+      if (state.authored.indexOf(node) !== -1) {
+        // A raw bypass MOVE of an already-authored node back onto the host:
+        // the record is right but the node now physically sits outside its
+        // slot. Re-apply so the physically-verifying placement step repairs
+        // it (no slotchange fires: the assigned SET is unchanged).
+        dirty = true;
+        continue;
+      }
+      FRAMEWORK_DETACHED.add(node);
+      state.authored.push(node);
+      dirty = true;
+    }
+    for (const node of r.removedNodes) {
+      const i = state.authored.indexOf(node);
+      if (i === -1) continue;
+      if (host.contains(node)) continue; // placement/park move: still ours
+      // Containment is evaluated at PROCESSING time, so a stale placement
+      // record (host to slot move) can be processed after a rescue detached
+      // the node as a record value: retain exactly that shape (marked,
+      // parentless, untouched by the author this pass). Everything else in
+      // a host-childList removal record was author-removed or author-moved
+      // (their same-pass add marks touchedThisPass; a placed node is
+      // unmarked; a re-homed node has a parent) and leaves the record.
+      const rescueValue =
+        FRAMEWORK_DETACHED.has(node) &&
+        node.parentNode == null &&
+        !touchedThisPass.has(node);
+      if (!rescueValue) {
+        state.authored.splice(i, 1);
+        dirty = true;
+      }
+    }
+  }
+  if (dirty) applySlotAssignments(host);
+}
+
+/**
+ * Drain the host's backstop at a renderer-write window close, PROCESSING the
+ * records (renderer output is skipped structurally by processBackstop) so a
+ * genuine bypass write coinciding with the commit is not lost. Exported so
+ * render-client's render() window can share the exact same drain.
+ *
+ * @param {Element} host
+ */
+export function drainRendererBackstop(host) {
+  const h = /** @type {any} */ (host);
+  const state = /** @type {SlotState | undefined} */ (h[SLOT_STATE]);
+  if (!(state && state.backstop)) return;
+  const records = state.backstop.takeRecords();
+  // Only PROCESS when there is a rendered instance: processBackstop skips
+  // renderer output via instanceOwns, which needs the instance bookends. On the
+  // non-template render path (render() returns a string / array / number) the
+  // instance is null and the renderer's own text nodes are direct host
+  // children, so processing would fold them into the record and park them (the
+  // component would render blank). With no instance to discriminate, discard,
+  // matching the pre-processing behavior.
+  // Process when an instance exists OR the host has NEVER rendered (the
+  // symbol is absent: a pre-first-render bypass write must be folded so the
+  // first render's replaceChildren does not silently destroy it); discard
+  // only on the EXPLICIT null of the non-template render path, whose text
+  // output would otherwise be folded and parked.
+  const hasInstanceSym = Symbol.for('webjs.instance') in h;
+  if (!hasInstanceSym || h[Symbol.for('webjs.instance')]) {
+    processBackstop(host, state, records);
+  }
+}
+
+/**
+ * Flip-sensor callback body: a RELEVANT slot=/name= flip re-derives + re-places.
+ * Relevant = a `name=` change on one of the host's own light slots, or a `slot=`
+ * change on an authored (projected) child. An unrelated `name=` deep in the tree
+ * (e.g. an `<input name>`) is ignored, so common markup does not trigger a
+ * spurious full re-apply.
+ */
+function processFlip(host, records) {
+  const state = /** @type {SlotState | undefined} */ (
+    /** @type {any} */ (host)[SLOT_STATE]
+  );
+  if (!state) return;
+  // ONE pass over ALL records first: every explicit slot= change clears that
+  // node's self-heal adoption (the author's attribute is now the routing
+  // intent), unconditionally. Deleting for a node no longer authored is
+  // always safe, and gating on authored membership let a stale adoption
+  // outlive a same-task detach and mis-route a later re-append. Only then is
+  // relevance decided and the single apply run, so a batch with several
+  // relevant flips never leaves a later record's adoption uncleared.
+  let relevant = false;
+  for (const r of records) {
+    if (r.type !== 'attributes') continue;
+    const target = /** @type {Element} */ (r.target);
+    if (r.attributeName === 'name') {
+      if (
+        target.tagName === 'SLOT' &&
+        target.hasAttribute(LIGHT_SLOT_ATTR) &&
+        isOwnSlot(host, target)
+      ) {
+        relevant = true;
+      }
+    } else if (r.attributeName === 'slot') {
+      if (state.adoptedKey) state.adoptedKey.delete(target);
+      if (state.authored.indexOf(target) !== -1) relevant = true;
+    }
+  }
+  if (relevant) applySlotAssignments(host);
+}
+
+/**
+ * Tear down the sensors, PROCESSING any queued records first (a bare
+ * `disconnect()` drops them, which would lose a flip or bypass write captured
+ * but not yet delivered when the host disconnects).
+ *
+ * @param {Element} host
+ */
+export function teardownSlotSensors(host) {
+  const state = /** @type {SlotState | undefined} */ (
+    /** @type {any} */ (host)[SLOT_STATE]
+  );
+  if (!state) return;
+  if (state.backstop) {
+    processBackstop(host, state, state.backstop.takeRecords());
+    state.backstop.disconnect();
+    state.backstop = undefined;
+  }
+  if (state.flipSensor) {
+    processFlip(host, state.flipSensor.takeRecords());
+    state.flipSensor.disconnect();
+    state.flipSensor = undefined;
+  }
+}
+
+/**
+ * Reconnect sweep: after a host is re-inserted, fold any direct host child that
+ * is not already authored, not the park, and not the render root into
+ * `authored` (covers a raw bypass write made while the host was disconnected,
+ * which no sensor was live to see). Then re-apply.
+ *
+ * @param {Element} host
+ */
+export function reconnectSweep(host) {
+  if (!inBrowser) return;
+  const h = /** @type {any} */ (host);
+  const state = /** @type {SlotState | undefined} */ (h[SLOT_STATE]);
+  if (!state) return;
+  const inst = h[Symbol.for('webjs.instance')];
+  const rendered = Symbol.for('webjs.instance') in h;
+  // Gate on the RECORDED connect branch (adoptSSRAssignments sets
+  // state.adopted), never on structural re-detection: a bypass write can
+  // itself carry a rendered-looking chunk (slot[data-webjs-light]
+  // [data-projection] under plain wrappers) and would spoof a structural
+  // check, suppressing the fold for unrelated writes in the same batch.
+  // The flag is also free per reconnect where the structural query walked
+  // the subtree.
+  const adoptedMarkup = !rendered && state.adopted === true;
+  let changed = false;
+  for (const node of Array.from(host.childNodes)) {
+    if (node === h[PARK]) continue;
+    if (state.authored.indexOf(node) !== -1) {
+      // Authored but physically a direct host child: a bypass MOVE made
+      // while disconnected pulled it out of its slot. Re-apply so the
+      // placement step repairs it.
+      changed = true;
+      continue;
+    }
+    // Skip the renderer's own top-level nodes. With an instance, ownership
+    // is checked via the bookends. With an EXPLICIT null instance (the
+    // non-template render path sets host[INSTANCE] = null: render() returned
+    // a string / number / array) the renderer's text output IS the direct
+    // host children, so folding is skipped entirely, like
+    // drainRendererBackstop's no-instance guard. A host that has NEVER
+    // rendered (the symbol is absent: moved before its deferred first
+    // render) has no CLIENT-renderer output, so a disconnected-window
+    // bypass write IS folded UNLESS the host carries adopted
+    // framework-rendered markup (SSR/hydration before the deferred first
+    // render, or a first render that threw): folding THAT subtree would
+    // push template wrappers into the record and brick placement on a
+    // HierarchyRequestError.
+    if (rendered && (!inst || instanceOwns(inst, node))) continue;
+    if (!rendered && adoptedMarkup) continue;
+    FRAMEWORK_DETACHED.add(node);
+    state.authored.push(node);
+    changed = true;
+  }
+  if (changed) applySlotAssignments(host);
+}

package/src/slot/state.js

@@ -0,0 +1,245 @@
+/**
+ * Per-host slot state: the authored-children capture, the name to node
+ * partition, and SSR assignment adoption.
+ *
+ * Moved verbatim out of the pre-split `slot.js`; see that barrel for the
+ * runtime's full contract.
+ *
+ * @module
+ */
+import { isOwnSlot } from './assignment.js';
+import { isInsideAuthored } from './interception.js';
+import { manualSlotFor } from './polyfills.js';
+import { FRAMEWORK_DETACHED, LIGHT_SLOT_ATTR, PROJECTION_ACTUAL, PROJECTION_ATTR, SLOT_STATE } from './symbols.js';
+
+/**
+ * Lazily create and return the slot state for a host element.
+ *
+ * @param {Element} host
+ * @returns {SlotState}
+ */
+export function ensureSlotState(host) {
+  /** @type {any} */
+  const h = host;
+  let state = h[SLOT_STATE];
+  if (!state) {
+    state = {
+      host,
+      authored: [],
+      assignedByName: new Map(),
+      lastSnapshot: new WeakMap(),
+    };
+    h[SLOT_STATE] = state;
+  }
+  return state;
+}
+
+/** True when the host has slot state initialised. */
+export function hasSlotState(host) {
+  return Boolean(/** @type {any} */ (host)[SLOT_STATE]);
+}
+
+// ---------------------------------------------------------------------------
+// Capture: once per host lifetime
+// ---------------------------------------------------------------------------
+
+/**
+ * Move every authored child of `host` into the slot record, partitioning
+ * by each child's `slot=""` attribute. After this runs, `host` has no
+ * children; the renderer re-inserts them at slot-apply time inside the
+ * correct <slot> elements. Runs ONCE per host lifetime (first mount, no
+ * SSR); there is no later re-capture, so rendered nodes can never be
+ * misclassified as authored children (#1006, closed by construction).
+ *
+ * @param {Element} host
+ */
+export function captureAuthoredChildren(host) {
+  const state = ensureSlotState(host);
+  while (host.firstChild) {
+    const node = host.firstChild;
+    state.authored.push(node);
+    // Detached by the framework, awaiting placement at slot-apply time: the
+    // prune rule must not treat this parentless window as an author removal.
+    FRAMEWORK_DETACHED.add(node);
+    host.removeChild(node);
+  }
+  repartition(state);
+}
+
+/**
+ * Rebuild `assignedByName` from `authored`: group every authored node by its
+ * current `slot=""` attribute (default = null key). Pure and idempotent, the
+ * single place a node's slot assignment is decided. Called after any change
+ * to `authored` and at the top of `applySlotAssignments`.
+ *
+ * @param {SlotState} state
+ */
+export function repartition(state) {
+  const byName = state.assignedByName;
+  byName.clear();
+  for (const node of state.authored) {
+    appendToMap(byName, effectiveKeyOf(state, node), node);
+  }
+}
+
+/**
+ * The slot key a node is ASSIGNED under: the manual `HTMLSlotElement.assign()`
+ * overlay when the node is named in one, else the node's `slot=""` attribute.
+ * The ONE key rule, shared by `repartition`, the park step, and the router
+ * seam, so a manually-assigned node is never judged by its overlay in one
+ * place and its raw attribute in another (which parked an assigned node out
+ * of its own slot).
+ *
+ * @param {SlotState} state
+ * @param {Node} node
+ * @returns {string | null}
+ */
+export function effectiveKeyOf(state, node) {
+  const m = manualSlotFor(state, node);
+  if (m) return keyOfName(m.getAttribute('name'));
+  // A node a NON-record writer placed inside a NAMED slot (folded by the
+  // self-heal resync) keeps the key of the container it was written into;
+  // deriving from its (absent or different) slot= attribute would teleport
+  // it to the default slot on the next apply. An explicit later slot=
+  // change clears the adoption (the flip sensor owns that).
+  if (state.adoptedKey) {
+    const adopted = state.adoptedKey.get(node);
+    if (adopted !== undefined) return adopted;
+  }
+  return slotNameOf(node);
+}
+
+/**
+ * After SSR + hydration, projected children already live inside their
+ * <slot data-webjs-light> elements. Walk the host's render tree and
+ * record those existing assignments in the record without moving DOM.
+ * The capture-once counterpart for the hydration path.
+ *
+ * @param {Element} host
+ */
+export function adoptSSRAssignments(host) {
+  const state = ensureSlotState(host);
+  // Record the connect branch: reconnectSweep's pre-render fold gate keys on
+  // this flag (an adopted host's children ARE rendered markup; a captured
+  // host's are only bypass writes).
+  state.adopted = true;
+  /** @type {Set<string|null>} first-wins per name across the host's own slots */
+  const seen = new Set();
+  const slots = host.querySelectorAll(`slot[${LIGHT_SLOT_ATTR}]`);
+  for (const slot of slots) {
+    /** @type {HTMLSlotElement} */
+    const s = /** @type {any} */ (slot);
+    // Only the host's OWN slots. A nested component's slot (another custom
+    // element sits between it and the host) belongs to THAT component and is
+    // adopted from its own record. Without this filter, a nested actual slot
+    // that precedes the outer host's same-named slot in document order wins
+    // the first-wins `has(name)` check below, so the outer record adopts the
+    // inner component's children and the outer's first apply physically steals
+    // them. `applySlotAssignments` and the router both filter; this path must
+    // too.
+    if (!isOwnSlot(host, s)) continue;
+    if (s.getAttribute(PROJECTION_ATTR) !== PROJECTION_ACTUAL) continue;
+    // The authored-content invariant applies at adopt time too: a slot
+    // sitting inside ALREADY-ADOPTED children (an SSR'd forwarded slot
+    // serialized as content of an earlier own slot) is content, not an own
+    // slot; adopting it would first-wins-collide with a later legitimate
+    // same-named own slot and destroy that slot's children. Document order
+    // guarantees a container slot precedes its descendants, so the check
+    // sees the container's children in `authored` by the time a nested slot
+    // is tested.
+    if (isInsideAuthored(state, host, s)) continue;
+    const name = keyOfName(s.getAttribute('name'));
+    if (!seen.has(name)) {
+      seen.add(name);
+      const children = Array.from(s.childNodes);
+      // The SSR'd projected children retain their own `slot=` attribute, so
+      // pushing them into `authored` and re-deriving reproduces the same
+      // per-name grouping without moving any DOM (no flash). Note: `authored`
+      // is rebuilt in slot-document order, not the original interleaved
+      // host-child order, which SSR did not preserve. Per-name grouping (all
+      // that placement uses) is exact; the only observable difference from a
+      // fresh mount is the cross-name ordering a post-hydration `insertBefore`
+      // with a ref in a DIFFERENT named slot would resolve against.
+      // A child whose OWN attribute keys elsewhere (a snapshot-restored
+      // adoption or manual assignment, provenance the HTML cannot carry) is
+      // re-adopted under the container's key, so the first client render
+      // never relocates a node out of the slot the restored markup showed it
+      // in.
+      for (const child of children) {
+        state.authored.push(child);
+        // No prune-exemption mark here: when createInstance detaches the old
+        // SSR subtree, these children still sit in the OLD slot, which this
+        // adopt just recorded in lastSnapshot, so the prune gate keeps them
+        // through the detach window. Skipping the mark also means an author
+        // removing an adopted child BEFORE the first apply (child.remove()
+        // in another component's boot hook) is honoured instead of the node
+        // being resurrected by the resync.
+        if (slotNameOf(child) !== name) {
+          if (!state.adoptedKey) state.adoptedKey = new WeakMap();
+          state.adoptedKey.set(child, name);
+        }
+      }
+      state.lastSnapshot.set(s, children.slice());
+    }
+  }
+  // A serialized snapshot (back/forward restore) also carries the PARK: an
+  // authored child whose slot name matched no rendered slot at snapshot time
+  // sits inside <wj-slot-park>. Sweep its children into the record and drop
+  // the serialized park element itself (a fresh park is created on demand),
+  // so a parked node survives the restore and a later render that DOES emit
+  // its slot pulls it back out.
+  for (const oldPark of host.querySelectorAll('wj-slot-park')) {
+    if (!isOwnSlot(host, oldPark)) continue;
+    for (const child of Array.from(oldPark.childNodes)) {
+      // The children keep the DETACHED oldPark as parent until placement;
+      // the FRAMEWORK_DETACHED mark is what shields them from the prune
+      // rule across that window.
+      FRAMEWORK_DETACHED.add(child);
+      state.authored.push(child);
+    }
+    oldPark.remove();
+  }
+  repartition(state);
+}
+
+/**
+ * Normalise a slot name to the record key, applied at EVERY name read
+ * (capture, adopt, application, rescue, and the public API) so the record
+ * key is uniform end to end. The default slot is stored under `null`;
+ * `''` and `'default'` are aliases for it. Consequence: `default` is a
+ * RESERVED slot name (a literal `name="default"` slot addresses the
+ * default slot); the SSR substitution applies the same rule.
+ *
+ * @param {string | null | undefined} name
+ * @returns {string | null}
+ */
+export function keyOfName(name) {
+  return name == null || name === '' || name === 'default' ? null : name;
+}
+
+/**
+ * Read the slot="" attribute on an element child. Text and comment nodes
+ * always route to the default slot (key = null).
+ *
+ * @param {Node} node
+ * @returns {string | null}
+ */
+function slotNameOf(node) {
+  if (node.nodeType !== 1) return null;
+  const el = /** @type {Element} */ (node);
+  return keyOfName(el.getAttribute('slot'));
+}
+
+/** Append a value to a Map<K, V[]>, creating the array on first hit. */
+function appendToMap(map, key, value) {
+  let arr = map.get(key);
+  if (!arr) {
+    arr = [];
+    map.set(key, arr);
+  }
+  arr.push(value);
+}
+
+// ---------------------------------------------------------------------------
+// Router coordination seam
+// ---------------------------------------------------------------------------

package/src/slot/symbols.js

@@ -0,0 +1,85 @@
+/**
+ * Symbol keys, attribute names and shared constants for the light-DOM
+ * slot runtime. The leaf of the directory: it imports nothing.
+ *
+ * Moved verbatim out of the pre-split `slot.js`; see that barrel for the
+ * runtime's full contract.
+ *
+ * @module
+ */
+
+/**
+ * Symbol-keyed slot state stored on each light-DOM WebComponent host.
+ * Lazily initialised by ensureSlotState(host).
+ */
+export const SLOT_STATE = Symbol('webjs.slot.state');
+
+/** Marker attribute that opts a <slot> element into framework projection. */
+export const LIGHT_SLOT_ATTR = 'data-webjs-light';
+
+/** Records whether a slot is showing real assignment or fallback. */
+export const PROJECTION_ATTR = 'data-projection';
+
+export const PROJECTION_ACTUAL = 'actual';
+export const PROJECTION_FALLBACK = 'fallback';
+
+/**
+ * Symbol-keyed property on a slot element that holds a DocumentFragment
+ * containing the slot's fallback content (cloned from the compiled template
+ * by render-client.js at slot-part bind time). The apply step swaps these
+ * nodes into and out of the slot as the projection state toggles between
+ * "actual" and "fallback".
+ */
+export const SLOT_FALLBACK_FRAG = Symbol('webjs.slot.fallbackFrag');
+
+/**
+ * The host whose TEMPLATE produced this `<slot>` (the render container the
+ * renderer cloned the template into). Authoritative over the structural
+ * `isOwnSlot` walk: a slot a template FORWARDS into a nested component
+ * (`html\`<inner><slot></slot></inner>\``) sits physically inside that child
+ * but is owned by the OUTER host, which the structural walk (a custom element
+ * sits between them) gets wrong. Stamped by the renderer at bind time
+ * (render-client) and resolved from the SSR `data-wj-slot-owner` attribute on
+ * hydration so client-only mount and hydration share one mechanism.
+ */
+export const SLOT_OWNER = Symbol('webjs.slot.templateOwner');
+
+/** The SSR carrier for SLOT_OWNER (a symbol cannot cross the HTML boundary). */
+export const SLOT_OWNER_ATTR = 'data-wj-slot-owner';
+
+/** Maximum recursion depth for assignedNodes({flatten: true}); guards cycles. */
+export const FLATTEN_MAX_DEPTH = 64;
+
+// ---------------------------------------------------------------------------
+// Saved native references and prototype polyfills
+//
+// Module-load tries to install polyfills immediately. In a pure Node
+// process without a DOM library, HTMLSlotElement is undefined and the
+// install is a no-op. Tests that set up linkedom AFTER module load can
+// call installSlotPolyfills() explicitly to re-attempt the install.
+// Subsequent calls are idempotent; native references are captured only
+// on the first successful install.
+// ---------------------------------------------------------------------------
+
+/**
+ * Set on a host WHILE the renderer is committing into it. The patched host
+ * methods check it and delegate to the saved native, so a renderer commit is
+ * never mistaken for authored content. This is the one discriminator between
+ * renderer writes and author writes: a synchronous framework-write window, set
+ * structurally (an own symbol), never inferred from comment markers.
+ */
+export const RENDERING = Symbol('webjs.slot.rendering');
+
+/** Marks a host whose mutating methods have been patched (install once). */
+export const INTERCEPTED = Symbol('webjs.slot.intercepted');
+
+/** The per-host hidden holding element for authored nodes whose slot name
+ *  matches no rendered slot (native keeps them connected but unrendered). */
+export const PARK = Symbol('webjs.slot.park');
+
+/**
+ * Authored nodes the framework detached ON PURPOSE (capture, teardown rescue),
+ * so the prune rule does not treat them as author-removed while they sit
+ * parentless waiting to be (re)placed. Cleared once a node is placed.
+ */
+export const FRAMEWORK_DETACHED = new WeakSet();