@ogygia/core 0.0.0 → 0.11.0

package/dist/plugin/utils.d.ts

@@ -0,0 +1,13 @@
+import { fnv1a32 } from "../runtime/hash.js";
+import { escape_amp_quot, escape_text } from "../escape.js";
+import { SizedLru } from "../server/sized-lru.js";
+import { source_tag_of } from "../source.js";
+import { StandardIssue, StandardResult, StandardSchemaV1 } from "./standard-schema.js";
+/**
+ * The stable cross-build key for a markup module's own scoped CSS (a `.svx` body with a `<style>`):
+ * the path from the first `/src/` segment, POSIX (`/…/proj/src/content/docs/x.svx` →
+ * `content/docs/x.svx`). The preprocessor that bakes the key into the module and the build that emits
+ * the CSS and writes the handoff compute it identically from the same absolute filename.
+ */
+export declare function content_css_key(abs: string): string;
+export { SizedLru, type StandardIssue, type StandardResult, type StandardSchemaV1, content_css_key as contentCssKey, escape_amp_quot as escapeAttr, escape_text as escapeText, fnv1a32, source_tag_of as sourceTag };

package/dist/plugin/utils.js

@@ -0,0 +1,19 @@
+import { fnv1a32 } from "../runtime/hash.js";
+import { escape_amp_quot, escape_text } from "../escape.js";
+import { SizedLru } from "../server/sized-lru.js";
+import { source_tag_of } from "../source.js";
+// src/plugin/utils.ts
+const BACKSLASHES = /\\/g;
+const LEADING_SLASH = /^\//;
+/**
+* The stable cross-build key for a markup module's own scoped CSS (a `.svx` body with a `<style>`):
+* the path from the first `/src/` segment, POSIX (`/…/proj/src/content/docs/x.svx` →
+* `content/docs/x.svx`). The preprocessor that bakes the key into the module and the build that emits
+* the CSS and writes the handoff compute it identically from the same absolute filename.
+*/
+function content_css_key(abs) {
+	const p = abs.replace(BACKSLASHES, "/").split("?")[0];
+	const i = p.indexOf("/src/");
+	return i >= 0 ? p.slice(i + 5) : p.replace(LEADING_SLASH, "");
+}
+export { SizedLru, content_css_key as contentCssKey, content_css_key, escape_amp_quot as escapeAttr, escape_text as escapeText, fnv1a32, source_tag_of as sourceTag };

package/dist/portable-form.d.ts

@@ -0,0 +1,22 @@
+/**
+ * THE PORTABLE FORM of a live region snippet — swapped in only where the snippet CROSSES.
+ *
+ * A `{#snippet}` handed to a component that may carry it into an island is branded at its definition
+ * site (region-snippet.ts `og_portable`), but it stays the snippet as written: rendered where it is
+ * written it runs in place, in the host's tree — the host's context, its scoped CSS, and any island
+ * inside it a plain page island. Only a boundary needs the other shape: the body compiled to its own
+ * entry, rendered in isolation on the server and hydrated alone on the client. That shape rides on the
+ * snippet as `__ogPortable`, and the ONE thing that knows a value is crossing — the code preparing an
+ * island's props (or a server-picked region's) for its render and its wire — swaps it in here, so the
+ * server markup and the client's revived snippet are the same shape.
+ *
+ * Leaf module (no svelte imports): region.ts reaches it on both legs.
+ */
+/** Where a branded snippet carries its portable form. */
+export declare const PORTABLE_FORM = "__ogPortable";
+/**
+ * `value` with every branded snippet in it (at any depth of plain objects and arrays) replaced by its
+ * portable form. Copy-on-write: returns the SAME object when nothing in it is branded, and never
+ * mutates the input.
+ */
+export declare function with_portable_forms<T>(value: T): T;

package/dist/portable-form.js

@@ -0,0 +1,52 @@
+// src/portable-form.ts
+/**
+* THE PORTABLE FORM of a live region snippet — swapped in only where the snippet CROSSES.
+*
+* A `{#snippet}` handed to a component that may carry it into an island is branded at its definition
+* site (region-snippet.ts `og_portable`), but it stays the snippet as written: rendered where it is
+* written it runs in place, in the host's tree — the host's context, its scoped CSS, and any island
+* inside it a plain page island. Only a boundary needs the other shape: the body compiled to its own
+* entry, rendered in isolation on the server and hydrated alone on the client. That shape rides on the
+* snippet as `__ogPortable`, and the ONE thing that knows a value is crossing — the code preparing an
+* island's props (or a server-picked region's) for its render and its wire — swaps it in here, so the
+* server markup and the client's revived snippet are the same shape.
+*
+* Leaf module (no svelte imports): region.ts reaches it on both legs.
+*/
+/** Where a branded snippet carries its portable form. */
+const PORTABLE_FORM = "__ogPortable";
+function is_plain(v) {
+	const proto = Object.getPrototypeOf(v);
+	return proto === Object.prototype || proto === null;
+}
+/**
+* `value` with every branded snippet in it (at any depth of plain objects and arrays) replaced by its
+* portable form. Copy-on-write: returns the SAME object when nothing in it is branded, and never
+* mutates the input.
+*/
+function with_portable_forms(value) {
+	return swap(value, /* @__PURE__ */ new WeakSet());
+}
+function swap(v, seen) {
+	if (typeof v === "function") return v[PORTABLE_FORM] ?? v;
+	if (!v || typeof v !== "object" || seen.has(v)) return v;
+	if (Array.isArray(v)) {
+		seen.add(v);
+		let out = null;
+		for (let i = 0; i < v.length; i++) {
+			const next = swap(v[i], seen);
+			if (next !== v[i]) (out ??= v.slice())[i] = next;
+		}
+		return out ?? v;
+	}
+	if (!is_plain(v)) return v;
+	seen.add(v);
+	let out = null;
+	for (const k of Object.keys(v)) {
+		const cur = v[k];
+		const next = swap(cur, seen);
+		if (next !== cur) (out ??= { ...v })[k] = next;
+	}
+	return out ?? v;
+}
+export { PORTABLE_FORM, with_portable_forms };

package/dist/preference.d.ts

@@ -0,0 +1,35 @@
+/** A preference declaration: its name, allowed values, and default (which must be one of the values). */
+export type PreferenceSpec = {
+  name: string;
+  values: readonly string[];
+  default: string;
+};
+/** A live preference handle — SSR `head()`, client `get()`/`set()`, and the `attr` CSS authors target. */
+export interface Preference {
+  readonly name: string;
+  readonly values: readonly string[];
+  readonly default: string;
+  /** The attribute set on `<html>`: `data-pref-<name>`. CSS targets `:root[<attr>="<value>"]`. */
+  readonly attr: string;
+  /** No-flash inline `<script>` string — reads localStorage and applies the attr before paint.
+   *  `{@html}` it once in `<svelte:head>`. Idempotent, so emitting it more than once is harmless. */
+  head(): string;
+  /** CLIENT: persist + apply a new value (wire a control's handler to this). No-op on the server. */
+  set(value: string): void;
+  /** CLIENT: the current value (from the applied attr), or the default. Returns the default on the server. */
+  get(): string;
+}
+/**
+ * ONE delegated click handler that wires every preference switcher on the page: a click on any
+ * `[data-pref][data-pref-set]` control (the buttons a variant switcher / package-manager tabs emit)
+ * persists + applies that preference. Event delegation, so it survives SPA body-swaps and needs no
+ * island. `{@html preference.switch()}` once in the layout, alongside each `preference(spec).head()`.
+ * (`switch` is a property, not a binding — reserved words are fine there; mirrors `region.snippet`.)
+ */
+declare function preference_switch(): string;
+/** Declare a site-wide client preference. Throws at creation if `default` isn't one of `values`. */
+declare function preference_impl(spec: PreferenceSpec): Preference;
+export declare const preference: typeof preference_impl & {
+  switch: typeof preference_switch;
+};
+export {};

package/dist/preference.js

@@ -0,0 +1,84 @@
+import { script } from "./script.js";
+// src/preference.ts
+/**
+* `preference()` — a persisted, site-wide client CHOICE that flips a CSS state, with zero shipped JS
+* beyond one pre-paint inline script. The csr=false-native primitive behind the JS↔TS code toggle,
+* package-manager tabs, site-wide tab memory, and the theme toggle: one mechanism, many features.
+*
+* A preference is a NAME, its allowed VALUES, and a DEFAULT. On the client the current value lives in
+* `localStorage` and is mirrored onto `<html data-pref-<name>="<value>">` — set BEFORE first paint by
+* {@link Preference.head} (no flash), so CSS can show/hide variants with pure `:root[data-pref-…]`
+* selectors and no hydration. A control calls {@link Preference.set} to change it.
+*
+* ```ts
+* const codeLang = preference({ name: 'code-language', values: ['ts', 'js'], default: 'ts' });
+* // layout <svelte:head>: {@html codeLang.head()}   ← no-flash apply
+* // a toggle's onchange: codeLang.set(checked ? 'ts' : 'js')
+* // CSS: :root[data-pref-code-language="js"] [data-variant="ts"] { display: none }
+* ```
+*/
+const KEY = (name) => "og-pref-" + name;
+const ATTR = (name) => "data-pref-" + name;
+/**
+* ONE delegated click handler that wires every preference switcher on the page: a click on any
+* `[data-pref][data-pref-set]` control (the buttons a variant switcher / package-manager tabs emit)
+* persists + applies that preference. Event delegation, so it survives SPA body-swaps and needs no
+* island. `{@html preference.switch()}` once in the layout, alongside each `preference(spec).head()`.
+* (`switch` is a property, not a binding — reserved words are fine there; mirrors `region.snippet`.)
+*/
+function preference_switch() {
+	return script(() => {
+		document.addEventListener("click", function(e) {
+			var t = e.target;
+			var btn = t && t.closest ? t.closest("[data-pref][data-pref-set]") : null;
+			if (!btn) return;
+			var name = btn.getAttribute("data-pref");
+			var val = btn.getAttribute("data-pref-set");
+			if (!name || !val) return;
+			try {
+				localStorage.setItem("og-pref-" + name, val);
+			} catch {}
+			document.documentElement.setAttribute("data-pref-" + name, val);
+		});
+	});
+}
+/** Declare a site-wide client preference. Throws at creation if `default` isn't one of `values`. */
+function preference_impl(spec) {
+	if (!spec.values.includes(spec.default)) throw new Error(`[ogygia] preference('${spec.name}'): default '${spec.default}' is not one of values [${spec.values.join(", ")}]`);
+	const name = spec.name;
+	const values = spec.values;
+	const def = spec.default;
+	const attr = ATTR(name);
+	return {
+		name,
+		values,
+		default: def,
+		attr,
+		head() {
+			return script((n, vs, d) => {
+				try {
+					var v = localStorage.getItem("og-pref-" + n);
+					if (!v || vs.indexOf(v) < 0) v = d;
+					document.documentElement.setAttribute("data-pref-" + n, v);
+				} catch {
+					document.documentElement.setAttribute("data-pref-" + n, d);
+				}
+			}, name, values, def);
+		},
+		set(value) {
+			if (typeof document === "undefined") return;
+			const v = values.includes(value) ? value : def;
+			try {
+				localStorage.setItem(KEY(name), v);
+			} catch {}
+			document.documentElement.setAttribute(attr, v);
+		},
+		get() {
+			if (typeof document === "undefined") return def;
+			const v = document.documentElement.getAttribute(attr);
+			return v && values.includes(v) ? v : def;
+		}
+	};
+}
+const preference = Object.assign(preference_impl, { switch: preference_switch });
+export { preference };

package/dist/preload.d.ts

@@ -0,0 +1 @@
+export declare function preload(region: unknown): void;

package/dist/preload.js

@@ -0,0 +1,21 @@
+import { REGION_BRAND } from "./region-brand.js";
+import { frameAddress } from "./frame.js";
+import { ensure } from "./runtime/frame-store.js";
+// src/preload.ts
+function preload(region) {
+	if (typeof document === "undefined") return;
+	const r = region;
+	if (!r || r[REGION_BRAND] !== true) return;
+	const url = typeof r.url === "string" ? r.url : "";
+	if (!url || r.html != null) return;
+	const address = frameAddress(url);
+	ensure(address, async (signal) => {
+		const res = await fetch(url, {
+			credentials: "same-origin",
+			signal
+		});
+		if (!res.ok) throw new Error("status " + res.status);
+		return res.text();
+	}).catch(() => {});
+}
+export { preload };

package/dist/ref-watch.d.ts

@@ -0,0 +1,31 @@
+/**
+ * THE HUB'S WATCH CHANNEL (hub v2, phases W and B) — split out of ref.ts so the boot, which needs only
+ * "subscribe to an id / tell its watchers" (runtime/frame-store.ts: region frames), never carries the
+ * whole identity hub. ref.ts re-exports all of it: one channel either way.
+ *
+ * WATCH — subscribe to fresh data settling for a hub id. THE one subscription primitive: region
+ * frames, streamed page-data, live refresh — every "a value arrives later for this identity" channel
+ * routes through here instead of owning its own subscriber set. Browser-only in practice (the
+ * request-scoped server never re-settles an id within one render).
+ */
+type Watcher = (live: unknown) => void;
+export declare function watchers(): Map<string, Set<Watcher>>;
+/** Subscribe to fresh data settling for `id`. Returns an unsubscribe fn. */
+export declare function watch(id: string, cb: Watcher): () => void;
+/**
+ * Notify watchers that fresh data settled for `id`. Called by resolve's live-merge path AND
+ * directly by subsystems that push a value in (a region frame landing, a streamed promise
+ * resolving) — those pass the settled value; resolve's path passes the merged live instance.
+ * A throwing watcher never blocks the others.
+ */
+export declare function notify(id: string, live: unknown): void;
+/**
+ * Run `fn` with watch notifications BUFFERED, flushing them once when the outermost batch exits.
+ * Wrap any operation that resolves several refs at once (a context parse, a props decode, a nav's
+ * ref bag) so cross-ref invariants hold before any watcher reacts. Returns `fn`'s result.
+ */
+export declare function batch<T>(fn: () => T): T;
+/** How many watchers are registered for `id` — lets a subsystem that owns lifecycle around a
+ *  hub id (fetch dedupe, eviction TTL) make refcount decisions without a parallel subscriber set. */
+export declare function watcher_count(id: string): number;
+export {};

package/dist/ref-watch.js

@@ -0,0 +1,66 @@
+// src/ref-watch.ts
+/** id → callbacks. One per realm (a second bundle evaluating this module shares it). */
+const WATCHERS_KEY = Symbol.for("ogygia.hub.watchers");
+function watchers() {
+	const g = globalThis;
+	return g[WATCHERS_KEY] ??= /* @__PURE__ */ new Map();
+}
+/** Subscribe to fresh data settling for `id`. Returns an unsubscribe fn. */
+function watch(id, cb) {
+	const all = watchers();
+	let set = all.get(id);
+	if (set === void 0) all.set(id, set = /* @__PURE__ */ new Set());
+	set.add(cb);
+	return () => {
+		const s = all.get(id);
+		if (s === void 0) return;
+		s.delete(cb);
+		if (s.size === 0) all.delete(id);
+	};
+}
+/**
+* Notify watchers that fresh data settled for `id`. Called by resolve's live-merge path AND
+* directly by subsystems that push a value in (a region frame landing, a streamed promise
+* resolving) — those pass the settled value; resolve's path passes the merged live instance.
+* A throwing watcher never blocks the others.
+*/
+function notify(id, live) {
+	if (batch_depth > 0) {
+		(batch_pending ??= /* @__PURE__ */ new Map()).set(id, live);
+		return;
+	}
+	notify_now(id, live);
+}
+function notify_now(id, live) {
+	const set = watchers().get(id);
+	if (set === void 0) return;
+	for (const cb of Array.from(set)) try {
+		cb(live);
+	} catch {}
+}
+let batch_depth = 0;
+let batch_pending = null;
+/**
+* Run `fn` with watch notifications BUFFERED, flushing them once when the outermost batch exits.
+* Wrap any operation that resolves several refs at once (a context parse, a props decode, a nav's
+* ref bag) so cross-ref invariants hold before any watcher reacts. Returns `fn`'s result.
+*/
+function batch(fn) {
+	batch_depth++;
+	try {
+		return fn();
+	} finally {
+		batch_depth--;
+		if (batch_depth === 0) {
+			const pending = batch_pending;
+			batch_pending = null;
+			if (pending !== void 0 && pending !== null) for (const [id, live] of pending) notify_now(id, live);
+		}
+	}
+}
+/** How many watchers are registered for `id` — lets a subsystem that owns lifecycle around a
+*  hub id (fetch dedupe, eviction TTL) make refcount decisions without a parallel subscriber set. */
+function watcher_count(id) {
+	return watchers().get(id)?.size ?? 0;
+}
+export { batch, notify, watch, watcher_count, watchers };

package/dist/ref.d.ts

@@ -0,0 +1,124 @@
+import { batch, notify, watch, watcher_count } from "./ref-watch.js";
+/**
+ * THE HUB — ogygia's identity layer. One primitive carries everything that crosses an
+ * island boundary:
+ *
+ *     Ref = { k: kind, i: identity, t: code tag, d: data }
+ *
+ * A held region, a portable snippet, a store, a `[og.wire]` class, a hoisted function —
+ * each is a Ref of a different KIND. A kind teaches the hub how its values travel
+ * (`match`/`encode`/`decode`); the hub owns everything identity:
+ *
+ *  - MINT: every live instance gets ONE id (WeakMap-memoized), however many props or
+ *    context keys carry it — which is what lets the client reunite all copies.
+ *  - RESOLVE: the browser memoizes decode by id (`remember: true`), so five islands
+ *    decoding one handle share ONE live object. The server never memoizes
+ *    (`remember: false`): each request decodes fresh — nothing leaks between users.
+ *  - THE KEEP: a kind may name a ref for SESSION continuity (`keep_name`); the tab then
+ *    reunites navigations with the same live instance, reconciling fresh server data via
+ *    the kind's `merge`. Browser-only; the server never touches it.
+ *
+ * Everything interesting in the framework is an operation on `i`, not `d`: reunify across
+ * islands = same id; survive a navigation = same id in the Keep; dedupe = same id; the
+ * future region reconciler = diff two id sets. Kinds are plugins; identity is the spine.
+ *
+ * All registry state lives on `globalThis` under `Symbol.for` keys — the runtime and each
+ * island entry are separate bundles, and per-module state would silently fork.
+ */
+/** The wire shape. `k` picks the kind, `i` is identity, `t` names code (module tag /
+ *  chunk / factory), `d` is devalue-safe data (value, snapshot, props, bound captures). */
+export interface Ref {
+  k: string;
+  i: string;
+  t?: string;
+  d?: unknown;
+  /** Scope hint (hub v2, phase S) — which lifetime bucket governs this instance:
+   *  'request' (server, never memoized) | 'page' (this render) | 'session' (cross-nav, tab).
+   *  Optional on the wire; when absent, resolve derives it (keep_name ⇒ session, else the
+   *  caller's page/request choice). Present so a scope can be DISPOSED as a unit (phase D). */
+  sc?: Scope;
+}
+/** The three identity lifetimes, one axis of the hub's policy space. */
+export type Scope = "request" | "page" | "session";
+/** A kind teaches the hub one family of transportable values. */
+export interface RefKind {
+  /** Kind discriminator carried in `Ref.k` ('wire' | 'store' | 'snippet' | 'region' | 'fn' | …). */
+  k: string;
+  /** Claim a live value (mint dispatch, first registered wins). */
+  match(value: unknown): boolean;
+  /** Sending side: code tag + devalue-safe data. */
+  encode(value: object): {
+    t?: string;
+    d?: unknown;
+  };
+  /** Receiving side: rebuild a live value from the ref. */
+  decode(ref: Ref): unknown;
+  /** An id DERIVED from the descriptor, for a kind whose decode reads only `d` and whose instances
+   *  hold no state: equal descriptors ARE the same value, so they may share the id — and a render
+   *  mints the same id every time (the HTML, the island's fingerprint and every cache keyed on them
+   *  stay put across requests). `undefined` (or no hook) → a fresh random id, as every stateful kind
+   *  needs (a store, a class instance: identity is the point). */
+  stable_id?(d: unknown): string | undefined;
+  /** SESSION continuity: name this ref to promote its instance to tab lifetime (browser only). */
+  keep_name?(ref: Ref): string | undefined;
+  /** Reconcile a kept live instance with a freshly arrived ref (default: kept wins untouched). */
+  merge?(kept: object, ref: Ref): void;
+  /** Tear down a live instance when its scope is disposed (hub v2, phase D) — close a channel,
+   *  abort a fetch, drop a subscription. Most kinds have nothing to release (GC handles the
+   *  object); implement only when the instance owns a resource beyond memory. */
+  dispose?(live: object): void;
+}
+/** Register a kind. Idempotent by discriminator — a re-registration (second bundle evaluating
+ *  the same module) keeps the FIRST, so identity state never forks. */
+export declare function register_kind(kind: RefKind): void;
+/**
+ * Mint: live value → Ref, or undefined to fall through to devalue's normal handling.
+ * `only` restricts the dispatch to named kinds — a seam may deliberately exclude a family
+ * (the drop-in context path excludes snippets so a stray function THROWS instead of being
+ * silently mis-read as one). Same instance → same id, always.
+ */
+export declare function mint(value: unknown, only?: ReadonlySet<string>): Ref | undefined;
+export declare function set_resolve_sink(fn: ((id: string) => void) | null): void;
+/**
+ * DISPOSE a whole scope (hub v2, phase D) — tear down every instance in its bucket via the
+ * instance's `kind.dispose`, run any registered scope-disposers (side-effect cleanups like the
+ * remote cache), then empty the bucket. `dispose_scope('page')` on nav is what replaces the old
+ * MAX_LIVE cap: stale page-scoped aliases go, session/forever instances stay.
+ *
+ * SAFETY: a page-bucket instance that is ALSO in a longer-lived bucket (a wire class aliased into
+ * 'session' for continuity) is NOT torn down — only its page alias is dropped. Its resources
+ * belong to the session and outlive the nav.
+ */
+export declare function dispose_scope(scope: Scope): void;
+/**
+ * DISPOSE specific page-scoped ids (reconciler R3) — the SELECTIVE counterpart to dispose_scope.
+ * A reconcile nav keeps matched islands mounted, so it can't blanket-dispose the page scope; it
+ * disposes only the ids owned by REMOVED regions. Each id's instance is torn down via its
+ * kind.dispose and removed from the page bucket, instance_kind, and dep_index — UNLESS it is also
+ * session-aliased (continuity), in which case only nothing happens (the session bucket keeps it).
+ * ids not present in the page bucket are skipped silently.
+ */
+export declare function dispose_ids(ids: Iterable<string>): void;
+/** Register a side-effect cleanup to run whenever `scope` is disposed. Returns an unregister fn.
+ *  Lets subsystems (the remote cache) fold their nav-time clearing into scope disposal. */
+export declare function register_scope_disposer(scope: Scope, fn: () => void): () => void;
+/**
+ * Resolve: Ref → live value.
+ *
+ * Second arg is a {@link Scope} (or a legacy boolean shim: `true` ⇒ 'page', `false` ⇒ 'request').
+ * 'page'/'session' (browser) memoize by id — decoding the same ref twice returns the SAME instance
+ * (the liveness mechanism), and a kind-named ref reunites with the session bucket across
+ * navigations (the kind's `merge` reconciles fresh server data in; default kept-wins). 'request'
+ * (server, defer/streaming renders) always decodes fresh: memoizing across requests would leak one
+ * user's state into another's HTML.
+ */
+export declare function resolve(ref: Ref, scope_or_remember: boolean | Scope): unknown;
+/** Resolve a bag of refs as one transaction (sugar over {@link batch}). */
+export declare function resolve_batch(refs: readonly Ref[], scope: boolean | Scope): unknown[];
+/** Devalue custom-type name for hub refs on the wire (the ONE key every seam will converge on). */
+export declare const REF_WIRE_KEY = "OgygiaRef";
+/** Devalue reducer for a seam. `only` deliberately restricts which families may cross there. */
+export declare function ref_reducer(only?: ReadonlySet<string>): (value: unknown) => Ref | undefined;
+/** Devalue reviver for a seam. Browser passes `remember: true`; the server must pass `false`. */
+export declare function ref_reviver(remember: boolean): (ref: Ref) => unknown;
+export { batch, notify, watch, watcher_count };