@ogygia/core 0.0.0 → 0.11.1

package/dist/compiler/dev/region-bytes.d.ts

@@ -0,0 +1,34 @@
+import { IslandHazard } from "../../insights/hydration-hazards.js";
+/** Structural shape of a Vite dev module-graph node (the fields the byte walk reads). */
+export type ByteGraphModule = {
+  url?: string | null;
+  id?: string | null;
+  file?: string | null;
+  transformResult?: {
+    code?: string | null;
+  } | null;
+  importedModules?: Iterable<ByteGraphModule>;
+};
+/**
+ * `island id → { bytes, modules }` for every island entry present in the graph, where `bytes` is the
+ * summed served size of the entry's whole transitive import subgraph and `modules` the node count.
+ * When two graph nodes resolve to the same island id (e.g. `?v=` query variants), the larger wins.
+ */
+export declare function island_subgraph_bytes(modules: Iterable<ByteGraphModule>, read?: (file: string) => string | undefined): Record<string, IslandBytes>;
+/** An island's app code in dev: the total, its heaviest modules, and any barrel it pulls whole. */
+export interface IslandBytes {
+  bytes: number;
+  modules: number;
+  /** the heaviest modules (served size, heaviest first): what to look at first */
+  top?: {
+    file: string;
+    bytes: number;
+  }[];
+  /** re-export barrels still in the island's graph, with how many app modules each drags in */
+  barrels?: {
+    file: string;
+    fanout: number;
+  }[];
+  /** its components' lines that draw differently in the browser (a top-level await, a browser-only value) */
+  hazards?: IslandHazard[];
+}

package/dist/compiler/dev/region-bytes.js

@@ -0,0 +1,126 @@
+import { hydration_hazards } from "../../insights/hydration-hazards.js";
+import { OWN_FILE_RE } from "../../own-package.js";
+// src/compiler/dev/region-bytes.ts
+/**
+* Dev-only per-island byte estimate — walks DOWN the Vite dev module graph from each island entry
+* and sums the served (transformed) size of the APP modules it transitively imports: its wrapper,
+* the component, and every child component / app util the component pulls in. Not just the wrapper
+* chunk a `PerformanceResourceTiming` lookup sees — but also NOT the shared framework.
+*
+* The framework boundary is pruned (`node_modules`, Vite's `.vite/deps` prebundles): Svelte's runtime
+* is loaded ONCE for the whole page, so folding it into every island makes them all read as ~2 MB and
+* hides the real difference. Counting only app code surfaces the number that actually varies island to
+* island — "what does THIS component cost on top of the shared runtime".
+*
+* Caveats (surfaced in the tab): dev code is unbundled + unminified, so the number is an ESTIMATE of
+* relative cost, not the shipped byte count; and a still-cold island (one that hasn't woken, so its
+* component was never loaded) has no subgraph in the graph yet — it simply doesn't appear here until
+* it wakes. Pure over the nodes it's handed; reads, never mutates.
+*/
+/** An island entry module — `virtual:ogygia/island/<id>.js` (dev url carries the id). */
+const ISLAND_RE = /virtual:ogygia\/island\/([0-9a-f]+)\.js/;
+/** Shared framework / prebundled deps — pruned so per-island totals reflect app code, not Svelte. */
+function is_framework(mod) {
+	const s = (mod.file || "") + "\n" + (mod.url || mod.id || "");
+	const u = mod.url || mod.id || "";
+	return s.includes("node_modules") || s.includes("/.vite/deps/") || OWN_FILE_RE.test(s) || u.includes("virtual:ogygia/") && !u.includes("virtual:ogygia/island/");
+}
+/**
+* The island's own entry glue (`virtual:ogygia/island/<id>.js`, its wrapper). Traversed THROUGH to
+* reach the real component, but not COUNTED — it's the island's door, not the component's weight.
+*/
+function is_glue(mod) {
+	return (mod.url || mod.id || "").includes("virtual:ogygia/island/");
+}
+/**
+* `island id → { bytes, modules }` for every island entry present in the graph, where `bytes` is the
+* summed served size of the entry's whole transitive import subgraph and `modules` the node count.
+* When two graph nodes resolve to the same island id (e.g. `?v=` query variants), the larger wins.
+*/
+function island_subgraph_bytes(modules, read) {
+	const out = {};
+	for (const mod of modules) {
+		const url = mod.url || mod.id || "";
+		const m = ISLAND_RE.exec(url);
+		if (!m) continue;
+		const iid = m[1];
+		const seen = /* @__PURE__ */ new Set();
+		const stack = [mod];
+		let bytes = 0;
+		let count = 0;
+		let steps = 0;
+		const each = [];
+		const barrels = [];
+		const hazards = [];
+		while (stack.length && steps++ < 2e4) {
+			const n = stack.pop();
+			if (seen.has(n)) continue;
+			seen.add(n);
+			if (is_framework(n)) {
+				const f = (n.file || "").split("\\").join("/");
+				const at = f.indexOf("/content/");
+				if (read && at !== -1 && OWN_FILE_RE.test(f) && f.endsWith(".svelte") && hazards.length < 5) {
+					const src = read(n.file);
+					if (src) {
+						for (const h of hydration_hazards(src).slice(0, 3)) if (hazards.length < 5) hazards.push({
+							file: `ogygia/${f.slice(at + 1)}`,
+							...h
+						});
+					}
+				}
+				continue;
+			}
+			let fanout = 0;
+			for (const dep of n.importedModules ?? []) {
+				stack.push(dep);
+				if (!is_framework(dep)) fanout++;
+			}
+			if (is_glue(n)) continue;
+			const code = n.transformResult?.code;
+			if (typeof code === "string") {
+				bytes += code.length;
+				count++;
+				const file = short_url(n);
+				each.push({
+					file,
+					bytes: code.length
+				});
+				if (fanout >= BARREL_FANOUT && code.length <= fanout * BARREL_BYTES_PER_EXPORT && !file.endsWith(".svelte")) barrels.push({
+					file,
+					fanout
+				});
+				if (read && n.file && file.endsWith(".svelte") && hazards.length < 5) {
+					const src = read(n.file);
+					if (src) {
+						for (const h of hydration_hazards(src).slice(0, 3)) if (hazards.length < 5) hazards.push({
+							file,
+							...h
+						});
+					}
+				}
+			}
+		}
+		if ((count > 0 || hazards.length) && (!out[iid] || out[iid].bytes < bytes)) {
+			each.sort((a, b) => b.bytes - a.bytes);
+			out[iid] = {
+				bytes,
+				modules: count,
+				top: each.slice(0, 5),
+				...barrels.length ? { barrels: barrels.sort((a, b) => b.fanout - a.fanout).slice(0, 3) } : {},
+				...hazards.length ? { hazards } : {}
+			};
+		}
+	}
+	return out;
+}
+/** a barrel re-exports at least this many app modules… */
+const BARREL_FANOUT = 6;
+/** …with about this much code of its own per module (an `export … from` line, transformed) */
+const BARREL_BYTES_PER_EXPORT = 160;
+/** A module's served path, query dropped; a file outside the root (`/@fs/…`) by its last parts. */
+function short_url(n) {
+	const u = (n.url || n.id || "").split("?")[0];
+	if (u.startsWith("/@fs/")) return u.split("/").slice(-3).join("/");
+	return u.startsWith("/") ? u.slice(1) : u;
+}
+export { island_subgraph_bytes };

package/dist/compiler/driver.d.ts

@@ -0,0 +1,280 @@
+import { transformTsRegions } from "./region/transform.js";
+import { Program } from "./program.js";
+import { CompileCtx } from "./ctx.js";
+/** The bundler's `emitFile` for an entry chunk, by `name` (the output pattern content-hashes it).
+ *  Returns the reference id. */
+export type EmitChunk = (chunk: {
+  type: "chunk";
+  id: string;
+  name: string;
+}) => string;
+/** Shared OGYGIA_PROFILE instrument — the adapter owns the maps/counters; the driver writes into
+ *  them so the transform-phase metrics (and the determinism digest source) live with the transform. */
+export interface Profiler {
+  prof: {
+    transformMs: number;
+    transformN: number;
+    transformHit: number;
+    prescanMs: number;
+    bakeMs: number;
+    bakeN: number;
+    resolveMs: number;
+    loadMs: number;
+  };
+  P: boolean;
+  outHash: Map<string, number>;
+}
+/**
+ * The island shim for an `$app/*` import, by specifier or by where Kit's alias sent it: Vite's alias
+ * plugin runs before any plugin's resolveId, so an import the transform did not rewrite (a module
+ * that joined the island graph late) arrives as `<kit>/src/runtime/app/state`, `…/state/index.js`.
+ */
+export declare function app_shim_for(source: string, shims: Record<string, string>): string | null;
+export declare class Compiler {
+  #private;
+  readonly program: Program;
+  readonly transform_cache: Map<string, {
+    code: string;
+    result: unknown;
+  }>;
+  readonly profiler: Profiler;
+  /** Every `import.meta.og.$` hoist collected across the build (tag → factory source). Filled by
+   *  `macros()`; drained by the adapter's fn-manifest emit (dev load leg, renderChunk, writeBundle). */
+  readonly dollar_hoists: Map<string, string>;
+  /** True (once) when a server island registered since the last manifest emit — re-invalidate it. */
+  server_manifest_stale(): boolean;
+  constructor(program: Program, profiler: Profiler);
+  /** Bind the resolved compile context (called once the bundler has resolved the build). */
+  configure(ctx: CompileCtx): void;
+  /**
+   * Devtools: the `island id → component name` map, read at call time off the live registry (so a
+   * dev-server middleware serves a COMPLETE, current map — no stale virtual-module snapshot). Keys
+   * are the island id (`<hash>` in `virtual:ogygia/island/<hash>.js`); values the component's
+   * basename. A held/generated island with no source file is skipped (the tab keeps its short hash).
+   */
+  region_names(): Record<string, string>;
+  /**
+   * Run the module-macro passes (`wire`/`$`/`source`/`store`/auto-brand, the plugins' macros, then
+   * `bake`) over one module — the leg that must land before the island transform / svelte compile /
+   * ts-region minting sees it. `source` is the CURRENT text (a plugin's pre-transform may already have
+   * edited it). Returns `{ code, touched }`; the caller nulls its own sourcemap when `touched`.
+   */
+  macros(source: string, id: string): Promise<{
+    code: string;
+    touched: boolean;
+  }>;
+  /**
+   * Transform a content (`.svx`/`.md`) island source the markdown preprocessor hands back — always
+   * wrapper-linked (`linkVirtual: true`), because a preprocessor output is shared across the ssr/client
+   * legs and can't take the csr=false stub split; content files aren't routes, so they'd get wrappers
+   * anyway. Registers the descriptors and returns the rewritten code, or `null` when it has no islands.
+   * This is the transform the adapter installs on the content-island bridge.
+   */
+  transform_content_island(source: string, filename: string): string | null;
+  transform(source: string, id: string, opts?: {
+    ssr?: boolean;
+    linkVirtual?: boolean;
+  }): unknown;
+  /**
+   * Mint the `.ts` / `.js` regions in one module — `with { wake: … }` load/remote imports become
+   * island descriptors. The ts-region half of the front-end, sharing the driver's resolved context
+   * (so both the prescan and the transform hook mint identically). Not memoized — the caller gates it
+   * on the id + marker; the returned descriptors are the caller's to `register`.
+   */
+  ts_regions(source: string, id: string): ReturnType<typeof transformTsRegions>;
+  /**
+   * Discover every island up front — walk `src/`, transform each `.svelte` host and mint each
+   * `.ts`/`.js` region, register the descriptors, then complete `island_graph` TRANSITIVELY and
+   * finalize the runtime capability marks (so the sticky runtime entry bundles only what the app
+   * uses, and its immutable chunk name busts on a feature-set change). Once per session, so the
+   * adapter can call it from any hook. Populates the `Program`; the fs walk is the only side effect.
+   */
+  prescan(): void;
+  /** DEV: take the modules newly marked as island code since the last drain (see above). */
+  drain_closure_marks(): string[];
+  mark_island_closure(componentAbs: string): string[];
+  /**
+   * Scan ENTRIES for Vite's dep optimizer: every hydrate island's component file and the host file
+   * that places it — real, absolute, on-disk source paths. Under `csr = false` Kit ships no client
+   * entry and registers only `routes/**\/+*` as scan entries, so Vite's scanner reaches an island
+   * only when a route file imports it statically. An island behind a block registry, an
+   * `import.meta.og.regions()` glob or a `.remote.ts` mint is never crawled: its client deps are
+   * discovered LAZILY on its first wake, and every discovery re-optimizes, rotates the optimizer's
+   * browserHash and full-reloads — on a large app a reload storm that never settles. The adapter
+   * appends these to `optimizeDeps.entries` (dev) so Vite's OWN scanner crawls them at startup with
+   * the full plugin pipeline: its resolver, every plugin's `resolveId` (a `?client` import resolves
+   * through vite-plugin-iso-import), a linked workspace package followed as SOURCE and never
+   * pre-bundled, the app's `exclude` honoured.
+   *
+   * Deliberately NOT a self-computed `optimizeDeps.include` list. A resolver that is not Vite's
+   * mis-classifies something Vite knows — a plugin query, a workspace link, an `exports` map — and
+   * a wrong `include` hands rolldown an id it cannot load: `UNLOADABLE_DEPENDENCY`, a dead dev
+   * server (two field-reported regressions). An entry can only ever ADD a crawl root; what the
+   * crawl finds is Vite's call. A `defer` island renders on the server (its closure is not client
+   * code) and a lake ships no client JS, so neither is an entry; the host file covers a
+   * portable-snippet synth, which has no component file of its own. Needs `prescan()`; deduped,
+   * sorted, existing source files only.
+   */
+  island_scan_entries(): string[];
+  /** The feature-selected runtime chunk name (immutable-cached). Needs prescan to have run for a
+   *  non-empty feature hash; both build legs prescan the same source → the same name. */
+  runtime_chunk_filename(): string;
+  /** Public URL of the runtime chunk (asset prefix + filename — honors a non-root base / assets CDN). */
+  runtime_chunk_url(): string;
+  /** The server-router component roots (link/router-css.ts). Build: prescan is complete before any
+   *  consumer runs — memoized. Dev: modules appear lazily (HMR), recompute per call. */
+  router_css_roots(): string[];
+  /** Does the program hold ANY hydrate island? The runtime-emission gate needs this because
+   *  `hasAnyCsrFalseRoute` only inspects Kit PAGE leaves — an app whose islands live solely in
+   *  router-rendered components (a pure-router / fragment-only service has ZERO `+page` files)
+   *  answers "no csr=false page" while its documents still `<script src>` the runtime. */
+  /**
+   * Server-only islands — `render: 'deferred'` with no client chunk — and the component file each
+   * renders. Nothing on any page links such a component's CSS (Kit collects stylesheets from the
+   * client graph; this subtree is never in it), so the client leg compiles each one's whole tree
+   * CSS into a dedicated asset the hole response links (vite/index.ts, `region_css_links`).
+   * Sorted for determinism; a component shared by several ids is emitted once (by `abs`).
+   */
+  server_island_css_roots(): Array<{
+    iid: string;
+    abs: string;
+  }>;
+  /** The public URL key a server island's CSS is handed off under (matches `island_url[id]`). */
+  island_public_url(iid: string): string;
+  has_hydrate_regions(): boolean;
+  /** The server leg's real module graph, for the client-leg handoff (link/emit-gate.ts). */
+  ssr_transformed_hosts(): string[];
+  /**
+   * Client leg: the runtime chunk + one deterministic chunk per deduped hydrate region. `loaded` —
+   * the server leg's transformed-module set (the handoff the plugin reads) — gates the emit to
+   * islands whose HOST the server bundle actually contains; `null` (no handoff: standalone, or a
+   * client-only build) keeps every prescanned island, as before. Returns how many were skipped.
+   */
+  emit_build_chunks(emitFile: EmitChunk, { emitRuntime, loaded }: {
+    emitRuntime: boolean;
+    loaded?: Set<string> | null;
+  }): number;
+  /** Client-build refs of each emitted island entry (by island id) and of the runtime entry: the
+   *  bundle end turns them into the hashed file names the handoff maps the stable names to. */
+  readonly island_entry_refs: Map<string, string>;
+  runtime_entry_ref: string | null;
+  /**
+   * At the bundle's end (the names are final): each entry's IDENTITY → its LOCATION. `islands` maps
+   * an island entry's hashed file to its identity (the collector keys every map by identity);
+   * `locations` is what the handoff carries to the server (`entries`): identity → served path.
+   * `get_file_name` is the bundler's `this.getFileName`.
+   */
+  entry_locations(get_file_name: (ref: string) => string): {
+    islands: Map<string, string>;
+    runtime: string | null;
+    runtime_file: string | null;
+    locations: Record<string, string>;
+  };
+  /** One hydrate island's entry, content-hashed by the bundler (its stable-name shim is written at
+   *  the bundle's end: `entry_shims`). */
+  emit_island_entry(emitFile: EmitChunk, rid: string, virtualPath: string): void;
+  /**
+   * The output file pattern for one of OUR entries (by the chunk name `emit_island_entry` / the
+   * runtime emit gave it), else null (the app's own naming applies). Readable and content-hashed:
+   * `<appDir>/immutable/og-region.<iid>.<hash>.js`, `…/og-runtime-<features>.<hash>.js` — the hash is the
+   * cache law, the name is for people (a network tab, a CDN rule, a profile). It never equals a
+   * stable name, which has no hash segment.
+   */
+  entry_file_pattern(chunk_name: string | undefined): string | null;
+  /**
+   * The stable-name shims (link/entry-shim.ts), for the bundle's end (the names are final): one per
+   * island entry, plus the runtime's — each a plain file at the old stable name re-exporting the
+   * hashed file. `get_file_name` is the bundler's `this.getFileName`.
+   */
+  entry_shims(get_file_name: (ref: string) => string): {
+    fileName: string;
+    source: string;
+  }[];
+  /**
+   * Emit one ogygia VIRTUAL module's source: the config/capability virtuals (secret / sign / rate-limit
+   * / router / session / ttl / manifests / runtime entry+url / transport / dev-hmr / request-event /
+   * region-endpoint), and the registered island/region sources (with the client leg's `$app/*`-shim +
+   * lake-placeholder rewrites). Returns the source string, or `null` if `id` is not an ogygia virtual —
+   * the adapter owns only the FOUC-css virtuals (they carry a Vite `moduleType`) and the Vite build
+   * value threaded in here (the `universalHooks` path).
+   */
+  emit(id: string, { ssr, universalHooks, resolve, kitCodec }: {
+    ssr: boolean;
+    universalHooks: string | null;
+    /** the bundler's resolver (the router-CSS tree walk: compiler/fouc-css.ts) */
+    resolve?: (spec: string, importer: string) => Promise<string | null>;
+    /** Kit 3's own codec module (`#app/internal/transport`), when the app's Kit has one */
+    kitCodec?: string | null;
+  }): string | Promise<string> | null;
+  /**
+   * Resolve an ogygia-owned import id: the virtual-module vocabulary (config/manifest virtuals + FOUC
+   * graph + client-binding stub), and the island CLIENT graph — `$app/*` shims for island importers,
+   * virtual island/wrapper ids, and relative imports of a generated island module resolved against its
+   * host (marking each resolved dep into `island_graph` so its own `$app/*` stays shimmed). `resolve` is
+   * the bundler's own resolver (Vite `this.resolve`), threaded in so the driver stays bundler-agnostic.
+   * Returns a resolved id / result, or `null` to defer to the bundler. The adapter handles the few
+   * package/Kit-specific ids first (ogygia injected imports, Kit's remote runtime, the kit-wire path).
+   */
+  resolve_id(source: string, importer: string | undefined, { ssr, resolve }: {
+    ssr: boolean;
+    resolve: (source: string, importer: string, opts: {
+      skipSelf: boolean;
+    }) => Promise<{
+      id: string;
+    } | null>;
+  }): Promise<string | {
+    id: string;
+  } | null>;
+  /**
+   * The per-file transform pass: content-preset tagging ▸ `import.meta.og.*` macros ▸ the host-island
+   * transform (`.svelte`) ▸ ts/js region minting (`.ts/.js`) ▸ the client `$app/*` shim. Registers the
+   * discovered descriptors into the `Program`, and (client build only) emits the deterministic chunk for
+   * any hydrate island a library component declares that the prescan couldn't see — via the `emitFile`
+   * callback (the one Vite primitive threaded in). Returns the Vite transform result, or `null` if the
+   * module was untouched. `prescan()` runs first so `island_graph` is complete before any module lowers.
+   */
+  transform_module(code: string, id: string, { ssr, emitFile }: {
+    ssr: boolean;
+    emitFile: EmitChunk;
+  }): Promise<{
+    code: string;
+    map: unknown;
+  } | null>;
+  /**
+   * Patch the fn-manifest placeholder in a finished chunk with the collected `og.$` factory
+   * registrations — every transform has run by renderChunk, so `dollar_hoists` is complete. Registrations
+   * go through the globalThis bridge the placeholder module installed (rename-proof under minification).
+   * Returns the patched chunk, or `null` if this chunk carries no placeholder.
+   */
+  patch_fn_manifest(code: string): {
+    code: string;
+    map: null;
+  } | null;
+  /**
+   * Patch the server manifest's page-data placeholder: per server island (a hole), does its SERVER
+   * tree — the component and everything it imports, statically or dynamically (a registry's blocks)
+   * — read `page.data`? The transform recorded each module's reads (`page_keys`, seed shaping); by
+   * renderChunk the graph is complete. A hole that never reads it never pays the page lookup
+   * (server/render-page.ts). One walk per hole, sharing what earlier walks proved: a walk that ends
+   * with no reader proves every module it visited reads nothing. `graph` is the bundler's module info.
+   */
+  patch_page_data_reads(code: string, graph: (id: string) => {
+    importedIds: readonly string[];
+    dynamicallyImportedIds: readonly string[];
+  } | null, module_ids: () => Iterable<string>): {
+    code: string;
+    map: null;
+  } | null;
+  /** True when `file` is a registered island HOST (a component that declares islands). */
+  is_registered_host(file: string): boolean;
+  /**
+   * Drop the cached virtual island modules + the registry rows for `file` — call when a HOST changes
+   * (an import-target rename keeps the same island id) or an ENTRY component is deleted (NOT on ordinary
+   * entry-component content edits — those are soft HMR). Mutates the Program; `invalidate` is the
+   * bundler's module-invalidation (Vite's moduleGraph), threaded in. Returns whether anything changed.
+   */
+  invalidate_for_file(file: string, { deleted, invalidate }: {
+    deleted?: boolean;
+    invalidate: (id: string) => void;
+  }): boolean;
+}