@ogygia/core 0.0.0 → 0.11.0

package/dist/compiler/debarrel/plugin.d.ts

@@ -0,0 +1,31 @@
+import { DebarrelOptions } from "./options.js";
+import { is_script_request } from "../script-request.js";
+import { Plugin } from "vite";
+export interface DebarrelInternal {
+  /** Import-attribute keys that mark an import as ogygia's: such an import is never rewritten. */
+  skip_attribute_keys?: string[];
+  /** Local bindings of a file that carry an island identity without an attribute (ogygia:
+   *  `import.meta.og.asRegion(X)`): a declaration binding one of them is never rewritten, so
+   *  the id the compiler's prescan derives from the raw source is the id the transform sees. */
+  skip_locals?: (code: string) => ReadonlySet<string>;
+}
+export declare function debarrel(options?: DebarrelOptions | true, internal?: DebarrelInternal): Plugin;
+/** The build-time report: totals, time spent in the pass, and the barrels by names moved — the
+ *  `limit` biggest and a count of the rest (`Infinity` for every one). */
+export declare function format_report(r: ReturnType<typeof debarrel_report_shape>, root: string, limit: number): string;
+/** The report record's shape (for `format_report`'s signature — the value lives in the closure). */
+interface DebarrelReport {
+  files: number;
+  importers: number;
+  imports: number;
+  names: number;
+  first_ms: number;
+  last_ms: number;
+  barrels: Map<string, {
+    names: number;
+    importers: Set<string>;
+  }>;
+  skipped: Set<string> | undefined;
+}
+declare function debarrel_report_shape(): DebarrelReport;
+export { is_script_request };

package/dist/compiler/debarrel/plugin.js

@@ -0,0 +1,190 @@
+import { BarrelIndex } from "./barrel.js";
+import { matches_any, normalize_options } from "./options.js";
+import { rewrite_module } from "./rewrite.js";
+import { rewrite_svelte } from "./svelte.js";
+import { is_script_request } from "../script-request.js";
+import { strip_bom } from "../bom.js";
+import { readFileSync, statSync } from "node:fs";
+import { searchForWorkspaceRoot } from "vite";
+// src/compiler/debarrel/plugin.ts
+/**
+* The debarrel Vite plugin — barrel imports become leaf imports at transform time.
+*
+*   import { Button, Card } from '$lib/components';        // an index.ts that re-exports 40 files
+*   → import Button from '/…/components/Button.svelte';
+*     import Card from '/…/components/Card.svelte';
+*
+* Why a plugin and not tree-shaking: dev never tree-shakes (every module behind the barrel is
+* transformed and served); build only drops what `sideEffects: false` allows, and a package that
+* registers components or creates stores is not that; the chunk graph follows the import graph
+* before shaking.
+*
+* Two ways in, one code path: `ogygia({ barrels })` folds it into the ogygia plugin array (first,
+* so the region transform sees leaf imports) and tells it to leave region-marked imports alone;
+* `debarrel()` from `ogygia/vite` is the same plugin for any Vite app, marks or not.
+*
+* Runs `enforce: 'pre'`. Uses the compiler's parser for modules, the Svelte parser for `.svelte`
+* script blocks, `this.resolve` for resolution (aliases, `exports` maps, extensions — whatever the
+* app's Vite knows), and `this.addWatchFile` so an edit to a barrel re-transforms the importers
+* that no longer import it.
+*/
+const IMPORTER_RE = /\.(?:[cm]?[jt]sx?|svelte|svelte\.[jt]s)$/;
+const NODE_MODULES_RE = /[\\/]node_modules[\\/]/;
+const QUERY_RE = /[?#].*$/;
+const BACKSLASH_G = /\\/g;
+function debarrel(options = {}, internal = {}) {
+	const o = normalize_options(options);
+	const skip_keys = new Set(internal.skip_attribute_keys ?? []);
+	const policy_for = (code) => {
+		const locals = internal.skip_locals?.(code);
+		return { skip: (decl) => decl.attribute_keys.some((k) => skip_keys.has(k)) || !!locals && locals.size > 0 && decl.specs.some((s) => locals.has(s.local)) };
+	};
+	let root = process.cwd().replace(BACKSLASH_G, "/");
+	let resolver = null;
+	let log = (msg) => console.log(msg);
+	let command = "serve";
+	const mtimes = /* @__PURE__ */ new Map();
+	const fresh_report = () => ({
+		files: 0,
+		importers: 0,
+		imports: 0,
+		names: 0,
+		first_ms: 0,
+		last_ms: 0,
+		barrels: /* @__PURE__ */ new Map(),
+		/** components the parser could not read: their imports were left on their barrels */
+		skipped: /* @__PURE__ */ new Set()
+	});
+	let report = fresh_report();
+	const warned = /* @__PURE__ */ new Set();
+	const host = {
+		read(id) {
+			try {
+				const st = statSync(id);
+				const prev = mtimes.get(id);
+				if (prev !== void 0 && prev !== st.mtimeMs) index.invalidate(id);
+				mtimes.set(id, st.mtimeMs);
+				return strip_bom(readFileSync(id, "utf8"));
+			} catch {
+				return null;
+			}
+		},
+		async resolve(spec, importer) {
+			if (!resolver) return null;
+			let r;
+			try {
+				r = await resolver.resolve(spec, importer, { skipSelf: true });
+			} catch {
+				return null;
+			}
+			if (!r || r.external) return null;
+			return r.id.replace(BACKSLASH_G, "/");
+		},
+		candidate(id, spec) {
+			if (o.packages.length && matches_any(o.packages, id, spec)) return true;
+			if (o.force.length && matches_any(o.force, id, spec)) return true;
+			return !NODE_MODULES_RE.test(id) && id.startsWith(root + "/");
+		},
+		forced: (id, spec) => o.force.length > 0 && matches_any(o.force, id, spec),
+		kept: (id, spec) => o.keep.length > 0 && matches_any(o.keep, id, spec),
+		follow_packages: o.follow_packages
+	};
+	const index = new BarrelIndex(host);
+	const is_importer = (id) => {
+		if (id.includes("\0")) return false;
+		if (!is_script_request(id)) return false;
+		const clean = id.replace(QUERY_RE, "");
+		if (!IMPORTER_RE.test(clean)) return false;
+		if (o.importer_include.length) return matches_any(o.importer_include, clean, clean);
+		if (NODE_MODULES_RE.test(clean)) return false;
+		if (o.importer_exclude.length && matches_any(o.importer_exclude, clean, clean)) return false;
+		return true;
+	};
+	return {
+		name: "ogygia:debarrel",
+		enforce: "pre",
+		configResolved(config) {
+			root = searchForWorkspaceRoot(config.root).replace(BACKSLASH_G, "/");
+			command = config.command;
+			log = (msg) => config.logger.info(msg);
+		},
+		buildStart() {
+			resolver = this;
+		},
+		async transform(raw, id) {
+			if (!is_importer(id)) return null;
+			const code = strip_bom(raw);
+			resolver = this;
+			const t0 = performance.now();
+			if (report.files === 0) report.first_ms = t0;
+			report.files++;
+			const importer = id.replace(QUERY_RE, "");
+			const seen = [];
+			const lookup = async (spec) => {
+				const resolved = await host.resolve(spec, importer);
+				if (!resolved) return null;
+				const map = await index.map(resolved, spec);
+				if (map) seen.push(map);
+				return map;
+			};
+			const policy = policy_for(code);
+			const result = importer.endsWith(".svelte") ? await rewrite_svelte(code, importer, lookup, policy, (why) => {
+				report.skipped.add(importer);
+				if (warned.has(importer)) return;
+				warned.add(importer);
+				console.warn(`[ogygia] barrels: skipped ${short(importer, root)}: ${why.code}${why.line ? ` at ${why.line}:${why.column ?? 1}` : ""} — its imports stay on their barrels`);
+			}) : await rewrite_module(code, importer, lookup, policy);
+			for (const map of seen) for (const d of map.deps) if (!d.includes("\0")) this.addWatchFile(d);
+			report.last_ms = performance.now();
+			if (!result) return null;
+			report.importers++;
+			report.imports += result.moves.length;
+			for (const m of result.moves) {
+				report.names += m.names.length;
+				const b = report.barrels.get(m.barrel) ?? {
+					names: 0,
+					importers: /* @__PURE__ */ new Set()
+				};
+				b.names += m.names.length;
+				b.importers.add(importer);
+				report.barrels.set(m.barrel, b);
+			}
+			if (o.debug) for (const m of result.moves) log(`[ogygia] barrels: ${short(importer, root)}: ${m.names.join(", ")} ← ${short(m.barrel, root)} → ${m.leaves.map((l) => short(l, root)).join(", ")}`);
+			return {
+				code: result.code,
+				map: result.map
+			};
+		},
+		watchChange(id) {
+			index.invalidate(id.replace(BACKSLASH_G, "/"));
+		},
+		closeBundle() {
+			if (o.report && command === "build") log(format_report(report, root, o.report === "all" ? Infinity : 8));
+			report = fresh_report();
+		}
+	};
+}
+function short(id, root) {
+	return id.startsWith(root + "/") ? id.slice(root.length + 1) : id;
+}
+const n = (v) => v.toLocaleString("en-US");
+/** The build-time report: totals, time spent in the pass, and the barrels by names moved — the
+*  `limit` biggest and a count of the rest (`Infinity` for every one). */
+function format_report(r, root, limit) {
+	const span_s = ((r.last_ms - r.first_ms) / 1e3).toFixed(2);
+	const skipped = r.skipped?.size ? [`  ${n(r.skipped.size)} component${r.skipped.size === 1 ? "" : "s"} skipped (could not be parsed; their imports stay on their barrels): ${[...r.skipped].slice(0, limit).map((id) => short(id, root)).join(", ")}${r.skipped.size > limit ? ` and ${n(r.skipped.size - limit)} more` : ""}`] : [];
+	if (r.importers === 0) return [`[ogygia] barrels: ${n(r.files)} files scanned, no barrel imports to rewrite (${span_s} s)`, ...skipped].join("\n");
+	const head = `[ogygia] barrels: ${n(r.importers)} of ${n(r.files)} files rewritten — ${n(r.imports)} barrel imports → leaves (${n(r.names)} names), ${n(r.barrels.size)} barrels bypassed, ${span_s} s first to last transform`;
+	const sorted = [...r.barrels.entries()].sort((a, b) => b[1].names - a[1].names);
+	const top = sorted.slice(0, limit);
+	const width = Math.max(...top.map(([, b]) => n(b.names).length));
+	const rows = top.map(([id, b]) => `  ${n(b.names).padStart(width)} names  ${short(id, root)}  ← ${n(b.importers.size)} importer${b.importers.size === 1 ? "" : "s"}`);
+	const rest = sorted.length - top.length;
+	if (rest > 0) rows.push(`  … and ${n(rest)} more barrel${rest === 1 ? "" : "s"} (\`barrels: { report: 'all' }\` lists every one)`);
+	return [
+		head,
+		...rows,
+		...skipped
+	].join("\n");
+}
+export { debarrel, format_report, is_script_request };

package/dist/compiler/debarrel/rewrite.d.ts

@@ -0,0 +1,27 @@
+import { ExportMap } from "./barrel.js";
+import { ImportDecl } from "./parse.js";
+import MagicString from "magic-string";
+export interface RewriteMove {
+  barrel: string;
+  names: string[];
+  leaves: string[];
+}
+export interface RewriteResult {
+  code: string;
+  map: ReturnType<MagicString["generateMap"]>;
+  moves: RewriteMove[];
+}
+export interface Lookup {
+  /** The barrel's export map for the import's specifier, or null when the import is left alone. */
+  (source: string): Promise<ExportMap | null>;
+}
+export interface RewritePolicy {
+  /** Leave this declaration exactly as written (ogygia: an import that carries region marks). */
+  skip?: (decl: ImportDecl) => boolean;
+}
+/** Rewrite one module's import declarations. `offset` maps positions when `code` is a slice of a
+ *  bigger file (a Svelte `<script>` block): edits are applied to `ms` at `offset + pos`. `id`
+ *  names the code for the parser (its extension picks the dialect). */
+export declare function rewrite_imports(code: string, id: string, lookup: Lookup, ms: MagicString, offset?: number, policy?: RewritePolicy): Promise<RewriteMove[]>;
+/** Whole-file rewrite for a JS/TS module. */
+export declare function rewrite_module(code: string, id: string, lookup: Lookup, policy?: RewritePolicy): Promise<RewriteResult | null>;

package/dist/compiler/debarrel/rewrite.js

@@ -0,0 +1,118 @@
+import { analyze_imports } from "./parse.js";
+import MagicString from "magic-string";
+// src/compiler/debarrel/rewrite.ts
+/**
+* The importer rewrite: every `import { … } from 'barrel'` whose names the index can place is
+* replaced, in place, by one import per leaf — attributes preserved, local names unchanged, type
+* modifiers kept. Names the index cannot place stay on the barrel; a pure barrel whose names all
+* moved loses its import, an impure (forced) one keeps a bare `import 'barrel'` so its own code
+* still runs. Pure over a lookup function and a code string; sourcemap via magic-string.
+*/
+const BAD_IDENT_RE = /[^A-Za-z0-9_$\u0080-\uFFFF]/;
+const JS_STRING_ESCAPE_RE = /[\\'\n\r\u2028\u2029]/g;
+const JS_STRING_ESCAPES = {
+	"\\": "\\\\",
+	"'": "\\'",
+	"\n": "\\n",
+	"\r": "\\r",
+	"\u2028": "\\u2028",
+	"\u2029": "\\u2029"
+};
+const quote = (s) => "'" + s.replace(JS_STRING_ESCAPE_RE, (c) => JS_STRING_ESCAPES[c]) + "'";
+/** Rewrite one module's import declarations. `offset` maps positions when `code` is a slice of a
+*  bigger file (a Svelte `<script>` block): edits are applied to `ms` at `offset + pos`. `id`
+*  names the code for the parser (its extension picks the dialect). */
+async function rewrite_imports(code, id, lookup, ms, offset = 0, policy = {}) {
+	const decls = analyze_imports(code, id);
+	if (!decls) return [];
+	const moves = [];
+	for (const decl of decls) {
+		if (decl.side_effect) continue;
+		if (decl.type_only) continue;
+		if (decl.specs.some((s) => s.kind === "namespace")) continue;
+		if (policy.skip && policy.skip(decl)) continue;
+		const map = await lookup(decl.source);
+		if (!map || !map.rewritable) continue;
+		const by_leaf = /* @__PURE__ */ new Map();
+		const stays = [];
+		for (const spec of decl.specs) {
+			const entry = map.entries.get(spec.imported);
+			if (!entry || entry === "own" || entry === "ambiguous") {
+				stays.push(spec);
+				continue;
+			}
+			const namespace = "namespace" in entry;
+			const key = namespace ? entry.id + "\0*" : entry.id;
+			const group = by_leaf.get(key) ?? {
+				id: entry.id,
+				namespace,
+				items: []
+			};
+			group.items.push({
+				spec,
+				leaf: entry
+			});
+			by_leaf.set(key, group);
+		}
+		if (by_leaf.size === 0) continue;
+		const lines = [];
+		const leaves = [];
+		const moved = [];
+		for (const group of by_leaf.values()) {
+			leaves.push(group.id);
+			const specs = group.items.map((i) => i.spec);
+			for (const s of specs) moved.push(s.imported);
+			const attrs = decl.attributes;
+			if (group.namespace) {
+				for (const s of specs) lines.push(`import * as ${s.local} from ${quote(group.id)}${attrs};`);
+				continue;
+			}
+			const type_all = decl.type_only || specs.every((s) => s.type_only);
+			const type_kw = type_all ? "type " : "";
+			const named = [];
+			let default_local = null;
+			const more_defaults = [];
+			for (const { spec: s, leaf } of group.items) {
+				const target = "namespace" in leaf ? "*" : leaf.name;
+				if (target === "default") {
+					if (default_local === null) default_local = s.local;
+					else more_defaults.push(s.local);
+					continue;
+				}
+				const mod = !type_all && s.type_only ? "type " : "";
+				const name = BAD_IDENT_RE.test(target) ? JSON.stringify(target) : target;
+				named.push(target === s.local ? `${mod}${target}` : `${mod}${name} as ${s.local}`);
+			}
+			if (default_local !== null && named.length) lines.push(`import ${type_kw}${default_local}, { ${named.join(", ")} } from ${quote(group.id)}${attrs};`);
+			else if (default_local !== null) lines.push(`import ${type_kw}${default_local} from ${quote(group.id)}${attrs};`);
+			else lines.push(`import ${type_kw}{ ${named.join(", ")} } from ${quote(group.id)}${attrs};`);
+			for (const local of more_defaults) lines.push(`import ${type_kw}${local} from ${quote(group.id)}${attrs};`);
+		}
+		if (stays.length) {
+			const type_kw = decl.type_only ? "type " : "";
+			const def = stays.find((s) => s.kind === "default");
+			const named = stays.filter((s) => s.kind === "named").map((s) => `${!decl.type_only && s.type_only ? "type " : ""}${s.imported === s.local ? s.imported : `${s.imported} as ${s.local}`}`);
+			const parts = [def ? def.local : null, named.length ? `{ ${named.join(", ")} }` : null].filter(Boolean);
+			lines.push(`import ${type_kw}${parts.join(", ")} from ${quote(decl.source)}${decl.attributes};`);
+		} else if (!map.pure) lines.push(`import ${quote(decl.source)}${decl.attributes};`);
+		ms.overwrite(offset + decl.start, offset + decl.end, lines.join("\n"));
+		moves.push({
+			barrel: map.id,
+			names: moved,
+			leaves: [...new Set(leaves)]
+		});
+	}
+	return moves;
+}
+/** Whole-file rewrite for a JS/TS module. */
+async function rewrite_module(code, id, lookup, policy = {}) {
+	const ms = new MagicString(code);
+	const moves = await rewrite_imports(code, id, lookup, ms, 0, policy);
+	if (moves.length === 0) return null;
+	return {
+		code: ms.toString(),
+		map: ms.generateMap({ hires: true }),
+		moves
+	};
+}
+export { rewrite_imports, rewrite_module };

package/dist/compiler/debarrel/svelte.d.ts

@@ -0,0 +1,13 @@
+import { blank_styles } from "../blank-styles.js";
+import { Lookup, RewritePolicy, RewriteResult } from "./rewrite.js";
+/** Why a component was skipped: the parser's code and where (1-based line and column). */
+export interface SvelteSkip {
+  code: string;
+  line?: number;
+  column?: number;
+}
+/** Rewrite the imports in a Svelte component's script blocks. Null when nothing changed.
+ *  `on_skip`: told when the component still cannot be parsed (its imports then stay on their
+ *  barrels) — the plugin warns and counts it, rather than skip in silence. */
+export declare function rewrite_svelte(code: string, filename: string, lookup: Lookup, policy?: RewritePolicy, on_skip?: (why: SvelteSkip) => void): Promise<RewriteResult | null>;
+export { blank_styles };

package/dist/compiler/debarrel/svelte.js

@@ -0,0 +1,56 @@
+import { blank_styles } from "../blank-styles.js";
+import { rewrite_imports } from "./rewrite.js";
+import { parse } from "svelte/compiler";
+import MagicString from "magic-string";
+// src/compiler/debarrel/svelte.ts
+/**
+* Svelte importers: the imports live in `<script>` and `<script module>` blocks. The Svelte parser
+* (modern AST, the one the region transform uses) gives their exact content ranges — no regex over
+* markup, so a `<script>` inside a template string or an `{@html}` never confuses us. The block's
+* `lang` picks the dialect: the slice is parsed under `<file>.svelte.ts` / `<file>.svelte.js`.
+* The styles are blanked before the parse (`blank_styles`): only the scripts are read.
+*/
+function lang_of_block(block) {
+	for (const attr of block.attributes) {
+		if (attr.type !== "Attribute" || attr.name !== "lang" || attr.value === true) continue;
+		const v = (Array.isArray(attr.value) ? attr.value : [attr.value]).map((t) => t.type === "Text" ? t.data ?? "" : "").join("");
+		return v === "ts" || v === "typescript" ? "ts" : "js";
+	}
+	return "js";
+}
+/** Rewrite the imports in a Svelte component's script blocks. Null when nothing changed.
+*  `on_skip`: told when the component still cannot be parsed (its imports then stay on their
+*  barrels) — the plugin warns and counts it, rather than skip in silence. */
+async function rewrite_svelte(code, filename, lookup, policy = {}, on_skip) {
+	let ast;
+	try {
+		ast = parse(blank_styles(code), {
+			modern: true,
+			filename
+		});
+	} catch (err) {
+		const e = err;
+		on_skip?.({
+			code: e.code ?? (e.message ?? "parse error").split("\n")[0].slice(0, 80),
+			line: e.start?.line,
+			column: e.start?.column !== void 0 ? e.start.column + 1 : void 0
+		});
+		return null;
+	}
+	const ms = new MagicString(code);
+	const moves = [];
+	for (const block of [ast.module, ast.instance]) {
+		if (!block) continue;
+		const { start, end } = block.content;
+		const inner = code.slice(start, end);
+		const id = `${filename}.${lang_of_block(block)}`;
+		moves.push(...await rewrite_imports(inner, id, lookup, ms, start, policy));
+	}
+	if (moves.length === 0) return null;
+	return {
+		code: ms.toString(),
+		map: ms.generateMap({ hires: true }),
+		moves
+	};
+}
+export { blank_styles, rewrite_svelte };

package/dist/compiler/dev/css-scope.d.ts

@@ -0,0 +1,16 @@
+/** Structural shape of a Vite dev module-graph node (the two fields the owner walk reads). */
+export type DevGraphModule = {
+  file?: string | null;
+  importers?: Iterable<DevGraphModule>;
+};
+/**
+ * Which top-level route scopes can reach `abs_file` — walked UP the dev module graph until route
+ * files are hit. A scope is a route file's first path segment under `src/routes` (`'(docs)'`,
+ * `'playground'`, `''` for a root-level route file). `[]` = no route owner found; the client treats
+ * that as shared and joins anywhere (the safe default for exotic graphs).
+ *
+ * @internal Exported for unit tests.
+ */
+export declare function derive_css_scope_owners(abs_file: string, root: string, graphs: Array<{
+  getModulesByFile?: (f: string) => Set<DevGraphModule> | undefined;
+} | undefined | null>): string[];

package/dist/compiler/dev/css-scope.js

@@ -0,0 +1,38 @@
+import { path } from "../host.js";
+import { kit_dirs } from "../kit.js";
+// src/compiler/dev/css-scope.ts
+/**
+* Dev-only CSS scope ownership — walks UP the Vite dev module graph to find which top-level route
+* scopes can reach a changed stylesheet, so the soft-CSS-HMR bridge joins a file only on the pages
+* whose sub-app actually owns it. Pure over the graph nodes it is handed; reads, never mutates.
+*/
+/**
+* Which top-level route scopes can reach `abs_file` — walked UP the dev module graph until route
+* files are hit. A scope is a route file's first path segment under `src/routes` (`'(docs)'`,
+* `'playground'`, `''` for a root-level route file). `[]` = no route owner found; the client treats
+* that as shared and joins anywhere (the safe default for exotic graphs).
+*
+* @internal Exported for unit tests.
+*/
+function derive_css_scope_owners(abs_file, root, graphs) {
+	const routes_dir = kit_dirs(root).routes_dir + path.sep;
+	const owners = /* @__PURE__ */ new Set();
+	const seen = /* @__PURE__ */ new Set();
+	const stack = [];
+	for (const g of graphs) for (const m of g?.getModulesByFile?.(abs_file) ?? []) stack.push(m);
+	let steps = 0;
+	while (stack.length && steps++ < 5e3) {
+		const mod = stack.pop();
+		if (seen.has(mod)) continue;
+		seen.add(mod);
+		const f = mod.file ? path.normalize(mod.file) : null;
+		if (f && f.startsWith(routes_dir)) {
+			const seg = f.slice(routes_dir.length).split(path.sep)[0] ?? "";
+			owners.add(seg.includes(".") ? "" : seg);
+			continue;
+		}
+		for (const imp of mod.importers ?? []) stack.push(imp);
+	}
+	return [...owners].sort();
+}
+export { derive_css_scope_owners };

package/dist/compiler/dev/dev-hmr.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Client bridge source for `virtual:ogygia/dev-hmr` (vite serve only). Pure codegen: it returns the
+ * JS text the adapter serves for the dev soft-CSS-HMR bridge. No build state.
+ */
+/**
+ * Client bridge source for `virtual:ogygia/dev-hmr` (vite serve only): a LAZY map of app CSS under
+ * `/src`, joined per-file when the plugin broadcasts a scoped `ogygia:css` event — plus full-reload
+ * on `vite:error`.
+ *
+ * LAZY is load-bearing. The bridge used to join every `/src` stylesheet EAGERLY, which painted the
+ * whole app's CSS onto every page — invisible while one app owned one look, but the moment two
+ * sub-apps share one project (the `(docs)` / `playground` split), each page wore the other's skin
+ * in dev while prod (Kit's per-route CSS) stayed clean. Now a page boots with exactly its SSR CSS,
+ * and joins a stylesheet only when it changes AND this page's route scope owns it (the
+ * `ogygia-dev-scope` meta the handle stamps vs. the owners the plugin derives from the module
+ * graph). Once joined, later edits soft-apply through Vite's normal CSS HMR.
+ *
+ * Do **not** strip Kit’s `<style data-sveltekit>` FOUC bag. Under `csr = false` that bag is
+ * how page + component CSS is delivered (no client module graph for route shells). Removing
+ * it blanks the page; a MutationObserver would also delete FOUC styles the SPA router merges
+ * in on navigation.
+ *
+ * @internal Emitted by the plugin; exported for unit tests.
+ */
+export declare function dev_hmr_client_source(): string;

package/dist/compiler/dev/dev-hmr.js

@@ -0,0 +1,29 @@
+// src/compiler/dev/dev-hmr.ts
+/**
+* Client bridge source for `virtual:ogygia/dev-hmr` (vite serve only). Pure codegen: it returns the
+* JS text the adapter serves for the dev soft-CSS-HMR bridge. No build state.
+*/
+/**
+* Client bridge source for `virtual:ogygia/dev-hmr` (vite serve only): a LAZY map of app CSS under
+* `/src`, joined per-file when the plugin broadcasts a scoped `ogygia:css` event — plus full-reload
+* on `vite:error`.
+*
+* LAZY is load-bearing. The bridge used to join every `/src` stylesheet EAGERLY, which painted the
+* whole app's CSS onto every page — invisible while one app owned one look, but the moment two
+* sub-apps share one project (the `(docs)` / `playground` split), each page wore the other's skin
+* in dev while prod (Kit's per-route CSS) stayed clean. Now a page boots with exactly its SSR CSS,
+* and joins a stylesheet only when it changes AND this page's route scope owns it (the
+* `ogygia-dev-scope` meta the handle stamps vs. the owners the plugin derives from the module
+* graph). Once joined, later edits soft-apply through Vite's normal CSS HMR.
+*
+* Do **not** strip Kit’s `<style data-sveltekit>` FOUC bag. Under `csr = false` that bag is
+* how page + component CSS is delivered (no client module graph for route shells). Removing
+* it blanks the page; a MutationObserver would also delete FOUC styles the SPA router merges
+* in on navigation.
+*
+* @internal Emitted by the plugin; exported for unit tests.
+*/
+function dev_hmr_client_source() {
+	return "import \"/@vite/client\";\nconst css_modules = import.meta.glob(\"/src/**/*.{css,scss,sass,less,styl}\", { eager: false });\nconst scope_meta = document.querySelector('meta[name=\"ogygia-dev-scope\"]');\nconst scope = scope_meta ? scope_meta.getAttribute(\"content\") || \"\" : \"\";\n// Soft path: scoped join on first change, then Vite CSS HMR (injected after FOUC; later rules win).\n// Hard path: anything Vite can't apply.\nfunction ogygia_full_reload() {\n  location.reload();\n}\nif (import.meta.hot) {\n  import.meta.hot.accept();\n  import.meta.hot.on(\"vite:error\", ogygia_full_reload);\n  import.meta.hot.on(\"ogygia:css\", (d) => {\n    const p = d && d.path;\n    if (!p || !css_modules[p]) return;\n    const owners = (d && d.owners) || [];\n    // Join only what this page's sub-app owns; ownerless css (shared / undeterminable) joins anywhere.\n    if (owners.length && owners.indexOf(scope) === -1) return;\n    css_modules[p]();\n  });\n}\n";
+}
+export { dev_hmr_client_source };

package/dist/compiler/dev/hmr.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Host route shells (`+page` / `+layout` / …) never join the browser module graph under
+ * `csr=false`, so Vite's fine-grained HMR for them has no client importer. Force a full reload.
+ * Standalone CSS is soft-updated via `virtual:ogygia/dev-hmr` (Vite inject after Kit FOUC).
+ * If that soft path fails, the client bridge listens for `vite:error` and reloads the document.
+ *
+ * @internal HMR policy helper (also covered by unit tests).
+ */
+export declare function needs_csr_false_full_reload(file: string): boolean;
+/**
+ * Island entry `.svelte` files (the `import X from '…' with { hydrate }`) sit behind a virtual
+ * wrapper; Svelte soft HMR through that edge is unreliable. Shared `.ts` deps still soft-update.
+ *
+ * @internal HMR policy helper (also covered by unit tests).
+ */
+export declare function needs_island_entry_full_reload(file: string, entries: Iterable<{
+  componentPath?: string | null;
+}>): boolean;
+/**
+ * Absolute path equality with querystrings stripped (host vs component vs Vite watch paths).
+ * @internal
+ */
+export declare function same_module_path(a: string | null | undefined, b: string | null | undefined): boolean;
+/**
+ * Virtual island ids whose generated source must be dropped when `file` changes or is deleted.
+ * Island ids are `hash(componentPath\\0strategyKey)` — renaming a host route keeps the same id, so
+ * Vite's moduleGraph must be invalidated or it keeps serving the old import.
+ *
+ * @internal HMR invalidation helper (also covered by unit tests).
+ */
+export declare function island_vpaths_affected_by_file(file: string, entries: Iterable<[string, {
+  hostPath?: string | null;
+  componentPath?: string | null;
+}]>): string[];

package/dist/compiler/dev/hmr.js

@@ -0,0 +1,57 @@
+import { path } from "../host.js";
+// src/compiler/dev/hmr.ts
+/**
+* HMR reload-decision helpers — pure policy functions the Vite adapter's `handleHotUpdate` /
+* `watchChange` consult to decide between a soft update and a full document reload. No build state;
+* data in → decision out. Covered by unit tests.
+*/
+const BACKSLASH = /\\/g;
+const STYLE_EXT = /\.(css|scss|sass|less|styl)(?:$|\?)/i;
+const KIT_ROUTE_FILE = /(?:^|\/)\+(?:page|layout|error|server|hooks)(?:\.|$)/;
+/**
+* Host route shells (`+page` / `+layout` / …) never join the browser module graph under
+* `csr=false`, so Vite's fine-grained HMR for them has no client importer. Force a full reload.
+* Standalone CSS is soft-updated via `virtual:ogygia/dev-hmr` (Vite inject after Kit FOUC).
+* If that soft path fails, the client bridge listens for `vite:error` and reloads the document.
+*
+* @internal HMR policy helper (also covered by unit tests).
+*/
+function needs_csr_false_full_reload(file) {
+	const norm = file.replace(BACKSLASH, "/");
+	if (STYLE_EXT.test(norm)) return false;
+	return KIT_ROUTE_FILE.test(norm);
+}
+/**
+* Island entry `.svelte` files (the `import X from '…' with { hydrate }`) sit behind a virtual
+* wrapper; Svelte soft HMR through that edge is unreliable. Shared `.ts` deps still soft-update.
+*
+* @internal HMR policy helper (also covered by unit tests).
+*/
+function needs_island_entry_full_reload(file, entries) {
+	const bare = file.split("?")[0];
+	if (!bare.endsWith(".svelte")) return false;
+	if (STYLE_EXT.test(bare.replace(BACKSLASH, "/"))) return false;
+	for (const entry of entries) if (same_module_path(entry.componentPath, file)) return true;
+	return false;
+}
+/**
+* Absolute path equality with querystrings stripped (host vs component vs Vite watch paths).
+* @internal
+*/
+function same_module_path(a, b) {
+	if (!a || !b) return false;
+	return path.resolve(a.split("?")[0]) === path.resolve(b.split("?")[0]);
+}
+/**
+* Virtual island ids whose generated source must be dropped when `file` changes or is deleted.
+* Island ids are `hash(componentPath\\0strategyKey)` — renaming a host route keeps the same id, so
+* Vite's moduleGraph must be invalidated or it keeps serving the old import.
+*
+* @internal HMR invalidation helper (also covered by unit tests).
+*/
+function island_vpaths_affected_by_file(file, entries) {
+	const out = [];
+	for (const [vpath, entry] of entries) if (same_module_path(entry.hostPath, file) || same_module_path(entry.componentPath, file)) out.push(vpath);
+	return out;
+}
+export { island_vpaths_affected_by_file, needs_csr_false_full_reload, needs_island_entry_full_reload, same_module_path };