@ogygia/core 0.0.0 → 0.11.1

package/dist/fn-transport.js

@@ -0,0 +1,140 @@
+import { mint, register_kind, resolve } from "./ref.js";
+// src/fn-transport.ts
+/**
+* Transportable functions — the hub's FN kind (the runtime half of `import.meta.og.$`).
+*
+* A closure can never serialize — there is no runtime API for a function's captured scope.
+* What CAN cross is a QRL-style handle: WHERE the code lives (a build tag) plus WHAT it
+* closed over (bound captures, as data). The compiler half (a later phase) hoists a marked
+* closure to a generated module at build time:
+*
+* ```ts
+* // source:                         setContext('fmt', import.meta.og.$((n) => `${n * rate}`));
+* // generated module (tagged):      export const $0 = (rate) => (n) => `${n * rate}`;
+* //                                 __register_fn('routes/+layout#$0', $0);
+* // call site rewrites to:          setContext('fmt', fn_handle('routes/+layout#$0', [rate]));
+* ```
+*
+* This module is the machinery both halves share: the factory registry, the branded live
+* handle (`fn_handle` — callable on the SERVER leg too, where the factory module is loaded),
+* and the kind. Decode = look the tag up, `factory(...bound)` → the live closure. Captures
+* are themselves refs-or-data, so a bound capture may be a store/wire instance that reunites.
+*
+* IDENTITY: functions are deliberately NEVER memoized by the hub (`resolve` only remembers
+* objects). Each consumer rebinds its own closure — stateless until called, exactly like
+* snippets. Anything stateful a function closes over should be a store/wire capture, which
+* DOES reunite; then every rebound copy sees the same live state.
+*/
+/** Brand on a live handle: carries `{ t, d }` so encode is a field read, not an analysis. */
+const FN_BRAND = Symbol.for("ogygia.fn");
+const REGISTRY_KEY = Symbol.for("ogygia.fns");
+function fn_registry() {
+	const g = globalThis;
+	return g[REGISTRY_KEY] ??= { factories: /* @__PURE__ */ new Map() };
+}
+/** Register a hoisted-function factory under its build tag (module path + export name).
+*  Called by the generated module; runs wherever that chunk loads (server AND island bundles). */
+function __register_fn(tag, factory) {
+	register_fn_kind();
+	if (typeof factory !== "function") return;
+	fn_registry().factories.set(tag, factory);
+}
+/** Is this a transportable (og.$-branded) function? The drop-in setContext bridges these —
+*  the "functions never cross" law applies to BARE functions only. */
+function is_branded_fn(value) {
+	return typeof value === "function" && value[FN_BRAND] !== void 0;
+}
+/**
+* The call-site rewrite target: build the LIVE function for this side (the factory's module is
+* imported right there, so it is always registered) and brand it with its travel handle. The
+* host renders with a real function; if it crosses a boundary, the brand is what travels.
+*/
+function fn_handle(tag, bound) {
+	register_fn_kind();
+	const factory = fn_registry().factories.get(tag);
+	if (factory === void 0) throw new Error(`[ogygia] fn_handle("${tag}"): its factory is not registered on this side. The generated module must be imported as a VALUE at the call site (the compiler emits this import).`);
+	const live = factory(...bound);
+	if (typeof live !== "function") throw new Error(`[ogygia] fn factory "${tag}" did not return a function.`);
+	live[FN_BRAND] = {
+		t: tag,
+		d: bound,
+		s: factory.toString()
+	};
+	return live;
+}
+/** The hub kind: a branded hoisted function. Bare functions are NEVER claimed (the snippet kind
+*  owns SSR-freezable snippets; an unmarked function at a boundary must keep failing loudly). */
+function register_fn_kind() {
+	register_kind({
+		k: "fn",
+		match(value) {
+			return typeof value === "function" && value[FN_BRAND] !== void 0;
+		},
+		encode(value) {
+			const brand = value[FN_BRAND];
+			return {
+				t: brand.t,
+				d: {
+					b: brand.d,
+					...brand.s ? { s: brand.s } : {}
+				}
+			};
+		},
+		decode(ref) {
+			const payload = ref.d ?? {};
+			let factory = fn_registry().factories.get(ref.t);
+			if (factory === void 0) {
+				const from_page = globalThis.__OG_FNM?.[ref.t];
+				if (typeof from_page === "function") {
+					factory = from_page;
+					fn_registry().factories.set(ref.t, factory);
+				}
+			}
+			if (factory === void 0 && typeof payload.s === "string") {
+				factory = (0, eval)(`(${payload.s})`);
+				fn_registry().factories.set(ref.t, factory);
+			}
+			if (factory === void 0) throw new Error(`[ogygia] cannot revive fn "${ref.t}": its factory is not loaded on this side and the payload carries no source. The island must import the generated module as a VALUE so \`__register_fn\` runs in its bundle (or the fn manifest must be in the runtime).`);
+			const bound = Array.isArray(payload.b) ? payload.b : [];
+			const live = factory(...bound);
+			live[FN_BRAND] = {
+				t: ref.t,
+				d: bound,
+				...payload.s ? { s: payload.s } : {}
+			};
+			return live;
+		}
+	});
+}
+const FN_ONLY = /* @__PURE__ */ new Set(["fn"]);
+/** Devalue reducer (legacy-shaped wrapper, mirrors the other kinds). */
+function reduce_fn(value) {
+	register_fn_kind();
+	const ref = mint(value, FN_ONLY);
+	if (ref === void 0) return void 0;
+	return {
+		t: ref.t,
+		i: ref.i,
+		d: ref.d
+	};
+}
+/** Devalue reviver. Functions never memoize; `remember` rides through for capture resolution. */
+function revive_fn(payload, remember) {
+	register_fn_kind();
+	return resolve({
+		k: "fn",
+		i: payload.i,
+		t: payload.t,
+		d: payload.d
+	}, remember);
+}
+/**
+* The `import.meta.og.$` rewrite target: register the hoisted factory (pull-registration —
+* the call site IS the moment the code exists) and return the LIVE bound function, branded
+* with its travel handle. One expression, no import-time side effects.
+*/
+function __og_$(tag, bound, factory) {
+	__register_fn(tag, factory);
+	return fn_handle(tag, bound);
+}
+export { __og_$, __register_fn, fn_handle, is_branded_fn, reduce_fn, register_fn_kind, revive_fn };

package/dist/frame.d.ts

@@ -0,0 +1,20 @@
+export type Frame = {
+  /** Address — the serialized call that produced this content. */
+  a: string;
+  /**
+   * Version ticket. Assigned at REQUEST time (not arrival time) by the store, so a slow response
+   * that started earlier can never overwrite one that started later. `write()` drops `v <=` applied.
+   */
+  v: number;
+  /** The content. HTML in, morph out — no component trees over the wire. */
+  html: string;
+};
+/**
+ * Address of a region: the CALL that produced it — region id + serialized props — NOT the full
+ * signed URL. Critically, `exp` and `sig` vary per request (they're time + MAC), so keying on the
+ * whole URL would give the same call a different address every request, and a mutation's fresh
+ * region could never update a mounted one. Keying on `id|props` makes the address stable across
+ * requests: same component + same props ⇒ same address, so single-flight updates land in place and
+ * identical twins dedupe. Falls back to the raw endpoint when there's no query to parse.
+ */
+export declare function frameAddress(endpoint: string): string;

package/dist/frame.js

@@ -0,0 +1,19 @@
+// src/frame.ts
+/**
+* Address of a region: the CALL that produced it — region id + serialized props — NOT the full
+* signed URL. Critically, `exp` and `sig` vary per request (they're time + MAC), so keying on the
+* whole URL would give the same call a different address every request, and a mutation's fresh
+* region could never update a mounted one. Keying on `id|props` makes the address stable across
+* requests: same component + same props ⇒ same address, so single-flight updates land in place and
+* identical twins dedupe. Falls back to the raw endpoint when there's no query to parse.
+*/
+function frameAddress(endpoint) {
+	const q = endpoint.indexOf("?");
+	if (q === -1) return endpoint;
+	const params = new URLSearchParams(endpoint.slice(q + 1));
+	const id = params.get("id");
+	const props = params.get("props");
+	const pv = params.get("pv");
+	return id != null ? `${id}|${props ?? ""}${pv ? "|" + pv : ""}` : endpoint.slice(0, q);
+}
+export { frameAddress };

package/dist/holes-record.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The holes record's script type — ONE constant shared by the server (document-tail.ts writes the
+ * record) and the runtime (hole-facts.ts reads it), kept import-free so the runtime bundle never
+ * reaches into server code for a string.
+ */
+export declare const HOLES_SCRIPT_TYPE = "application/ogygia-holes";

package/dist/holes-record.js

@@ -0,0 +1,8 @@
+// src/holes-record.ts
+/**
+* The holes record's script type — ONE constant shared by the server (document-tail.ts writes the
+* record) and the runtime (hole-facts.ts reads it), kept import-free so the runtime bundle never
+* reaches into server code for a string.
+*/
+const HOLES_SCRIPT_TYPE = "application/ogygia-holes";
+export { HOLES_SCRIPT_TYPE };

package/dist/hooks.d.ts

@@ -0,0 +1,43 @@
+import { TransformKind } from "./server/reversible.js";
+import { ogygiaTransport } from "./transport.js";
+import { DocumentOptions, document } from "./document.js";
+import { LiftResult, LiftedRegion, RegionKind, RegionSpan, liftRegions, restoreRegions, scanRegions } from "./server/split-regions.js";
+import { Handle, RequestEvent } from "@sveltejs/kit";
+/**
+ * Options for {@link handle}.
+ */
+export interface OgygiaHandleOptions {
+  /**
+   * Path (relative to Kit `base`) of the islands endpoint: the handle answers on it, and every hole
+   * and live region on a page is minted against it. Default `/__ogygia__`. Must start with `/`.
+   *
+   * It must be a path your deployment forwards to the app (behind a proxy that forwards only known
+   * prefixes, pick one under them, e.g. `/_server/api/__ogygia__`). Not under Kit's `appDir`
+   * (`/_app/…`): Kit answers those itself, before any handle runs.
+   */
+  endpoint?: string;
+  /**
+   * Post-process the HTML ogygia sends — every document (the chunk carrying `</head>`; a streamed
+   * tail passes untouched) and every region answer (a hole, a lake remount) — e.g. a web-component
+   * server render. `html` in, `html` out, may be async; it is on the response path, so keep it fast.
+   *
+   * It may reshape Svelte-owned markup. ogygia marks the HTML before the call and restores in the
+   * browser, before anything hydrates, what the transform moved:
+   * - a custom element marked `og-h` is one ogygia restores (in Svelte-owned markup, above it, or in
+   *   a region answer). To reshape it, render its plan: its slot positions as `<slot>` elements
+   *   wrapping the moved children, `og-shadow="key …"` (the keyed sheets for its shadow root), and
+   *   optionally `og-keep="attr …"` (attributes you added that survive the restore; never per-render
+   *   state). One without `og-shadow` is left exactly as Svelte wrote it.
+   * - `<template data-og-head="key">css</template>` is a shadow sheet; `<style>` / `<link>` with
+   *   `data-og-head="key"` apply to the page. Both go into `<head>`, once per key.
+   * - everything else `og-*` is ogygia's: carry it along wherever you move a node; it is gone from
+   *   the final DOM.
+   */
+  transform?: (html: string, ctx: {
+    kind: TransformKind;
+    csr: boolean;
+    event: RequestEvent;
+  }) => string | Promise<string>;
+}
+export declare function handle(options?: OgygiaHandleOptions): Handle;
+export { type DocumentOptions, type LiftResult, type LiftedRegion, type RegionKind, type RegionSpan, document, liftRegions, restoreRegions, scanRegions, ogygiaTransport as transport };