@ogygia/core 0.0.0 → 0.11.0

package/dist/vite/paths.d.ts

@@ -0,0 +1,45 @@
+/** This package's root (the plugin runs from `dist/vite/`, so `../..` is the package root). A NATIVE
+ *  path (backslashes on Windows): for the file system, never to compare against a module id. */
+export declare const PKG_ROOT: string;
+/** A native path as Vite writes module ids: symlinks resolved (pnpm), forward slashes (Windows). */
+export declare function real_posix(p: string): string;
+/** A native directory as the PREFIX of the module ids inside it: `real_posix` + one trailing `/`, so a
+ *  `startsWith` never matches a sibling (`ogygia-x/`) and holds on Windows, where the native path has
+ *  backslashes and Vite's ids do not. */
+export declare function id_dir(p: string): string;
+/** THE own-package test: every module id inside this package starts with this. Every check of "is
+ *  this id ogygia's own file" compares against it, never against PKG_ROOT. */
+export declare const PKG_ROOT_ID: string;
+/** An island file as an `optimizeDeps.entries` pattern, or null for one of ogygia's OWN islands (the
+ *  profiler UI): ogygia is in `optimizeDeps.exclude`, so the scanner can't resolve inside it, and one
+ *  unresolved import fails the whole scan (nothing pre-bundles). Its client deps are named up front
+ *  instead (the plugin's `dev_island_deps`). */
+export declare function scan_entry_pattern(file: string, own_root?: string): string | null;
+/** The two ogygia self-imports the transform injects into hosts / generated island modules. */
+export declare const OGYGIA_INJECTED_IMPORTS: Set<string>;
+/** ogygia's `Region.svelte` — either copy, as the POSIX id Vite hands the transform hook (a workspace
+ *  can load the src one and the dist one both): its LateIsland import is the awaiting one where the
+ *  app runs Svelte's async mode (late-island.ts). */
+export declare const OGYGIA_REGION_MODULES: ReadonlySet<string>;
+export declare const OGYGIA_INJECTED_FILES: Record<string, string>;
+/** Client-side shims aliased for island modules (Kit's client runtime is absent under csr=false). */
+export declare const APP_SHIMS: {
+  "$app/state": string;
+  "$app/stores": string;
+  "$app/navigation": string;
+};
+/** On-disk stub for `virtual:ogygia/client-binding-stub` (csr=false client hosts). */
+export declare const CLIENT_BINDING_STUB_FILE: string;
+export declare const STUB_CLIENT: string;
+export declare const STUB_STATE: string;
+export declare const STUB_PATHS: string;
+export declare const KIT_REMOTE_CLIENT: RegExp;
+export declare const KIT_REMOTE_STATE: RegExp;
+/** Absolute path to real HMAC (SSR-only via `virtual:ogygia/sign`). */
+export declare const HMAC_MODULE: string;
+/** The prebuilt runtime dir the runtime chunk bundles (for `generateRuntimeEntrySource`). */
+export declare const RUNTIME_DIR: string;
+/** Absolute path to SSR region-endpoint helper (signed capability URLs). */
+export declare const REGION_ENDPOINT_MODULE: string;
+/** The runtime chunk's source-content hash (the immutable-filename base; feature hash rides on top). */
+export declare const RUNTIME_HASH: string;

package/dist/vite/paths.js

@@ -0,0 +1,112 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+// src/vite/paths.ts
+/**
+* Package-internal path resolution for the Vite adapter — ogygia's OWN files, addressed head-on
+* (never via `this.resolve`, which isn't portable off a synthetic importer). Split out of index.ts so
+* the plugin file stays lean. Every path resolves relative to THIS module's URL; paths.js and index.js
+* ship in the same `dist/vite/` directory, so `../…` resolves identically from either.
+*/
+/** This package's root (the plugin runs from `dist/vite/`, so `../..` is the package root). A NATIVE
+*  path (backslashes on Windows): for the file system, never to compare against a module id. */
+const PKG_ROOT = fileURLToPath(new URL("../..", import.meta.url));
+/** Windows separators → posix. */
+const WIN_SEP_RE = /\\/g;
+/** A native path as Vite writes module ids: symlinks resolved (pnpm), forward slashes (Windows). */
+function real_posix(p) {
+	try {
+		p = fs.realpathSync(p);
+	} catch {}
+	return p.replace(WIN_SEP_RE, "/");
+}
+/** A native directory as the PREFIX of the module ids inside it: `real_posix` + one trailing `/`, so a
+*  `startsWith` never matches a sibling (`ogygia-x/`) and holds on Windows, where the native path has
+*  backslashes and Vite's ids do not. */
+function id_dir(p) {
+	const posix = real_posix(p);
+	return posix.endsWith("/") ? posix : posix + "/";
+}
+/** THE own-package test: every module id inside this package starts with this. Every check of "is
+*  this id ogygia's own file" compares against it, never against PKG_ROOT. */
+const PKG_ROOT_ID = id_dir(PKG_ROOT);
+const GLOB_META_RE = /[()[\]{}*?!]/g;
+/** An island file as an `optimizeDeps.entries` pattern, or null for one of ogygia's OWN islands (the
+*  profiler UI): ogygia is in `optimizeDeps.exclude`, so the scanner can't resolve inside it, and one
+*  unresolved import fails the whole scan (nothing pre-bundles). Its client deps are named up front
+*  instead (the plugin's `dev_island_deps`). */
+function scan_entry_pattern(file, own_root = PKG_ROOT_ID) {
+	const posix = real_posix(file);
+	return posix.startsWith(own_root) ? null : posix.replace(GLOB_META_RE, "\\$&");
+}
+/** The two ogygia self-imports the transform injects into hosts / generated island modules. */
+const OGYGIA_INJECTED_IMPORTS = /* @__PURE__ */ new Set(["ogygia/internal", "ogygia/internal/server"]);
+/**
+* DIRECT paths to ogygia's OWN injected runtime entries, resolved WITHOUT `this.resolve`. The
+* transform writes `ogygia/internal` / `ogygia/internal/server` into a host or a generated island
+* module, and a host in a monorepo sub-package that doesn't depend on ogygia must still resolve them.
+* `this.resolve` off a synthetic importer is NOT portable across bundler versions (returns null in
+* vite@8, can THROW in rolldown-vite@7 — which aborts the whole hook), and `config.root` can be
+* undefined on a throwaway Kit plugin instance — so we address ogygia's own files head-on instead.
+*
+* A published install ships only `dist` → `dist/internal.js`. ogygia's OWN source checkout has `src/`,
+* and the rest of the app resolves ogygia through the `svelte` export condition (→ `src`), so there we
+* point at `src/internal.ts` too — same module, no Region/brand identity fork.
+*/
+const OG_HAS_SRC = fs.existsSync(path.join(PKG_ROOT, "src/internal.ts"));
+/** ogygia's `Region.svelte` — either copy, as the POSIX id Vite hands the transform hook (a workspace
+*  can load the src one and the dist one both): its LateIsland import is the awaiting one where the
+*  app runs Svelte's async mode (late-island.ts). */
+const OGYGIA_REGION_MODULES = /* @__PURE__ */ new Set([PKG_ROOT_ID + "src/Region.svelte", PKG_ROOT_ID + "dist/Region.svelte"]);
+const OGYGIA_INJECTED_FILES = OG_HAS_SRC ? {
+	"ogygia/internal": path.join(PKG_ROOT, "src/internal.ts"),
+	"ogygia/internal/server": path.join(PKG_ROOT, "src/internal-server.ts")
+} : {
+	"ogygia/internal": path.join(PKG_ROOT, "dist/internal.js"),
+	"ogygia/internal/server": path.join(PKG_ROOT, "dist/internal-server.js")
+};
+/** Client-side shims aliased for island modules (Kit's client runtime is absent under csr=false). */
+const APP_SHIMS = {
+	"$app/state": fileURLToPath(new URL("../shims/app-state.svelte.js", import.meta.url)),
+	"$app/stores": fileURLToPath(new URL("../shims/app-stores.js", import.meta.url)),
+	"$app/navigation": fileURLToPath(new URL("../shims/app-navigation.js", import.meta.url))
+};
+/** On-disk stub for `virtual:ogygia/client-binding-stub` (csr=false client hosts). */
+const CLIENT_BINDING_STUB_FILE = fileURLToPath(new URL("../ClientBindingStub.svelte", import.meta.url));
+const STUB_CLIENT = fileURLToPath(new URL("../shims/kit-remote/client-stub.js", import.meta.url));
+const STUB_STATE = fileURLToPath(new URL("../shims/kit-remote/state-stub.js", import.meta.url));
+const STUB_PATHS = fileURLToPath(new URL("../shims/kit-remote/paths-internal-stub.js", import.meta.url));
+const KIT_REMOTE_CLIENT = /(^|\/)client\.js$/;
+const KIT_REMOTE_STATE = /state\.svelte\.js$/;
+/** Absolute path to real HMAC (SSR-only via `virtual:ogygia/sign`). */
+const HMAC_MODULE = fileURLToPath(new URL("../server/hmac.js", import.meta.url));
+/** The prebuilt runtime dir the runtime chunk bundles (for `generateRuntimeEntrySource`). */
+const RUNTIME_DIR = fileURLToPath(new URL("../runtime", import.meta.url));
+/** Absolute path to SSR region-endpoint helper (signed capability URLs). */
+const REGION_ENDPOINT_MODULE = fileURLToPath(new URL("../server/region-endpoint.js", import.meta.url));
+function runtime_content_hash() {
+	const inputs = [
+		fileURLToPath(new URL("../compiler/link/runtime-entry.js", import.meta.url)),
+		fileURLToPath(new URL("../live-transport.js", import.meta.url)),
+		fileURLToPath(new URL("../context-bridge.js", import.meta.url)),
+		fileURLToPath(new URL("../keep-fallback-marker.js", import.meta.url)),
+		fileURLToPath(new URL("../shims/page-store.svelte.js", import.meta.url)),
+		fileURLToPath(new URL("../shims/kit-remote/client-stub.js", import.meta.url)),
+		fileURLToPath(new URL("../NestedProvider.svelte", import.meta.url)),
+		fileURLToPath(new URL("../LiveHost.svelte", import.meta.url)),
+		fileURLToPath(new URL("../KeepHost.svelte", import.meta.url))
+	];
+	try {
+		const rt_dir = fileURLToPath(new URL("../runtime", import.meta.url));
+		for (const name of fs.readdirSync(rt_dir)) if (name.endsWith(".js")) inputs.push(path.join(rt_dir, name));
+	} catch {}
+	const h = crypto.createHash("sha256");
+	for (const f of inputs) try {
+		h.update(fs.readFileSync(f));
+	} catch {}
+	return h.digest("hex").slice(0, 12);
+}
+/** The runtime chunk's source-content hash (the immutable-filename base; feature hash rides on top). */
+const RUNTIME_HASH = runtime_content_hash();
+export { APP_SHIMS, CLIENT_BINDING_STUB_FILE, HMAC_MODULE, KIT_REMOTE_CLIENT, KIT_REMOTE_STATE, OGYGIA_INJECTED_FILES, OGYGIA_INJECTED_IMPORTS, OGYGIA_REGION_MODULES, PKG_ROOT, PKG_ROOT_ID, REGION_ENDPOINT_MODULE, RUNTIME_DIR, RUNTIME_HASH, STUB_CLIENT, STUB_PATHS, STUB_STATE, id_dir, real_posix, scan_entry_pattern };

package/dist/vite/plugin-api.d.ts

@@ -0,0 +1,166 @@
+import { ServerRealm } from "../compiler/link/caps.js";
+import { Plugin } from "vite";
+/** Where `definePlugin` puts the definition on the Vite plugin it returns. A registered symbol, so a
+ *  second copy of ogygia in one app still recognizes the first's plugins. */
+export declare const PLUGIN: unique symbol;
+/** The value a plugin's factory returns: a Vite plugin carrying its definition. */
+export interface OgygiaPlugin<Options = unknown> extends Plugin {
+  readonly [PLUGIN]: PluginDefinition<Options>;
+}
+/** What a plugin is: the argument to `definePlugin`. */
+export interface PluginDefinition<Options = unknown> {
+  /** The plugin's package name (`'@ogygia/postrender'`): its identity. */
+  name: string;
+  /** The SERVER realm: a module whose default export is `defineServer({…})` (`ogygia/plugin`), as a
+   *  `file:` URL or an absolute path — `import.meta.resolve('./server.ts')`. */
+  server?: string;
+  /** The BROWSER realm: a module whose default export is `defineClient({…})` (`ogygia/plugin/client`),
+   *  booted on every page — same form as `server`. */
+  client?: string;
+  /** Settings for every realm (JSON: no functions, no clients — live objects are configured at
+   *  runtime, in hooks.server.ts). */
+  options?: Options;
+  /** Run before (`'pre'`) or after (`'post'`) the other plugins, in every realm. */
+  enforce?: "pre" | "post";
+  /** Build-time contributions, with the build context. */
+  build?(b: BuildContext): void;
+}
+/** A `import.meta.og.<name>` macro: rewrites a module that contains the marker (it is called only
+ *  then), before the island transform or region minting see it. Returns the new code (the same
+ *  string when nothing changed). */
+export type MacroHandler = (code: string, m: MacroContext) => string | Promise<string>;
+/** What a macro knows about the module it rewrites. */
+export interface MacroContext {
+  /** The module id, query stripped. */
+  readonly id: string;
+  /** The id relative to the app root, POSIX (a stable identity for stamps). */
+  readonly rel: string;
+  readonly root: string;
+  /** Markup extensions whose `<script>` blocks hold the macro calls (`.svelte`). */
+  readonly markupExts: readonly string[];
+}
+/** A source format that becomes Svelte only through a preprocessor (markdown → Svelte): how its
+ *  islands and its modules' own scoped CSS reach the build. */
+export interface MarkupSource {
+  /** The format's file extensions (`['.svx', '.md']`). */
+  extensions: readonly string[];
+  /** Discover the format's islands up front (build start, dev included): read each file, turn it
+   *  into Svelte, and hand that to `transform` so its islands are registered before chunks emit. */
+  scan?(ctx: {
+    root: string;
+    readFile(abs: string): string | null;
+  }): void | Promise<void>;
+  /** Modules that carry their OWN scoped `<style>`, absolute path → their post-preprocess Svelte
+   *  source: the build compiles each one's CSS and ships it as a client asset (the module itself
+   *  only ever renders on the server). The plugin keeps filling this map; the build reads it late. */
+  styles?: ReadonlyMap<string, string>;
+}
+/** What the build hands back for a markup source: run the region transform on preprocessed Svelte. */
+export interface MarkupRegions {
+  /** Rewrite the marked imports in already-preprocessed Svelte and register its regions. The code,
+   *  or null when nothing changed. */
+  transform(source: string, filename: string): string | null;
+}
+/** The build, as one plugin sees it (handed to `build`). */
+export interface BuildContext {
+  /** The app's root directory. */
+  readonly root: string;
+  /** `vite dev` (true) or `vite build` (false). */
+  readonly dev: boolean;
+  /** A key this plugin reads inside Kit's own `config` page option (`export const config = { <key>:
+   *  false }` in a `+page` / `+layout` module, `.server` included). Read at build time, merged the
+   *  way Kit merges `config` (layouts, then the page; later wins), and answered on the server by
+   *  `ctx.routeConfig(key)`. Literal values only (a boolean, number, string or null); nothing is
+   *  stripped, because Kit accepts any key inside `config`. */
+  routeConfig(key: string): void;
+  /** Keep the foreign-hydrate exports on this app's island entries: another app's page may host
+   *  them and wake them through its own runtime (fragment federation). Off by default — they cost
+   *  every island ~185 B gz and a preload. */
+  foreignHydrate(): void;
+  /** An `import.meta.og.<name>(…)` construct this plugin compiles (`'code'`, `'loader'`). Plugin
+   *  macros run after core's own (`wire`, `$`, `source`, `store`) and before `bake`, in plugin order. */
+  macro(name: string, handler: MacroHandler): void;
+  /** A source format that becomes Svelte through a preprocessor (markdown): register it, get the
+   *  island transform to call from that preprocessor. */
+  markup(source: MarkupSource): MarkupRegions;
+  /** Compile core's EVENT emits in, browser and server (`ogygia/events`: island wakes, server renders,
+   *  hub mints, navigations) — off, every emit folds away. `lazy`: measure only once a viewer opens a
+   *  tool (the page carries a launcher; a preview build). */
+  events(options?: {
+    lazy?: boolean;
+  }): void;
+  /** Record the build's MEASUREMENT data: per-island detail, chunk contents, server source maps, the
+   *  module map, the embedded maps, the request stats' detail — what a profiler reads. */
+  measure(): void;
+  /** Compile a package's files as app source (their islands, router-css roots): `dirs` / `files`
+   *  absolute, under `root` (the package's directory). For a plugin's own pages (a UI it serves). */
+  files(scan: {
+    root: string;
+    dirs?: string[];
+    files?: string[];
+  }): void;
+  /** Modules that render pages outside Kit's routes (a programmatic router): every component they
+   *  import gets its whole-tree CSS linked when it renders (`componentCssHead()` from
+   *  `ogygia/plugin/css`). `importers`: any compiled module importing one of these specifiers is a
+   *  page module; `files`: absolute paths that are page modules themselves (compiled ones: app source,
+   *  or a `files()` / `ogygia.files` surface). */
+  pageModules(modules: {
+    importers?: string[];
+    files?: string[];
+  }): void;
+}
+/** A plugin, as the Vite plugin the app lists beside `ogygia()`. */
+export declare function definePlugin<Options = undefined>(definition: PluginDefinition<Options>): OgygiaPlugin<Options>;
+/** The plugin definitions in the app's Vite plugin list (nested arrays and promises included), in
+ *  list order, shape-checked. `ogygia()` and its plugins come before `sveltekit()`: Vite runs
+ *  same-stage hooks in list order, and theirs (the content pre-transforms, the config ogygia hands
+ *  Kit) must see a module before Kit's do. */
+export declare function find_plugins(list: unknown): Promise<PluginDefinition[]>;
+/** What the build takes from the app's plugins. */
+export interface ResolvedPlugins {
+  /** each server realm, in plugin order (`enforce` applied) */
+  servers: ServerRealm[];
+  /** each browser realm (an absolute path), in plugin order */
+  clients: string[];
+  /** every key any plugin claims inside Kit's `config` page option */
+  route_config: string[];
+  /** a plugin asked for island entries' foreign-hydrate exports */
+  foreign_hydrate: boolean;
+  /** plugin macros, in plugin order */
+  macros: {
+    name: string;
+    handler: MacroHandler;
+  }[];
+  /** markup sources (a preprocessor format with islands) */
+  markup: MarkupSource[];
+  /** a plugin asked for core's events (`lazy`: measure once a tool opens), or false */
+  events: false | {
+    lazy: boolean;
+  };
+  /** a plugin asked for the build's measurement data */
+  measure: boolean;
+  /** package files compiled as app source, per plugin */
+  files: {
+    name: string;
+    root: string;
+    dirs: string[];
+    files: string[];
+  }[];
+  /** page modules (`b.pageModules()`): the specifiers whose importers are page modules, and files
+   *  that are page modules themselves */
+  page_modules: {
+    importers: string[];
+    files: string[];
+  };
+}
+/**
+ * Config-time shape check of the definitions found: each named once, its realms locations, its
+ * options JSON.
+ */
+export declare function check_plugins(plugins: readonly unknown[]): PluginDefinition[];
+/**
+ * When the app's root and mode are known (the `config` hook): order the plugins (`enforce`), check their
+ * realms, run their `build` hooks. `markup_transform` is the configured compiler's island
+ * transform for preprocessed markup (what `b.markup()` hands back).
+ */
+export declare function resolve_plugins(plugins: readonly PluginDefinition[], root: string, dev: boolean, markup_transform?: MarkupRegions["transform"]): ResolvedPlugins;

package/dist/vite/plugin-api.js

@@ -0,0 +1,212 @@
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+// src/vite/plugin-api.ts
+/**
+* The BUILD side of a plugin (design: internal/notes/packages.md, plugin API v2): `definePlugin` and
+* the build context. Loads in plain node — vite.config imports it before any bundler runs.
+*
+*   export const postrender = (options: PostrenderOptions = {}) =>
+*     definePlugin({
+*       name: '@ogygia/postrender',                    // the package name: the plugin's identity
+*       options,                                        // JSON; reaches the server realm as `app.options`
+*       server: import.meta.resolve('./server.ts'),     // the server realm (`defineServer`)
+*       build(b) { b.routeConfig('postrender'); }
+*     });
+*
+* A plugin IS a Vite plugin: the app lists it beside `ogygia()` (`plugins: [ogygia(), postrender(),
+* sveltekit()]`), and `ogygia()` finds it there by the definition it carries under {@link PLUGIN} —
+* never by its name. A factory that needs Vite hooks of its own returns them beside it, as an array.
+*
+* REALMS are named by the plugin: `server` and `client` point at the modules themselves, resolved
+* next to the factory (`import.meta.resolve`), so they are the same files the package's own imports
+* reach and a plugin's modules exist once. A package's export names stay its own.
+*/
+/** Where `definePlugin` puts the definition on the Vite plugin it returns. A registered symbol, so a
+*  second copy of ogygia in one app still recognizes the first's plugins. */
+const PLUGIN = Symbol.for("ogygia.plugin");
+/** The name of `ogygia()`'s own Vite plugin: what a listed plugin looks for beside it. */
+const OGYGIA_VITE_PLUGIN = "ogygia";
+/** A plugin, as the Vite plugin the app lists beside `ogygia()`. */
+function definePlugin(definition) {
+	return {
+		name: definition.name,
+		[PLUGIN]: definition,
+		configResolved(config) {
+			if (!config.plugins.some((p) => p.name === OGYGIA_VITE_PLUGIN)) throw new Error(`[ogygia] \`${definition.name}\` is listed in vite.config but \`ogygia()\` is not — add \`ogygia()\` from \`ogygia/vite\` to \`plugins\`.`);
+		}
+	};
+}
+/** The prefix of SvelteKit's own Vite plugins' names (`sveltekit()` returns several). */
+const KIT_VITE_PLUGIN_PREFIX = "vite-plugin-sveltekit";
+/** The plugin definitions in the app's Vite plugin list (nested arrays and promises included), in
+*  list order, shape-checked. `ogygia()` and its plugins come before `sveltekit()`: Vite runs
+*  same-stage hooks in list order, and theirs (the content pre-transforms, the config ogygia hands
+*  Kit) must see a module before Kit's do. */
+async function find_plugins(list) {
+	const found = [];
+	let kit_seen = false;
+	const walk = async (entry) => {
+		const value = await entry;
+		if (Array.isArray(value)) {
+			for (const item of value) await walk(item);
+			return;
+		}
+		if (typeof value === "function") throw new Error("[ogygia] a function is listed in vite.config `plugins` — call the factory: `flags()`, not `flags`.");
+		const plugin = value;
+		const name = typeof plugin?.name === "string" ? plugin.name : "";
+		const definition = plugin?.[PLUGIN];
+		if (name.startsWith(KIT_VITE_PLUGIN_PREFIX)) kit_seen = true;
+		const own = name === OGYGIA_VITE_PLUGIN;
+		if ((own || definition) && kit_seen) throw new Error(`[ogygia] \`${own ? "ogygia()" : String(definition?.name)}\` is listed after \`sveltekit()\` in vite.config — list \`ogygia()\` and its plugins first: \`plugins: [ogygia(), flags(), sveltekit()]\`.`);
+		if (definition) found.push(definition);
+	};
+	await walk(list);
+	return check_plugins(found);
+}
+const MACRO_NAME_RE = /^[a-z][A-Za-z0-9]*$/;
+/** core's own `import.meta.og.*` constructs: a plugin may never claim one */
+const CORE_MACROS = /* @__PURE__ */ new Set([
+	"wire",
+	"$",
+	"source",
+	"store",
+	"bake"
+]);
+function order(plugins) {
+	return [
+		...plugins.filter((p) => p.enforce === "pre"),
+		...plugins.filter((p) => p.enforce !== "pre" && p.enforce !== "post"),
+		...plugins.filter((p) => p.enforce === "post")
+	];
+}
+const ROUTE_CONFIG_KEY_RE = /^[a-z][A-Za-z0-9]*$/;
+/**
+* Config-time shape check of the definitions found: each named once, its realms locations, its
+* options JSON.
+*/
+function check_plugins(plugins) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const p of plugins) {
+		const plugin = p;
+		if (!plugin || typeof plugin !== "object" || typeof plugin.name !== "string" || plugin.name === "") throw new Error("[ogygia] a plugin definition needs a `name` (its package name).");
+		if (seen.has(plugin.name)) throw new Error(`[ogygia] plugin \`${plugin.name}\` is listed twice.`);
+		seen.add(plugin.name);
+		for (const realm of ["server", "client"]) if (plugin[realm] !== void 0 && typeof plugin[realm] !== "string") throw new Error(`[ogygia] plugin \`${plugin.name}\`: \`${realm}\` is a module location — \`import.meta.resolve('./${realm}.ts')\`.`);
+		if (plugin.options !== void 0) try {
+			JSON.stringify(plugin.options);
+		} catch {
+			throw new Error(`[ogygia] plugin \`${plugin.name}\`: \`options\` must be plain JSON (configure live objects in hooks.server.ts).`);
+		}
+	}
+	return plugins;
+}
+/** A realm's module as an absolute POSIX path (what the generated imports name), or null when the
+*  plugin has none. A location that is not a file is a mistake, said loudly. */
+function realm_path(plugin, realm) {
+	const where = plugin[realm];
+	if (where === void 0) return null;
+	const abs = where.startsWith("file:") ? fileURLToPath(where) : where;
+	if (!path.isAbsolute(abs) || !fs.existsSync(abs)) throw new Error(`[ogygia] plugin \`${plugin.name}\`: its \`${realm}\` realm \`${where}\` is not a file — resolve it next to the factory: \`import.meta.resolve('./${realm}.ts')\`.`);
+	return abs.split(path.sep).join("/");
+}
+function package_resolves(req, name) {
+	try {
+		req.resolve(`${name}/package.json`);
+		return true;
+	} catch (e) {
+		return e.code === "ERR_PACKAGE_PATH_NOT_EXPORTED";
+	}
+}
+/**
+* When the app's root and mode are known (the `config` hook): order the plugins (`enforce`), check their
+* realms, run their `build` hooks. `markup_transform` is the configured compiler's island
+* transform for preprocessed markup (what `b.markup()` hands back).
+*/
+function resolve_plugins(plugins, root, dev, markup_transform = () => null) {
+	const ordered = order(plugins);
+	const req = createRequire(path.join(root, "package.json"));
+	const out = {
+		servers: [],
+		clients: [],
+		route_config: [],
+		foreign_hydrate: false,
+		macros: [],
+		markup: [],
+		events: false,
+		measure: false,
+		files: [],
+		page_modules: {
+			importers: [],
+			files: []
+		}
+	};
+	const config_owner = /* @__PURE__ */ new Map();
+	const macro_owner = /* @__PURE__ */ new Map();
+	for (const plugin of ordered) {
+		if (!package_resolves(req, plugin.name)) throw new Error(`[ogygia] plugin \`${plugin.name}\`: no package by that name resolves from ${root} — its name must be its package name.`);
+		const server = realm_path(plugin, "server");
+		if (server) out.servers.push({
+			name: plugin.name,
+			module: server,
+			options: plugin.options ?? {}
+		});
+		const client = realm_path(plugin, "client");
+		if (client) out.clients.push(client);
+		plugin.build?.({
+			root,
+			dev,
+			routeConfig(key) {
+				if (!ROUTE_CONFIG_KEY_RE.test(key)) throw new Error(`[ogygia] plugin \`${plugin.name}\`: route config key \`${key}\` must be a camelCase identifier.`);
+				const owner = config_owner.get(key);
+				if (owner && owner !== plugin.name) throw new Error(`[ogygia] route config key \`${key}\` is claimed by both \`${owner}\` and \`${plugin.name}\`.`);
+				if (!owner) {
+					config_owner.set(key, plugin.name);
+					out.route_config.push(key);
+				}
+			},
+			foreignHydrate() {
+				out.foreign_hydrate = true;
+			},
+			macro(name, handler) {
+				if (!MACRO_NAME_RE.test(name) || CORE_MACROS.has(name)) throw new Error(`[ogygia] plugin \`${plugin.name}\`: macro \`import.meta.og.${name}\` must be a camelCase name core does not own.`);
+				const owner = macro_owner.get(name);
+				if (owner) throw new Error(`[ogygia] macro \`import.meta.og.${name}\` is claimed by both \`${owner}\` and \`${plugin.name}\`.`);
+				macro_owner.set(name, plugin.name);
+				out.macros.push({
+					name,
+					handler
+				});
+			},
+			markup(source) {
+				out.markup.push(source);
+				return { transform: markup_transform };
+			},
+			events(options) {
+				const lazy = options?.lazy === true;
+				out.events = out.events ? { lazy: out.events.lazy && lazy } : { lazy };
+			},
+			measure() {
+				out.measure = true;
+			},
+			files(scan) {
+				out.files.push({
+					name: plugin.name,
+					root: scan.root,
+					dirs: scan.dirs ?? [],
+					files: scan.files ?? []
+				});
+			},
+			pageModules(modules) {
+				for (const spec of modules.importers ?? []) if (!out.page_modules.importers.includes(spec)) out.page_modules.importers.push(spec);
+				for (const file of modules.files ?? []) {
+					if (!path.isAbsolute(file)) throw new Error(`[ogygia] plugin \`${plugin.name}\`: \`pageModules({ files })\` takes absolute paths (got \`${file}\`).`);
+					if (!out.page_modules.files.includes(file)) out.page_modules.files.push(file);
+				}
+			}
+		});
+	}
+	return out;
+}
+export { PLUGIN, check_plugins, definePlugin, find_plugins, resolve_plugins };

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

@@ -0,0 +1,23 @@
+/** the payload the profiler reads (profiler/embedded-maps.ts) */
+export interface ProfilerMaps {
+  v: 1;
+  /** chunk file (relative to the server output) → [first line, last line, module id] */
+  modules: Record<string, [number, number, string][]>;
+  /** chunk file → its sourcemap, as the JSON text the build wrote */
+  maps: Record<string, string>;
+  /** a build WITHOUT maps: the app's own source files at the lines of its chunks, by module id
+   *  (`src/lib/x.ts`) — what the profiler matches the chunks' lines to by text on a host without
+   *  `src/` */
+  sources?: Record<string, string>;
+  /** ...and those chunks' own text, by chunk file */
+  chunks?: Record<string, string>;
+}
+export declare function fill_profiler_maps(dir: string, bundle: Record<string, unknown>, root: string): boolean;
+/**
+ * A CHUNK'S MAP, CUT TO WHAT THE PROFILER READS: the mappings and names whole (every frame's line
+ * and name), the source TEXT only for the app's own code files — what the source checks read on a
+ * host without `src/` (a load line by line, a component's `{#each}`, a late island's data). A
+ * package's text and imported data (`.json`: no function runs on its lines) are the bulk of a real
+ * app's maps and never read there. Undefined for a map of data alone (nothing to name).
+ */
+export declare function slim_map(raw: string, chunk_dir: string, src: string): string | undefined;