@ogygia/core 0.0.0 → 0.11.0

package/dist/region-snippet.js

@@ -0,0 +1,351 @@
+import { mint, register_kind } from "./ref.js";
+import { kit_render_context, kit_request_event } from "./server/kit-context.js";
+import { islands_endpoint } from "./server/endpoint.js";
+import { PORTABLE_FORM, with_portable_forms } from "./portable-form.js";
+import { analyze } from "./seed-refs.js";
+import { fnv1a, fnv1a32 } from "./runtime/hash.js";
+import { import_entry } from "./runtime/entry-locations.js";
+import { createRawSnippet, getAllContexts, hydrate, unmount } from "svelte";
+import { render } from "svelte/server";
+import { BROWSER, DEV } from "esm-env";
+// src/region-snippet.ts
+/**
+* Region snippets — the snippet shape of a region. "Everything that crosses an island boundary is a
+* region; components and snippets are its two shapes; static freezes, live wakes."
+*
+* A snippet handed to a component is a function, so it can't cross an island boundary directly (devalue
+* can't stringify a function). A region snippet is a real Svelte snippet — same-graph `{@render}`
+* renders it inline — that also carries a serializable DESCRIPTOR and knows how to REVIVE on the far
+* side. One primitive, two modes:
+*
+*  - **live** — the compiler, at a snippet's DEFINITION site, compiles its body into an island ENTRY
+*    and constructs a live region snippet (`{ m:'live', e, p }`). It renders the entry inline on the
+*    server and HYDRATES it on the client, so the markup comes alive. This is the former "portable
+*    snippet" path, unchanged in behavior, now expressed as the live mode of this one primitive.
+*  - **static** — a PLAIN snippet reaching a boundary is FROZEN to its server-rendered HTML
+*    (`{ m:'static', h }`). The client adopts that HTML byte-for-byte; nothing re-runs. No compiler
+*    involvement, so it survives wrappers, re-exports, and a consumer swapping in their own component.
+*    Correct for markdown content (prose, code): static, never reactive.
+*
+* The boundary law lives in ONE place — {@link reduce_region_snippet}: a branded region snippet crosses
+* as its descriptor; a bare snippet is captured static; a parameterized snippet that can't be frozen
+* throws, loudly. Revival is its single inverse, {@link revive_region_snippet}. `createRawSnippet` is
+* isomorphic (server calls `render`, client calls `setup`), so one factory serves both legs of both
+* modes with no manual environment branch.
+*/
+/**
+* A hand-written SERVER component that renders a bare snippet: svelte has no public API to
+* stringify a snippet, but a server component is just `($$renderer, $$props) => void` and a server
+* snippet is `($$renderer) => void` — so the component simply invokes the snippet. Hand-written
+* (not a `.svelte` file) so this module stays importable from plain node (endpoints, tests)
+* without a svelte compiler in the loader.
+*/
+const RenderSnippet = (($$renderer, $$props) => {
+	$$props.s($$renderer);
+});
+/** Devalue custom-type name a region snippet crosses under (wire-stable; was `OgygiaS`). */
+const REGION_SNIPPET_WIRE_KEY = "OgygiaS";
+const WRAP_OPEN = "<ogygia-snippet style=\"display:contents\">";
+const WRAP_CLOSE = "</ogygia-snippet>";
+const STATIC_OPEN = "<ogygia-snippet data-og-static style=\"display:contents\">";
+const host_context = () => {
+	try {
+		return getAllContexts();
+	} catch {
+		return null;
+	}
+};
+/** context.ts `isInLiveSnippet` reads it: a hole in the body stays deferred (Region.svelte). */
+const LIVE_SNIPPET_KEY = Symbol.for("ogygia.live-snippet");
+const with_host = (context, host) => {
+	if (host) for (const [k, v] of host) context.set(k, v);
+	context.set(LIVE_SNIPPET_KEY, true);
+	return context;
+};
+/** Where a live snippet's pending hydrate waits on its host region: a global key, as the runtime
+*  bundle and each island-entry bundle carry their own copy of this module (runtime/core.ts reads it). */
+const SNIPPET_BOOTS = Symbol.for("ogygia.snippet-boots");
+/** The host region is awake only once its snippets are: it signals `data-hydrated` after them. */
+function hold_host(el, booted) {
+	const host = el.closest("ogygia-region");
+	if (host && !host.hasAttribute("data-hydrated")) (host[SNIPPET_BOOTS] ??= []).push(booted);
+}
+/**
+* The ONE factory. Build a region snippet from its descriptor (+ the live entry when we're at its
+* definition site and it's in the same bundle). Handles both modes and both legs.
+*/
+function make(desc, live_entry = null) {
+	if (desc.m === "slot") {
+		const el = BROWSER ? document.querySelector(`ogygia-slot[data-og-slot="${desc.id}"]`) : null;
+		const h = el ? el.outerHTML : slot_marker_open(desc.id) + SLOT_MARKER_CLOSE;
+		const slot_snip = createRawSnippet(() => ({
+			render: () => h,
+			setup: () => {}
+		}));
+		slot_snip.__ogRegion = desc;
+		return slot_snip;
+	}
+	if (!BROWSER && desc.m === "live") {
+		const thread_head = (r, head) => {
+			if (head && typeof r.head === "function") r.head((child) => child.push(head));
+		};
+		const dev_css_link = DEV ? `<link rel="modulepreload" href="${desc.e}" data-ogygia-region-css>` : "";
+		const server_snip = ((renderer, ...args) => {
+			const props = args.length ? {
+				...desc.p,
+				__ogArgs: args
+			} : desc.p;
+			const host = host_context();
+			if (!!live_entry && renderer?.global?.mode === "async" && typeof renderer.child === "function") renderer.child(async (r) => {
+				const out = await render(live_entry, {
+					props,
+					context: with_host(kit_render_context(), host)
+				});
+				thread_head(r, (out.head || "") + dev_css_link);
+				r.push(WRAP_OPEN + out.body + WRAP_CLOSE);
+			});
+			else {
+				const out = live_entry ? render(live_entry, {
+					props,
+					context: with_host(kit_render_context(), host)
+				}) : {
+					head: "",
+					body: ""
+				};
+				thread_head(renderer, (out.head || "") + dev_css_link);
+				renderer.push(WRAP_OPEN + out.body + WRAP_CLOSE);
+			}
+		});
+		server_snip.__ogRegion = desc;
+		return server_snip;
+	}
+	const snip = createRawSnippet((...params) => {
+		const host = host_context();
+		const live_props = () => desc.m === "live" ? params.length ? {
+			...desc.p,
+			__ogArgs: params.map((g) => g())
+		} : desc.p : {};
+		return {
+			render: () => {
+				if (desc.m === "static") return STATIC_OPEN + desc.h + WRAP_CLOSE;
+				return WRAP_OPEN + (BROWSER || !live_entry ? "" : render(live_entry, {
+					props: live_props(),
+					context: with_host(kit_render_context(), host)
+				}).body) + WRAP_CLOSE;
+			},
+			setup: (el) => {
+				if (desc.m === "static") return;
+				let app;
+				let dead = false;
+				const boot = (Comp) => {
+					if (!dead) app = hydrate(Comp, {
+						target: el,
+						props: live_props(),
+						context: with_host(/* @__PURE__ */ new Map(), host)
+					});
+				};
+				if (live_entry) boot(live_entry);
+				else hold_host(el, import_entry(desc.e).then((m) => boot(m.default)));
+				return () => {
+					dead = true;
+					if (app) unmount(app);
+				};
+			}
+		};
+	});
+	snip.__ogRegion = desc;
+	return snip;
+}
+/** Freeze a plain snippet to a static region snippet by SSR-rendering it once (SERVER only). A snippet
+*  that needs parameters can't be frozen — surface that as the actionable boundary error. `label` names
+*  the island prop when known, so a plain function passed by mistake points at the right prop. */
+function capture_static(snippet, label) {
+	let body;
+	try {
+		body = render(RenderSnippet, {
+			props: { s: snippet },
+			context: kit_render_context()
+		}).body;
+	} catch (e) {
+		const where = label ? `prop \`${label}\`` : "a function prop";
+		throw new Error(`[ogygia] ${where} is a function that can't cross the island boundary — ${e instanceof Error ? e.message : String(e)}. Island props must be SERIALIZABLE; a function crosses only as a Svelte snippet that freezes to HTML, and this one didn't. Usually one of:\n  • it's a PLAIN function (an event handler / callback) — those can't cross into an island; pass serializable data as props and keep the behavior inside the island component;\n  • it's a snippet WITH PARAMETERS — declare it as a {#snippet} so it crosses LIVE, or pass its data as props;\n  • it's children containing a NESTED island — keep those out of frozen children for now.`);
+	}
+	return make({
+		m: "static",
+		h: body
+	});
+}
+/**
+* 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.
+*/
+function og_portable(native, Entry, props, url) {
+	const desc = {
+		m: "live",
+		e: url,
+		p: props
+	};
+	const snip = native;
+	snip.__ogRegion = desc;
+	let portable = null;
+	Object.defineProperty(snip, PORTABLE_FORM, {
+		configurable: true,
+		enumerable: false,
+		get: () => portable ??= make(desc, Entry)
+	});
+	return snip;
+}
+/** Lift a parameterless snippet, or a raw `{ render, setup?, captures? }`, into a region snippet. */
+function region_snippet(input) {
+	if (typeof input === "function" && !BROWSER) return capture_static(input);
+	if (typeof input === "function") throw new Error("[ogygia] region_snippet(fn) freezes a snippet by server-rendering it — call it during SSR, not on the client. Pass a raw { render, setup } region snippet for client-constructed regions.");
+	const caps = input.captures ?? [];
+	const snip = createRawSnippet(() => ({
+		render: () => WRAP_OPEN + input.render(...caps) + WRAP_CLOSE,
+		setup: input.setup ? (el) => void input.setup(el, ...caps) : () => {}
+	}));
+	snip.__ogRegion = {
+		m: "static",
+		h: input.render(...caps)
+	};
+	return snip;
+}
+/**
+* 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).
+*/
+function prepare_region_props(input) {
+	if (BROWSER) return input;
+	if (analyze(input).json) return input;
+	const props = with_portable_forms(input);
+	let out = null;
+	for (const k in props) {
+		const v = props[k];
+		if (typeof v === "function" && !v.__ogRegion && v[Symbol.for("ogygia.fn")] === void 0) (out ??= { ...props })[k] = capture_static(v, k);
+	}
+	return out ?? props;
+}
+/** 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. */
+function slot_marker_open(id) {
+	return `<ogygia-slot data-og-slot="${id}" style="display:contents">`;
+}
+const SLOT_MARKER_CLOSE = "</ogygia-slot>";
+/**
+* Slot marker ids: PER REQUEST, so two renders of the same page mint the same ids and the HTML is
+* byte-identical across requests (a host's post-render cache, a freeze store, an ETag all key on
+* the bytes; a process-wide counter made every page differ from its previous render). Page-unique
+* within one SSR pass is all the id must be — it fences a marker to its payload pointer. A hole
+* response is spliced INTO a page that has its own sequence, so an endpoint render prefixes its
+* ids with its region id and can never collide with the page's. Off-request (a test, a tool, the
+* client) the process counter stands in. The request comes through the kit-context reader the
+* handle installs (no Vite virtual here — this module is imported by plain-Node consumers too).
+*
+* COUNTED PER `key` (the island's entry): with async SSR, regions start in the order their data
+* arrives, so ONE counter for the page gave an island in an async branch a different number on each
+* request (and every island after it). Per entry, an island's id moves only against another copy of
+* the SAME island that started in a different order — rare, and still page-unique.
+*/
+const slot_seq_by_request = /* @__PURE__ */ new WeakMap();
+let _slot_seq = 0;
+function next_slot_id(key = "") {
+	const event = kit_request_event();
+	if (event && typeof event === "object") {
+		let seq = slot_seq_by_request.get(event);
+		if (!seq) {
+			const url = event.url;
+			const hole = url?.pathname.endsWith(islands_endpoint()) ? (url.searchParams.get("id") ?? "").slice(0, 6) : "";
+			slot_seq_by_request.set(event, seq = {
+				prefix: hole ? hole + "-" : "",
+				n: /* @__PURE__ */ new Map()
+			});
+		}
+		let c = seq.n.get(key);
+		if (!c) seq.n.set(key, c = {
+			n: 0,
+			tag: key ? fnv1a32(key).toString(36) + "-" : ""
+		});
+		return "og" + seq.prefix + c.tag + (++c.n).toString(36);
+	}
+	_slot_seq = _slot_seq + 1 & 2147483647;
+	return "og" + _slot_seq.toString(36);
+}
+/** 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. */
+function slot_pointer(id) {
+	const snip = (() => {});
+	snip.__ogRegion = {
+		m: "slot",
+		id
+	};
+	return snip;
+}
+/** 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. */
+function register_snippet_kind() {
+	register_kind({
+		k: "snippet",
+		match(value) {
+			if (typeof value !== "function") return false;
+			if (value.__ogRegion) return true;
+			if (value[Symbol.for("ogygia.fn")] !== void 0) return false;
+			return !BROWSER;
+		},
+		encode(value) {
+			const branded = value.__ogRegion;
+			if (branded) return { d: branded };
+			return { d: capture_static(value).__ogRegion };
+		},
+		decode(ref) {
+			return make(ref.d);
+		},
+		stable_id: snippet_stable_id
+	});
+}
+/**
+* A snippet's ref id from its descriptor: decode reads only `d` and a revived snippet holds no state,
+* so equal descriptors are the same snippet — and a render names it the same every time (a random id
+* here changed the fingerprint and the bytes of every island with children, on every request).
+*  - `slot`: its slot id, already page-unique and stable (next_slot_id);
+*  - `static`: a hash of its frozen HTML;
+*  - `live`: a hash of its entry and props — only when the props are JSON-exact (seed-refs `analyze`,
+*    the JSON lane's own rule): `JSON.stringify` turns a Map, a Set, a Date or a class instance into
+*    something that two different values share, and those must not share a revived snippet.
+*    Anything else keeps a random id.
+*/
+function snippet_stable_id(d) {
+	const desc = d;
+	if (desc.m === "slot") return "slot:" + desc.id;
+	if (desc.m === "static") return "s" + fnv1a(desc.h);
+	if (desc.m === "live" && analyze(desc.p).json) return "l" + fnv1a(desc.e + "\0" + JSON.stringify(desc.p));
+}
+const SNIPPET_ONLY = /* @__PURE__ */ new Set(["snippet"]);
+/** Codec encode (legacy `OgygiaS` wire shape: the bare descriptor). Branded region snippet → its
+*  descriptor; a bare snippet → frozen static; anything else falls through. */
+function reduce_region_snippet(value) {
+	register_snippet_kind();
+	const ref = mint(value, SNIPPET_ONLY);
+	return ref === void 0 ? void 0 : ref.d;
+}
+/** 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. */
+function revive_region_snippet(desc) {
+	return make(desc);
+}
+export { REGION_SNIPPET_WIRE_KEY, SLOT_MARKER_CLOSE, next_slot_id, og_portable, prepare_region_props, reduce_region_snippet, region_snippet, register_snippet_kind, revive_region_snippet, slot_marker_open, slot_pointer };

package/dist/region.d.ts

@@ -0,0 +1,127 @@
+import { region_snippet } from "./region-snippet.js";
+import { REGION_BRAND } from "./region-brand.js";
+import { Component } from "svelte";
+/** Schedule options for a held region. `wake` = when its JS runs; `margin` = IntersectionObserver
+ * rootMargin for `wake: 'visible'`. Merged OVER the binding's baked schedule (from a `wake:` mark) —
+ * anything set here WINS; a `region: 'raw'` binding bakes nothing, so this is the whole schedule. */
+export type RegionOptions = {
+  wake?: string;
+  margin?: string;
+};
+/**
+ * The `region()` schedule argument: a function handed the component's own props (its "generated
+ * data") that returns the schedule. Always a function, never a bare object — the object case is the
+ * baked `wake:` mark on the import. The function is for a registry of `region: 'raw'` components that
+ * decides each one's timing from its data — e.g.
+ * `region(block, data, (d) => ({ wake: d.interactive ? 'load' : undefined }))`.
+ */
+export type RegionSchedule<P = Record<string, unknown>> = (data: P) => RegionOptions;
+/**
+ * The region result types erase the component's prop type — `region()` type-checks props
+ * against the component at the call site, so the stored value doesn't need to stay generic. Erasing
+ * keeps every concrete region assignable to the bare {@link RegionValue} supertype (a `C` in both a
+ * covariant `props` and a contravariant `component` position has no non-`any` supertype otherwise).
+ */
+type AnyComponent = Component<Record<string, unknown>>;
+/** A plain component. Renders in the current server pass; **awaiting** it bakes its SSR HTML so it
+ *  can cross the wire as an HTML-only ticket (no chunk, no signer — nothing to fetch). */
+export type InlineRegion = {
+  readonly [REGION_BRAND]: true;
+  readonly kind: "inline";
+  readonly component: AnyComponent;
+  readonly props: Record<string, unknown>;
+  /** Server-rendered HTML, present once the region has been awaited. What lets an inline region
+   *  (a content `body`) travel: the transport ships the markup, the runtime swaps it in and wakes
+   *  any islands inside it — the same machinery as body-swap navigation. */
+  readonly html?: string;
+  /** Content-body CSS key (`content_css_key`) for a `.svx`/`.md` body whose own scoped `<style>`
+   *  lives on no page stylesheet — the leak-free corpus is server-only, so its CSS never joins the
+   *  page's static import graph. Region.svelte resolves it through the handoff (`contentCss`) and
+   *  links the client CSS asset the plugin emitted. Absent for a body with no scoped `<style>`. */
+  readonly content_id?: string;
+};
+/** A marked component: renders inline here, or becomes a signed ticket when it crosses the wire. */
+export type DualRegion = {
+  readonly [REGION_BRAND]: true;
+  readonly kind: "dual";
+  readonly component: AnyComponent;
+  readonly props: Record<string, unknown>;
+  readonly id: string;
+  readonly module: string;
+  readonly hydrate?: string;
+  readonly hydrateMargin?: string;
+  /** Server signer, invoked by the transport at serialization. Never crosses the wire. */
+  readonly sign: (id: string, props: Record<string, unknown>) => string;
+  /**
+   * Server-only renderer, invoked when the region is **awaited** (see {@link region}). Renders
+   * the component to HTML on the server so the ticket can travel with its markup — no client fetch.
+   * Provided by the SSR region-binding leg; never crosses the wire.
+   */
+  readonly renderHtml?: (props: Record<string, unknown>) => string | Promise<string>;
+  /** Server-rendered HTML, present once the region has been awaited. Rides the wire in the ticket. */
+  readonly html?: string;
+};
+/** A held region that arrived over the wire: a signed capability, no component. */
+export type DeferredRegion = {
+  readonly [REGION_BRAND]: true;
+  readonly kind: "deferred";
+  readonly id: string;
+  readonly props: Record<string, unknown>;
+  /** Signed `/__ogygia__?id&props&exp&sig` capability the runtime fetches. */
+  readonly url: string;
+  /** Client hydrate-module URL, imported after the HTML swaps in; `''` for a static region. */
+  readonly module: string;
+  /** Wake schedule ('load' | 'idle' | 'visible' | media); absent for a static region. */
+  readonly hydrate?: string;
+  /** IntersectionObserver rootMargin when `hydrate` is `'visible'`. */
+  readonly hydrateMargin?: string;
+  /**
+   * Server-rendered HTML baked into the ticket (the region was awaited before it crossed). When
+   * present the runtime swaps it in immediately and morphs across updates — no fetch. Absent → the
+   * runtime fetches the signed `url` as usual.
+   */
+  readonly html?: string;
+};
+export type RegionValue = InlineRegion | DualRegion | DeferredRegion;
+/**
+ * What {@link region} returns: a {@link RegionValue} you can render right now with `<Region of={…} />`,
+ * AND a `PromiseLike<Region>` you can `await` to bake its server-rendered HTML into the ticket. In an
+ * async generator (`query.live`) or async remote, `yield` / `return` awaits it for you.
+ */
+export type AwaitableRegion = RegionValue & PromiseLike<RegionValue>;
+/** True for any value produced by {@link region} (or decoded from the wire). */
+export declare function isRegion(value: unknown): value is RegionValue;
+/** `region()` itself; the export below adds `region.snippet`. */
+declare function make_region<P extends Record<string, unknown>>(component: Component<P>, props: P, opts?: RegionSchedule<P>, content_id?: string): AwaitableRegion;
+/**
+ * INTERNAL (content formats): an inline region whose SSR HTML is already known — a serialized-region
+ * content body, baked at markdown-compile time. Renders like any inline region (the component is the
+ * thin `{@html}` shell the emitter produced); awaiting it is a no-op because the HTML is present from
+ * birth, so the wire crossing never pays a svelte/server render.
+ */
+export declare function prebaked_region(component: Component<Record<string, never>>, html: string, content_id?: string): AwaitableRegion;
+/**
+ * Make a held region with type-checked props.
+ *
+ * - A plain component import → an **inline** region (renders in this pass; can't cross the wire).
+ * - A component imported `with { region: 'raw' }` → a **dual** region: inline where it's made,
+ *   a signed ticket where it travels. Minting the marked form is server-only (the signer lives on
+ *   the SSR leg) — call it in a load / remote / render context.
+ *
+ * **A dual region is awaitable.** `await region(Card, props)` renders the component to HTML on
+ * the server and bakes it into the ticket, so the client swaps it in with no extra request. In an
+ * async generator (`query.live`) or an async remote, `yield region(…)` / `return region(…)` is
+ * awaited by the language, so the HTML travels automatically — LiveView over the channel you already
+ * have. A held region you *don't* await renders inline where it lands (first paint, same SSR pass).
+ */
+export declare const region: typeof make_region & {
+  snippet: typeof region_snippet;
+};
+/**
+ * A pure-HTML region — what `import.meta.og.code()` / `.md()` inline. The html is baked at build
+ * (Shiki / markdown), so this is an INLINE region whose component ({@link RawHtml}) simply renders
+ * the html in the page's own SSR pass. Static by construction: it ships as HTML and no client JS of
+ * its own. Rendered like any region: `<Region of={…} />`.
+ */
+export declare function og_html_region(html: string): InlineRegion;
+export { REGION_BRAND };

package/dist/region.js

@@ -0,0 +1,162 @@
+import { region_snippet } from "./region-snippet.js";
+import { with_portable_forms } from "./portable-form.js";
+import { REGION_BRAND } from "./region-brand.js";
+import { kit_page_facts_tail, kit_page_ready, kit_render_context } from "./server/kit-context.js";
+import { region_css_tags } from "./server/html-scan.js";
+import RawHtml from "./RawHtml.svelte";
+// src/region.ts
+/** Brand so the transport can recognize a region without false-matching plain objects. */
+/** context.ts's LAKE key (`isInLake`), by its global name — context.ts reaches virtual modules. */
+const LAKE_SUBTREE_KEY = Symbol.for("ogygia.lake-subtree");
+/** True for any value produced by {@link region} (or decoded from the wire). */
+function isRegion(value) {
+	return typeof value === "object" && value !== null && value[REGION_BRAND] === true;
+}
+function isBinding(value) {
+	return (typeof value === "object" || typeof value === "function") && value !== null && typeof value.__ogRegion === "string";
+}
+/** `region()` itself; the export below adds `region.snippet`. */
+function make_region(component, props, opts, content_id) {
+	const p = props ?? {};
+	const o = opts ? opts(props) : void 0;
+	if (isBinding(component)) {
+		if (!component.__component || !component.__sign) {
+			if (typeof component === "function") return make_inline_awaitable({
+				[REGION_BRAND]: true,
+				kind: "inline",
+				component,
+				props: p,
+				...content_id ? { content_id } : {}
+			});
+			throw new Error("[ogygia] a `with { region: 'raw' }` component must be turned into a region on the server (the signer lives server-side). Call region() in a load / remote / render context, not in client code.");
+		}
+		const hydrate = o?.wake ?? component.__hydrate;
+		const hydrateMargin = o?.margin ?? component.__hydrateMargin;
+		return make_awaitable({
+			[REGION_BRAND]: true,
+			kind: "dual",
+			component: component.__component,
+			props: p,
+			id: component.__ogRegion,
+			module: component.__module,
+			...hydrate ? { hydrate } : {},
+			...hydrateMargin ? { hydrateMargin } : {},
+			sign: component.__sign,
+			...component.__renderHtml ? { renderHtml: component.__renderHtml } : {}
+		});
+	}
+	return make_inline_awaitable({
+		[REGION_BRAND]: true,
+		kind: "inline",
+		component,
+		props: p,
+		...content_id ? { content_id } : {}
+	});
+}
+/**
+* Give an inline region a non-enumerable `then` so `await`-ing it (server-side) renders the
+* component to HTML and resolves to a plain (non-thenable) inline region carrying that HTML — which
+* is what lets it cross the wire as an HTML-only ticket (see the transport). Mirrors
+* {@link make_awaitable} for duals; `svelte/server` is imported lazily and only on the server, so
+* this module stays browser-safe. Awaiting on the client settles to an unchanged copy.
+*/
+function make_inline_awaitable(inline) {
+	Object.defineProperty(inline, "then", {
+		enumerable: false,
+		configurable: true,
+		writable: true,
+		value(onFulfilled, onRejected) {
+			const run = async () => {
+				if (typeof document !== "undefined") return { ...inline };
+				if (inline.html != null) return { ...inline };
+				const { render } = await import("svelte/server");
+				await kit_page_ready();
+				const context = kit_render_context();
+				context.set(LAKE_SUBTREE_KEY, true);
+				const r = await render(inline.component, {
+					props: inline.props,
+					context
+				});
+				const nested = region_css_tags(r.head);
+				return {
+					...inline,
+					html: nested + r.body + kit_page_facts_tail()
+				};
+			};
+			return run().then(onFulfilled, onRejected);
+		}
+	});
+	return inline;
+}
+/**
+* Give a dual region a non-enumerable `then` so `await`-ing it renders the component to HTML and
+* resolves to a plain (non-thenable) dual region carrying that HTML. Non-enumerable so a spread or
+* `devalue` walk never copies it (which would re-arm the thenable / try to serialize a function);
+* the transport reads only the data fields. A held region with no `renderHtml` (SSR leg absent) is left
+* un-awaitable — awaiting it would be a no-op and only masks a mis-wired build.
+*/
+function make_awaitable(dual) {
+	if (!dual.renderHtml) return dual;
+	Object.defineProperty(dual, "then", {
+		enumerable: false,
+		configurable: true,
+		writable: true,
+		value(onFulfilled, onRejected) {
+			const run = async () => {
+				const html = dual.renderHtml ? await dual.renderHtml(with_portable_forms(dual.props)) : void 0;
+				return {
+					...dual,
+					...html != null ? { html } : {}
+				};
+			};
+			return run().then(onFulfilled, onRejected);
+		}
+	});
+	return dual;
+}
+/**
+* INTERNAL (content formats): an inline region whose SSR HTML is already known — a serialized-region
+* content body, baked at markdown-compile time. Renders like any inline region (the component is the
+* thin `{@html}` shell the emitter produced); awaiting it is a no-op because the HTML is present from
+* birth, so the wire crossing never pays a svelte/server render.
+*/
+function prebaked_region(component, html, content_id) {
+	return make_inline_awaitable({
+		[REGION_BRAND]: true,
+		kind: "inline",
+		component,
+		props: {},
+		html,
+		...content_id ? { content_id } : {}
+	});
+}
+/**
+* Make a held region with type-checked props.
+*
+* - A plain component import → an **inline** region (renders in this pass; can't cross the wire).
+* - A component imported `with { region: 'raw' }` → a **dual** region: inline where it's made,
+*   a signed ticket where it travels. Minting the marked form is server-only (the signer lives on
+*   the SSR leg) — call it in a load / remote / render context.
+*
+* **A dual region is awaitable.** `await region(Card, props)` renders the component to HTML on
+* the server and bakes it into the ticket, so the client swaps it in with no extra request. In an
+* async generator (`query.live`) or an async remote, `yield region(…)` / `return region(…)` is
+* awaited by the language, so the HTML travels automatically — LiveView over the channel you already
+* have. A held region you *don't* await renders inline where it lands (first paint, same SSR pass).
+*/
+const region = Object.assign(make_region, { snippet: region_snippet });
+/**
+* A pure-HTML region — what `import.meta.og.code()` / `.md()` inline. The html is baked at build
+* (Shiki / markdown), so this is an INLINE region whose component ({@link RawHtml}) simply renders
+* the html in the page's own SSR pass. Static by construction: it ships as HTML and no client JS of
+* its own. Rendered like any region: `<Region of={…} />`.
+*/
+function og_html_region(html) {
+	return {
+		[REGION_BRAND]: true,
+		kind: "inline",
+		component: RawHtml,
+		props: { html }
+	};
+}
+export { REGION_BRAND, isRegion, og_html_region, prebaked_region, region };

package/dist/request-event.d.ts

@@ -0,0 +1 @@
+export declare function requestEvent<E = unknown>(): E | null;