@ogygia/core 0.0.0 → 0.11.0

package/dist/ref.js

@@ -0,0 +1,272 @@
+import { emit } from "./events/bus.js";
+import { batch, notify, watch, watcher_count, watchers } from "./ref-watch.js";
+// src/ref.ts
+const DEVTOOLS = typeof __OGYGIA_DEVTOOLS__ !== "undefined" ? __OGYGIA_DEVTOOLS__ : false;
+const REGISTRY_KEY = Symbol.for("ogygia.hub");
+function registry() {
+	const g = globalThis;
+	return g[REGISTRY_KEY] ??= {
+		kinds: /* @__PURE__ */ new Map(),
+		order: [],
+		ids: /* @__PURE__ */ new WeakMap(),
+		instances: /* @__PURE__ */ new Map([["page", /* @__PURE__ */ new Map()], ["session", /* @__PURE__ */ new Map()]]),
+		instance_kind: /* @__PURE__ */ new WeakMap(),
+		scope_disposers: /* @__PURE__ */ new Map(),
+		keep_owner: /* @__PURE__ */ new Map()
+	};
+}
+/** Register a kind. Idempotent by discriminator — a re-registration (second bundle evaluating
+*  the same module) keeps the FIRST, so identity state never forks. */
+function register_kind(kind) {
+	const reg = registry();
+	if (reg.kinds.has(kind.k)) return;
+	reg.kinds.set(kind.k, kind);
+	reg.order.push(kind);
+}
+function mint_id() {
+	const c = globalThis.crypto;
+	if (c?.randomUUID) return c.randomUUID();
+	return "r" + Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2);
+}
+/**
+* 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.
+*/
+function mint(value, only) {
+	if (value === null || typeof value !== "object" && typeof value !== "function") return void 0;
+	const reg = registry();
+	for (const kind of reg.order) {
+		if (only && !only.has(kind.k)) continue;
+		if (!kind.match(value)) continue;
+		const { t, d } = kind.encode(value);
+		let i = reg.ids.get(value);
+		if (i === void 0) {
+			i = kind.stable_id?.(d) ?? mint_id();
+			reg.ids.set(value, i);
+		}
+		const ref = {
+			k: kind.k,
+			i,
+			d
+		};
+		if (t !== void 0) ref.t = t;
+		if (DEVTOOLS) emit({
+			domain: "hub",
+			name: "hub.mint",
+			kind: kind.k,
+			id: i,
+			tag: t
+		});
+		return ref;
+	}
+}
+/**
+* RESOLVE SINK (reconciler R3) — a hook the runtime installs during an island's hydration to learn
+* which page-scoped ids that island resolves, WITHOUT the hub knowing anything about the DOM.
+* `resolve()` calls the current sink with each id it freshly remembers in the page scope; the
+* runtime's sink attributes it to the island currently hydrating (region → id-set), so a reconcile
+* nav can dispose exactly the ids owned by REMOVED regions. Null when no island is hydrating.
+*/
+let resolve_sink = null;
+function set_resolve_sink(fn) {
+	resolve_sink = fn;
+}
+/** The live bucket for a scope (never 'request' — that scope is never stored). */
+function bucket(reg, scope) {
+	let b = reg.instances.get(scope);
+	if (b === void 0) reg.instances.set(scope, b = /* @__PURE__ */ new Map());
+	return b;
+}
+/** Memoize an instance in a scope's bucket, recording its kind for later disposal. No MAX_LIVE
+*  cap since phase D — the 'page' bucket is emptied by `dispose_scope('page')` on every nav, so
+*  it can't creep across the tab's lifetime the way the old unbounded map could. */
+function remember_in(reg, scope, key, instance, kind_k) {
+	bucket(reg, scope).set(key, instance);
+	reg.instance_kind.set(instance, kind_k);
+	if (scope === "page" && resolve_sink !== null) resolve_sink(key);
+}
+/**
+* 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.
+*/
+function dispose_scope(scope) {
+	const reg = registry();
+	const b = reg.instances.get(scope);
+	if (DEVTOOLS) emit({
+		domain: "hub",
+		name: "hub.dispose",
+		scope,
+		count: b?.size ?? 0
+	});
+	if (b !== void 0 && b.size > 0) {
+		const survivors = /* @__PURE__ */ new Set();
+		if (scope === "page") for (const inst of bucket(reg, "session").values()) survivors.add(inst);
+		for (const inst of b.values()) {
+			if (survivors.has(inst)) continue;
+			const kind = reg.kinds.get(reg.instance_kind.get(inst) ?? "");
+			try {
+				kind?.dispose?.(inst);
+			} catch {}
+		}
+		b.clear();
+	}
+	const ds = reg.scope_disposers.get(scope);
+	if (ds !== void 0) for (const fn of Array.from(ds)) try {
+		fn();
+	} catch {}
+}
+/**
+* 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.
+*/
+function dispose_ids(ids) {
+	const reg = registry();
+	const page = bucket(reg, "page");
+	const survivors = new Set(bucket(reg, "session").values());
+	let dt_disposed = 0;
+	for (const id of ids) {
+		const inst = page.get(id);
+		if (inst === void 0) continue;
+		page.delete(id);
+		if (DEVTOOLS) dt_disposed++;
+		if (survivors.has(inst)) continue;
+		const kind = reg.kinds.get(reg.instance_kind.get(inst) ?? "");
+		reg.instance_kind.delete(inst);
+		try {
+			kind?.dispose?.(inst);
+		} catch {}
+	}
+	if (DEVTOOLS && dt_disposed > 0) emit({
+		domain: "hub",
+		name: "hub.dispose",
+		scope: "ids",
+		count: dt_disposed
+	});
+}
+/** 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. */
+function register_scope_disposer(scope, fn) {
+	const reg = registry();
+	let set = reg.scope_disposers.get(scope);
+	if (set === void 0) reg.scope_disposers.set(scope, set = /* @__PURE__ */ new Set());
+	set.add(fn);
+	return () => reg.scope_disposers.get(scope)?.delete(fn);
+}
+/**
+* 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.
+*/
+function resolve(ref, scope_or_remember) {
+	const scope = typeof scope_or_remember === "boolean" ? scope_or_remember ? "page" : "request" : scope_or_remember;
+	const remember = scope !== "request";
+	const reg = registry();
+	if (remember) {
+		const existing = bucket(reg, "page").get(ref.i);
+		if (existing !== void 0) {
+			const w = watchers().get(ref.i);
+			if (w !== void 0 && w.size > 0) {
+				const kind = reg.kinds.get(ref.k);
+				if (kind?.merge !== void 0) {
+					kind.merge(existing, ref);
+					notify(ref.i, existing);
+				}
+			}
+			if (DEVTOOLS) emit({
+				domain: "hub",
+				name: "hub.resolve",
+				kind: ref.k,
+				id: ref.i,
+				scope,
+				tag: ref.t,
+				hit: true
+			});
+			return existing;
+		}
+	}
+	const kind = reg.kinds.get(ref.k);
+	if (kind === void 0) throw new Error(`[ogygia] cannot resolve a "${ref.k}" ref: no such kind is registered on this side. The module that registers it must be imported as a VALUE in this bundle.`);
+	if (remember) {
+		const name = kind.keep_name?.(ref);
+		if (typeof name === "string") {
+			const tag = ref.t ?? ref.k;
+			const owner = reg.keep_owner.get(name);
+			if (owner === void 0) reg.keep_owner.set(name, tag);
+			else if (owner !== tag && typeof console !== "undefined") console.error(`[ogygia] two transportables both use continuity id "${name}" ("${owner}" and "${tag}"). A continuity id must be unique per class — rename one, or they will clobber each other in the session Keep.`);
+			const kept = bucket(reg, "session").get(name);
+			if (kept !== void 0) {
+				kind.merge?.(kept, ref);
+				remember_in(reg, "page", ref.i, kept, ref.k);
+				if (DEVTOOLS) emit({
+					domain: "hub",
+					name: "hub.resolve",
+					kind: ref.k,
+					id: ref.i,
+					scope,
+					tag: ref.t,
+					hit: true
+				});
+				return kept;
+			}
+			const instance = kind.decode(ref);
+			if (instance !== null && typeof instance === "object") {
+				remember_in(reg, "session", name, instance, ref.k);
+				remember_in(reg, "page", ref.i, instance, ref.k);
+			}
+			if (DEVTOOLS) emit({
+				domain: "hub",
+				name: "hub.resolve",
+				kind: ref.k,
+				id: ref.i,
+				scope,
+				tag: ref.t,
+				hit: false
+			});
+			return instance;
+		}
+	}
+	const instance = kind.decode(ref);
+	if (remember && instance !== null && typeof instance === "object") remember_in(reg, "page", ref.i, instance, ref.k);
+	if (DEVTOOLS) emit({
+		domain: "hub",
+		name: "hub.resolve",
+		kind: ref.k,
+		id: ref.i,
+		scope,
+		tag: ref.t,
+		hit: false
+	});
+	return instance;
+}
+/** Resolve a bag of refs as one transaction (sugar over {@link batch}). */
+function resolve_batch(refs, scope) {
+	return batch(() => refs.map((r) => resolve(r, scope)));
+}
+/** Devalue custom-type name for hub refs on the wire (the ONE key every seam will converge on). */
+const REF_WIRE_KEY = "OgygiaRef";
+/** Devalue reducer for a seam. `only` deliberately restricts which families may cross there. */
+function ref_reducer(only) {
+	return (value) => mint(value, only);
+}
+/** Devalue reviver for a seam. Browser passes `remember: true`; the server must pass `false`. */
+function ref_reviver(remember) {
+	return (ref) => resolve(ref, remember);
+}
+export { REF_WIRE_KEY, batch, dispose_ids, dispose_scope, mint, notify, ref_reducer, ref_reviver, register_kind, register_scope_disposer, resolve, resolve_batch, set_resolve_sink, watch, watcher_count };

package/dist/region-brand.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The brand marking a held-region value (`region()` results / deferred tickets). It lives ALONE, with
+ * no imports, on purpose: the client transport hook only needs to TEST `value[REGION_BRAND]` to know
+ * whether to decode a region — and importing that test from `region.js` used to drag the whole
+ * `region → region-snippet → svelte/server` graph (~20kB) into every client that installs the hook.
+ * `Symbol.for` so every bundle (server render, client hook, runtime) agrees on one brand.
+ */
+export declare const REGION_BRAND: unique symbol;

package/dist/region-brand.js

@@ -0,0 +1,10 @@
+// src/region-brand.ts
+/**
+* The brand marking a held-region value (`region()` results / deferred tickets). It lives ALONE, with
+* no imports, on purpose: the client transport hook only needs to TEST `value[REGION_BRAND]` to know
+* whether to decode a region — and importing that test from `region.js` used to drag the whole
+* `region → region-snippet → svelte/server` graph (~20kB) into every client that installs the hook.
+* `Symbol.for` so every bundle (server render, client hook, runtime) agrees on one brand.
+*/
+const REGION_BRAND = Symbol.for("ogygia.region");
+export { REGION_BRAND };

package/dist/region-core.d.ts

@@ -0,0 +1,2 @@
+import { isRegion, og_html_region, region } from "./region.js";
+export { isRegion, og_html_region, region };

package/dist/region-core.js

@@ -0,0 +1 @@
+export { isRegion, og_html_region, region } from "./region.js";

package/dist/region-snippet.d.ts

@@ -0,0 +1,73 @@
+import { Component, Snippet } from "svelte";
+/** Devalue custom-type name a region snippet crosses under (wire-stable; was `OgygiaS`). */
+export declare const REGION_SNIPPET_WIRE_KEY = "OgygiaS";
+/** The serializable stand-in a region snippet crosses as, discriminated by mode. */
+export type RegionSnippetDescriptor = {
+  m: "live";
+  e: string;
+  p: Record<string, unknown>;
+} | {
+  m: "static";
+  h: string;
+} | {
+  m: "slot";
+  id: string;
+};
+/** A snippet stamped with its region descriptor. */
+type RegionSnippet = Snippet & {
+  __ogRegion?: RegionSnippetDescriptor;
+};
+/**
+ * Definition-site factory (compiler-emitted). Brands the snippet AS WRITTEN (`native`) — it keeps
+ * rendering in place, in the host's tree: the host's context, its scoped CSS, a nested island as a plain
+ * page island — with the descriptor (`__ogRegion`, what crosses the wire) and its PORTABLE form: the
+ * body compiled to `Entry`, rendered in isolation on the server and hydrated alone on the client. Only a
+ * boundary swaps the portable form in (portable-form.ts, via {@link prepare_region_props}), so the server
+ * markup and the client's revived snippet agree. `Entry` is `null` in a client bundle (the far side
+ * imports it by url). The native function is branded in place (not wrapped), so its identity — what a
+ * `{@render}` keys on — is stable across re-evaluations of the prop.
+ */
+export declare function og_portable(native: Snippet, Entry: Component | null, props: Record<string, unknown>, url: string): RegionSnippet;
+export interface RawRegionSnippet {
+  /** Single-root HTML for SSR + hydration match (same rule as `createRawSnippet`). */
+  render: (...captures: unknown[]) => string;
+  /** Client behavior after mount/adoption. DROPPED if this snippet is reduced across a wire. */
+  setup?: (root: Element, ...captures: unknown[]) => (() => void) | void;
+  /** Devalue-serializable inputs — same law as island props. */
+  captures?: unknown[];
+}
+/** Lift a parameterless snippet, or a raw `{ render, setup?, captures? }`, into a region snippet. */
+export declare function region_snippet(input: Snippet | RawRegionSnippet): RegionSnippet;
+/**
+ * Prepare an island's props for crossing: freeze each BARE snippet prop to a single-rooted static
+ * region snippet, so the SAME value renders the island body AND serializes — the body HTML and the
+ * revived client snippet then agree byte-for-byte, and hydration adopts cleanly. Server-only (uses SSR
+ * capture). A branded (live) snippet, at any depth, is swapped for its PORTABLE form; non-snippet values
+ * pass through untouched. Returns the original object when nothing changed (no needless copy).
+ */
+export declare function prepare_region_props(input: Record<string, unknown>): Record<string, unknown>;
+/** The SSR marker that fences an island's in-place children so the client can adopt exactly that range.
+ *  `display:contents` keeps it layout-neutral. */
+export declare function slot_marker_open(id: string): string;
+export declare const SLOT_MARKER_CLOSE = "</ogygia-slot>";
+export declare function next_slot_id(key?: string): string;
+/** The serialize-only stand-in for in-place children: a branded value the codec reduces to a `slot`
+ *  descriptor. Never rendered (the server body renders the real children); on the client it revives to a
+ *  snippet that ADOPTS the marked DOM range. */
+export declare function slot_pointer(id: string): RegionSnippet;
+/** The hub kind: a snippet is a renderable Ref ("a snippet is a region", now literal). A branded
+ *  region snippet crosses as its descriptor; a bare snippet FREEZES at the boundary (server-only —
+ *  the BROWSER guard also keeps `capture_static` → `svelte/server` DCE-able out of client bundles);
+ *  a bare function on the CLIENT falls through (never claimed — it can't freeze there). */
+/** Explicit registration — called at module scope AND from live-transport's install():
+ *  a bare side-effect import gets tree-shaken (the package marks JS side-effect-free),
+ *  which silently un-registers the kind in client bundles. A CALLED import cannot be dropped. */
+export declare function register_snippet_kind(): void;
+/** Codec encode (legacy `OgygiaS` wire shape: the bare descriptor). Branded region snippet → its
+ *  descriptor; a bare snippet → frozen static; anything else falls through. */
+export declare function reduce_region_snippet(value: unknown): RegionSnippetDescriptor | undefined;
+/** Codec decode. Rebuild a live snippet from the descriptor (both modes). Snippets are functions,
+ *  which the hub deliberately never memoizes — each consumer revives its own (stateless until
+ *  rendered), exactly the pre-hub behavior. */
+export declare function revive_region_snippet(desc: RegionSnippetDescriptor): RegionSnippet;
+export {};