@ogygia/core 0.0.0 → 0.11.0

package/dist/compiler/program.js

@@ -0,0 +1,242 @@
+import { path } from "./host.js";
+import { renderId } from "./region/identity.js";
+// src/compiler/program.ts
+/**
+* The `Program` — the compiler's cross-file linker / island graph. It is the ONE long-lived,
+* stateful phase: a deterministic reduction of every file's `IslandDescriptor[]` into a whole-program
+* registry, deduped by content-hashed id. The blind, file-local front-end (parse ▸ analyze ▸ lower ▸
+* emit) mints descriptors; the `Program` accumulates them — never their sources — and the linker's
+* whole-program emitters read it.
+*
+* One instance per `Compiler` session, constructed in the plugin factory closure, never module-global
+* — so Kit's throwaway plugin instance is a different `Program` and can't leak into the real build.
+*
+* State has an owner: the registry Maps + the feature-mark bag live here with the behavior over them
+* (`register` / `unregister_host` / `note_runtime_mark`). Config-free by construction — it knows the
+* descriptors, never the resolved build context (that is `CompileCtx`'s job).
+*/
+/** Strip a `?query` off a module id (host vs component vs Vite watch paths). */
+const strip_id = (id) => id ? id.split("?")[0] : id;
+/** Canonical absolute host key (query-stripped, resolved) — the registry's cross-host dedupe key. */
+const host_key = (hostPath) => path.resolve(strip_id(hostPath));
+var Program = class {
+	/** keyed by virtual path → the island's registry row (entry / wrapper / region binding) */
+	registry = /* @__PURE__ */ new Map();
+	/** Absolute module ids in an island's CLIENT dependency graph. `$app/*` resolves to shims
+	*  for these importers (virtual island module AND its transitive component imports). */
+	island_graph = /* @__PURE__ */ new Set();
+	/** iid -> entry virtual path (hydrate / defer / swr-lake) */
+	by_id = /* @__PURE__ */ new Map();
+	/** every region id -> kind (server manifest / emit) */
+	region_kinds = /* @__PURE__ */ new Map();
+	/** host abs path → region ids + virtual paths discovered on last transform of that host */
+	host_index = /* @__PURE__ */ new Map();
+	/** region id → hosts still claiming it (cross-host dedupe: don't drop shared wrappers) */
+	id_hosts = /* @__PURE__ */ new Map();
+	/** Client-leg: hydrate island ids whose deterministic chunk has been emitFile'd (dedup across the
+	*  buildStart prescan emit AND the transform-time emit that catches islands prescan can't see —
+	*  those declared inside LIBRARY components, where the host lives outside the app's `src`). */
+	emitted_island_chunks = /* @__PURE__ */ new Set();
+	/** BUILD, server leg: every module id Vite actually transformed (`host_key`-normalised) — the
+	*  server bundle's real graph. Handed to the client leg, which emits island chunks only for
+	*  islands whose HOST is in it: the prescan registers every marked import under `src/`, but a
+	*  host nothing imports (a second route tree's pages, a retired component) must not cost a
+	*  chunk — or drag its imports into a client build whose server pass never saw them (a
+	*  `.remote.ts` there fails Kit's "expected to find metadata" check). */
+	ssr_transformed = /* @__PURE__ */ new Set();
+	/** Absolute paths of app modules that define a transportable class (built during prescan). */
+	transportable_modules = /* @__PURE__ */ new Set();
+	/** PAGE MODULES (`b.pageModules()`: importers of a page specifier such as `'@ogygia/router'`, plus
+	*  files named directly — server-router definition sites) + every walked
+	*  module's import specifiers — the build data `virtual:ogygia/router-css` computes its
+	*  component closure from (see link/router-css.ts). Filled during the prescan walk. */
+	router_modules = /* @__PURE__ */ new Set();
+	module_specs = /* @__PURE__ */ new Map();
+	/** flag()/experiment() call sites the prescan OBSERVED (modules importing 'ogygia' only) —
+	*  written to node_modules/.ogygia/flags-manifest.json at build for CI flag-debt diffs. */
+	flag_sites = [];
+	/** SEED SHAPING: per module (query-less id, forward slashes), the top-level `page.data` keys its
+	*  code reads — `'all'` when a read could not be pinned to a literal key. Recorded by the driver's
+	*  transform for every module that imports Kit's page store (link/page-keys.ts); the client
+	*  `writeBundle` unions them over each island's chunk closure (link/island-deps.ts), and the
+	*  handle ships only those keys of `page.data`. */
+	page_keys = /* @__PURE__ */ new Map();
+	/** Per module that answered `'all'`: why, and on which line — the build report names it, so a
+	*  developer sees the one read that makes a page ship its whole `page.data`. */
+	page_key_reasons = /* @__PURE__ */ new Map();
+	/** Per module: the `helper(page)` calls into IMPORTED helpers the build follows at `writeBundle`
+	*  (resolve the specifier, summarize the export, fold the answer into `page_keys`). */
+	page_pending = /* @__PURE__ */ new Map();
+	/** App crosses a held region / transportable value through Kit's `transport` hook — a `.remote.*`
+	*  file, or a `region`/`site`/content import (loads & remotes that carry regions or wired values).
+	*  Set during the prescan walk; with `runtime_marks.wire` it decides whether `ogygia.transport`
+	*  (the generated `virtual:ogygia/kit-transport`) carries the codec cluster or is an empty map. */
+	crosses_wire = false;
+	/** Build-time capability marks for the sticky runtime entry. Incomplete → kitchen-sink. */
+	runtime_marks;
+	/** The resolved feature set folded into the runtime chunk name (busts the immutable URL when the
+	*  app's feature set changes, not only when ogygia's source does). Filled by the driver's prescan;
+	*  empty until then (dev serves the package entry). Both build legs prescan the same source → same
+	*  hash → the server↔client filename handoff holds. */
+	runtime_feature_hash = "";
+	constructor(init) {
+		this.runtime_marks = {
+			complete: false,
+			forms: init.forms,
+			wire: false,
+			remoteSeeds: true,
+			hydrate: [],
+			defer: [],
+			persistKeys: [],
+			router: init.router,
+			live: false,
+			lakes: false
+		};
+	}
+	note_runtime_mark(patch) {
+		const runtime_marks = this.runtime_marks;
+		if (patch.hydrate) runtime_marks.hydrate = [.../* @__PURE__ */ new Set([...runtime_marks.hydrate || [], ...patch.hydrate])];
+		if (patch.defer) runtime_marks.defer = [.../* @__PURE__ */ new Set([...runtime_marks.defer || [], ...patch.defer])];
+		if (patch.persistKeys) runtime_marks.persistKeys = [.../* @__PURE__ */ new Set([...runtime_marks.persistKeys || [], ...patch.persistKeys])];
+		if (patch.router) runtime_marks.router = true;
+		if (patch.live) runtime_marks.live = true;
+		if (patch.persist) runtime_marks.persist = true;
+		if (patch.morph) runtime_marks.morph = true;
+		if (patch.lakes) runtime_marks.lakes = true;
+		if (patch.wire) runtime_marks.wire = true;
+	}
+	/** Drop this host's claims; shared region ids (cross-host dedupe) stay until unused. */
+	unregister_host(hostPath) {
+		const { registry, island_graph, by_id, region_kinds, host_index, id_hosts } = this;
+		const key = host_key(hostPath);
+		const prev = host_index.get(key);
+		if (prev) {
+			for (const id of prev.ids) {
+				const holders = id_hosts.get(id);
+				if (holders) {
+					holders.delete(key);
+					if (holders.size === 0) {
+						id_hosts.delete(id);
+						region_kinds.delete(id);
+						by_id.delete(id);
+					}
+				} else {
+					region_kinds.delete(id);
+					by_id.delete(id);
+				}
+			}
+			for (const vpath of prev.vpaths) {
+				const entry = registry.get(vpath);
+				if (entry) {
+					const holders = id_hosts.get(entry.id);
+					if (!holders || holders.size === 0) {
+						registry.delete(vpath);
+						island_graph.delete(vpath);
+					}
+				} else {
+					registry.delete(vpath);
+					island_graph.delete(vpath);
+				}
+			}
+			host_index.delete(key);
+		}
+	}
+	/** Replace this host's claims; shared ids keep one registry entry (path+strategy dedupe). */
+	register(result, hostId) {
+		const { registry, island_graph, by_id, region_kinds, host_index, id_hosts } = this;
+		this.unregister_host(hostId);
+		const key = host_key(hostId);
+		if (result.hasWireCrossing) this.note_runtime_mark({ wire: true });
+		const idx = {
+			ids: /* @__PURE__ */ new Set(),
+			vpaths: /* @__PURE__ */ new Set()
+		};
+		for (const isl of result.islands ?? []) {
+			region_kinds.set(isl.id, isl.kind ?? (isl.server ? "defer" : "hydrate"));
+			idx.ids.add(isl.id);
+			const kind = isl.kind ?? (isl.server ? "defer" : "hydrate");
+			if (kind === "defer") this.note_runtime_mark({ defer: [isl.fetchWhen || "load"] });
+			if (kind === "hydrate") this.note_runtime_mark({ hydrate: [isl.strategy || "load"] });
+			if (isl.wakeAfter) this.note_runtime_mark({ hydrate: [isl.wakeAfter] });
+			if (kind === "lake") this.note_runtime_mark({
+				lakes: true,
+				hydrate: ["none"]
+			});
+			if (isl.held) this.note_runtime_mark({
+				live: true,
+				morph: true
+			});
+			if (isl.lakes?.length) this.note_runtime_mark({ lakes: true });
+			if (isl.keep) this.note_runtime_mark({
+				persist: true,
+				persistKeys: [isl.keep]
+			});
+			let holders = id_hosts.get(isl.id);
+			if (!holders) {
+				holders = /* @__PURE__ */ new Set();
+				id_hosts.set(isl.id, holders);
+			}
+			holders.add(key);
+			if (isl.wrapperPath && isl.wrapperSource) {
+				registry.set(isl.wrapperPath, {
+					source: isl.wrapperSource,
+					clientSource: isl.wrapperClientSource,
+					hostPath: isl.hostPath,
+					id: isl.id,
+					server: false,
+					lakes: isl.lakes ?? [],
+					componentPath: isl.componentPath ?? null,
+					role: "wrapper"
+				});
+				idx.vpaths.add(isl.wrapperPath);
+				island_graph.add(isl.wrapperPath);
+			}
+			if (isl.lazyPath && isl.lazySource) {
+				registry.set(isl.lazyPath, {
+					source: isl.lazySource,
+					hostPath: isl.hostPath,
+					id: isl.id,
+					server: false,
+					lakes: [],
+					componentPath: isl.componentPath ?? null,
+					role: "lazy"
+				});
+				idx.vpaths.add(isl.lazyPath);
+				island_graph.add(isl.lazyPath);
+			}
+			if (isl.bindingPath && isl.bindingSsrSource) {
+				registry.set(isl.bindingPath, {
+					ssrSource: isl.bindingSsrSource,
+					clientSource: isl.bindingClientSource ?? isl.bindingSsrSource,
+					hostPath: isl.hostPath,
+					id: isl.id,
+					server: false,
+					lakes: [],
+					componentPath: isl.componentPath ?? null,
+					role: "region"
+				});
+				idx.vpaths.add(isl.bindingPath);
+				island_graph.add(isl.bindingPath);
+			}
+			if (isl.virtualPath && isl.source) {
+				registry.set(isl.virtualPath, {
+					source: isl.source,
+					hostPath: isl.hostPath,
+					id: isl.id,
+					server: !!isl.server,
+					lakes: [],
+					componentPath: isl.componentPath ?? null,
+					role: "entry",
+					portable: isl.portable === true,
+					...isl.server && isl.identity ? { renderId: renderId(isl.identity) } : {}
+				});
+				by_id.set(isl.id, isl.virtualPath);
+				idx.vpaths.add(isl.virtualPath);
+				island_graph.add(isl.virtualPath);
+			} else if (isl.virtualPath) by_id.set(isl.id, isl.virtualPath);
+			if (isl.componentPath) island_graph.add(isl.componentPath);
+		}
+		host_index.set(key, idx);
+	}
+};
+export { Program, host_key, strip_id };

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

@@ -0,0 +1,169 @@
+/**
+ * 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.
+ */
+export declare function component_import_line(local: string, spec: string, exportName?: string): string;
+/**
+ * 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.
+ */
+export declare function island_entry_source(componentPath: string, iid: string, exportName?: string): string;
+/** Where an island entry's foreign-hydrate exports begin (compiler/driver.ts cuts from here). */
+export declare 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).
+ */
+export declare function island_wrapper_source(iid: string, componentPath: string, entryPath: string, strategy: string, options: Record<string, unknown> | undefined, exportName: string | undefined, entry_url: string, lang: string): string;
+/**
+ * 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.
+ */
+export declare function island_wrapper_client_source(iid: string, lazyPath: string, strategy: string, options: Record<string, unknown> | undefined, entry_url: string, lang: string): string;
+/**
+ * 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.
+ */
+export declare function lazy_entry_source(entryPath: string, entry_url: string): string;
+/**
+ * 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.
+ */
+export declare function make_region_binding(opts: {
+  iid: string;
+  componentPath: string;
+  entryPath: string;
+  hostPath: string;
+  moduleUrl: string;
+  /** baked wake schedule from a `wake:` mark; absent for `region: 'raw'` (schedule set at the call) */
+  hydrate?: string;
+  /** rootMargin baked when `hydrate` is `'visible'` */
+  hydrateMargin?: string;
+  /** named export to pull (asRegion/barrel); undefined → default import */
+  exportName?: string;
+  identity: string;
+}): {
+  id: string;
+  virtualPath: string;
+  source: string;
+  bindingPath: string;
+  bindingSsrSource: string;
+  bindingClientSource: string;
+  hostPath: string;
+  componentPath: string;
+  server: boolean;
+  kind: string;
+  held: boolean;
+  lakes: never[];
+  identity: string;
+};
+/**
+ * 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).
+ */
+export declare function make_wake_island(opts: {
+  iid: string;
+  componentPath: string;
+  entryPath: string;
+  wrapperPath: string;
+  moduleUrl: string;
+  strategy: string;
+  options?: Record<string, unknown>;
+  exportName?: string;
+  hostPath: string;
+  identity: string;
+  lang: string;
+  /**
+   * A `.ts` registry / remote binding, which may be handed to `region()` and CROSS the wire (a live
+   * or remote region): it needs a server-manifest entry (`server`) so its endpoint can render it, and
+   * the `held` mark that pulls in the live/morph runtime. A `.svelte` placed island never crosses, so
+   * it stays `server:false`. Either way the binding is the SAME mountable wrapper — only the manifest
+   * flags differ, which is also why the two carry distinct identities (an endpoint vs none).
+   */
+  held?: boolean;
+}): {
+  kind: string;
+  lakes: never[];
+  identity: string;
+  strategy: string;
+  keep: unknown;
+  held?: boolean;
+  id: string;
+  virtualPath: string;
+  wrapperPath: string;
+  wrapperSource: string;
+  wrapperClientSource: string;
+  lazyPath: string;
+  lazySource: string;
+  bindingPath: string;
+  bindingSsrSource: string;
+  bindingClientSource: string;
+  source: string;
+  hostPath: string;
+  componentPath: string;
+  server: boolean;
+};
+/**
+ * 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.
+ */
+export declare function server_wrapper_source(iid: string, componentPath: string, entryPath: string, options: Record<string, unknown> | undefined, exportName: string | undefined, module_url: string, lang: string, component?: boolean): string;
+/**
+ * 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.
+ */
+export declare function lake_wrapper_source(iid: string, componentPath: string, options: Record<string, unknown> | undefined, exportName: string | undefined, lang: string): string;
+/** Map a hydrate strategy (+ options) to the Island wrapper attribute markup. */
+export declare function strategy_to_attr(strategy: string, options?: Record<string, unknown>): string;
+/** Rewrite `$app/{state,stores,navigation}` string literals to absolute shim paths. */
+export declare const APP_SHIM_IMPORT: RegExp;
+/**
+ * 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.
+ */
+export declare function rewrite_lake_import_to_placeholder(src: string, local: string, placeholder: string): string;