@ogygia/core 0.0.0 → 0.11.1

package/dist/transport.js

@@ -0,0 +1,181 @@
+import { REGION_BRAND } from "./region-brand.js";
+import { frameAddress } from "./frame.js";
+import { ticket, write } from "./runtime/frame-store.js";
+import { REF_WIRE_KEY, mint, ref_reducer, ref_reviver, register_kind, resolve } from "./ref.js";
+import { register_wire_kind } from "./live-transport.js";
+import { register_derived_kind, register_store_kind } from "./store-transport.js";
+import { register_snippet_kind } from "./region-snippet.js";
+import { register_fn_kind } from "./fn-transport.js";
+// src/transport.ts
+/**
+* `ogygiaTransport` — the SvelteKit `transport` entry that lets a held region cross the wire.
+*
+* A held region holds a live component, which devalue can't serialize. This teaches the wire to carry
+* one: at **encode** (server → wire) it signs the capability and drops the component, sending just
+* the ticket; at **decode** (client) it rebuilds a `deferred` region. It fires only when a
+* held region actually crosses the wire — an inline region rendered in the same pass never touches it.
+*
+* Install once, in the app's UNIVERSAL hooks (kept separate from `ogygiaHandle`, which is
+* server-only), so no server code leaks into the client:
+*
+* ```ts
+* // src/hooks.ts
+* import { ogygiaTransport } from 'ogygia';
+* export const transport = { ...ogygiaTransport };
+* ```
+*/
+/** The region ENCODE law (ticket pass-through / dual signs at crossing / awaited-inline bakes /
+*  inline-unawaited throws), byte-for-byte the pre-hub behavior. */
+function encode_region(value) {
+	{
+		if (typeof value !== "object" || value === null) return false;
+		const f = value;
+		if (f[REGION_BRAND] !== true) return false;
+		if (f.kind === "deferred") return pack(f.id, f.props, f.url, f.module, f.hydrate, f.hydrateMargin, f.html);
+		if (f.kind === "dual") {
+			const sign = f.sign;
+			const props = f.props ?? {};
+			return pack(f.id, props, sign(f.id, props), f.module, f.hydrate, f.hydrateMargin, f.html);
+		}
+		if (typeof f.html === "string") return pack("", f.props ?? {}, "", "", void 0, void 0, f.html);
+		throw new Error("[ogygia] a held region reached the wire but its component is a plain import, so nothing built a chunk for it. `await` the region before returning it from a remote/load — an awaited region bakes its SSR HTML and crosses as an HTML-only ticket. Or import the component `with { region: 'raw' }` (or a `wake:` mark) to make it a signed, fetchable capability. On a csr=false page you can also skip the wire entirely: call `get()` in a universal `+page.ts` load / the component — its data reaches the render by reference.");
+	}
+}
+/** The region DECODE law (single-flight frame write for baked HTML + deferred rebuild),
+*  byte-for-byte the pre-hub behavior. */
+function decode_region(raw) {
+	if (raw.x != null && raw.u && typeof document !== "undefined") {
+		const a = frameAddress(raw.u);
+		write({
+			a,
+			v: ticket(a),
+			html: raw.x
+		});
+	}
+	return {
+		[REGION_BRAND]: true,
+		kind: "deferred",
+		id: raw.i,
+		props: raw.p,
+		url: raw.u,
+		module: raw.m,
+		...raw.h ? { hydrate: raw.h } : {},
+		...raw.g ? { hydrateMargin: raw.g } : {},
+		...raw.x != null ? { html: raw.x } : {}
+	};
+}
+/**
+* A region value AS THE BROWSER RECEIVES IT: through the crossing (encode, then decode) on the server,
+* itself in the browser (it already crossed). A promise `of` resolves to a wire value — a remote's
+* answer — so a server render that awaits one renders this form, the same shape the browser hydrates
+* against (PromiseRegionAwait.svelte). Not a region: unchanged. A plain inline region nothing awaited
+* throws, exactly as the crossing would.
+*/
+function wire_form(value) {
+	if (typeof document !== "undefined") return value;
+	const encoded = encode_region(value);
+	return encoded === false ? value : decode_region(encoded);
+}
+/** The hub kind: a held/dual/awaited region — the RENDERABLE Ref. `d` is the EncodedRegion.
+*  Decode is deliberately un-memoized at the legacy seam (the wrapper below passes ids through
+*  raw); hub-memoized region identity arrives with the one-key collapse, where it becomes the
+*  foundation for persistent regions (the reconciler resolves by id). */
+function register_region_kind() {
+	register_kind({
+		k: "region",
+		match(value) {
+			return value[REGION_BRAND] === true;
+		},
+		encode(value) {
+			const packed = encode_region(value);
+			if (packed === false) throw new Error("[ogygia] region kind claimed a non-region value");
+			return { d: packed };
+		},
+		decode(ref) {
+			return decode_region(ref.d);
+		}
+	});
+}
+const REGION_ONLY = /* @__PURE__ */ new Set(["region"]);
+/** Every hub family the ONE `OgygiaRef` transport entry carries (hub v2 phase Y — symmetry).
+*  Region stays in the list for decode-completeness, but the `Region` entry below is first in
+*  object order so regions still ENCODE through it (legacy `EncodedRegion` wire shape kept). */
+const ALL_FAMILIES = /* @__PURE__ */ new Set([
+	"wire",
+	"store",
+	"snippet",
+	"fn",
+	"derived",
+	"region"
+]);
+let all_kinds_ready = false;
+let all_families_reducer = null;
+function ensure_all_kinds() {
+	if (!all_kinds_ready) {
+		all_kinds_ready = true;
+		register_wire_kind();
+		register_store_kind();
+		register_snippet_kind();
+		register_fn_kind();
+		register_derived_kind();
+		register_region_kind();
+	}
+	return all_families_reducer ??= ref_reducer(ALL_FAMILIES);
+}
+/**
+* The SvelteKit `transport` entry (install once in universal hooks). TWO entries, ONE codec
+* underneath (hub v2 phase Y): `Region` preserves the legacy region wire shape/tag for
+* compatibility; `OgygiaRef` carries EVERY OTHER hub kind through the same `ref_reducer` /
+* `ref_reviver` the island seams use — so a universal `load` can put a store, wire class, fn or
+* resumable derived in `page.data`, and a remote function can take/return one, all by identity.
+* Kit routes remote args + load data through this same `transport`, so the symmetry is total.
+* Decode is REQUEST-scoped on the server (no `document`) — client-sent identity never memoizes
+* across requests — and PAGE-scoped in the browser (reunification).
+*/
+const ogygiaTransport = {
+	Region: {
+		encode(value) {
+			if (typeof value !== "object" || value === null) return false;
+			if (value[REGION_BRAND] !== true) return false;
+			register_region_kind();
+			const ref = mint(value, REGION_ONLY);
+			if (ref === void 0) return false;
+			return {
+				...ref.d,
+				hi: ref.i
+			};
+		},
+		decode(raw) {
+			register_region_kind();
+			const remember = typeof document !== "undefined" && typeof raw.hi === "string" && raw.hi.length > 0;
+			return resolve({
+				k: "region",
+				i: raw.hi ?? (raw.i || ""),
+				d: raw
+			}, remember);
+		}
+	},
+	[REF_WIRE_KEY]: {
+		encode(value) {
+			if (value === null || typeof value !== "object" && typeof value !== "function") return false;
+			return ensure_all_kinds()(value) ?? false;
+		},
+		decode(ref) {
+			ensure_all_kinds();
+			return ref_reviver(typeof document !== "undefined")(ref);
+		}
+	}
+};
+function pack(id, props, url, module, hydrate, hydrateMargin, html) {
+	const out = {
+		i: id,
+		p: props,
+		u: url,
+		m: module
+	};
+	if (hydrate) out.h = hydrate;
+	if (hydrateMargin) out.g = hydrateMargin;
+	if (html != null) out.x = html;
+	return out;
+}
+export { ogygiaTransport, register_region_kind, wire_form };

package/dist/unscoped-css.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The comment an unscoped CSS fallback carries in the shipped stylesheet. When the build cannot
+ * compile a component's scoped CSS (compiler/fouc-css.ts), it ships the raw style bodies, which
+ * then apply to the WHOLE page (`.bar {…}` instead of `.bar.svelte-x {…}`). A build log line is
+ * easy to miss, so the CSS itself says so, and devtools (the page's sheets) and the profiler (the
+ * weighed CSS files) name the component. Import-free: the browser loads this too.
+ *
+ * A legal comment (`/*!`) so a minifier keeps it; the file NAME only, never the build machine's path.
+ */
+export declare const UNSCOPED_MARK = "ogygia-unscoped:";
+export declare function unscoped_marker(abs: string, why: string): string;
+export interface UnscopedStyles {
+  /** the component's file name (`Card.svelte`) */
+  file: string;
+  /** why the build could not scope it (the compiler's first message line) */
+  why: string;
+}
+/** The finding both devtools and the profiler raise, in the same words. */
+export declare function unscoped_finding(list: readonly UnscopedStyles[]): {
+  code: "css-unscoped";
+  message: string;
+  fix: string;
+};
+/** Every unscoped fallback a stylesheet's text carries, once per file. Plain scan, no regex: it
+ *  runs over whole stylesheets in the browser. */
+export declare function find_unscoped(css: string): UnscopedStyles[];

package/dist/unscoped-css.js

@@ -0,0 +1,53 @@
+// src/unscoped-css.ts
+/**
+* The comment an unscoped CSS fallback carries in the shipped stylesheet. When the build cannot
+* compile a component's scoped CSS (compiler/fouc-css.ts), it ships the raw style bodies, which
+* then apply to the WHOLE page (`.bar {…}` instead of `.bar.svelte-x {…}`). A build log line is
+* easy to miss, so the CSS itself says so, and devtools (the page's sheets) and the profiler (the
+* weighed CSS files) name the component. Import-free: the browser loads this too.
+*
+* A legal comment (`/*!`) so a minifier keeps it; the file NAME only, never the build machine's path.
+*/
+const UNSCOPED_MARK = "ogygia-unscoped:";
+function unscoped_marker(abs, why) {
+	const name = abs.slice(Math.max(abs.lastIndexOf("/"), abs.lastIndexOf("\\")) + 1);
+	const safe = (s) => s.split("*/").join("* /").split("\n").join(" ").slice(0, 160);
+	return `/*! ${UNSCOPED_MARK} ${safe(name)} | ${safe(why)} */\n`;
+}
+/** The finding both devtools and the profiler raise, in the same words. */
+function unscoped_finding(list) {
+	const names = list.slice(0, 4).map((u) => u.why ? `${u.file} (${u.why})` : u.file);
+	const one = list.length === 1;
+	return {
+		code: "css-unscoped",
+		message: `${names.join(", ")}${list.length > 4 ? ` and ${list.length - 4} more` : ""}: ${one ? "its" : "their"} styles shipped without the component's scope, so every rule in them applies to the whole page. A \`.row\` or \`.bar\` in ${one ? "it" : "them"} restyles any element with that class, in any component. The build could not compile ${one ? "it" : "them"} and fell back to the raw style ${one ? "body" : "bodies"}.`,
+		fix: `The build log has a line "scoped CSS for … could not be compiled" with the full reason. Usually a style language the build cannot read here (scss and sass are compiled; less and stylus are not) or markup the compiler rejects. Fix that and rebuild.`
+	};
+}
+/** Every unscoped fallback a stylesheet's text carries, once per file. Plain scan, no regex: it
+*  runs over whole stylesheets in the browser. */
+function find_unscoped(css) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	let at = css.indexOf(UNSCOPED_MARK);
+	while (at !== -1) {
+		const end = css.indexOf("*/", at);
+		if (end === -1) break;
+		const body = css.slice(at + 16, end).trim();
+		const bar = body.indexOf(" | ");
+		const u = bar === -1 ? {
+			file: body,
+			why: ""
+		} : {
+			file: body.slice(0, bar),
+			why: body.slice(bar + 3).trim()
+		};
+		if (!seen.has(u.file)) {
+			seen.add(u.file);
+			out.push(u);
+		}
+		at = css.indexOf(UNSCOPED_MARK, end);
+	}
+	return out;
+}
+export { UNSCOPED_MARK, find_unscoped, unscoped_finding, unscoped_marker };

package/dist/vite/dev-maps.d.ts

@@ -0,0 +1,33 @@
+import { ViteDevServer } from "vite";
+export declare const DEV_MAPS: unique symbol;
+export declare const DEV_PAGE_KEYS: unique symbol;
+/** what an island's code reads of `page.data`, as the build would say: its keys, or `'all'` with
+ *  the lines that make it so; `null` when nothing in it reads the page */
+export interface DevPageKeys {
+  keys: string[] | "all" | null;
+  why: {
+    file: string;
+    line: number | null;
+    why: string;
+  }[];
+}
+/**
+ * THE BUILD'S SEED ANSWER, ON THE DEV SERVER: the build pins which `page.data` keys each island's
+ * code reads (seed shaping); the dev server does not — every island reads "everything" there, so
+ * the profiler could not tell a late island's data or point at the line that ships it all. This
+ * puts the same analysis behind a global the profiler (same process) asks: the island id's
+ * component and the app modules it imports (the SSR graph, eight deep), each read by the build's
+ * own `page_data_keys_answer`, a helper handed the page followed one level like the build does.
+ * Only what the report says changes: the dev seed itself still ships whole.
+ */
+export declare function install_dev_page_keys(server: ViteDevServer, component_of: (iid: string) => string | null | undefined, root: string): void;
+/**
+ * THE BROWSER'S MODULES, TOO: a CPU trace from the browser names a frame by the URL the dev server
+ * served (`/src/lib/Save.svelte?t=…`) at the SERVED code's lines — a `.svelte` file's compiled output,
+ * not its source. The client module graph holds each served module's map (the browser runs the code
+ * as served: no header to shift by). Looked up by the URL's path, then with its query minus Vite's
+ * `t=` / `v=` stamps (a virtual island id keeps its own query).
+ */
+export declare const DEV_CLIENT_MAPS: unique symbol;
+export declare function install_dev_client_maps(server: ViteDevServer): void;
+export declare function install_dev_maps(server: ViteDevServer): void;

package/dist/vite/dev-maps.js

@@ -0,0 +1,140 @@
+import { page_data_keys_answer, summarize_export } from "../compiler/link/page-keys.js";
+import fs from "node:fs";
+// src/vite/dev-maps.ts
+/**
+* THE DEV SERVER'S SOURCE MAPS, FOR THE PROFILER: Vite's module runner evaluates each server module's
+* transformed code inside an `AsyncFunction` (`"use strict";\n` first), with `//# sourceURL=<id>`, so a
+* CPU profile names the module by its id and its lines are the transformed code's, shifted by the
+* function's own header. The map from that code back to the source is in the SSR module graph. This
+* puts a lookup on a global the profiler (loaded by the same process) reads: module id → the map,
+* shifted to the lines V8 reports.
+*/
+const DEV_MAPS = Symbol.for("ogygia.profiler.dev-maps");
+const DEV_PAGE_KEYS = Symbol.for("ogygia.profiler.dev-page-keys");
+/**
+* THE BUILD'S SEED ANSWER, ON THE DEV SERVER: the build pins which `page.data` keys each island's
+* code reads (seed shaping); the dev server does not — every island reads "everything" there, so
+* the profiler could not tell a late island's data or point at the line that ships it all. This
+* puts the same analysis behind a global the profiler (same process) asks: the island id's
+* component and the app modules it imports (the SSR graph, eight deep), each read by the build's
+* own `page_data_keys_answer`, a helper handed the page followed one level like the build does.
+* Only what the report says changes: the dev seed itself still ships whole.
+*/
+function install_dev_page_keys(server, component_of, root) {
+	const ssr = () => server.environments?.ssr?.moduleGraph;
+	const app_file = (f) => !!f && f.startsWith(root) && !f.includes("/node_modules/");
+	const kind = (f) => f.endsWith(".svelte") ? "svelte" : "script";
+	const read = (f) => {
+		try {
+			return fs.readFileSync(f, "utf8");
+		} catch {
+			return;
+		}
+	};
+	globalThis[DEV_PAGE_KEYS] = async (iid) => {
+		const component = component_of(iid)?.split("?")[0];
+		const graph = ssr();
+		if (!component || !graph) return void 0;
+		const files = [];
+		const seen = /* @__PURE__ */ new Set();
+		let level = [component];
+		for (let depth = 0; depth < 8 && level.length; depth++) {
+			const next = [];
+			for (const f of level) {
+				if (seen.has(f)) continue;
+				seen.add(f);
+				files.push(f);
+				for (const node of graph.getModulesByFile(f) ?? []) for (const dep of node.importedModules ?? []) {
+					const df = dep.file?.split("?")[0];
+					if (app_file(df) && !seen.has(df)) next.push(df);
+				}
+			}
+			level = next;
+		}
+		const read_keys = /* @__PURE__ */ new Set();
+		let all = false;
+		let any = false;
+		const why = [];
+		const add = (k) => {
+			if (k === null) return;
+			any = true;
+			if (k === "all") all = true;
+			else for (const x of k) read_keys.add(x);
+		};
+		for (const f of files) {
+			const code = read(f);
+			if (!code) continue;
+			const a = page_data_keys_answer(code, f, kind(f));
+			if (a.keys === "all" && a.reason) why.push({
+				file: f,
+				line: a.reason.line,
+				why: a.reason.why
+			});
+			add(a.keys);
+			for (const p of a.pending) {
+				const target = (await server.pluginContainer.resolveId(p.specifier, f, { ssr: true }).catch(() => null))?.id?.split("?")[0];
+				const tcode = target && app_file(target) ? read(target) : void 0;
+				const s = tcode ? summarize_export(tcode, target, kind(target), p.imported, p.arg) : "all";
+				if (s === "all" || !(s instanceof Set)) {
+					why.push({
+						file: f,
+						line: p.line,
+						why: `the page is handed to ${p.imported}(), which the analysis cannot follow`
+					});
+					add("all");
+				} else add(s);
+			}
+		}
+		return {
+			keys: !any ? null : all ? "all" : [...read_keys],
+			why
+		};
+	};
+}
+/** lines V8 counts before a module's first line: the `AsyncFunction` header, and `"use strict";` */
+function runner_offset() {
+	const AsyncFunction = async function() {}.constructor;
+	const src = new AsyncFunction("a", "b", "/*code*/").toString();
+	return src.slice(0, src.indexOf("/*code*/")).split("\n").length - 1 + 1;
+}
+/**
+* THE BROWSER'S MODULES, TOO: a CPU trace from the browser names a frame by the URL the dev server
+* served (`/src/lib/Save.svelte?t=…`) at the SERVED code's lines — a `.svelte` file's compiled output,
+* not its source. The client module graph holds each served module's map (the browser runs the code
+* as served: no header to shift by). Looked up by the URL's path, then with its query minus Vite's
+* `t=` / `v=` stamps (a virtual island id keeps its own query).
+*/
+const DEV_CLIENT_MAPS = Symbol.for("ogygia.profiler.dev-client-maps");
+function install_dev_client_maps(server) {
+	const graph = () => server.environments?.client?.moduleGraph;
+	globalThis[DEV_CLIENT_MAPS] = (url) => {
+		const by_url = graph()?.urlToModuleMap;
+		if (!by_url) return void 0;
+		const q = url.indexOf("?");
+		const path = q === -1 ? url : url.slice(0, q);
+		const keys = [path];
+		if (q !== -1) {
+			const kept = url.slice(q + 1).split("&").filter((p) => !p.startsWith("t=") && !p.startsWith("v="));
+			if (kept.length) keys.unshift(`${path}?${kept.join("&")}`);
+		}
+		for (const k of keys) {
+			const map = by_url.get(k)?.transformResult?.map;
+			if (map && typeof map.mappings === "string") return JSON.stringify(map);
+		}
+	};
+}
+function install_dev_maps(server) {
+	const offset = runner_offset();
+	const graph = () => {
+		return server.environments?.ssr?.moduleGraph;
+	};
+	globalThis[DEV_MAPS] = (id) => {
+		const map = graph()?.getModuleById(id)?.transformResult?.map;
+		if (!map || typeof map.mappings !== "string") return void 0;
+		return JSON.stringify({
+			...map,
+			mappings: ";".repeat(offset) + map.mappings
+		});
+	};
+}
+export { DEV_CLIENT_MAPS, DEV_MAPS, DEV_PAGE_KEYS, install_dev_client_maps, install_dev_maps, install_dev_page_keys };

package/dist/vite/index.d.ts

@@ -0,0 +1,19 @@
+import { regionId, regionIdentity, strategyKey } from "../compiler/region/identity.js";
+import { CLIENT_BINDING_STUB, DEFAULT_IMPORT_KEYS, ImportKeys, import_keys_hint, islandChunkFileName, islandId, islandPublicUrl, normalize_import_keys, wrapperVirtualId } from "../compiler/region/transform.js";
+import { rewrite_lake_import_to_placeholder } from "../compiler/region/emit.js";
+import { debarrel } from "../compiler/debarrel/plugin.js";
+import { BuildContext, MacroContext, MacroHandler, MarkupRegions, MarkupSource, OgygiaPlugin, PluginDefinition, definePlugin } from "./plugin-api.js";
+import { DebarrelOptions, Matcher } from "../compiler/debarrel/options.js";
+import { OgygiaOptions, OgygiaPreset, OgygiaRateLimit } from "./options.js";
+import { Plugin } from "vite";
+/**
+ * Vite plugin: transforms `with { hydrate | defer | preset }` imports into islands,
+ * serves virtual island modules, and wires signed region endpoints for deferred HTML.
+ *
+ * Place **before** `sveltekit()` in `vite.config`.
+ *
+ * @param options - Plugin configuration. See {@link OgygiaOptions}.
+ * @returns Vite plugins (`ogygia` pre + island sourcemap fix post). Vite flattens the array.
+ */
+export declare function ogygia(options?: OgygiaOptions): Plugin[];
+export { type BuildContext, CLIENT_BINDING_STUB, DEFAULT_IMPORT_KEYS, type Matcher as DebarrelMatcher, type DebarrelOptions, type ImportKeys, type MacroContext, type MacroHandler, type MarkupRegions, type MarkupSource, type OgygiaOptions, type OgygiaPlugin, type OgygiaPreset, type OgygiaRateLimit, type PluginDefinition, debarrel, definePlugin, import_keys_hint, islandChunkFileName, islandId, islandPublicUrl, normalize_import_keys, regionId, regionIdentity, rewrite_lake_import_to_placeholder, strategyKey, wrapperVirtualId };