@firsthandjs/dom 0.7.1 → 0.9.0

package/dist/dev-chunk-HTXIHAW7.js

@@ -0,0 +1,501 @@
+// packages/dom/src/dev.ts
+function devWarn(message) {
+  console.warn(`[firsthand] ${message}`);
+}
+var seen = /* @__PURE__ */ new Set();
+function devWarnOnce(key, message) {
+  if (!seen.has(key)) {
+    seen.add(key);
+    devWarn(message);
+  }
+}
+function devWarnRenderedObject(value) {
+  const cellish = "peek" in value && typeof value.peek === "function" && "value" in value;
+  devWarnOnce(
+    cellish ? "rendered-cell" : "rendered-object",
+    cellish ? 'A signal or computed was rendered directly, so the page shows "[object Object]". Read it instead: {count.value} rather than {count}.' : `An object was rendered as text, so the page shows "${String(value)}". Render a string, a number or a node.`
+  );
+}
+function hook() {
+  const installed = globalThis.__FIRSTHAND_DEVTOOLS__;
+  return installed !== void 0 && installed.attached ? installed : void 0;
+}
+function devPart(node, property) {
+  hook()?.part(node, property);
+}
+function devComponent(owner, name) {
+  hook()?.component(owner, name);
+}
+function label(value, kind, name) {
+  if (typeof value === "object" && value !== null) {
+    hook()?.label(value, kind, name);
+  }
+  return value;
+}
+var QUIET = 20;
+function devRan(store2) {
+  if (store2.busy === true) {
+    store2.busy = false;
+    store2.quiet = 0;
+    return;
+  }
+  const quiet = (store2.quiet ?? 0) + 1;
+  store2.quiet = quiet;
+  if (quiet !== QUIET) {
+    return;
+  }
+  devWarnOnce(
+    `quiet-run:${store2.name}`,
+    `<${store2.name}> ran ${String(QUIET)} times and wrote nothing.
+Something it reads in a statement changes more often than what it shows. Move that read into the markup, where it is a part of its own, or move the derivation into a computed in the setup.`
+  );
+}
+function devHandedNewFunction(store2, value) {
+  if (typeof value !== "function") {
+    return;
+  }
+  devWarnOnce(
+    `new-function:${store2.name}`,
+    `<${store2.name}> hands a child a new function on every run, so that child runs again whenever this one does.
+If the handler does not depend on the run, define it in the setup.`
+  );
+}
+function devHydrationMismatch(node, html) {
+  const template = document.createElement("template");
+  template.innerHTML = html;
+  const expected = template.content.firstElementChild;
+  if (expected === null) {
+    return;
+  }
+  for (const attribute of expected.attributes) {
+    const found = node.getAttribute(attribute.name);
+    if (found !== attribute.value) {
+      devWarn(
+        `Hydration found <${node.tagName.toLowerCase()} ${attribute.name}="${found ?? ""}"> where this render describes "${attribute.value}". The markup is kept as the server sent it, because static markup is never written again. Render the same thing on both sides, or render this part in the browser only.`
+      );
+      return;
+    }
+  }
+}
+
+// packages/dom/src/claim.ts
+var hydration = { current: null };
+function first(node) {
+  const child = node.firstChild;
+  const claimer = hydration.current;
+  return claimer === null ? child : claimer.step(child);
+}
+function next(node) {
+  const sibling = node.nextSibling;
+  const claimer = hydration.current;
+  return claimer === null ? sibling : claimer.step(sibling);
+}
+
+// packages/dom/src/insert.ts
+import {
+  bind,
+  createOwner,
+  signal,
+  disposeOwner,
+  getOwner,
+  onCleanup,
+  runWithOwner,
+  setOwner
+} from "@firsthandjs/core";
+var discarding = 0;
+function discard(body) {
+  discarding++;
+  try {
+    body();
+  } finally {
+    discarding--;
+  }
+}
+var TEXT_NODE = 3;
+function isNode(value) {
+  return typeof value.nodeType === "number";
+}
+var PART = /* @__PURE__ */ Symbol("firsthand.part");
+var FLAT = /* @__PURE__ */ Symbol("firsthand.flat");
+function part(thunk) {
+  return { [PART]: true, anchor: document.createTextNode(""), thunk, owner: getOwner() };
+}
+function isDynamicChild(value) {
+  return PART in value;
+}
+function store(name = "") {
+  return { slots: [], owner: getOwner(), generation: 0, name };
+}
+function wrote(store2) {
+  store2.busy = true;
+}
+function site(store2, index) {
+  const existing = store2.slots[index];
+  if (existing !== void 0) {
+    existing.seen = store2.generation;
+    return existing;
+  }
+  const slot = { seen: store2.generation };
+  store2.slots[index] = slot;
+  return slot;
+}
+function open(store2, slot) {
+  const owner = createOwner(store2.owner);
+  slot.owner = owner;
+  return setOwner(owner);
+}
+function close(previous) {
+  setOwner(previous);
+}
+function ran(store2, value) {
+  devRan(store2);
+  const generation = store2.generation;
+  const slots = store2.slots;
+  for (let i = 0; i < slots.length; i++) {
+    const slot = slots[i];
+    if (slot === void 0 || slot.seen === generation) {
+      continue;
+    }
+    if (slot.owner !== void 0) {
+      disposeOwner(slot.owner);
+    }
+    slots[i] = void 0;
+  }
+  store2.generation = generation + 1;
+  return value;
+}
+function cell(store2, index, value) {
+  const slot = site(store2, index);
+  const existing = slot.cell;
+  if (existing === void 0) {
+    const made = signal(value);
+    slot.cell = made;
+    return made;
+  }
+  if (existing.peek() !== value) {
+    devHandedNewFunction(store2, value);
+    wrote(store2);
+    existing.value = value;
+  }
+  return existing;
+}
+function writeChild(store2, index, parent, marker, value) {
+  const slot = site(store2, index);
+  if (slot.node === void 0 && hydration.current !== null) {
+    const claimed = hydration.current.claim(parent, marker);
+    if (claimed !== null) {
+      if (typeof value === "object" && value !== null && isDynamicChild(value)) {
+        slot.last = value;
+        hydration.current.keep(slot, parent, value.anchor, claimed);
+        runWithOwner(value.owner, () => {
+          insert(parent, value.thunk, value.anchor);
+        });
+        return;
+      }
+      slot.node = claimed.nodes;
+      slot.text = claimed.text;
+    }
+  }
+  const type = typeof value;
+  if (type === "string" || type === "number") {
+    const text = String(value);
+    if (text === slot.text) {
+      return;
+    }
+    wrote(store2);
+    slot.text = text;
+    slot.node = applyChild(parent, marker, slot.node ?? null, text);
+    return;
+  }
+  slot.text = void 0;
+  if (value === slot.last) {
+    return;
+  }
+  wrote(store2);
+  slot.last = value;
+  slot.node = applyChild(parent, marker, slot.node ?? null, value);
+}
+function insert(parent, value, marker = null, seed) {
+  if (typeof value !== "function") {
+    applyChild(parent, marker, null, value);
+    return;
+  }
+  let current = null;
+  let written;
+  const claimed = seed !== void 0 ? seed : hydration.current === null ? null : hydration.current.claim(parent, marker);
+  let adopting = claimed !== null;
+  if (claimed !== null) {
+    current = claimed.nodes;
+    written = claimed.text;
+  }
+  const body = () => {
+    const next2 = value();
+    const type = typeof next2;
+    if (type === "string" || type === "number") {
+      const text = String(next2);
+      if (text !== written) {
+        written = text;
+        current = applyChild(parent, marker, current, text);
+      }
+      return;
+    }
+    written = void 0;
+    if (type === "function") {
+      if (adopting) {
+        current = null;
+        insert(parent, next2, marker, claimed);
+        return;
+      }
+      current = clear(current);
+      insert(parent, next2, marker, null);
+      return;
+    }
+    current = applyChild(parent, marker, current, next2);
+  };
+  if (claimed === null) {
+    bind(body);
+  } else {
+    hydration.current.within(claimed.region, () => {
+      bind(body);
+    });
+  }
+  adopting = false;
+  onCleanup(() => {
+    current = discarding > 0 ? null : clear(current);
+  });
+}
+function applyChild(parent, marker, current, value) {
+  const type = typeof value;
+  if (value == null || type === "boolean") {
+    devPart(parent, "text");
+    return clearIn(parent, marker, current);
+  }
+  if (type === "string" || type === "number") {
+    devPart(parent, "text");
+    const text = String(value);
+    if (current !== null && !Array.isArray(current) && current.nodeType === TEXT_NODE) {
+      current.data = text;
+      return current;
+    }
+    return single(parent, marker, current, document.createTextNode(text));
+  }
+  if (type === "function") {
+    return applyChild(parent, marker, current, value());
+  }
+  if (Array.isArray(value)) {
+    if (FLAT in value) {
+      const rows = value;
+      if (rows.length === 0) {
+        return clearIn(parent, marker, current);
+      }
+      reconcile(
+        parent,
+        marker,
+        current === null ? [] : Array.isArray(current) ? current : [current],
+        rows
+      );
+      return rows;
+    }
+    const next2 = [];
+    const dynamic = [];
+    flatten(value, next2, dynamic);
+    if (next2.length === 0) {
+      return clearIn(parent, marker, current);
+    }
+    reconcile(
+      parent,
+      marker,
+      current === null ? [] : Array.isArray(current) ? current : [current],
+      next2
+    );
+    for (let i = 0; i < dynamic.length; i++) {
+      const child = dynamic[i];
+      runWithOwner(child.owner ?? getOwner(), () => {
+        insert(parent, child.thunk, child.anchor);
+      });
+    }
+    return next2;
+  }
+  if (isDynamicChild(value)) {
+    return applyChild(parent, marker, current, [value]);
+  }
+  if (isNode(value)) {
+    return single(parent, marker, current, value);
+  }
+  devWarnRenderedObject(value);
+  return applyChild(parent, marker, current, String(value));
+}
+function flatten(value, out, dynamic) {
+  for (let i = 0; i < value.length; i++) {
+    let item = value[i];
+    if (typeof item === "object" && item !== null && isDynamicChild(item)) {
+      out.push(item.anchor);
+      dynamic.push(item);
+      continue;
+    }
+    while (typeof item === "function") {
+      item = item();
+    }
+    if (item == null || typeof item === "boolean") {
+      continue;
+    }
+    if (Array.isArray(item)) {
+      flatten(item, out, dynamic);
+    } else if (typeof item === "object" && isNode(item)) {
+      out.push(item);
+    } else {
+      out.push(document.createTextNode(String(item)));
+    }
+  }
+}
+function detach(node) {
+  const owner = node.parentNode;
+  if (owner !== null) {
+    owner.removeChild(node);
+  }
+}
+function clearIn(parent, marker, current) {
+  if (marker === null && Array.isArray(current) && current.length > 1 && parent.childNodes.length === current.length) {
+    parent.textContent = "";
+    return null;
+  }
+  return clear(current);
+}
+function clear(current) {
+  if (current !== null) {
+    if (Array.isArray(current)) {
+      for (let i = 0; i < current.length; i++) {
+        detach(current[i]);
+      }
+    } else {
+      detach(current);
+    }
+  }
+  return null;
+}
+function single(parent, marker, current, node) {
+  if (current === node) {
+    return node;
+  }
+  if (current !== null && !Array.isArray(current)) {
+    parent.replaceChild(node, current);
+    return node;
+  }
+  clear(current);
+  parent.insertBefore(node, marker);
+  return node;
+}
+function reconcile(parent, marker, a, b) {
+  let aStart = 0;
+  let bStart = 0;
+  let aEnd = a.length - 1;
+  let bEnd = b.length - 1;
+  while (aStart <= aEnd && bStart <= bEnd && a[aStart] === b[bStart]) {
+    aStart++;
+    bStart++;
+  }
+  while (aStart <= aEnd && bStart <= bEnd && a[aEnd] === b[bEnd]) {
+    aEnd--;
+    bEnd--;
+  }
+  const after = bEnd + 1 < b.length ? b[bEnd + 1] : marker;
+  if (aStart > aEnd) {
+    for (let i = bStart; i <= bEnd; i++) {
+      parent.insertBefore(b[i], after);
+    }
+    return;
+  }
+  if (bStart > bEnd) {
+    for (let i = aStart; i <= aEnd; i++) {
+      parent.removeChild(a[i]);
+    }
+    return;
+  }
+  const oldIndex = /* @__PURE__ */ new Map();
+  for (let i = aStart; i <= aEnd; i++) {
+    oldIndex.set(a[i], i);
+  }
+  const middle = bEnd - bStart + 1;
+  const sources = new Int32Array(middle).fill(-1);
+  for (let j = 0; j < middle; j++) {
+    const node = b[bStart + j];
+    const found = oldIndex.get(node);
+    if (found !== void 0) {
+      sources[j] = found;
+      oldIndex.delete(node);
+    }
+  }
+  for (const node of oldIndex.keys()) {
+    parent.removeChild(node);
+  }
+  const keep = longestIncreasing(sources);
+  let k = keep.length - 1;
+  let anchor = after;
+  for (let j = middle - 1; j >= 0; j--) {
+    const node = b[bStart + j];
+    if (k >= 0 && keep[k] === j) {
+      k--;
+    } else {
+      parent.insertBefore(node, anchor);
+    }
+    anchor = node;
+  }
+}
+function longestIncreasing(sources) {
+  const length = sources.length;
+  const predecessor = new Int32Array(length).fill(-1);
+  const tails = [];
+  for (let i = 0; i < length; i++) {
+    const value = sources[i];
+    if (value === -1) {
+      continue;
+    }
+    let low = 0;
+    let high = tails.length;
+    while (low < high) {
+      const mid = low + high >> 1;
+      if (sources[tails[mid]] < value) {
+        low = mid + 1;
+      } else {
+        high = mid;
+      }
+    }
+    if (low > 0) {
+      predecessor[i] = tails[low - 1];
+    }
+    tails[low] = i;
+  }
+  const result = [];
+  let cursor = tails.length > 0 ? tails[tails.length - 1] : -1;
+  while (cursor !== -1) {
+    result.push(cursor);
+    cursor = predecessor[cursor];
+  }
+  return result.reverse();
+}
+
+export {
+  devWarn,
+  devWarnOnce,
+  devPart,
+  devComponent,
+  label,
+  devHydrationMismatch,
+  hydration,
+  first,
+  next,
+  discard,
+  FLAT,
+  part,
+  store,
+  wrote,
+  site,
+  open,
+  close,
+  ran,
+  cell,
+  writeChild,
+  insert,
+  applyChild,
+  reconcile
+};

package/dist/dev.d.ts

@@ -38,4 +38,38 @@ export declare function devComponent(owner: object, name: string): void;
  * emits no call to it at all.
  */
 export declare function label<T>(value: T, kind: string, name: string): T;
+/**
+ * Reports a render function that keeps running and keeps changing nothing.
+ *
+ * Nothing is optimised here and nothing is hidden: this is bookkeeping, said
+ * out loud. A run that produces exactly what is already on screen did work for
+ * no one, and the reason is always the same — it reads something in a
+ * statement that moves more often than what it shows.
+ */
+export declare function devRan(store: {
+    name: string;
+    busy?: boolean;
+    quiet?: number;
+}): void;
+/**
+ * Reports a child that is handed a new function on every run.
+ *
+ * A function made in a run is never equal to the one before it, so the child
+ * it is given to runs again every time its parent does — the `useCallback`
+ * problem, named rather than papered over.
+ */
+export declare function devHandedNewFunction(store: {
+    name: string;
+}, value: unknown): void;
+/**
+ * Reports markup a server sent that is not the markup this run describes.
+ *
+ * Only the element's own attributes are compared, and only in development:
+ * what is inside it may already have been hydrated, and parsing the template
+ * to compare more is the cost hydration exists to avoid. That is enough to
+ * name the mistake, which is always the same mistake — a view that renders
+ * one thing on a server and another in a browser, from props or state that
+ * differ between them.
+ */
+export declare function devHydrationMismatch(node: Element, html: string): void;
 //# sourceMappingURL=dev.d.ts.map

package/dist/dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../src/dev.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAID,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAK9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAWzD;AAkBD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED,oDAAoD;AACpD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAKhE"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../src/dev.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAID,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAK9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAWzD;AAkBD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED,oDAAoD;AACpD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAKhE;AAKD;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAkBpF;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAUlF;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAoBtE"}

package/dist/dev.prod.d.ts

@@ -5,4 +5,13 @@ export declare function devWarnRenderedObject(_value: object): void;
 export declare function devPart(_node: object, _property: string): void;
 export declare function devComponent(_owner: object, _name: string): void;
 export declare function label<T>(value: T, _kind: string, _name: string): T;
+export declare function devRan(_store: {
+    name: string;
+    busy?: boolean;
+    quiet?: number;
+}): void;
+export declare function devHandedNewFunction(_store: {
+    name: string;
+}, _value: unknown): void;
+export declare function devHydrationMismatch(_node: Element, _html: string): void;
 //# sourceMappingURL=dev.prod.d.ts.map

package/dist/dev.prod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.prod.d.ts","sourceRoot":"","sources":["../src/dev.prod.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAE3E,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEhE;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE1D;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAE9D;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAEhE;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,CAElE"}
+{"version":3,"file":"dev.prod.d.ts","sourceRoot":"","sources":["../src/dev.prod.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAE3E,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEhE;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE1D;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAE9D;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAEhE;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,CAElE;AAED,wBAAgB,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAErF;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAEpF;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAExE"}

package/dist/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkEH;;;;;;GAMG;AACH,wBAAgB,EAAE,CAChB,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EAC/B,OAAO,CAAC,EAAE,uBAAuB,GAAG,IAAI,GACvC,IAAI,CAUN;AAED,yEAAyE;AACzE,wBAAgB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAIrD;AAED,kEAAkE;AAClE,wBAAgB,eAAe,IAAI,IAAI,CAKtC"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkEH;;;;;;GAMG;AACH,wBAAgB,EAAE,CAChB,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EAC/B,OAAO,CAAC,EAAE,uBAAuB,GAAG,IAAI,GACvC,IAAI,CA2BN;AAED,yEAAyE;AACzE,wBAAgB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAIrD;AAED,kEAAkE;AAClE,wBAAgB,eAAe,IAAI,IAAI,CAKtC"}

package/dist/hydrate.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Adopting server-rendered markup instead of building it.
+ *
+ * ```ts
+ * import { hydrate } from '@firsthandjs/dom/hydrate';
+ *
+ * hydrate(() => <App />, document.getElementById('app')!);
+ * ```
+ *
+ * Its own entry point, not part of `@firsthandjs/dom`, for one reason: an
+ * application without a server must not carry this. Nothing in the render
+ * path imports this module — `template` and `insert` read the holder in
+ * `claim.ts`, which stays empty — so a bundle that never imports it never
+ * contains it.
+ *
+ * A hydrating render runs exactly the same compiled code as a fresh one. What
+ * changes is where nodes come from: `template()` hands back a node the server
+ * already sent rather than a clone, and a dynamic child finds its content in
+ * place rather than creating it. Nothing else in the render path knows.
+ *
+ * The only thing that makes that possible is knowing which nodes belong to
+ * which dynamic child, and the server says so: it wraps every dynamic child in
+ * `<!--[-->` … marker, where the marker is the same comment the browser's own
+ * template has at that position. Two consequences follow, and they are the
+ * whole design:
+ *
+ * - **Navigation still works.** `firstChild.nextSibling` would walk into the
+ *   content of a dynamic child, because the content has a length the template
+ *   does not. Compiled with `hydratable`, navigation goes through `first` and
+ *   `next` instead, which step over a whole region in one move — landing on
+ *   the marker, which is the node the template has there.
+ * - **Text does not run together.** The parser would read `Hello, ` and a
+ *   dynamic `Ada` as one text node. The opening comment sits between them, so
+ *   the part gets a text node of its own to write to.
+ *
+ * The comments are in the server's markup only. A build without SSR emits
+ * neither them nor the navigation helpers, and pays nothing at all.
+ */
+import type { Dispose } from '@firsthandjs/core';
+import { type Claimed, type Region } from './claim.js';
+import type { View } from './component.js';
+/**
+ * Takes over markup a server already sent.
+ *
+ * The same call as `render`, against the same view, with the same result — a
+ * live application and a disposer. What it does not do is build anything that
+ * is already there: every element is adopted, every text node is kept, and the
+ * only writes are the listeners and the properties markup cannot express.
+ *
+ * The view has to be the view the server rendered — same props, same state,
+ * same answer. Where it is not:
+ *
+ * - A **dynamic** value that disagrees is written, as it would be on any other
+ *   change. The page ends up right; the work hydration saved is spent.
+ * - A **different element** is not adopted. The browser builds its own and the
+ *   part it belongs to puts it in place of what was sent.
+ * - **Static markup** that disagrees is kept as the server wrote it, because
+ *   static markup is the markup nothing ever writes again. Development says so
+ *   by name; production cannot, and a view that renders two different things
+ *   from the same props is a bug this cannot repair.
+ */
+export declare function hydrate(view: () => View, container?: ParentNode): Dispose;
+/**
+ * Runs `body` against server markup already in `container`.
+ *
+ * Nested calls are counted rather than nested: an island inside an island is
+ * one hydration as far as the markup is concerned, and the outer one finishes
+ * the sweep.
+ */
+export declare function hydrateWith<T>(container: Node, body: () => T): T;
+/**
+ * The next node this region has not handed out yet, if it is a `tag`.
+ *
+ * A node that is not what was asked for is left where it is rather than
+ * consumed: the caller builds its own, and the part it belongs to replaces
+ * what is there. Nothing is adopted on a guess.
+ */
+export declare function adopt(tag: string): Node | null;
+/**
+ * Finds the region belonging to the next dynamic child of `parent`.
+ *
+ * Dynamic children are claimed in document order, which is the order the
+ * compiled code reaches them in, so this is a cursor and never a search.
+ * `marker` is what navigation landed on, and it has to be where the region
+ * ends: if it is not, the server and the client disagree about this subtree
+ * and the caller renders it from nothing instead.
+ */
+export declare function claimRegion(parent: Node, marker: Node | null): Claimed | null;
+/** Makes `region` the one nodes are adopted from while `body` runs. */
+export declare function within<T>(region: Region, body: () => T): T;
+//# sourceMappingURL=hydrate.d.ts.map

package/dist/hydrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../src/hydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAa,KAAK,OAAO,EAAe,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AA0B3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,IAAI,EAAE,SAAS,GAAE,UAA0B,GAAG,OAAO,CAIxF;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAgBhE;AAaD;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAW9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,GAAG,IAAI,CAqD7E;AAED,uEAAuE;AACvE,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAQ1D"}