@ogygia/core 0.0.0 → 0.11.1

package/dist/hydration-info.d.ts

@@ -0,0 +1 @@
+export declare function hydratedBy(): string | null;

package/dist/hydration-info.js

@@ -0,0 +1,31 @@
+// src/hydration-info.ts
+/**
+* `hydratedBy()` — which schedule woke the hydration root this component is mounting under.
+*
+* Call during component SETUP (like `getContext`): the runtime marks the region it is hydrating
+* (the same anchor cross-island context uses), and this reads that region's `hydrate` attribute.
+*
+* Why you'd care: when a visitor's input woke the island, its first event is a REPLAY — real
+* interaction, but not a trusted browser gesture (`event.isTrusted === false`), so gesture-gated APIs
+* (`window.open`, clipboard, fullscreen) will be blocked for it, and a guard that ignores untrusted
+* clicks ignores it. A component that needs those can check `hydratedBy() === 'interaction'` and
+* adapt (e.g. render the popup as a link the SECOND click uses, or skip an entrance animation that
+* assumes a fresh load).
+*
+* Returns:
+* - `'interaction'` when a visitor's input woke it — an `interaction` island, and a scheduled one
+*   pressed before its schedule made it live (its click is replayed too)
+* - else `'load' | 'idle' | 'visible'` or a media-query string — the region's schedule
+* - `null` on the server (SSR pass), and on csr=true pages where Kit (not ogygia) hydrates.
+*
+* A nested island hydrates with its parent, so it reports the PARENT region's schedule — correct:
+* that is the wake that ran its code.
+*/
+const CURRENT_REGION = Symbol.for("ogygia.context.current-region");
+function hydratedBy() {
+	if (typeof window === "undefined") return null;
+	const region = globalThis[CURRENT_REGION];
+	if (!region) return null;
+	return region.getAttribute("data-og-woke") || region.getAttribute("wake") || "load";
+}
+export { hydratedBy };

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { AwaitableRegion, DeferredRegion, DualRegion, InlineRegion, RegionOptions, RegionSchedule, RegionValue, isRegion, region } from "./region.js";
+import { og_derived } from "./store-transport.js";
+import { preload } from "./preload.js";
+import { script } from "./script.js";
+import { requestEvent } from "./request-event.js";
+import { keepFallback } from "./keep-fallback.js";
+import { Preference, PreferenceSpec, preference } from "./preference.js";
+import { TransportCodec } from "./live-transport.js";
+import { __tag_context, createContext, setContext } from "./context-bridge.js";
+import { hydratedBy } from "./hydration-info.js";
+import { isOgygiaPage } from "./context.js";
+import { SharedState } from "./shared-state.js";
+import { getContext } from "svelte";
+import Region from "./Region.svelte";
+import Boundary from "./OgygiaBoundary.svelte";
+import { transport } from "virtual:ogygia/kit-transport";
+import Provide from "./Provide.svelte";
+export type Fallback<P = unknown> = P & {
+  ogygiaFallback?: import("svelte").Snippet;
+};
+export { type AwaitableRegion, Boundary, type DeferredRegion, type DualRegion, type InlineRegion, type Preference, type PreferenceSpec, Provide, Region, type RegionOptions, type RegionSchedule, type RegionValue, SharedState, type TransportCodec, __tag_context, createContext, getContext, hydratedBy, isOgygiaPage, isRegion, keepFallback, og_derived, preference, preload, region, requestEvent, script, setContext, transport };

package/dist/index.js

@@ -0,0 +1,17 @@
+import { isRegion, region } from "./region.js";
+import { og_derived } from "./store-transport.js";
+import { preload } from "./preload.js";
+import { script } from "./script.js";
+import { requestEvent } from "./request-event.js";
+import { keepFallback } from "./keep-fallback.js";
+import { preference } from "./preference.js";
+import { __tag_context, createContext, setContext } from "./context-bridge.js";
+import { hydratedBy } from "./hydration-info.js";
+import { isOgygiaPage } from "./context.js";
+import { SharedState } from "./shared-state.js";
+import { getContext } from "svelte";
+import Region from "./Region.svelte";
+import Boundary from "./OgygiaBoundary.svelte";
+import { transport } from "virtual:ogygia/kit-transport";
+import Provide from "./Provide.svelte";
+export { Boundary, Provide, Region, SharedState, __tag_context, createContext, getContext, hydratedBy, isOgygiaPage, isRegion, keepFallback, og_derived, preference, preload, region, requestEvent, script, setContext, transport };

package/dist/insights/attr-rules.d.ts

@@ -0,0 +1,15 @@
+import { AttrChange } from "../runtime/beacon.js";
+export type Pat = string | {
+  re: string;
+  flags?: string;
+};
+export interface AttrRule {
+  tag?: Pat;
+  name: Pat;
+  value?: Pat;
+}
+/** Split `changes` into those `rules` ignore and those left. */
+export declare function apply_attr_rules(changes: AttrChange[], rules: AttrRule[]): {
+  left: AttrChange[];
+  ignored: AttrChange[];
+};

package/dist/insights/attr-rules.js

@@ -0,0 +1,27 @@
+// src/insights/attr-rules.ts
+function matcher(p) {
+	if (p === void 0) return () => true;
+	if (typeof p === "string") return (s) => s === p;
+	const re = new RegExp(p.re, p.flags);
+	return (s) => s !== null && re.test(s);
+}
+/** Split `changes` into those `rules` ignore and those left. */
+function apply_attr_rules(changes, rules) {
+	if (!rules.length) return {
+		left: changes,
+		ignored: []
+	};
+	const ms = rules.map((r) => ({
+		tag: matcher(r.tag),
+		name: matcher(r.name),
+		value: matcher(r.value)
+	}));
+	const left = [];
+	const ignored = [];
+	for (const c of changes) (ms.some((m) => m.tag(c.tag) && m.name(c.name) && m.value(c.to ?? c.from)) ? ignored : left).push(c);
+	return {
+		left,
+		ignored
+	};
+}
+export { apply_attr_rules };

package/dist/insights/cpu.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The main thread, from the browser's own sampler (the JS Self-Profiling API; runtime/beacon.ts keeps
+ * the trace in the page on a devtools build). Pure: a trace + the islands' hydrate windows in, out:
+ * busy time by kind of code (the app, ogygia, Svelte, packages, a page script, the browser itself),
+ * the functions and files that ran, the CPU inside each island's hydrate window and what it was,
+ * and what ran in long tasks outside any island. The Page tab shows it; the findings quote it.
+ *
+ * The trace's timestamps share `performance.now()`'s clock, so the windows line up with the
+ * beacon's island timings without conversion.
+ */
+export interface SelfProfileTrace {
+  frames: {
+    name?: string;
+    resourceId?: number;
+    line?: number;
+    column?: number;
+  }[];
+  resources: string[];
+  samples: {
+    timestamp: number;
+    stackId?: number;
+  }[];
+  stacks: {
+    frameId: number;
+    parentId?: number;
+  }[];
+}
+export type CodeKind = "app" | "ogygia" | "svelte" | "dependency" | "page script" | "browser" | "devtools";
+export interface CpuFn {
+  name: string;
+  file: string;
+  line: number | null;
+  kind: CodeKind;
+  self_ms: number;
+  total_ms: number;
+}
+export interface CpuSummary {
+  /** sampled span (first to last sample) */
+  window_ms: number;
+  busy_ms: number;
+  by_kind: {
+    kind: CodeKind;
+    ms: number;
+  }[];
+  fns: CpuFn[];
+  files: {
+    file: string;
+    kind: CodeKind;
+    ms: number;
+  }[];
+  /** per island fingerprint: CPU inside its hydrate window and the functions that took it */
+  islands: Record<string, {
+    ms: number;
+    top: CpuFn[];
+  }>;
+  /** long tasks outside every island's hydrate window */
+  outside: {
+    ms: number;
+    top: CpuFn[];
+  };
+  /** the sampling interval seen (ms) */
+  interval_ms: number;
+  /** main-thread ms per other origin (the nearest frame with a script URL decides) */
+  by_host?: Record<string, number>;
+}
+export interface IslandWindow {
+  fp: string;
+  from: number;
+  to: number;
+}
+/** A frame's script, readable: origin, Vite's `/@fs` / `/@id/` prefixes and `?v=` queries off. */
+export declare function clean_file(url: string, page_origin?: string): string;
+/** What kind of code a frame is, from its script URL (and name, for the browser's own). */
+export declare function kind_of(url: string, page_url: string): CodeKind;
+export declare function analyze_cpu(trace: SelfProfileTrace, windows: IslandWindow[], longtasks: {
+  t: number;
+  ms: number;
+}[], page_url: string): CpuSummary;
+/** `name (file:line)` for a finding. */
+export declare function fn_label(f: CpuFn): string;
+/** Is this a trace the analyzer can read. */
+export declare function is_trace(x: unknown): x is SelfProfileTrace;

package/dist/insights/cpu.js

@@ -0,0 +1,177 @@
+// src/insights/cpu.ts
+/** A frame's script, readable: origin, Vite's `/@fs` / `/@id/` prefixes and `?v=` queries off. */
+function clean_file(url, page_origin = "") {
+	let u = url;
+	if (page_origin && u.startsWith(page_origin)) u = u.slice(page_origin.length);
+	const q = u.indexOf("?");
+	if (q !== -1) u = u.slice(0, q);
+	if (u.startsWith("/@fs")) u = u.slice(4);
+	if (u.startsWith("/@id/")) u = u.slice(5);
+	if (u.startsWith("__x00__")) u = u.slice(7);
+	for (const mark of [
+		"/node_modules/.vite/deps/",
+		"/node_modules/",
+		"/packages/",
+		"/src/"
+	]) {
+		const at = u.lastIndexOf(mark);
+		if (at !== -1) return mark === "/src/" ? u.slice(at + 1) : u.slice(at + (mark === "/packages/" ? 10 : mark.length));
+	}
+	return u;
+}
+/** ogygia's own instruments: the devtools dock, the event layer, the analysis engine */
+const OWN_INSTRUMENT_RE = /\/(?:ogygia|@ogygia\/core|packages\/core)\/(?:src|dist)\/(?:devtools|events|insights)\//;
+/** What kind of code a frame is, from its script URL (and name, for the browser's own). */
+function kind_of(url, page_url) {
+	if (!url) return "browser";
+	const path = url.split("?")[0];
+	if (page_url && path === page_url.split("?")[0].split("#")[0]) return "page script";
+	if (path.includes("/.vite/deps/")) return path.slice(path.lastIndexOf("/") + 1).startsWith("svelte") ? "svelte" : "dependency";
+	if (path.includes("/svelte/src/") || path.includes("/node_modules/svelte/")) return "svelte";
+	if (OWN_INSTRUMENT_RE.test(path) || path.endsWith("/runtime/beacon.ts") || path.endsWith("/runtime/beacon.js")) return "devtools";
+	if (path.includes("/packages/ogygia/") || path.includes("/packages/core/") || path.includes("/node_modules/ogygia/") || path.includes("/node_modules/@ogygia/core/") || path.includes("virtual:ogygia")) return "ogygia";
+	if (path.includes("/node_modules/")) return "dependency";
+	if (path.includes("/src/")) return "app";
+	return "dependency";
+}
+const round1 = (n) => Math.round(n * 10) / 10;
+function analyze_cpu(trace, windows, longtasks, page_url) {
+	const { frames, resources, samples, stacks } = trace;
+	const origin = page_url ? new URL(page_url).origin : "";
+	const gaps = [];
+	for (let i = 1; i < samples.length; i++) gaps.push(samples[i].timestamp - samples[i - 1].timestamp);
+	gaps.sort((a, b) => a - b);
+	const interval = gaps.length ? Math.max(1, gaps[gaps.length >> 1]) : 10;
+	const cap = interval * 3;
+	const fn_self = /* @__PURE__ */ new Map();
+	const fn_total = /* @__PURE__ */ new Map();
+	const kind_ms = /* @__PURE__ */ new Map();
+	const file_ms = /* @__PURE__ */ new Map();
+	const host_ms = /* @__PURE__ */ new Map();
+	const page_host = host_of(page_url);
+	const win_self = windows.map(() => /* @__PURE__ */ new Map());
+	const win_ms = windows.map(() => 0);
+	const out_self = /* @__PURE__ */ new Map();
+	let out_ms = 0;
+	let busy = 0;
+	const frame_kind = (fid) => {
+		const f = frames[fid];
+		return kind_of(f?.resourceId !== void 0 ? resources[f.resourceId] ?? "" : "", page_url);
+	};
+	for (let i = 0; i < samples.length; i++) {
+		const s = samples[i];
+		if (s.stackId === void 0) continue;
+		const next = samples[i + 1];
+		const dt = next ? Math.min(cap, Math.max(0, next.timestamp - s.timestamp)) : interval;
+		if (dt <= 0) continue;
+		busy += dt;
+		const leaf = stacks[s.stackId]?.frameId;
+		if (leaf === void 0) continue;
+		fn_self.set(leaf, (fn_self.get(leaf) ?? 0) + dt);
+		const k = frame_kind(leaf);
+		kind_ms.set(k, (kind_ms.get(k) ?? 0) + dt);
+		const lf = frames[leaf];
+		if (lf?.resourceId !== void 0) {
+			const file = clean_file(resources[lf.resourceId] ?? "", origin);
+			const e = file_ms.get(file) ?? {
+				kind: k,
+				ms: 0
+			};
+			e.ms += dt;
+			file_ms.set(file, e);
+		}
+		for (let sid = s.stackId, guard = 0; sid !== void 0 && guard < 512; guard++) {
+			const st = stacks[sid];
+			if (!st) break;
+			const rid = frames[st.frameId]?.resourceId;
+			if (rid !== void 0) {
+				const host = host_of(resources[rid] ?? "");
+				if (host && host !== page_host) host_ms.set(host, (host_ms.get(host) ?? 0) + dt);
+				break;
+			}
+			sid = st.parentId;
+		}
+		const seen = /* @__PURE__ */ new Set();
+		for (let sid = s.stackId, guard = 0; sid !== void 0 && guard < 512; guard++) {
+			const st = stacks[sid];
+			if (!st) break;
+			if (!seen.has(st.frameId)) {
+				seen.add(st.frameId);
+				fn_total.set(st.frameId, (fn_total.get(st.frameId) ?? 0) + dt);
+			}
+			sid = st.parentId;
+		}
+		let hit = false;
+		for (let w = 0; w < windows.length; w++) if (s.timestamp >= windows[w].from && s.timestamp <= windows[w].to) {
+			win_ms[w] += dt;
+			win_self[w].set(leaf, (win_self[w].get(leaf) ?? 0) + dt);
+			hit = true;
+			break;
+		}
+		if (!hit && longtasks.some((t) => s.timestamp >= t.t && s.timestamp <= t.t + t.ms)) {
+			out_ms += dt;
+			out_self.set(leaf, (out_self.get(leaf) ?? 0) + dt);
+		}
+	}
+	const fn_of = (fid, self, total) => {
+		const f = frames[fid] ?? {};
+		const url = f.resourceId !== void 0 ? resources[f.resourceId] ?? "" : "";
+		const path = url.split("?")[0];
+		const stem = path.endsWith(".svelte") ? path.slice(path.lastIndexOf("/") + 1, -7) : "";
+		return {
+			name: f.name || stem || (url ? "(anonymous)" : "(browser)"),
+			file: url ? clean_file(url, origin) : "",
+			line: typeof f.line === "number" ? f.line : null,
+			kind: frame_kind(fid),
+			self_ms: round1(self),
+			total_ms: round1(total)
+		};
+	};
+	const top = (m, n) => [...m].sort((a, b) => b[1] - a[1]).slice(0, n).map(([fid, ms]) => fn_of(fid, ms, fn_total.get(fid) ?? ms));
+	const islands = {};
+	windows.forEach((w, i) => {
+		if (win_ms[i] > 0) islands[w.fp] = {
+			ms: round1(win_ms[i]),
+			top: top(win_self[i], 3)
+		};
+	});
+	return {
+		window_ms: samples.length ? round1(samples[samples.length - 1].timestamp - samples[0].timestamp) : 0,
+		busy_ms: round1(busy),
+		by_kind: [...kind_ms].map(([kind, ms]) => ({
+			kind,
+			ms: round1(ms)
+		})).sort((a, b) => b.ms - a.ms),
+		fns: top(new Map([...fn_self].filter(([fid]) => frame_kind(fid) !== "devtools")), 25),
+		files: [...file_ms].map(([file, e]) => ({
+			file,
+			kind: e.kind,
+			ms: round1(e.ms)
+		})).sort((a, b) => b.ms - a.ms).slice(0, 15),
+		islands,
+		outside: {
+			ms: round1(out_ms),
+			top: top(out_self, 3)
+		},
+		interval_ms: round1(interval),
+		by_host: Object.fromEntries([...host_ms].map(([h, ms]) => [h, round1(ms)]))
+	};
+}
+function host_of(url) {
+	try {
+		return url ? new URL(url).host : "";
+	} catch {
+		return "";
+	}
+}
+/** `name (file:line)` for a finding. */
+function fn_label(f) {
+	const where = f.file ? ` (${f.file.slice(f.file.lastIndexOf("/") + 1)}${f.line !== null ? `:${f.line}` : ""})` : "";
+	return `${f.name}${where}`;
+}
+/** Is this a trace the analyzer can read. */
+function is_trace(x) {
+	const t = x;
+	return !!t && Array.isArray(t.frames) && Array.isArray(t.samples) && Array.isArray(t.stacks) && Array.isArray(t.resources);
+}
+export { analyze_cpu, clean_file, fn_label, is_trace, kind_of };

package/dist/insights/fp-drift.d.ts

@@ -0,0 +1,28 @@
+export interface FpDrift {
+  entry: string;
+  fp_was: string;
+  fp_now: string;
+  /** the first differing path in the props (`stamp`, `items[2].id`), when the props parse */
+  path?: string;
+  /** the values there, clipped (or the text around the first difference) */
+  was?: string;
+  now?: string;
+}
+/** One island as one load (or render) had it. */
+export interface KeptIsland {
+  entry: string;
+  fp: string;
+  props?: string;
+}
+type Kept = KeptIsland;
+/** Islands matched by entry and their place among its copies; a moved fingerprint, explained. */
+export declare function compare(was: Kept[], now: Kept[]): FpDrift[];
+/** Where two props texts differ: the first differing path when both parse as JSON, else the text
+ *  around the first differing character — ogygia's own ids (a store's, a class instance's: random
+ *  per render by design) left out. `null` when those ids are all that differs. */
+export declare function props_diff(a: string, b: string): {
+  path?: string;
+  was?: string;
+  now?: string;
+} | null;
+export {};

package/dist/insights/fp-drift.js

@@ -0,0 +1,148 @@
+import { unflatten } from "devalue";
+// src/insights/fp-drift.ts
+/**
+* ISLANDS WHOSE FINGERPRINT MOVES BETWEEN TWO LOADS OF THE SAME PAGE. An island's `data-og-fp` is
+* the hash of its props: what the router compares to keep a live island across a navigation, and
+* part of the page's bytes (a host's post-render cache, a postrender store, an ETag key on them). A prop
+* made fresh on every render — a time, a random id — moves it every time, so the island is patched on
+* every navigation and every such cache misses. ogygia's own ids are stable now; this finds the
+* app's.
+*
+* Per tab (sessionStorage): each page's islands as last loaded — entry, fingerprint, props text.
+* On the next load of the same page (or an in-app navigation back to it), each island is matched by
+* its entry and its place among copies of it; a moved fingerprint is named with the prop that
+* differs (the first differing path on the JSON lane, else the first differing text).
+*
+* PURE (no DOM): the devtools record each load (page.ts `fp_drift`), the profiler compares its own
+* renders of a page (report.ts) — one comparison, one rule.
+*/
+/** Islands matched by entry and their place among its copies; a moved fingerprint, explained. */
+function compare(was, now) {
+	const nth = (list) => {
+		const seen = /* @__PURE__ */ new Map();
+		return list.map((k) => {
+			const n = seen.get(k.entry) ?? 0;
+			seen.set(k.entry, n + 1);
+			return `${k.entry}#${n}`;
+		});
+	};
+	const before = new Map(nth(was).map((key, i) => [key, was[i]]));
+	const out = [];
+	const keys = nth(now);
+	for (let i = 0; i < now.length; i++) {
+		const a = before.get(keys[i]);
+		const b = now[i];
+		if (!a || a.fp === b.fp) continue;
+		if (a.props !== void 0 && b.props !== void 0) {
+			const d = props_diff(a.props, b.props);
+			if (!d) continue;
+			out.push({
+				entry: b.entry,
+				fp_was: a.fp,
+				fp_now: b.fp,
+				...d
+			});
+		} else out.push({
+			entry: b.entry,
+			fp_was: a.fp,
+			fp_now: b.fp
+		});
+	}
+	return out;
+}
+/** Where two props texts differ: the first differing path when both parse as JSON, else the text
+*  around the first differing character — ogygia's own ids (a store's, a class instance's: random
+*  per render by design) left out. `null` when those ids are all that differs. */
+function props_diff(a, b) {
+	if (a === b) return null;
+	try {
+		return first_path(revive(JSON.parse(a)), revive(JSON.parse(b)), "");
+	} catch {}
+	const ma = mask_ids(a);
+	const mb = mask_ids(b);
+	if (ma === mb) return null;
+	let i = 0;
+	while (i < ma.length && i < mb.length && ma.charCodeAt(i) === mb.charCodeAt(i)) i++;
+	const from = Math.max(0, i - 20);
+	return {
+		was: ma.slice(from, i + 40),
+		now: mb.slice(from, i + 40)
+	};
+}
+/**
+* The props as values, for naming a path. Props are an object, so a parsed ARRAY is the devalue
+* lane's flat table — `[7]` would name a slot, not a prop: unflattened back into the props, every
+* custom type (a transportable, a ref) kept as `{ "<type>": value }` (any reviver, so none throws).
+*/
+function revive(parsed) {
+	return Array.isArray(parsed) ? unflatten(parsed, ANY_REVIVER) : parsed;
+}
+const keep_typed = (type) => (value) => ({ [`<${type}>`]: value });
+/** A revivers table that has every type (devalue asks `Object.hasOwn`, then calls it). */
+const ANY_REVIVER = new Proxy({}, {
+	getOwnPropertyDescriptor: (_, k) => ({
+		value: keep_typed(String(k)),
+		configurable: true,
+		enumerable: true,
+		writable: false
+	}),
+	get: (_, k) => keep_typed(String(k))
+});
+/** ogygia's mint id: a UUID (`8-4-4-4-12` hex). */
+function is_mint_id(v) {
+	if (typeof v !== "string" || v.length !== 36) return false;
+	for (let i = 0; i < 36; i++) {
+		const c = v.charCodeAt(i);
+		if (i === 8 || i === 13 || i === 18 || i === 23) {
+			if (c !== 45) return false;
+		} else if (!(c >= 48 && c <= 57 || c >= 97 && c <= 102)) return false;
+	}
+	return true;
+}
+/** The text with every UUID replaced by a fixed one (for the non-JSON compare). */
+function mask_ids(s) {
+	let out = "";
+	let last = 0;
+	for (let i = 0; i + 36 <= s.length; i++) {
+		if (s.charCodeAt(i + 8) !== 45 || !is_mint_id(s.slice(i, i + 36))) continue;
+		out += s.slice(last, i) + "<id>";
+		last = i + 36;
+		i += 35;
+	}
+	return last === 0 ? s : out + s.slice(last);
+}
+function first_path(a, b, path) {
+	if (a === b) return null;
+	if (is_mint_id(a) && is_mint_id(b)) return null;
+	const clip = (v) => {
+		const s = JSON.stringify(v) ?? String(v);
+		return s.length > 60 ? s.slice(0, 60) + "…" : s;
+	};
+	if (a && b && typeof a === "object" && typeof b === "object" && Array.isArray(a) === Array.isArray(b)) {
+		if (Array.isArray(a)) {
+			const bb = b;
+			for (let i = 0; i < Math.max(a.length, bb.length); i++) {
+				const d = first_path(a[i], bb[i], `${path}[${i}]`);
+				if (d) return d;
+			}
+			return null;
+		}
+		const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+		for (const k of keys) {
+			const d = first_path(a[k], b[k], path ? `${path}.${k}` : k);
+			if (d) return d;
+		}
+		return null;
+	}
+	return {
+		path: tidy_path(path) || "(the props)",
+		was: clip(a),
+		now: clip(b)
+	};
+}
+/** A path as the author wrote the props: ogygia's own ref wrapper (a store, a shared class — the
+*  value inside it is `.d`) left out, so `cart.<OgygiaRef>.d.serverStamp` reads `cart.serverStamp`. */
+function tidy_path(path) {
+	return path.split(".<OgygiaRef>.d").join("").split(".<OgygiaRef>").join("");
+}
+export { compare, props_diff };

package/dist/insights/hole-segments.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A HOLE'S ANSWER, CUT INTO ITS PARTS — the one cut the devtools Page tab's waterfall and the
+ * profiler report's One clock both draw. Where the browser (Resource Timing) and the server
+ * (Server-Timing `og-queue`, `og-render`) timed it: before its request left (a busy page, the
+ * runtime's queue), the server's wait for a render slot, the server render (or, untimed, the wait
+ * for the first byte), then the rest (network, the body, the swap). Page times, ms.
+ */
+export interface HoleTimes {
+  /** when its fallback began to count (the first paint, or the hole's own start) */
+  shown_at?: number;
+  /** how long its fallback stood: from `shown_at` to the swap */
+  wait_ms: number;
+  left_at?: number;
+  first_at?: number;
+  server_queue_ms?: number;
+  server_ms?: number;
+}
+export type HoleSegKind = "wait" | "before" | "slot" | "render" | "server" | "rest";
+export declare const HOLE_SEG_LABEL: Record<HoleSegKind, string>;
+/** The segments, in order. Without a timing, one: the wait. A request the document preloaded
+ *  starts before the fallback counts: its segments start where it left. */
+export declare function hole_segments(h: HoleTimes): {
+  k: HoleSegKind;
+  a: number;
+  b: number;
+}[];

package/dist/insights/hole-segments.js

@@ -0,0 +1,50 @@
+// src/insights/hole-segments.ts
+const HOLE_SEG_LABEL = {
+	wait: "waiting for its answer",
+	before: "before its request left",
+	slot: "waiting for a render slot on the server",
+	render: "the server render",
+	server: "waiting on the server",
+	rest: "network, the body and the swap"
+};
+/** The segments, in order. Without a timing, one: the wait. A request the document preloaded
+*  starts before the fallback counts: its segments start where it left. */
+function hole_segments(h) {
+	const shown = h.shown_at ?? 0;
+	const at = shown + h.wait_ms;
+	if (h.left_at === void 0) return [{
+		k: "wait",
+		a: shown,
+		b: at
+	}];
+	const out = [];
+	const left = h.left_at;
+	if (left > shown) out.push({
+		k: "before",
+		a: shown,
+		b: left
+	});
+	let t = left;
+	if (h.server_queue_ms) out.push({
+		k: "slot",
+		a: t,
+		b: t += h.server_queue_ms
+	});
+	if (h.server_ms !== void 0) out.push({
+		k: "render",
+		a: t,
+		b: t += h.server_ms
+	});
+	else if (h.first_at !== void 0) out.push({
+		k: "server",
+		a: t,
+		b: t = h.first_at
+	});
+	if (at > t) out.push({
+		k: "rest",
+		a: t,
+		b: at
+	});
+	return out;
+}
+export { HOLE_SEG_LABEL, hole_segments };

package/dist/insights/html-diff.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A readable diff of two HTML strings — the server's markup and what the browser ended up with —
+ * for the Hydration tab. HTML is cut into tokens (a tag, or the text between tags; comments dropped,
+ * whitespace runs folded), the token lists are diffed (Myers, O(ND)), and the result is grouped into
+ * hunks with a little context. No regex. A diff too large to compute (edit distance past `max_d`)
+ * falls back to the first difference.
+ */
+export type DiffOp = {
+  op: "same" | "del" | "add";
+  text: string;
+};
+export interface DiffHunk {
+  ops: DiffOp[];
+}
+export interface HtmlDiff {
+  hunks: DiffHunk[];
+  /** tokens removed / added */
+  removed: number;
+  added: number;
+  /** the diff gave up (too many changes) and shows only where they start */
+  partial: boolean;
+}
+/** Tags and text runs; comments out; whitespace inside text folded to one space. */
+export declare function tokenize(html: string): string[];
+export declare function html_diff(server: string, browser: string, context?: number, max_d?: number): HtmlDiff;