@ogygia/core 0.0.0 → 0.11.0

package/dist/runtime/restore.js

@@ -0,0 +1,390 @@
+// src/runtime/restore.ts
+/**
+* THE RESTORER — the browser half of reversible transforms (server/reversible.ts). An app's server
+* transform rendered each planned custom element (`og-h`) in scoped form: its rendered tree in the
+* host's light DOM, Svelte's children moved into `<slot>` wrappers inside it. This puts it back into
+* the form hydration and the component's runtime both expect:
+*
+*   1. stand-ins (`<og-as tag="a">`: tags the HTML parser would have restructured) become their real
+*      element, in place — a DOM operation, which no content-model rule applies to;
+*   2. for each planned host, innermost first: an open shadow root with the host's keyed sheets, the
+*      rendered tree moved into it (its `<slot>` wrappers become real slots), Svelte's children back
+*      in the light DOM in their original order and exactly as Svelte rendered them (attributes reset,
+*      trimmed or dropped text put back), the host's attributes back to Svelte's (except `og-keep`).
+*
+* The page stays painted the same throughout: the scoped form and the shadow form render alike, and
+* each host is restored in one task. It must run before anything reads the markup — before an island
+* snapshots or hydrates, before Kit starts, before a web-component runtime upgrades a host. So the
+* handle inlines it at the end of the document's body (`restore.toString()`: this function is
+* self-contained, no imports, no outer names), and the runtime calls it on a hole / lake answer before
+* insertion and on an incoming page before a router swap.
+*
+* A host that already has a shadow root when it is reached was upgraded first — the restore came
+* too late. It is left as served and reported (`ogygia:restore-late` on the host), never restored into
+* a root the component's own constructor made (that tree would render twice).
+*/
+function restore(root) {
+	const doc = root.ownerDocument ?? root;
+	const head = document.head;
+	const W = window;
+	const sheets = W.__og_sheets ??= /* @__PURE__ */ new Map();
+	const esc = (s) => typeof CSS !== "undefined" && CSS.escape ? CSS.escape(s) : s.split("\\").join("\\\\").split("\"").join("\\\"");
+	const live = doc === document;
+	let restored = 0;
+	/**
+	* A KIT-HYDRATED page (csr=true) is hydrated by Kit's own start, which ogygia does not run — so
+	* the island hydrate's put-back of a component's class tokens (runtime/host-classes.ts) never
+	* runs there. Instead each restored custom element is watched once: Kit's hydrate writes its
+	* `class` whole, to exactly Svelte's tokens; the first write that leaves exactly those gets back
+	* every token it dropped (the component's, the render's `sc-*`), read from the value just before
+	* that write. A component only ever adds and removes its own tokens, so no later state of the
+	* host equals Svelte's alone. One observer for all of them; a host leaves the watch at that
+	* write, and the observer goes when the last one has.
+	*/
+	const watch_classes = live && document.querySelector("meta[name=\"ogygia-csr\"][content=\"true\"]") !== null;
+	const watch = (el) => {
+		let w = W.__og_class_watch;
+		if (!w) {
+			const hosts = /* @__PURE__ */ new Set();
+			const mo = new MutationObserver((records) => {
+				for (let i = 0; i < records.length; i++) {
+					const host = records[i].target;
+					if (!hosts.has(host)) continue;
+					let now;
+					for (let j = i + 1; j < records.length && now === void 0; j++) if (records[j].target === host) now = records[j].oldValue;
+					if (now === void 0) now = host.getAttribute("class");
+					if ((now ?? "") !== host.__og_svelte_class) continue;
+					hosts.delete(host);
+					const own = new Set((now ?? "").split(" "));
+					for (const t of (records[i].oldValue ?? "").split(" ")) if (t && !own.has(t)) host.classList.add(t);
+				}
+				if (hosts.size === 0) {
+					mo.disconnect();
+					W.__og_class_watch = void 0;
+				}
+			});
+			w = W.__og_class_watch = {
+				mo,
+				hosts
+			};
+		}
+		w.hosts.add(el);
+		w.mo.observe(el, {
+			attributes: true,
+			attributeFilter: ["class"],
+			attributeOldValue: true
+		});
+	};
+	if (root !== document && root.querySelectorAll) for (const el of Array.from(root.querySelectorAll("[data-og-head]"))) {
+		const key = el.getAttribute("data-og-head");
+		if (head.querySelector(`[data-og-head="${esc(key)}"]`)) el.remove();
+		else head.appendChild(el);
+	}
+	const sheet_for = (key) => {
+		const have = sheets.get(key);
+		if (have) return have;
+		const sel = `template[data-og-head="${esc(key)}"]`;
+		const tpl = doc !== document && doc.head?.querySelector(sel) || head.querySelector(sel);
+		if (!tpl) return null;
+		const css = tpl.content.textContent ?? "";
+		let sheet = null;
+		try {
+			sheet = new CSSStyleSheet();
+			sheet.replaceSync(css);
+		} catch {
+			sheet = null;
+		}
+		const made = {
+			sheet,
+			css
+		};
+		sheets.set(key, made);
+		return made;
+	};
+	/** Attributes back to Svelte's. A custom element's `class` has two owners — Svelte, and the
+	*  component, which may put state on its own host — so there it becomes Svelte's tokens PLUS the
+	*  ones the render added, and Svelte's are recorded on the element (`__og_svelte_class`): the
+	*  island's hydrate puts the component's back after Svelte writes `class` whole
+	*  (runtime/host-classes.ts). Unless the render kept `class` as its own (`og-keep`). */
+	const reset = (el) => {
+		const r = el.getAttribute("og-r");
+		const custom = el.localName.indexOf("-") !== -1 && (" " + (el.getAttribute("og-keep") ?? "") + " ").indexOf(" class ") === -1;
+		let svelte_class;
+		if (r) try {
+			const diff = JSON.parse(r);
+			for (const name in diff) {
+				const v = diff[name];
+				if (custom && name === "class") {
+					svelte_class = v;
+					const own = new Set((v ?? "").split(" "));
+					let theirs = "";
+					for (const t of Array.from(el.classList)) if (!own.has(t)) theirs += " " + t;
+					const merged = ((v ?? "") + theirs).trim();
+					if (merged) el.setAttribute("class", merged);
+					else el.removeAttribute("class");
+				} else if (v === null) el.removeAttribute(name);
+				else el.setAttribute(name, v);
+			}
+		} catch {}
+		if (custom) {
+			el.__og_svelte_class = svelte_class === void 0 ? el.getAttribute("class") ?? "" : svelte_class ?? "";
+			if (watch_classes) watch(el);
+		}
+		el.removeAttribute("og-r");
+	};
+	/** A mark's original text (`<!--og-c K.i t "…"-->`, `<!--og-t K.n "…"-->`), or undefined. */
+	const original = (data) => {
+		const q = data.indexOf(" \"");
+		if (q === -1) return void 0;
+		try {
+			return JSON.parse(data.slice(q + 1));
+		} catch {
+			return;
+		}
+	};
+	/** Put back the text after a text mark (trimmed, or dropped: then a new node), then drop the mark. */
+	const fix_text = (mark) => {
+		const was = original(mark.data);
+		if (was !== void 0) {
+			const next = mark.nextSibling;
+			if (next && next.nodeType === 3) next.data = was;
+			else mark.parentNode.insertBefore(doc.createTextNode(was), next);
+		}
+		const node = mark.nextSibling;
+		mark.remove();
+		return node;
+	};
+	const comments = (under, prefix) => {
+		const out = [];
+		const walk = doc.createTreeWalker(under, 128);
+		for (let n = walk.nextNode(); n; n = walk.nextNode()) if (n.data.startsWith(prefix)) out.push(n);
+		return out;
+	};
+	const swap_stand_ins = (under) => {
+		const list = Array.from(under.querySelectorAll("og-as"));
+		for (let x = list.length - 1; x >= 0; x--) {
+			const as = list[x];
+			const real = doc.createElement(as.getAttribute("tag") || "span");
+			for (const a of Array.from(as.attributes)) if (a.name !== "tag") real.setAttribute(a.name, a.value);
+			while (as.firstChild) real.appendChild(as.firstChild);
+			as.replaceWith(real);
+		}
+	};
+	let check = null;
+	const check_el = root.querySelector("script[type=\"application/ogygia-restore-check\"]");
+	if (check_el) {
+		try {
+			check = JSON.parse(check_el.textContent || "{}");
+		} catch {
+			check = null;
+		}
+		check_el.remove();
+	}
+	/** The first difference between Svelte's children and the restored ones (node types, tags, text,
+	*  comments, attributes — a web-component host may carry more than Svelte's: `og-keep`), or null. */
+	const differ = (want, got, path) => {
+		const a = want.childNodes;
+		const b = got.childNodes;
+		for (let i = 0; i < Math.max(a.length, b.length); i++) {
+			const x = a[i];
+			const y = b[i];
+			const here = `${path} > [${i}]`;
+			if (!x || !y) return `${here}: Svelte has ${x ? describe(x) : "nothing"}, the restored markup has ${y ? describe(y) : "nothing"}`;
+			if (x.nodeType !== y.nodeType || x.nodeName !== y.nodeName) return `${here}: Svelte has ${describe(x)}, the restored markup has ${describe(y)}`;
+			if (x.nodeType === 3 || x.nodeType === 8) {
+				if (x.data !== y.data) return `${here}: Svelte has ${describe(x)}, the restored markup has ${describe(y)}`;
+				continue;
+			}
+			if (x.nodeType !== 1) continue;
+			const ex = x;
+			const ey = y;
+			const custom = ex.localName.indexOf("-") !== -1;
+			for (const attr of Array.from(ex.attributes)) {
+				if (custom && attr.name === "class" ? within(attr.value, ey.getAttribute("class")) : norm(attr.name, attr.value) === norm(attr.name, ey.getAttribute(attr.name))) continue;
+				return `${here} <${ex.localName}>: Svelte has ${attr.name}="${attr.value}", the restored markup has ${ey.hasAttribute(attr.name) ? `"${ey.getAttribute(attr.name)}"` : "none"}`;
+			}
+			if (!custom) {
+				for (const attr of Array.from(ey.attributes)) if (!ex.hasAttribute(attr.name) && norm(attr.name, attr.value) !== null) return `${here} <${ex.localName}>: the restored markup adds ${attr.name}="${attr.value}"`;
+			}
+			const deeper = differ(x, y, `${here} <${ex.localName}>`);
+			if (deeper) return deeper;
+		}
+		return null;
+	};
+	/** An attribute as it matters, not as a serializer wrote it: `class` as its set of tokens, `style`
+	*  as its declarations, an empty value as absent (Svelte's hydration reads neither; a render's
+	*  serializer rewrites both). */
+	const norm = (name, value) => {
+		if (value === null || value.trim() === "") return name === "class" || name === "style" ? null : value;
+		if (name === "class") return value.split(/\s+/).filter(Boolean).sort().join(" ");
+		if (name === "style") return value.split(";").map((d) => {
+			const c = d.indexOf(":");
+			return c === -1 ? d.trim() : `${d.slice(0, c).trim().toLowerCase()}:${d.slice(c + 1).trim().replace(/\s+/g, " ")}`;
+		}).filter(Boolean).join(";");
+		return value;
+	};
+	/** Every class token of `want` is in `got`. */
+	const within = (want, got) => {
+		const have = new Set((got ?? "").split(/\s+/));
+		for (const t of want.split(/\s+/)) if (t && !have.has(t)) return false;
+		return true;
+	};
+	const describe = (n) => n.nodeType === 3 ? `the text ${JSON.stringify(n.data)}` : n.nodeType === 8 ? `the comment <!--${n.data}-->` : `<${n.localName}>`;
+	const verify = (host, k) => {
+		const want = check?.[k];
+		if (want === void 0) return;
+		const tpl = doc.createElement("template");
+		tpl.innerHTML = want;
+		const diff = differ(tpl.content, host, `<${host.localName}>`);
+		if (!diff) return;
+		console.error(`[ogygia] the transform broke hydration markup: ${diff}`);
+		host.dispatchEvent(new CustomEvent("ogygia:restore-mismatch", {
+			bubbles: true,
+			detail: {
+				host: host.localName,
+				diff
+			}
+		}));
+		log("mismatch", host, diff);
+	};
+	/** What went wrong, kept for whoever reads it later (the devtools, the profiler's beacon): the
+	*  restorer runs while the page parses — before any listener of theirs exists. */
+	const log = (kind, host, diff) => {
+		const list = W.__og_restore_log ??= [];
+		if (list.length >= 50) return;
+		const island = host.closest("ogygia-region")?.getAttribute("data-og-fp") ?? void 0;
+		list.push({
+			kind,
+			host: host.localName,
+			t: Math.round(performance.now()),
+			...diff ? { diff: diff.slice(0, 300) } : {},
+			...island ? { island } : {}
+		});
+	};
+	const scopes = [root];
+	for (let q = 0; q < scopes.length; q++) {
+		const walk = doc.createTreeWalker(scopes[q], 1);
+		for (let n = walk.nextNode(); n; n = walk.nextNode()) {
+			const sr = n.shadowRoot;
+			if (sr && sr.mode === "open") scopes.push(sr);
+		}
+	}
+	for (const scope of scopes) swap_stand_ins(scope);
+	const hosts = [];
+	for (const scope of scopes) hosts.push(...Array.from(scope.querySelectorAll("[og-h]")));
+	for (let x = hosts.length - 1; x >= 0; x--) {
+		const host = hosts[x];
+		const k = host.getAttribute("og-h");
+		const keys = (host.getAttribute("og-shadow") ?? "").split(" ").filter(Boolean);
+		if (host.shadowRoot) {
+			host.dispatchEvent(new CustomEvent("ogygia:restore-late", {
+				bubbles: true,
+				detail: { host: k }
+			}));
+			log("late", host);
+			continue;
+		}
+		const shadow = host.attachShadow({ mode: "open" });
+		if (!live) (W.__og_init ??= []).push(shadow);
+		const own = [];
+		const adoptable = Array.isArray(shadow.adoptedStyleSheets);
+		for (const key of keys) {
+			const s = sheet_for(key);
+			if (!s) continue;
+			if (s.sheet && adoptable) own.push(s.sheet);
+			else {
+				const style = doc.createElement("style");
+				style.textContent = s.css;
+				shadow.appendChild(style);
+			}
+		}
+		if (own.length) {
+			if (live) shadow.adoptedStyleSheets = [...shadow.adoptedStyleSheets, ...own];
+			else {
+				shadow.__og_pending = own;
+				(W.__og_adopt ??= []).push({
+					shadow,
+					sheets: own
+				});
+			}
+		}
+		const children = [];
+		const tag = `${k}.`;
+		for (const el of Array.from(host.querySelectorAll("[og-c]"))) {
+			const v = el.getAttribute("og-c");
+			if (v.startsWith(tag)) children.push({
+				i: Number(v.slice(tag.length)),
+				node: el
+			});
+		}
+		for (const mark of comments(host, `og-c ${tag}`)) {
+			const rest = mark.data.slice(5 + tag.length);
+			const i = Number(rest.slice(0, rest.indexOf(" ") === -1 ? rest.length : rest.indexOf(" ")));
+			const is_text = rest.indexOf(" t") !== -1;
+			const node = is_text ? fix_text(mark) : mark.nextSibling;
+			if (!is_text) mark.remove();
+			if (node) children.push({
+				i,
+				node
+			});
+		}
+		children.sort((a, b) => a.i - b.i);
+		const mine = new Set(children.map((c) => c.node));
+		for (const n of Array.from(host.childNodes)) if (!mine.has(n)) shadow.appendChild(n);
+		const made = W.__og_rendered ??= /* @__PURE__ */ new WeakSet();
+		for (const c of children) {
+			host.appendChild(c.node);
+			made.add(c.node);
+		}
+		for (const c of children) if (c.node.nodeType === 1) {
+			const el = c.node;
+			reset(el);
+			el.removeAttribute("og-c");
+		}
+		for (const mark of comments(host, `og-t ${tag}`)) fix_text(mark);
+		reset(host);
+		host.removeAttribute("og-h");
+		host.removeAttribute("og-shadow");
+		host.removeAttribute("og-keep");
+		verify(host, k);
+		restored++;
+	}
+	return restored;
+}
+/** Adopt the sheets of roots restored outside the page, now that their hosts are in it (after a hole
+*  answer's insertion or a router swap, in the same task: no paint in between). Each root is one of
+*  three: IN THE PAGE (adopted now); in a fragment not inserted yet (another hole's answer still
+*  waiting for its stylesheet: kept for the call after its insertion); or in ANOTHER DOCUMENT — the
+*  incoming page's parsed copy, where the swap left what it did not take (a morph kept the live
+*  host): dropped. That last one counts as connected (its document is its root), and adopting a page
+*  sheet into it throws — which stopped every root after it from getting its sheets. A fragment root
+*  still out after 30 s never goes in (a morph took a copy of it, the hole left): dropped. */
+function restore_adopt() {
+	const W = window;
+	const now = performance.now();
+	const waiting = (root) => now - (root.__og_out ??= now) < 3e4;
+	const where = (root) => root.host.isConnected ? root.host.ownerDocument === document ? "page" : "gone" : waiting(root) ? "later" : "gone";
+	const bare = W.__og_init;
+	if (bare?.length) {
+		const left = [];
+		const ce = customElements;
+		for (const root of bare) {
+			const at = where(root);
+			if (at === "later") left.push(root);
+			else if (at === "page" && root.customElementRegistry === null) ce.initialize?.(root);
+		}
+		W.__og_init = left;
+	}
+	const list = W.__og_adopt;
+	if (!list?.length) return;
+	const left = [];
+	for (const item of list) {
+		const at = where(item.shadow);
+		if (at === "later") left.push(item);
+		else if (at === "page") try {
+			item.shadow.adoptedStyleSheets = [...item.shadow.adoptedStyleSheets, ...item.sheets];
+		} catch {}
+	}
+	W.__og_adopt = left;
+}
+export { restore, restore_adopt };

package/dist/runtime/router-nav.d.ts

@@ -0,0 +1,63 @@
+import { SpaRouter } from "./router.js";
+/**
+ * Why a page fetch is happening — sent to the server so it can skip side effects a speculative or
+ * restorative fetch must not fire (analytics beacons, "last seen" writes, one-time banners):
+ *  • `nav`      — a real, user-driven navigation (default). No purpose header.
+ *  • `prefetch` — warmed on hover / press / viewport, BEFORE any intent to visit. Marked so the
+ *                 server can treat it as a dry run (htmx's `HX-Preloaded`).
+ *  • `history`  — a back/forward restore, re-fetched because we snapshot no DOM (htmx's
+ *                 `HX-History-Restore-Request`). The visitor has seen this page already.
+ * The header is advisory: a server that ignores it still renders correctly.
+ */
+export type NavPurpose = "nav" | "prefetch" | "history";
+/** The `Accept` a browser sends for a top-level document navigation (Chromium's value). */
+export declare const DOCUMENT_ACCEPT = "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8";
+/** One attribute's value in an open tag's attribute text (our own SSR: `name="value"`, no quotes
+ *  inside a value). Null when absent. @internal Exported for unit tests. */
+export declare function tag_attr(attrs: string, name: string): string | null;
+/** Stable-ish head node identity without serializing full outerHTML when possible. */
+export declare function head_node_key(node: Element): string;
+/**
+ * Head nodes that must survive SPA swaps even when absent from the next SSR head.
+ * @internal
+ */
+export declare function keep_head_node_across_spa(node: Element): boolean;
+/**
+ * Install a `<style>` into the live document. `cloneNode` from a `DOMParser` tree
+ * often fails to register the sheet; recreate with textContent instead.
+ * @internal
+ */
+export declare function install_head_style(source: Element, head?: HTMLHeadElement, before?: Node | null): HTMLStyleElement;
+/** Apply STREAMED-page late chunks after an SPA body swap: move each inert
+ *  `<template data-og-late>` into its `og-late-slot` (stylesheets hoisted first via the same
+ *  keyed head installer, so the swap never paints unstyled). On a full load the inline boot
+ *  script in the streamed head does this progressively during parse — this is the swap-path
+ *  twin. Islands inside the adopted content are custom elements: they connect and wake alone. */
+export declare function apply_late_templates(root: ParentNode): void;
+export declare function bust_page_cache(): void;
+export declare function page_cache_size(): number;
+export declare function fetch_page(href: string, signal?: AbortSignal, purpose?: NavPurpose): Promise<string | null>;
+export declare function navigate(r: SpaRouter, url: URL, from: URL, { push, pop_scroll, type, replace }?: {
+  push?: boolean;
+  pop_scroll?: {
+    x: number;
+    y: number;
+  } | null;
+  type?: string;
+  replace?: boolean;
+}): Promise<void>;
+/**
+ * Soft invalidate: refresh page/remote seeds for the current URL without navigation.
+ *
+ * Kit's `invalidateAll` re-runs loads in place — it is **not** a navigation (no
+ * `beforeNavigate` / `afterNavigate`). Remote `form()` always calls this on success; a
+ * full SPA navigate+VT here was wiping live island state. We bust the HTML cache,
+ * re-fetch, merge head, and refresh document seeds only — no VT, no body swap, no
+ * island remount, no live query-map clear, no auto-refresh of live queries. Islands
+ * that need query updates use `.refresh()`, or `submit().updates(q)` with server
+ * `requested(q).refreshAll()` (updates alone does not populate response `q`).
+ *
+ * Uses a separate abort/generation from hard `navigate()` so soft fetches never cancel
+ * an in-flight click navigation (and vice versa).
+ */
+export declare function invalidate_all(): Promise<void>;