@ogygia/core 0.0.0 → 0.11.1

package/dist/server/split-regions.js

@@ -0,0 +1,368 @@
+import { escape_amp_quot } from "../escape.js";
+import { is_space as is_space$1 } from "./html-scan.js";
+// src/server/split-regions.ts
+/**
+* REGIONS in the SSR HTML, for an app that runs a THIRD-PARTY SSR/hydration pass over the final
+* document (a web-component server-render, a translation proxy, an A/B injector). The one
+* integration rule such a pass must honour: **never reshape the bytes inside an island.** An island
+* hydrates against its exact server markup; a reshaped node sequence makes the hydration walk
+* mismatch, so the island discards its server DOM and re-renders client-side, and the first
+* interaction lands on the discarded tree (the classic tell: a dropdown that needs two clicks).
+* Lakes and holes are NOT hydrated — their bytes are safe to touch.
+*
+* Apps that hand-rolled this with a regex balance-count (`<ogygia-region>` opens vs closes) get
+* fooled by tag-like TEXT: a literal `<ogygia-region>` inside a CSS comment in an inlined `<style>`,
+* or an HTML comment, or an attribute value, throws the count off, the island skip silently stops
+* applying, and the pass reshapes island bytes — in dev but not in prod (where the comment minifies
+* away), so it passes every local test and breaks on the deploy.
+*
+* `scanRegions(html)` is a generator, not a regex: it tracks REAL element nesting of `<ogygia-region>`
+* and skips `<!-- … -->`, the raw-text bodies of `<script>` / `<style>`, and quoted attribute
+* values, so tag-like text in any of those is never counted. Each region is yielded once, a region
+* AFTER the regions nested inside it (post-order, by closing-tag position). An island's own span is
+* yielded — including an island nested inside a lake or hole, the header-lake login island being
+* exactly that case, so the caller can protect it — but the regions STRICTLY INSIDE an island are
+* not, because a reshape anywhere in an island's subtree breaks the same hydration walk.
+*
+* The pattern this is built for, robust at any nesting depth: protect every island's bytes, edit
+* everything else.
+*
+* ```ts
+* import { scanRegions } from 'ogygia/server';
+* const protect = [];
+* for (const r of scanRegions(html)) {
+*   if (r.kind === 'island') protect.push([r.start, r.end]); // its bytes stay verbatim
+* }
+* // reshape `html` everywhere EXCEPT the protected ranges …
+* ```
+*
+* If you edit by offset instead, splice in reverse `start` order so earlier offsets stay valid:
+* `[...scanRegions(html)].sort((a, b) => b.start - a.start)`.
+*
+* Malformed input never throws and never loses a region: an unterminated `<ogygia-region>` (no
+* matching close) is still yielded, with `innerStart === innerEnd` and `end` at the `>` of its
+* opening tag — i.e. its span is just the opening tag. A caller reshaping `[innerStart, innerEnd)`
+* of such a region edits nothing, which is the safe outcome.
+*
+* For the FULL round-trip — lift the regions out, run the foreign renderer over what is left, splice
+* them back — use {@link liftRegions} / {@link restoreRegions} (below). Restore transplants the marks
+* a scoped renderer stamps on the placeholder onto the region, unions `class`, and touches only
+* attributes, never light DOM. All three are also exported, Kit-free, from `ogygia/markup`, for the
+* non-SvelteKit half of a monorepo where these SSR passes usually live.
+*/
+const REGION_TAG = "ogygia-region";
+const RAW_TEXT_TAGS = ["script", "style"];
+/** ASCII whitespace that can follow a tag name. */
+function is_space(code) {
+	return code === 32 || code === 9 || code === 10 || code === 12 || code === 13;
+}
+/** ASCII letter — what a real tag name begins with (`<a…` / `</a…`). A `<` followed by anything
+*  else (space, digit, `=`) is text, not a tag, per the HTML tokenizer. */
+function is_ascii_alpha(code) {
+	return code >= 65 && code <= 90 || code >= 97 && code <= 122;
+}
+/** True when `tag`'s NAME sits at `name` as a real element name (followed by whitespace, `>`, or
+*  `/`), case-insensitive — so `ogygia-region-foo` or `styles` don't match a shorter tag. Callers
+*  pass the index of the tag name: for `<tag` that is `i + 1`, for `</tag` it is `i + 2`. */
+function name_at(html, name, tag) {
+	for (let k = 0; k < tag.length; k++) {
+		const c = html.charCodeAt(name + k);
+		if ((c >= 65 && c <= 90 ? c + 32 : c) !== tag.charCodeAt(k)) return false;
+	}
+	const after = html.charCodeAt(name + tag.length);
+	return Number.isNaN(after) || is_space(after) || after === 62 || after === 47;
+}
+/** True when an OPENING tag `<tag…` starts at `i`. */
+function open_tag_at(html, i, tag) {
+	return html.charCodeAt(i) === 60 && name_at(html, i + 1, tag);
+}
+/** True when a CLOSING tag `</tag…` starts at `i`. */
+function close_tag_at(html, i, tag) {
+	return html.charCodeAt(i) === 60 && html.charCodeAt(i + 1) === 47 && name_at(html, i + 2, tag);
+}
+/** Index of the `>` that ends the tag whose `<` is at `open`, respecting `"…"` / `'…'` attribute
+*  values (a `>` inside a value does not end the tag). `html.length` if the tag is unterminated. */
+function tag_end(html, open) {
+	let quote = 0;
+	for (let i = open + 1; i < html.length; i++) {
+		const c = html.charCodeAt(i);
+		if (quote) {
+			if (c === quote) quote = 0;
+		} else if (c === 34 || c === 39) quote = c;
+		else if (c === 62) return i;
+	}
+	return html.length;
+}
+/** Index of the `<` of the closing `</style>` / `<\/script>` at or after `from`, or -1. Allocation
+*  free: a native `indexOf('<')` scan (SIMD-fast in V8) plus a bounded tag check — never a substring
+*  copy or a per-call RegExp (this runs once per raw-text element on every SSR response, some of
+*  them megabytes). */
+function raw_text_end(html, from, tag) {
+	let at = from;
+	for (;;) {
+		const lt = html.indexOf("<", at);
+		if (lt === -1) return -1;
+		if (close_tag_at(html, lt, tag)) return lt;
+		at = lt + 1;
+	}
+}
+/** A char that ends an attribute NAME: `\s`, `/`, `>`, `=`. */
+function name_stop(c) {
+	return c === 47 || c === 62 || c === 61 || is_space$1(c);
+}
+/** A char that ends an UNQUOTED value: `\s`, `/`, `>`. */
+function value_stop(c) {
+	return c === 47 || c === 62 || is_space$1(c);
+}
+/**
+* Parse a tag's attribute run (everything between the tag name and its `>`) into a lower-cased map
+* with quotes stripped. Shared by the region opener and the `<og-lift>` placeholder on restore.
+*
+* Hand-written (measured faster, no match arrays) with the rules the pattern
+* `([^\s/>=]+)(?:\s*=\s*("[^"]*"|'[^']*'|[^\s/>]+))?` had, quirks included: a value is a closed
+* `"…"`, else a closed `'…'`, else an unquoted run (which may start with an unclosed quote — then
+* the first and last characters are stripped, as before); `=` with no value leaves the name valueless.
+* @internal Exported for test/regex-replacements.test.ts.
+*/
+function parse_attr_string(inner) {
+	const attrs = {};
+	const n = inner.length;
+	let i = 0;
+	while (i < n) {
+		if (name_stop(inner.charCodeAt(i))) {
+			i++;
+			continue;
+		}
+		const name_start = i;
+		while (i < n && !name_stop(inner.charCodeAt(i))) i++;
+		const name = inner.slice(name_start, i);
+		let value = "";
+		let j = i;
+		while (j < n && is_space$1(inner.charCodeAt(j))) j++;
+		if (inner.charCodeAt(j) === 61) {
+			j++;
+			while (j < n && is_space$1(inner.charCodeAt(j))) j++;
+			const q = inner.charCodeAt(j);
+			let end = -1;
+			if (q === 34 || q === 39) {
+				const close = inner.indexOf(q === 34 ? "\"" : "'", j + 1);
+				if (close !== -1) end = close + 1;
+			}
+			if (end === -1) {
+				let k = j;
+				while (k < n && !value_stop(inner.charCodeAt(k))) k++;
+				if (k > j) end = k;
+			}
+			if (end !== -1) {
+				value = inner.slice(j, end);
+				i = end;
+				const f = value.charCodeAt(0);
+				if (f === 34 || f === 39) value = value.slice(1, -1);
+			}
+		}
+		attrs[name.toLowerCase()] = value;
+	}
+	return attrs;
+}
+/** Parse the attributes out of an opening tag whose `<` is at `open` and `>` at `gt`. */
+function parse_attrs(html, open, gt) {
+	return parse_attr_string(html.slice(open + 1 + 13, gt));
+}
+/** The classification the whole framework agrees on (runtime region-attrs, the compiled tag): a
+*  region with an `endpoint` is a deferred HOLE; `wake="none"` is a frozen LAKE; anything else that
+*  wakes is an ISLAND. Matches `region_hydrate_schedule` / `is_deferred` / `is_frozen`. */
+function classify(attrs) {
+	if ("endpoint" in attrs) return "hole";
+	if (attrs.wake === "none") return "lake";
+	return "island";
+}
+/**
+* Yield every `<ogygia-region>` in `html`, in document order, an island's subtree treated as atomic
+* (its nested regions are not yielded). One linear pass, O(html length); allocates no copy of the
+* document. See the module doc for why this exists and how to use it.
+*/
+function* scanRegions(html) {
+	const stack = [];
+	const n = html.length;
+	let i = 0;
+	while (i < n) {
+		const lt = html.indexOf("<", i);
+		if (lt === -1) break;
+		i = lt;
+		if (html.startsWith("<!--", i)) {
+			const close = html.indexOf("-->", i + 4);
+			i = close === -1 ? n : close + 3;
+			continue;
+		}
+		let raw = null;
+		for (const t of RAW_TEXT_TAGS) if (open_tag_at(html, i, t)) raw = t;
+		if (raw) {
+			const gt = tag_end(html, i);
+			if (html.charCodeAt(gt - 1) === 47) {
+				i = gt + 1;
+				continue;
+			}
+			const close = raw_text_end(html, gt + 1, raw);
+			i = close === -1 ? n : tag_end(html, close) + 1;
+			continue;
+		}
+		if (close_tag_at(html, i, REGION_TAG)) {
+			const gt = tag_end(html, i);
+			const frame = stack.pop();
+			if (frame?.emit) {
+				frame.node.innerEnd = i;
+				frame.node.end = gt + 1;
+				yield frame.node;
+			}
+			i = gt + 1;
+			continue;
+		}
+		if (open_tag_at(html, i, REGION_TAG)) {
+			const gt = tag_end(html, i);
+			const parent_sealed = stack.length > 0 && stack[stack.length - 1].sealed;
+			const attrs = parse_attrs(html, i, gt);
+			const kind = classify(attrs);
+			const self_closing = html.charCodeAt(gt - 1) === 47;
+			const emit = !parent_sealed;
+			const sealed = parent_sealed || kind === "island";
+			const node = {
+				kind,
+				start: i,
+				end: gt + 1,
+				innerStart: gt + 1,
+				innerEnd: gt + 1,
+				attrs,
+				depth: stack.length
+			};
+			if (self_closing) {
+				if (emit) yield node;
+			} else stack.push({
+				node,
+				emit,
+				sealed
+			});
+			i = gt + 1;
+			continue;
+		}
+		const c1 = html.charCodeAt(i + 1);
+		i = is_ascii_alpha(c1) || c1 === 47 && is_ascii_alpha(html.charCodeAt(i + 2)) ? tag_end(html, i) + 1 : i + 1;
+	}
+	while (stack.length) {
+		const frame = stack.pop();
+		if (frame.emit) yield frame.node;
+	}
+}
+const LIFT_TAG = "og-lift";
+const LIFT_PLACEHOLDER_RE = /<og-lift\b([^>]*)>(?:<\/og-lift>)?/gi;
+const WS_SPLIT_RE = /\s+/;
+const CLASS_ATTR_RE = /(\sclass\s*=\s*)("[^"]*"|'[^']*'|[^\s/>]+)/i;
+const TRAILING_SELF_CLOSE_RE = /\s*\/\s*$/;
+const TRAILING_WS_RE = /\s+$/;
+function make_region(kind, attrs, openTag, innerHtml, closeTag, index) {
+	return {
+		kind,
+		attrs,
+		openTag,
+		innerHtml,
+		closeTag,
+		outerHtml: openTag + innerHtml + closeTag,
+		index,
+		withInner(next) {
+			return make_region(kind, attrs, openTag, next, closeTag, index);
+		}
+	};
+}
+/**
+* Lift every TOP-LEVEL `<ogygia-region>` out of `html`, leaving an `<og-lift>` placeholder where each
+* was. Hand `shell` to the foreign renderer (and, to render a lake / hole, its `innerHtml` — recurse
+* with `liftRegions` there so islands nested inside it stay protected), then {@link restoreRegions}.
+* Islands come back verbatim. A region deeper than top level rides inside its parent's `outerHtml`.
+*/
+function liftRegions(html) {
+	const regions = [];
+	if (!html.includes(`<${REGION_TAG}`)) return {
+		shell: html,
+		regions
+	};
+	let shell = "";
+	let cursor = 0;
+	for (const span of scanRegions(html)) {
+		if (span.depth !== 0) continue;
+		const openTag = html.slice(span.start, span.innerStart);
+		const innerHtml = html.slice(span.innerStart, span.innerEnd);
+		const closeTag = html.slice(span.innerEnd, span.end);
+		const index = regions.length;
+		shell += html.slice(cursor, span.start) + `<${LIFT_TAG} data-i="${index}"></${LIFT_TAG}>`;
+		regions.push(make_region(span.kind, span.attrs, openTag, innerHtml, closeTag, index));
+		cursor = span.end;
+	}
+	if (regions.length === 0) return {
+		shell: html,
+		regions
+	};
+	return {
+		shell: shell + html.slice(cursor),
+		regions
+	};
+}
+/** Escape a value for re-emission inside a double-quoted attribute. */
+function escape_attr(value) {
+	return escape_amp_quot(value);
+}
+/** Merge the renderer's `class` marks into the region's opening-tag head, unioning tokens with any
+*  class the region already carries. Returns the head unchanged when nothing new is added. */
+function merge_class(head, existing, added) {
+	const added_tokens = added.split(WS_SPLIT_RE).filter(Boolean);
+	if (added_tokens.length === 0) return [head, false];
+	if (existing === void 0) return [`${head} class="${escape_attr(added)}"`, true];
+	const have = new Set(existing.split(WS_SPLIT_RE).filter(Boolean));
+	let changed = false;
+	for (const token of added_tokens) if (!have.has(token)) {
+		have.add(token);
+		changed = true;
+	}
+	if (!changed) return [head, false];
+	const merged = [...have].join(" ");
+	return [head.replace(CLASS_ATTR_RE, (_m, prefix) => `${prefix}"${escape_attr(merged)}"`), true];
+}
+/** Transplant a placeholder's renderer-stamped marks onto the region's opening tag. Only marks the
+*  region does not already own are added; `class` is unioned; the region's light DOM is untouched. */
+function merge_marks(region, marks) {
+	const gt = region.openTag.lastIndexOf(">");
+	if (gt === -1) return region.outerHtml;
+	let head = region.openTag.slice(0, gt).replace(TRAILING_SELF_CLOSE_RE, "").replace(TRAILING_WS_RE, "");
+	const additions = [];
+	let changed = false;
+	for (const name in marks) {
+		if (name === "data-i") continue;
+		if (name === "class") {
+			const [next, did] = merge_class(head, region.attrs.class, marks.class);
+			head = next;
+			changed ||= did;
+			continue;
+		}
+		if (name in region.attrs) continue;
+		additions.push(`${name}="${escape_attr(marks[name])}"`);
+		changed = true;
+	}
+	if (!changed) return region.outerHtml;
+	return (additions.length ? `${head} ${additions.join(" ")}>` : `${head}>`) + region.innerHtml + region.closeTag;
+}
+/**
+* Splice lifted regions back over their `<og-lift>` placeholders, transplanting any attributes the
+* foreign renderer stamped on a placeholder (scoped slot marks — a `sc-*` class, `c-id`, `s-sn`)
+* onto the region's opening tag. The placeholder is matched loosely because the renderer annotates
+* it; only opening-tag attributes are merged, never the region's light DOM. An unknown placeholder
+* is left in place rather than dropped.
+*/
+function restoreRegions(shell, regions) {
+	if (regions.length === 0) return shell;
+	const by_index = new Map(regions.map((r) => [r.index, r]));
+	LIFT_PLACEHOLDER_RE.lastIndex = 0;
+	return shell.replace(LIFT_PLACEHOLDER_RE, (whole, raw) => {
+		const marks = parse_attr_string(raw);
+		const region = by_index.get(Number(marks["data-i"]));
+		return region === void 0 ? whole : merge_marks(region, marks);
+	});
+}
+export { liftRegions, parse_attr_string, restoreRegions, scanRegions };

package/dist/server/stream-regions.d.ts

@@ -0,0 +1,5 @@
+/** Build a parcel `<template data-ogygia-slot="…">…rendered html…</template>` (length-framed when
+ *  the html carries a `</template` of its own). */
+export declare function build_parcel(slot: string, html: string): string;
+/** The done-sentinel parcel (empty template) the client watches to end the batch. */
+export declare function done_parcel(): string;

package/dist/server/stream-regions.js

@@ -0,0 +1,36 @@
+// src/server/stream-regions.ts
+/**
+* Region parcels for the batch endpoint (single-flight navigation, a page's first-load holes, OOO).
+* Each rendered region call is boxed as a `<template data-ogygia-slot>` parcel keyed by its capability
+* signature; the client frame stream reads them out of order and drops each into the matching region.
+* A done-sentinel ends the batch.
+*
+* The client reads a parcel as TEXT (runtime/frame-nav.ts), never as DOM. A plain parcel ends at the
+* first `</template>`; an answer that itself carries `</template` (a web component's declarative
+* shadow root) is LENGTH-FRAMED instead — `data-og-len` is its UTF-16 length, the unit the client's
+* decoded string counts in — so its content can never close the box or forge a parcel for another
+* slot, and it no longer falls back to a second request.
+*
+* Pure (no I/O, no Kit) so it stays unit-testable.
+*/
+/** Sentinel slot appended once a batch finishes, so waiting regions know it is complete. */
+const STREAM_DONE_SLOT = "__ogygia_done__";
+/** Does `html` carry a `</template` (any case) — one that would close a plain parcel early? */
+function has_template_close(html) {
+	for (let i = html.indexOf("</"); i !== -1; i = html.indexOf("</", i + 2)) {
+		if (html.length - i < 10) return false;
+		if (html.slice(i + 2, i + 10).toLowerCase() === "template") return true;
+	}
+	return false;
+}
+/** Build a parcel `<template data-ogygia-slot="…">…rendered html…</template>` (length-framed when
+*  the html carries a `</template` of its own). */
+function build_parcel(slot, html) {
+	if (has_template_close(html)) return `<template data-ogygia-slot="${slot}" data-og-len="${html.length}">${html}</template>`;
+	return `<template data-ogygia-slot="${slot}">${html}</template>`;
+}
+/** The done-sentinel parcel (empty template) the client watches to end the batch. */
+function done_parcel() {
+	return `<template data-ogygia-slot="${STREAM_DONE_SLOT}"></template>`;
+}
+export { build_parcel, done_parcel };

package/dist/shared-state.d.ts

@@ -0,0 +1,7 @@
+export declare class SharedState<T extends object> {
+  #private;
+  constructor(name: string, initial: T);
+  /** The value — reactive wherever Svelte is watching, plain everywhere else. */
+  get current(): T;
+  set current(v: T);
+}

package/dist/shared-state.js

@@ -0,0 +1,152 @@
+import { parse, stringify } from "devalue";
+import { createSubscriber } from "svelte/reactivity";
+// src/shared-state.ts
+/**
+* EXPERIMENTAL — cross-fragment shared state: the Svelte-native cross-BUILD primitive.
+*
+* `new SharedState(name, initial)` in a tiny CONTRACT package every team depends on; each build
+* compiles its own copy of the class, but all copies meet at ONE page-global store keyed by
+* `Symbol.for` (same key in every realm/build). Reads are `.current` (the Svelte convention —
+* MediaQuery/Spring), reactive via `createSubscriber`; nested writes (`cart.current.items.push`)
+* publish through a mutation proxy. No subscriptions, no callbacks, no server involved: one
+* page, one value, every island of every team re-renders on write.
+*
+* Cross-language: any server can SEED the opening value by printing
+* `<script type="application/json" data-og-shared="<name>">{…}<\/script>`, and any vanilla JS on
+* the page can join via `globalThis.ogygia.shared(name)` → { get, set, subscribe }.
+*/
+const STORE_KEY = Symbol.for("ogygia.shared.v1");
+function page_store() {
+	const g = globalThis;
+	if (!g[STORE_KEY]) g[STORE_KEY] = {
+		map: /* @__PURE__ */ new Map(),
+		target: new EventTarget()
+	};
+	return g[STORE_KEY];
+}
+/** Read a server-printed seed: `<script type="application/json" data-og-shared="<name>">`. */
+function read_seed(name) {
+	if (typeof document === "undefined") return void 0;
+	const el = document.querySelector(`script[type="application/json"][data-og-shared=${JSON.stringify(name)}]`);
+	if (!el?.textContent) return void 0;
+	try {
+		return JSON.parse(el.textContent);
+	} catch {
+		return;
+	}
+}
+/** THE MEMBRANE: only inert data enters the page store — the two builds' svelte runtimes must
+*  never see each other's live values. A devalue ROUND-TRIP is the membrane on purpose:
+*  devalue-representable is ogygia's definition of "can cross a boundary" (props sidecars, page
+*  seeds, transport — one vocabulary), so a value that passes here is also seedable/serializable
+*  everywhere else. A reactive proxy degrades to a plain snapshot (safe — and what you meant);
+*  functions, class instances, and DOM nodes THROW here, loudly, at the write site — with
+*  devalue's path detail — never weirdly at a distance inside another team's render. */
+function snapshot(name, value) {
+	try {
+		return parse(stringify(value));
+	} catch (e) {
+		throw new Error(`[ogygia] SharedState '${name}': values must be plain data (devalue-serializable — JSON, Date, Map, Set, BigInt, RegExp). Functions, class instances, and DOM nodes do not cross build boundaries — share facts, not live objects. (${e instanceof Error ? e.message : e})`);
+	}
+}
+var SharedState = class {
+	#name;
+	#subscribe;
+	#publish_queued = false;
+	constructor(name, initial) {
+		this.#name = name;
+		const store = page_store();
+		if (!store.map.has(name)) {
+			const seed = read_seed(name);
+			store.map.set(name, {
+				value: seed !== void 0 ? seed : snapshot(name, initial),
+				version: 0
+			});
+		}
+		this.#subscribe = createSubscriber((update) => {
+			const on = (e) => {
+				if (e.detail === name) update();
+			};
+			store.target.addEventListener("og:shared", on);
+			return () => store.target.removeEventListener("og:shared", on);
+		});
+	}
+	#publish() {
+		if (this.#publish_queued) return;
+		this.#publish_queued = true;
+		queueMicrotask(() => {
+			this.#publish_queued = false;
+			const store = page_store();
+			const entry = store.map.get(this.#name);
+			entry.version++;
+			store.target.dispatchEvent(new CustomEvent("og:shared", { detail: this.#name }));
+		});
+	}
+	/** Deep mutation proxy: any nested write publishes. Functions pass through raw (their `this`
+	*  is the proxy, so array methods still trip the set traps). */
+	#proxy(value) {
+		if (value === null || typeof value !== "object") return value;
+		const publish = () => this.#publish();
+		const wrap = this.#proxy.bind(this);
+		if (value instanceof Map || value instanceof Set || value instanceof Date || value instanceof RegExp) return new Proxy(value, { get: (t, p) => {
+			const v = Reflect.get(t, p);
+			if (typeof v !== "function") return v;
+			return (...args) => {
+				const r = v.apply(t, args);
+				publish();
+				return r;
+			};
+		} });
+		return new Proxy(value, {
+			get: (t, p) => wrap(Reflect.get(t, p)),
+			set: (t, p, v) => {
+				Reflect.set(t, p, v);
+				publish();
+				return true;
+			},
+			deleteProperty: (t, p) => {
+				Reflect.deleteProperty(t, p);
+				publish();
+				return true;
+			}
+		});
+	}
+	/** The value — reactive wherever Svelte is watching, plain everywhere else. */
+	get current() {
+		this.#subscribe();
+		return this.#proxy(page_store().map.get(this.#name).value);
+	}
+	set current(v) {
+		page_store().map.get(this.#name).value = snapshot(this.#name, v);
+		this.#publish();
+	}
+};
+function vanilla(name) {
+	const store = page_store();
+	if (!store.map.has(name)) store.map.set(name, {
+		value: read_seed(name),
+		version: 0
+	});
+	return {
+		get: () => store.map.get(name).value,
+		set: (v) => {
+			const entry = store.map.get(name);
+			entry.value = snapshot(name, v);
+			entry.version++;
+			store.target.dispatchEvent(new CustomEvent("og:shared", { detail: name }));
+		},
+		subscribe: (fn) => {
+			const on = (e) => {
+				if (e.detail === name) fn(store.map.get(name).value);
+			};
+			store.target.addEventListener("og:shared", on);
+			return () => store.target.removeEventListener("og:shared", on);
+		}
+	};
+}
+if (typeof globalThis !== "undefined") {
+	const g = globalThis;
+	g.ogygia ??= {};
+	g.ogygia.shared ??= vanilla;
+}
+export { SharedState };

package/dist/shims/app-environment.d.ts

@@ -0,0 +1,4 @@
+export declare const browser: boolean;
+export declare const building: boolean;
+export declare const dev: boolean;
+export declare const version = "ogygia";

package/dist/shims/app-environment.js

@@ -0,0 +1,6 @@
+// src/shims/app-environment.ts
+const browser = true;
+const building = false;
+const dev = false;
+const version = "ogygia";
+export { browser, building, dev, version };

package/dist/shims/app-navigation.d.ts

@@ -0,0 +1,33 @@
+import { AfterNavigateCallback, BeforeNavigateCallback } from "../runtime/router.js";
+export declare function goto(url: string | URL, opts?: {
+  replaceState?: boolean;
+  external?: boolean;
+}): Promise<void>;
+export declare function invalidate(resource?: unknown): Promise<void>;
+export declare function invalidateAll(): Promise<void>;
+/**
+ * Kit's `refreshAll` (Kit 2.7x, Kit 3), which Kit 3's remote `form()` also calls after a successful
+ * submit (through the remote client stub). Island queries live in ogygia's remote cache, not Kit's,
+ * so they refresh here on every document; the page's data then refreshes through whoever owns the
+ * document. With neither runtime, the queries alone refresh: never a reload.
+ */
+export declare function refreshAll(): Promise<void>;
+export declare function preloadData(url: string | URL): Promise<unknown>;
+export declare function preloadCode(url?: string): Promise<void>;
+export declare function pushState(url: string | URL, state: unknown): void;
+export declare function replaceState(url: string | URL, state: unknown): void;
+export declare function disableScrollHandling(): void;
+export declare function beforeNavigate(fn: BeforeNavigateCallback): () => void;
+export declare function afterNavigate(fn: AfterNavigateCallback): () => void;
+export declare function onNavigate(fn: (navigation: unknown) => unknown): () => void;
+type SnapshotOptions = {
+  id?: string;
+  capture: () => unknown;
+  restore: (value: never) => void;
+  reset?: () => void;
+};
+export declare function snapshot(options: SnapshotOptions): void;
+/** `ogygia/app`'s `bust_page_cache`: drop the SPA router's warmed page HTML (after mutations / auth
+ *  changes). A no-op without the router — there is no page cache. */
+export declare function bust_page_cache(): void;
+export {};