@ogygia/core 0.0.0 → 0.11.1

package/dist/compiler/region/emit.js

@@ -0,0 +1,286 @@
+import { lazyEntryVirtualId, regionBindingVirtualId } from "../ids.js";
+// src/compiler/region/emit.ts
+/**
+* Region EMIT — codegen from a lowered descriptor to per-island virtual-module SOURCE. Pure leaves:
+* `descriptor → source string`, no state, no AST. The one shared set of emitters the `.svelte` host
+* and the `.ts` registry both call, so a `wake:` mark lowers to byte-identical artifacts from either
+* entry point:
+*   - the ENTRY  (`island_entry_source` / `region_entry_source`) — a JS re-export of the real component;
+*   - the WRAPPER (`island_wrapper_source`) — the mountable `.svelte` that renders `<ogygia-region>`;
+*   - the BINDING legs (`make_region_binding` / `wrapper_attach_binding` / `make_wake_island`) — the
+*     leg-split descriptor (SSR carries the signer + server render; client is metadata-only).
+*/
+/**
+* Source of the generated `__renderHtml(props)` for a binding's SSR leg. The returned HTML must be
+* self-sufficient when it crosses a wire, so it carries stylesheets THREE ways:
+* - the component's OWN `<link>`s (its island entry's CSS assets — the page never imported it);
+* - links NESTED regions emitted into `render().head` (a region rendered inside this render pass —
+*   props-composition, a recomposer's leaves — emits its `<link>`s via `svelte:head`, and keeping
+*   only `.body` would silently drop them: the leaf arrives unstyled);
+* - the body itself (which may contain nested self-describing `<ogygia-region>` island markup).
+*/
+function render_html_source(moduleUrl) {
+	return `(props) => __ogRegionHtml(__ogRegionComp, ${JSON.stringify(moduleUrl)}, props)`;
+}
+/**
+* The component-import line for a generated module — a NAMED export (`import { Header as X } from
+* '@barrel'`, the asRegion/barrel escape hatch) or a plain default (`import X from './X.svelte'`, a
+* `.svelte` file or a package default). `exportName` is undefined/`'default'` for the default case.
+*/
+function component_import_line(local, spec, exportName) {
+	return exportName && exportName !== "default" ? `import { ${exportName} as ${local} } from ${JSON.stringify(spec)};` : `import ${local} from ${JSON.stringify(spec)};`;
+}
+/** JS re-export of the real component — the held region's entry (SSR render + client hydrate). */
+function region_entry_source(componentPath, iid, exportName) {
+	return component_import_line(`__OgygiaComp_${iid}`, componentPath, exportName) + `
+export default __OgygiaComp_${iid};\n`;
+}
+/**
+* The island ENTRY module — a JS re-export of the real component, loaded on both client hydrate and
+* server render. The transportables import registers every `[ogygia.wire]` codec before props decode,
+* so an island receiving a transportable prop never needs to import the class itself. Shared by the
+* `.svelte` host and the `.ts` registry (a `wake:` mark) so a mountable binding is built the same way
+* from either.
+*/
+function island_entry_source(componentPath, iid, exportName) {
+	return `import 'virtual:ogygia/transportables-eager';\n` + component_import_line(`__OgygiaComp_${iid}`, componentPath, exportName) + `
+export default __OgygiaComp_${iid};\n` + FOREIGN_HYDRATE_MARK + `import { og_entry_hydrate as __og_hy, og_entry_unmount as __og_unmount } from 'ogygia/internal';
+export function __og_hydrate(target, props, options) {
+\treturn __og_hy(__OgygiaComp_${iid}, target, props, options);\n}\nexport { __og_unmount };\n`;
+}
+/** Where an island entry's foreign-hydrate exports begin (compiler/driver.ts cuts from here). */
+const FOREIGN_HYDRATE_MARK = "// og:foreign-hydrate\n";
+/**
+* The island WRAPPER (`.svelte`) — a MOUNTABLE component that renders `<ogygia-region>` on its wake
+* schedule. Placing it (`<C/>`, `<svelte:component this={C}/>`) emits the shell; the island's JS is
+* fetched only when the shell wakes (e.g. `wake: 'visible'` → on scroll-into-view). Shared by the
+* `.svelte` host and the `.ts` registry. `entry_url` is the resolved client/dev module URL the caller
+* computes (ctx-dependent); `lang` is the `<script>` lang attribute (`''` for plain JS).
+*/
+function island_wrapper_source(iid, componentPath, entryPath, strategy, options, exportName, entry_url, lang) {
+	const strategy_attrs = strategy_to_attr(strategy, options);
+	const persist_attr = options?.keep ? ` __keep={${JSON.stringify(options.keep)}}` : "";
+	return `<script${lang}>\n\timport { Region as OgygiaRegion__Wrapper } from 'ogygia/internal';\n\timport __OgygiaEntry from ${JSON.stringify(entryPath)};\n\t${component_import_line("__OgygiaCss", componentPath, exportName)}\n\tlet { children, ...__props } = $props();\n<\/script>\n<OgygiaRegion__Wrapper __mode="island" ${strategy_attrs}${persist_attr} __entry={${JSON.stringify(entry_url)}} __component={__OgygiaEntry} __css={__OgygiaCss} {__props} {children} />\n`;
+}
+/**
+* The island wrapper's CLIENT leg (a csr=true-capable host imports it; Kit hydrates the island
+* inline as a normal component). The SSR wrapper imports the component statically — it must
+* render. The client wrapper must NOT: Kit links a route's `node.stylesheets` and preloads from the
+* page's STATIC client graph, so a registry of N marked blocks imported by a csr=true route linked
+* every block's CSS + chunk on every page (a newsroom page: 172 stylesheets for 4 islands). The
+* component therefore comes through `lazy_entry_source` — a top-level-await module that imports
+* the real entry only for the islands this document RENDERED (the SSR stamped a
+* `<meta name="ogygia-kit-island">` per rendered island), so Kit still hydrates them in place with
+* the component in hand, and a block nobody rendered costs nothing. Mounted fresh on a Kit
+* client-side navigation (no SSR, no stamp), the wrapper loads the entry on demand and renders once
+* it lands — a client render, so no hydration to mismatch.
+*/
+function island_wrapper_client_source(iid, lazyPath, strategy, options, entry_url, lang) {
+	const strategy_attrs = strategy_to_attr(strategy, options);
+	const persist_attr = options?.keep ? ` __keep={${JSON.stringify(options.keep)}}` : "";
+	return `<script${lang}>\n\timport { Region as OgygiaRegion__Wrapper } from 'ogygia/internal';\n\timport __OgygiaEntry, { load as __OgygiaLoad } from ${JSON.stringify(lazyPath)};\n\tlet { children, ...__props } = $props();\n<\/script>\n<OgygiaRegion__Wrapper __mode="island" ${strategy_attrs}${persist_attr} __entry={${JSON.stringify(entry_url)}} __component={__OgygiaEntry} __load={__OgygiaLoad} {__props} {children} />\n`;
+}
+/**
+* The client wrapper's component source (`lazyEntryVirtualId`). Decides ONCE, at module
+* evaluation — before Kit hydrates, because Kit awaits the page node's import and a top-level
+* await holds it. The two facts it reads are the document's own: `documentIsCsrTrue()` (the ONE
+* csr fact Region reads on both legs) and the `<meta name="ogygia-kit-island">` stamp Region
+* emits per rendered inline island (context.ts `claim_kit_island`).
+*   - not a Kit-hydrated document (the runtime woke this island's parent; no stamp exists there):
+*     import the entry now — a nested island must be in hand when its parent hydrates;
+*   - a Kit document that rendered this island: import the entry now, Kit hydrates it in place;
+*   - a Kit document that did NOT render it (an unrendered registry block): `undefined`, nothing
+*     fetched, nothing linked — `load()` is the on-demand path a client-side navigation takes.
+* `entry_url` is the same string Region bakes into the stamp (`__entry`), on both legs.
+*/
+function lazy_entry_source(entryPath, entry_url) {
+	const entry = JSON.stringify(entryPath);
+	return `import { documentIsCsrTrue } from 'ogygia/internal';\nconst rendered = typeof document !== 'undefined' && !!document.querySelector(${JSON.stringify(`meta[name="ogygia-kit-island"][content=${JSON.stringify(entry_url)}]`)});\nexport default documentIsCsrTrue() && !rendered ? undefined : (await import(${entry})).default;\nexport const load = () => import(${entry}).then((m) => m.default);\n`;
+}
+/**
+* Build the held-region descriptor shared by the `.svelte` and `.ts` paths. It ALWAYS carries a
+* client chunk + `__module` (the region MIGHT be woken); when used statically the chunk is simply
+* never fetched (HTML only at runtime). Two marker flavors feed it:
+*   - `wake: 'x'`      → bakes `__hydrate: 'x'` — `region(C, props)` wakes on that schedule.
+*   - `region: 'raw'`  → bakes NO schedule — `region(C, props, { wake })` sets it at the call.
+* `region()` reads `opts.wake ?? binding.__hydrate`, so a baked schedule is the default and the call
+* can override. `kind` is always `'hydrate'` so the chunk is emitted; `server:true` — the endpoint
+* renders the HTML either way.
+*/
+function make_region_binding(opts) {
+	let meta = `__ogRegion: ${JSON.stringify(opts.iid)}, __module: ${JSON.stringify(opts.moduleUrl)}`;
+	if (opts.hydrate) meta += `, __hydrate: ${JSON.stringify(opts.hydrate)}`;
+	if (opts.hydrate && opts.hydrateMargin != null) meta += `, __hydrateMargin: ${JSON.stringify(opts.hydrateMargin)}`;
+	return {
+		id: opts.iid,
+		virtualPath: opts.entryPath,
+		source: region_entry_source(opts.componentPath, opts.iid, opts.exportName),
+		bindingPath: regionBindingVirtualId(opts.iid),
+		bindingSsrSource: component_import_line("__ogRegionComp", opts.componentPath, opts.exportName) + `
+import { makeRegionEndpoint as __ogRegionSign, render_region_html as __ogRegionHtml } from 'ogygia/internal/server';
+export default { ${meta}, __component: __ogRegionComp, __sign: __ogRegionSign, __renderHtml: ${render_html_source(opts.moduleUrl)} };\n`,
+		bindingClientSource: `export default { ${meta} };\n`,
+		hostPath: opts.hostPath,
+		componentPath: opts.componentPath,
+		server: true,
+		kind: "hydrate",
+		held: true,
+		lakes: [],
+		identity: opts.identity
+	};
+}
+/**
+* A `wake`-marked import is rewritten to a binding that is BOTH placeable and holdable: `<C/>` (or a
+* dynamic `<C/>` portable binding) renders the island wrapper, while `region(C)` reads a descriptor.
+* We get both from ONE binding by attaching the descriptor fields onto the wrapper component as own
+* properties — Svelte ignores them when rendering `<C/>`, and `region()` sees `__ogRegion` and reads
+* `__component`/`__sign`/`__hydrate`. The baked `__hydrate` is the mark's schedule; a `region()` call
+* can still override it. Leg-split like a held descriptor: the SSR leg carries the signer + server
+* render (server-only), the client leg is metadata. Returns `{ ssr, client }` module sources.
+*/
+function wrapper_attach_binding(opts) {
+	let meta = `__ogRegion: ${JSON.stringify(opts.iid)}, __module: ${JSON.stringify(opts.moduleUrl)}`;
+	if (opts.hydrate) meta += `, __hydrate: ${JSON.stringify(opts.hydrate)}`;
+	if (opts.hydrate && opts.hydrateMargin != null) meta += `, __hydrateMargin: ${JSON.stringify(opts.hydrateMargin)}`;
+	return {
+		ssr: `import __OgygiaWrap from ${JSON.stringify(opts.wrapperPath)};\n` + component_import_line("__ogRegionComp", opts.componentPath, opts.exportName) + `
+import { makeRegionEndpoint as __ogRegionSign, render_region_html as __ogRegionHtml } from 'ogygia/internal/server';
+Object.assign(__OgygiaWrap, { ${meta}, __component: __ogRegionComp, __sign: __ogRegionSign, __renderHtml: ${render_html_source(opts.moduleUrl)} });\nexport default __OgygiaWrap;\n`,
+		client: `import __OgygiaWrap from ${JSON.stringify(opts.wrapperPath)};\nObject.assign(__OgygiaWrap, { ${meta} });\nexport default __OgygiaWrap;\n`
+	};
+}
+/**
+* The complete island record for a `wake:` mark — the ONE emitter shared by the `.svelte` host (a
+* placed `import X with { wake }`) and the `.ts` registry (a `wake:` mark handed to a renderer). The
+* binding it produces is BOTH mountable (placing it, incl. via `<svelte:component>`, renders the
+* `<ogygia-region>` shell that fetches the island JS only on its schedule) AND holdable (the descriptor
+* fields ride on the wrapper, so `region(C)` still works). Threading both paths through here is what
+* keeps `.svelte` and `.ts` `wake:` byte-identical — a `.ts` `wake: 'visible'` is exactly a `.svelte`
+* `wake: 'visible'`. Callers own the host-specific import rewrite; this owns the record.
+* `moduleUrl` is the resolved client/dev module URL; `lang` is the wrapper `<script>` lang (`''` = JS).
+*/
+function make_wake_island(opts) {
+	const margin = opts.strategy === "visible" ? opts.options?.margin : void 0;
+	const attach = wrapper_attach_binding({
+		iid: opts.iid,
+		wrapperPath: opts.wrapperPath,
+		componentPath: opts.componentPath,
+		moduleUrl: opts.moduleUrl,
+		hydrate: opts.strategy,
+		hydrateMargin: margin,
+		exportName: opts.exportName
+	});
+	const lazyPath = lazyEntryVirtualId(opts.iid);
+	return {
+		id: opts.iid,
+		virtualPath: opts.entryPath,
+		wrapperPath: opts.wrapperPath,
+		wrapperSource: island_wrapper_source(opts.iid, opts.componentPath, opts.entryPath, opts.strategy, opts.options, opts.exportName, opts.moduleUrl, opts.lang),
+		wrapperClientSource: island_wrapper_client_source(opts.iid, lazyPath, opts.strategy, opts.options, opts.moduleUrl, opts.lang),
+		lazyPath,
+		lazySource: lazy_entry_source(opts.entryPath, opts.moduleUrl),
+		bindingPath: regionBindingVirtualId(opts.iid),
+		bindingSsrSource: attach.ssr,
+		bindingClientSource: attach.client,
+		source: island_entry_source(opts.componentPath, opts.iid, opts.exportName),
+		hostPath: opts.hostPath,
+		componentPath: opts.componentPath,
+		server: !!opts.held,
+		...opts.held ? { held: true } : {},
+		kind: "hydrate",
+		lakes: [],
+		identity: opts.identity,
+		strategy: opts.strategy,
+		keep: opts.options?.keep
+	};
+}
+/**
+* The SERVER-island wrapper (`.svelte`) — `render: 'deferred'`: a hole whose HTML is fetched on the
+* `wake` schedule. `__defer` carries the fetch schedule; `__cacheTtl` (when signed) sets the hole's
+* response cache; a deferred island that ALSO hydrates carries `__hydrate` + `__module` (its client
+* entry URL). `module_url` is the resolved client/dev entry URL (used only when it hydrates); `lang`
+* is the wrapper `<script>` lang.
+*/
+function server_wrapper_source(iid, componentPath, entryPath, options, exportName, module_url, lang, component = true) {
+	const deferred_hydrate = !!options?.hydrate;
+	const fetch_when = options?.when || "load";
+	let server_attrs = `__defer={${JSON.stringify(fetch_when)}}`;
+	if (options?.stitch) server_attrs += ` __stitch={${JSON.stringify(options.stitch)}}`;
+	if (options?.prefetch) server_attrs += ` __prefetch={${JSON.stringify(options.prefetch)}}`;
+	if (options?.margin != null) server_attrs += ` __margin={${JSON.stringify(options.margin)}}`;
+	if (options?.cacheTtlSec != null) server_attrs += ` __cacheTtl={${JSON.stringify(options.cacheTtlSec)}}`;
+	if (deferred_hydrate) {
+		server_attrs += ` __hydrate={${JSON.stringify(options.hydrate)}}`;
+		server_attrs += ` __module={${JSON.stringify(module_url)}}`;
+		if (options.hydrateMargin != null) server_attrs += ` __hydrateMargin={${JSON.stringify(options.hydrateMargin)}}`;
+	}
+	return `<script${lang}>\n\timport { Region as OgygiaRegion__Wrapper } from 'ogygia/internal';\n` + (component ? `\timport __OgygiaEntry from ${JSON.stringify(entryPath)};\n\t${component_import_line("__OgygiaCss", componentPath, exportName)}\n` : "") + `	let { ogygiaFallback, ...__props } = \$props();
+<\/script>
+<OgygiaRegion__Wrapper __mode="server" __entry={${JSON.stringify(iid)}} ` + (component ? `__component={__OgygiaEntry} __css={__OgygiaCss} ` : "") + `{__props} ${server_attrs} {ogygiaFallback} />\n`;
+}
+/**
+* The LAKE wrapper (`.svelte`) — `render: page, wake: none`: a frozen region inside a hydrated island.
+* A `swr` lake carries an endpoint (`__when` + `__props`) to remount on its schedule; `cache`/`empty`
+* are wrapper-only. Static `<OgygiaLakeInner>` (not dynamic) preserves the LAKE-ENVELOPE; the client
+* build swaps that import for the render-nothing stub. `lang` is the wrapper `<script>` lang.
+*/
+function lake_wrapper_source(iid, componentPath, options, exportName, lang) {
+	const remount = options?.remount || "cache";
+	const needs_endpoint = remount === "swr";
+	const when = options?.when || (needs_endpoint ? "load" : void 0);
+	let attrs = `__entry={${JSON.stringify(iid)}} __remount={${JSON.stringify(remount)}}`;
+	if (options?.maxAgeMs != null) attrs += ` __maxAge={${JSON.stringify(options.maxAgeMs)}}`;
+	if (options?.onExpire) attrs += ` __onExpire={${JSON.stringify(options.onExpire)}}`;
+	if (needs_endpoint) {
+		attrs += ` __when={${JSON.stringify(when || "load")}} __props={__props}`;
+		if (options?.margin != null) attrs += ` __margin={${JSON.stringify(options.margin)}}`;
+	}
+	return `<script${lang}>\n\timport { Region as OgygiaRegion__Wrapper } from 'ogygia/internal';\n\t${component_import_line("OgygiaLakeInner", componentPath, exportName)}\n\tlet __props = $props();\n<\/script>\n<OgygiaRegion__Wrapper __mode="lake" ${attrs}><OgygiaLakeInner {...__props} /></OgygiaRegion__Wrapper>\n`;
+}
+/** Map a hydrate strategy (+ options) to the Island wrapper attribute markup. */
+function strategy_to_attr(strategy, options) {
+	if (!strategy || strategy === "load") return "load";
+	if (strategy === "idle") return "idle";
+	if (strategy === "interaction") return "interaction";
+	if (strategy === "visible") return options && options.margin != null ? `visible=${JSON.stringify(options.margin)}` : "visible";
+	return `media=${JSON.stringify(strategy)}`;
+}
+/** Rewrite `$app/{state,stores,navigation}` string literals to absolute shim paths. */
+const APP_SHIM_IMPORT = /(['"])\$app\/(state|stores|navigation)\1/g;
+const REGEXP_META = /[.*+?^${}()|[\]\\]/g;
+const IMPORT_AS_CLAUSE = /^(.+?)(?:\s+as\s+(\w+))?$/;
+/**
+* Rewrite a lake binding's import to the render-nothing placeholder (client island modules only).
+* Default imports are repointed; named imports drop that specifier (and keep siblings) then add a
+* default import of the placeholder under the same local name.
+*
+* @internal Used by the plugin client emit and unit tests.
+*/
+function rewrite_lake_import_to_placeholder(src, local, placeholder) {
+	const esc = local.replace(REGEXP_META, "\\$&");
+	const ph = JSON.stringify(placeholder);
+	src = src.replace(new RegExp(`import\\s+${esc}\\s+from\\s+(['"])[^'"]+\\1`, "g"), `import ${local} from ${ph}`);
+	src = src.replace(new RegExp(`import\\s*\\{([^}]*)\\}\\s*from\\s*(['"])([^'"]+)\\2`, "g"), (full, specs, _q, from) => {
+		const parts = String(specs).split(",").map((s) => s.trim()).filter(Boolean);
+		const kept = [];
+		let hit = false;
+		for (const p of parts) {
+			const m = p.match(IMPORT_AS_CLAUSE);
+			if (!m) {
+				kept.push(p);
+				continue;
+			}
+			const imported = m[1].trim();
+			if ((m[2] || imported).trim() === local) {
+				hit = true;
+				continue;
+			}
+			kept.push(p);
+		}
+		if (!hit) return full;
+		const named = kept.length ? `import { ${kept.join(", ")} } from ${JSON.stringify(from)};` : "";
+		return `import ${local} from ${ph};${named ? "\n	" + named : ""}`;
+	});
+	return src;
+}
+export { APP_SHIM_IMPORT, FOREIGN_HYDRATE_MARK, component_import_line, island_entry_source, island_wrapper_client_source, island_wrapper_source, lake_wrapper_source, lazy_entry_source, make_region_binding, make_wake_island, rewrite_lake_import_to_placeholder, server_wrapper_source, strategy_to_attr };

package/dist/compiler/region/identity.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Fingerprint of a region mark for dedupe. Same component path + same key → one wrapper/entry.
+ * @param mark
+ */
+export declare function strategyKey(mark: {
+  strategy: string;
+  options?: Record<string, unknown> | null;
+}): string;
+/**
+ * Cross-host stable identity: posix component path + {@link strategyKey}.
+ * Drives region ids so multiple hosts / import sites / `<A />` usages share one module.
+ */
+export declare function regionIdentity(componentRelPath: string, mark: {
+  strategy: string;
+  options?: Record<string, unknown> | null;
+}): string;
+/**
+ * A server-rendered region's RENDER identity: what the islands endpoint renders — the component
+ * alone (posix path, `#export` for a named one). A region id names a WRAPPER (the component ⊕ its
+ * page-side schedule ⊕ the build's salt); the endpoint's render of a component is the same under
+ * every schedule, so a capability that names its render identity is answered by any build that
+ * still serves the component as a region, whatever its schedule, its preset or the build's salt.
+ * Unsalted: it is never a file name (nothing to enumerate) and only rides inside a signed URL.
+ * @param identityOrPath a {@link regionIdentity} (its component half is taken) or a component path
+ */
+export declare function renderId(identityOrPath: string): string;
+/** Hash an identity string (optional production salt) → 12-char region id. */
+export declare function regionId(identityKey: string, salt?: string): string;

package/dist/compiler/region/identity.js

@@ -0,0 +1,75 @@
+import { createHash } from "../host.js";
+// src/compiler/region/identity.ts
+/**
+* Region identity — the JOIN KEY of the whole compiler. Two files that mark the same component the
+* same way independently mint the SAME id, and the linker collapses them; that is why a blind,
+* file-local front-end and a dumb cross-file reducer stay decoupled. Pure functions, no state.
+*
+*   strategyKey    — a mark's dedupe fingerprint (schedule + the options baked into the wrapper)
+*   regionIdentity — posix component path ⊕ strategyKey (cross-host stable identity)
+*   regionId       — hash(identity, optional prod salt) → the 12-char content-hashed id
+*/
+const PATH_SEP = /[/\\]/;
+/**
+* Fingerprint of a region mark for dedupe. Same component path + same key → one wrapper/entry.
+* @param mark
+*/
+function strategyKey(mark) {
+	const o = mark.options || {};
+	if (mark.strategy === "server") {
+		let k = `defer:${o.when ?? "load"}`;
+		if (o.margin != null) k += `:margin:${o.margin}`;
+		if (o.cacheTtlSec != null) k += `:ttl:${o.cacheTtlSec}`;
+		if (o.stitch) k += `:stitch:${o.stitch}`;
+		if (o.prefetch) k += `:prefetch:${o.prefetch}`;
+		if (o.hydrate) {
+			k += `+hydrate:${o.hydrate}`;
+			if (o.hydrateMargin != null) k += `:hmargin:${o.hydrateMargin}`;
+		}
+		return k;
+	}
+	if (mark.strategy === "lake") {
+		let k = `lake:${o.remount || "cache"}`;
+		if (o.when) k += `:when:${o.when}`;
+		if (o.maxAgeMs != null) k += `:maxAge:${o.maxAgeMs}`;
+		if (o.onExpire) k += `:onExpire:${o.onExpire}`;
+		if (o.margin != null) k += `:margin:${o.margin}`;
+		return k;
+	}
+	if (mark.strategy === "held") {
+		let k = `region:${o.hydrate || "raw"}`;
+		if (o.hydrateMargin != null) k += `:hmargin:${o.hydrateMargin}`;
+		return k;
+	}
+	let k = `hydrate:${mark.strategy}`;
+	if (o.margin != null) k += `:margin:${o.margin}`;
+	if (o.keep != null) k += `:keep:${o.keep}`;
+	return k;
+}
+/**
+* Cross-host stable identity: posix component path + {@link strategyKey}.
+* Drives region ids so multiple hosts / import sites / `<A />` usages share one module.
+*/
+function regionIdentity(componentRelPath, mark) {
+	return `${String(componentRelPath).split(PATH_SEP).join("/")}\0${strategyKey(mark)}`;
+}
+/**
+* A server-rendered region's RENDER identity: what the islands endpoint renders — the component
+* alone (posix path, `#export` for a named one). A region id names a WRAPPER (the component ⊕ its
+* page-side schedule ⊕ the build's salt); the endpoint's render of a component is the same under
+* every schedule, so a capability that names its render identity is answered by any build that
+* still serves the component as a region, whatever its schedule, its preset or the build's salt.
+* Unsalted: it is never a file name (nothing to enumerate) and only rides inside a signed URL.
+* @param identityOrPath a {@link regionIdentity} (its component half is taken) or a component path
+*/
+function renderId(identityOrPath) {
+	const nul = identityOrPath.indexOf("\0");
+	const component = (nul === -1 ? identityOrPath : identityOrPath.slice(0, nul)).split(PATH_SEP).join("/");
+	return createHash("md5").update(`render\0${component}`).digest("hex").slice(0, 12);
+}
+/** Hash an identity string (optional production salt) → 12-char region id. */
+function regionId(identityKey, salt = "") {
+	const msg = salt ? `${salt}\0${identityKey}` : identityKey;
+	return createHash("md5").update(msg).digest("hex").slice(0, 12);
+}
+export { regionId, regionIdentity, renderId, strategyKey };

package/dist/compiler/region/ir.d.ts

@@ -0,0 +1,65 @@
+import { ImportKeys } from "./transform.js";
+import { AstNode } from "../parse/oxc.js";
+/** A Svelte / ESTree node as the front-end walks it — dynamic access, loosely typed by design. */
+export type SvelteNode = AstNode;
+/** A region mark — the `{ strategy, options }` a `with { … }` clause or `asRegion(…)` resolves to. */
+export interface RegionMark {
+  strategy: string;
+  options: Record<string, unknown>;
+}
+/** One host import the analyze pass indexed: its ImportDeclaration node + the `with {…}`-stripped text. */
+export interface HostImport {
+  /** the ImportDeclaration (or the synthetic one an asRegion call stands for), with its offsets */
+  node: SvelteNode & {
+    start: number;
+    end: number;
+  };
+  cleaned: string;
+}
+/**
+ * `FileIR` — analyze's output, lower's input. Everything the lowering pass reads about one file,
+ * bundled as plain data. Cross-file knowledge never enters here: a file's IR knows only its own
+ * source, never what another file did (the join is by content-hashed region id, in the Program).
+ */
+export interface FileIR {
+  source: string;
+  id: string;
+  /** the parsed Svelte AST (root `.fragment` / `.instance` / `.module`). */
+  ast: SvelteNode;
+  /** `<script>` (instance) top-level statements. */
+  instance_body: SvelteNode[];
+  /** `<script module>` top-level statements. */
+  module_body: SvelteNode[];
+  /** the `<script>` lang attribute (`''` for plain JS) — baked into generated wrapper scripts. */
+  lang: string;
+  /** posix root-relative host path — the stable prefix of error messages + snippet identities. */
+  rel_host: string;
+  /** the resolved import-attribute key names for this build. */
+  import_keys: ImportKeys;
+  /** localName → { node, cleaned } for every host import. */
+  imports: Map<string, HostImport>;
+  /** localName → the region mark it carries (a `with {…}` import or an asRegion synthetic import). */
+  marked_components: Map<string, RegionMark>;
+  /** ImportDeclaration nodes to remove from the host (unused marked imports / consumed barrels). */
+  imports_to_strip: Set<{
+    start: number;
+    end: number;
+  }>;
+  /** the asRegion call sites — the local binding, the component local, and the const statement node. */
+  as_regions: Array<{
+    local: string;
+    compLocal: string;
+    node: {
+      start: number;
+      end: number;
+    };
+  }>;
+  /** the asRegion `const` statement nodes (skipped by the stray-asRegion walk + barrel-cleanup). */
+  as_region_nodes: Set<SvelteNode>;
+  /** asRegion local → the barrel export name it pulls (undefined → default import). */
+  synthetic_export: Map<string, string | undefined>;
+  /** a hydrate island with real host children was placed (the app needs the wire slot revivers). */
+  has_island_children: boolean;
+  /** the cheap island-hint gate result (a marker-less snippet-only file is not "hinted"). */
+  has_island_hint: boolean;
+}

package/dist/compiler/region/transform.d.ts

@@ -0,0 +1,178 @@
+import { IslandDescriptor } from "../program.js";
+import { regionId, regionIdentity, strategyKey } from "./identity.js";
+import { regionBindingVirtualId } from "../ids.js";
+import { foucCssVirtualId } from "../fouc-css.js";
+import { SourceMap } from "magic-string";
+import * as NodePath from "node:path";
+/** The resolved context the adapter/driver threads into a host transform. */
+interface HostCtx {
+  root: string;
+  libDir: string;
+  readFile: (abs: string) => string | null;
+  pathModule: typeof NodePath;
+  dev: boolean;
+  virtualPathFor: (hostId: string, iid: string) => string;
+  /** Absent: the island's wrapper virtual id (`wrapperVirtualId`). */
+  wrapperPathFor?: (hostId: string, iid: string) => string;
+  devUrlFor: (virtualPath: string) => string;
+  /**
+   * The REAL source file a module derives from — the resolution base for its relative specifiers.
+   * A generated entry (a portable-snippet synth is authored markup re-processed under a
+   * `virtual:ogygia/…` id) has no directory of its own: every `./x` / `../x` inside it must resolve
+   * against the file the slice was cut from, exactly as the driver's `resolve_id` already rebases
+   * that entry's plain imports. Identity for a real file. Optional for legacy callers (= identity).
+   */
+  originOf?: (id: string) => string;
+  /** Install-independent identity (`<pkg-name>/<rel>`) for files under a declared `ogygia.files`
+   *  package — `null`/absent falls back to root-relative (see CompileCtx.pkg_identity). */
+  pkg_identity?: (abs: string) => string | null;
+  /** SvelteKit `appDir` (default `_app`) — where island chunks are emitted + served (base-less; Kit's
+   *  `asset()` adds `base`/assets at render). */
+  appDir?: string;
+  visibleMargin: string | undefined;
+  presets: Record<string, unknown>;
+  importKeys: Partial<ImportKeys> | undefined;
+  /** Absent or empty: no salt. */
+  idSalt?: string;
+  /** Absent: true (a binding links its real wrapper; `false` links the client stub). */
+  linkVirtualIsland?: boolean;
+  /** Absent or empty: the built-in `CLIENT_BINDING_STUB`. */
+  clientBindingStub?: string;
+  routeCsr: boolean | undefined;
+  ssr: boolean;
+}
+/** The resolved context threaded into a `.ts`/`.js` region mint (`transformTsRegions`). */
+interface TsRegionCtx {
+  root: string;
+  libDir: string;
+  pathModule: typeof NodePath;
+  dev: boolean;
+  virtualPathFor: (hostId: string, iid: string) => string;
+  devUrlFor: (virtualPath: string) => string;
+  /** SvelteKit `appDir` (default `_app`) — where island chunks are emitted + served (base-less; Kit's
+   *  `asset()` adds `base`/assets at render). */
+  appDir?: string;
+  importKeys: Partial<ImportKeys> | undefined;
+  /** Absent or empty: no salt. */
+  idSalt?: string;
+  /** Guarded (typeof) — the ts-region leg falls back to `wrapperVirtualId` when absent. */
+  wrapperPathFor?: (hostId: string, iid: string) => string;
+  /** Guarded (`!= null`) — only a `visible` strategy reads it. */
+  visibleMargin?: string;
+  /** Guarded (typeof) — install-independent identity for declared `ogygia.files` package files. */
+  pkg_identity?: (abs: string) => string | null;
+}
+export declare const ISLAND_DIR = ".ogygia";
+/** True for a GENERATED island glue id (virtual island entry / wrapper / region binding, or the legacy
+ *  on-disk `.ogygia/` shape) — the ids that are ogygia's own emit, not authored app/component source. */
+export declare function is_island_path(id: string): boolean;
+/**
+ * Default import-attribute keys — the two-dial grammar. Internal role names stay `hydrate`/`defer`
+ * (the wire format + runtime keep those anchors); the user-facing ATTRIBUTE names are the values.
+ * Override via `ogygia({ importKeys })`.
+ * - `render` attribute → the MODE: `static` (inline HTML) | `deferred` (a hole, fetched) | `live`
+ *   (a hole that revalidates). Defaults to `static`.
+ * - `fetch` attribute → a `deferred` hole's TIMING, when its HTML arrives (default `load`):
+ *   `with { render: 'deferred', fetch: 'visible' }`.
+ * - `wake` attribute → when an island's JS runs (`none`: a lake). Never a hole's timing.
+ */
+export declare const DEFAULT_IMPORT_KEYS: {
+  readonly wake: "wake";
+  readonly fetch: "fetch";
+  readonly render: "render";
+  readonly preset: "preset";
+  readonly region: "region";
+};
+/**
+ * Import-attribute key names claimed by the transform
+ * (`with { wake | fetch | render | preset | region }`). Override via `ogygia({ importKeys })` when
+ * another tool already uses the default names.
+ */
+export type ImportKeys = {
+  /** When an island's JS runs (default attribute `'wake'`); `'none'` makes a lake. For `live` it is
+   * the revalidate schedule. */
+  wake: string;
+  /** A `render: 'deferred'` hole's timing — when its HTML arrives (default attribute `'fetch'`):
+   * `'load'` | `'idle'` | `'visible'` | `'interaction'` | a media query. */
+  fetch: string;
+  /** The delivery MODE (default attribute `'render'`): `static` | `deferred` | `live`. */
+  render: string;
+  /** Named preset attribute (default `'preset'`). */
+  preset: string;
+  /** Held-across-a-boundary marker (default attribute `'region'`, only value `'raw'`) — a component
+   * a registry hands to `region()` where the transform can't see the call. */
+  region: string;
+};
+export declare function normalize_import_keys(overrides?: Partial<ImportKeys> | null): ImportKeys;
+export declare function import_keys_hint(import_keys: ImportKeys): RegExp;
+/** Deterministic short id for a region (stable across dev + build).
+ * When `salt` is set (production `OGYGIA_SECRET`), ids are not offline-computable (P1-ID).
+ * Paths are always posix so SSR/client builds agree across OS path separators. */
+export declare function islandId(relHostPath: string, index: string | number, salt?: string): string;
+/**
+ * Deterministic client chunk path for a hydrate island (mirrors `og-runtime.<hash>.js`).
+ * SSR bakes this into `<ogygia-region entry>` so the sticky runtime can `import(entry)` with no
+ * app-wide regions map — Kit builds server before client, so content-hashed Vite names can't hand off.
+ */
+export declare function islandChunkFileName(iid: string, appDir?: string): string;
+/** App-internal URL for {@link islandChunkFileName}: `/<appDir>/immutable/…` (leading slash, appDir,
+ *  NO base). It is what SSR bakes onto `<ogygia-region entry>`; `Region.svelte` runs it through Kit's
+ *  `asset()` at render time, which is the sole authority on `base` / the assets CDN / relative paths —
+ *  so a base is never baked here (that would double-apply it). NOT the on-disk output filename. */
+export declare function islandPublicUrl(iid: string, appDir?: string): string;
+/** Portable wrapper module id — SSR / csr=true host binding (Island/ServerIsland/Lake shell). */
+export declare function wrapperVirtualId(iid: string): string;
+/**
+ * The local bindings a file hands to `import.meta.og.asRegion(X)`. An island's identity is keyed on
+ * the import that binds `X` (`'<specifier>#<export>'`), and the prescan derives it from the raw
+ * source on disk — so no pass that runs before the transform may rewrite that import (the debarrel
+ * pass leaves declarations binding these names alone, as it does marked imports). A textual scan on
+ * purpose: it runs before any parse, on every transformed file.
+ */
+export declare function asRegionLocals(code: string): Set<string>;
+/**
+ * csr=false CLIENT host binding target. Kit still emits those page nodes; pointing marked
+ * imports here (instead of wrappers) keeps N island wrappers/entries out of the page graph so
+ * `emitFile` owns hydrate modules and Rolldown does not thin-facade them. Hydration uses
+ * `import(entry)` only — this stub is never loaded for island JS.
+ *
+ * Beside the stub the transform emits `import 'virtual:ogygia/fouc-css/<entry>'` so Kit still
+ * links stylesheets (FOUC) via CSS-only side effects. Importing the full `.svelte` JS module
+ * dual-owns it with the emitFile island entry and Rolldown thin-facades `og-region.*`.
+ * Omitting CSS entirely orphans rules (scoped class hashes, no stylesheet).
+ */
+export declare const CLIENT_BINDING_STUB = "virtual:ogygia/client-binding-stub";
+/**
+ * The `with { region: … }` marker has ONE value — `'raw'` (an adjective: "a raw/held region"). It
+ * carries NO schedule: the wake timing is set at the `region()` call (`region(C, props, { wake })`)
+ * or, in a block tree, per node. This is the only surviving import-attribute marker for a component
+ * a registry hands to `region()` where the transform can't see the call site.
+ *
+ * @param raw the marker value
+ * @param where host label for error messages
+ * @param regionKey configured `region` attribute name (for the message)
+ */
+export declare function normalize_region_value(raw: string, where: string, regionKey?: string): void;
+/**
+ * Validate a `wake:` schedule value on a held import (a `.ts` registry / remote). Accepts the wake
+ * strategies (`load` / `idle` / `visible` / `interaction`) or a media query — the same vocabulary as
+ * a placed island's `wake:`. Returns the value unchanged (it becomes the baked `__hydrate`).
+ */
+export declare function normalize_hydrate_value(raw: string, where: string, wakeKey?: string): string;
+export declare function transformHost(source: string, id: string, ctx: HostCtx): {
+  code: string;
+  map: SourceMap;
+  islands: never[];
+} | {
+  code: string;
+  map: SourceMap;
+  islands: IslandDescriptor[];
+  hasWireCrossing: boolean;
+} | null;
+export declare function transformTsRegions(source: string, id: string, ctx: TsRegionCtx): {
+  code: string;
+  map: SourceMap;
+  islands: IslandDescriptor[];
+  hasWireCrossing: boolean;
+} | null;
+export { foucCssVirtualId, regionBindingVirtualId, regionId, regionIdentity, strategyKey };