@ogygia/core 0.0.0 → 0.11.1

package/dist/plugin/css.js

@@ -0,0 +1,54 @@
+import { router_css_active, router_css_of } from "../router-css.js";
+import { claim_region_css } from "../context.js";
+import { DEV } from "esm-env";
+// src/plugin/css.ts
+/**
+* `ogygia/plugin/css` — the CSS of components a programmatic router renders (see the server-router-css
+* notes + compiler/link/router-css.ts). Such a page's component is a VALUE, not a Kit route, so nothing
+* file-derived links its scoped `<style>` / plain `.css` imports. The build registers every component a
+* page module (`b.pageModules()`) can reach in a runtime registry (`virtual:ogygia/router-css`); this
+* turns the components ONE render places into the `<link>` / `<style>` head tags `document()` hoists,
+* deduped against the request's held-region links.
+*
+* Its own subpath: the generated registry is a virtual module, so it stays out of `ogygia/plugin` (every
+* plugin's server realm) — and it is imported on the first call, never at module load.
+*/
+const STYLE_CLOSE_G = /<\/style/gi;
+let rcss_ready;
+let warned_inactive = false;
+function registry_ready() {
+	if (rcss_ready === void 0) try {
+		rcss_ready = import("virtual:ogygia/router-css").catch(() => null);
+	} catch {
+		rcss_ready = null;
+	}
+	return rcss_ready;
+}
+/** Head tags for the components ONE render places (a layout chain + its page or error component):
+*  each component's whole-tree CSS, linked once per request. */
+async function componentCssHead(components) {
+	const ready = registry_ready();
+	const registry = ready ? await ready : null;
+	if (DEV && registry && !warned_inactive && components.length && !router_css_active()) {
+		warned_inactive = true;
+		console.warn("[ogygia] a page rendered outside Kit's routes, but no plugin declared page modules, so its components' CSS is not linked. Using `@ogygia/router`? List `router()` from `@ogygia/router/vite` beside `ogygia()` in vite.config `plugins`.");
+	}
+	const entries = components.flatMap((c) => router_css_of(c));
+	if (!entries.length) return "";
+	const keys = entries.map((e) => e.key);
+	let fresh = new Set(claim_region_css(keys));
+	if (fresh.size === 0 && keys.length) try {
+		if (claim_region_css(["\0og-rcss-probe"]).length === 0) fresh = new Set(keys);
+	} catch {
+		fresh = new Set(keys);
+	}
+	let head = "";
+	for (const e of entries) {
+		if (!fresh.has(e.key)) continue;
+		fresh.delete(e.key);
+		if (e.href) head += `<link rel="stylesheet" href="${e.href}" data-ogygia-region-css>`;
+		else if (e.css) head += `<style data-ogygia-rcss>${e.css.replace(STYLE_CLOSE_G, "<\\/style")}</style>`;
+	}
+	return head;
+}
+export { componentCssHead };

package/dist/plugin/facts.d.ts

@@ -0,0 +1,42 @@
+/**
+ * FACTS — per-request shared state. A fact is filled by whoever learns it and read by whoever needs
+ * it; neither side imports the other. Keyed by the `Request` (every request has its own record, made
+ * on first touch, gone with the request), so a plugin's own code can reach them outside a hook too:
+ * a `flag()` read during the render holds its request.
+ *
+ * Plugins add their own facts by declaration merging:
+ *
+ *   declare module 'ogygia/plugin' { interface RequestFacts { myThing?: string } }
+ *
+ * One global slot, not module scope: a plugin package and core can end up as two module instances
+ * of this file (src beside dist, a dual install), and a fact written through one must be read
+ * through the other.
+ */
+export interface RequestFacts {
+  /** This render MAY be stored and served to others later (a plugin decided so before the render):
+   *  the holes it mints get prerender-grade capabilities, and data-source receipts are kept. */
+  storable: boolean;
+  /** The first reason this render is per-visitor (a flag read, a streamed promise, a personal
+   *  cookie or header a plugin observed), named for the dev note — or null. */
+  perVisitor: string | null;
+  /** The page streams load promises after the document. */
+  streamed: boolean;
+  /** The response belongs to one browser (devtools switched on for it): never store or share it. */
+  private: boolean;
+  /** An app transform renders this router-fetched page as an ANSWER, a form a store keyed by path
+   *  does not hold. */
+  answerForm: boolean;
+  /** Data-source receipts (`s:<id>:<fp>`) the render filed — collected only once a plugin asks for
+   *  them by setting a list here (a storable render's reverse index, a fragment's provenance). */
+  sources: string[] | null;
+  /** Every flag decided for this request (name → variant): federation carries them as claims. */
+  assignments: Record<string, string>;
+}
+/** This request's facts (made on first touch). */
+export declare function facts_of(request: Request): RequestFacts;
+/** Core only (hooks.ts): how the running code's Request is found. */
+export declare function set_current_request(fn: (() => Request | undefined) | null): void;
+/** The facts of the request the running code belongs to, or null outside one (the client, a test). */
+export declare function current_facts(): RequestFacts | null;
+/** Name the first reason a render is per-visitor (later reasons do not replace it). */
+export declare function mark_per_visitor(facts: RequestFacts, reason: string): void;

package/dist/plugin/facts.js

@@ -0,0 +1,37 @@
+// src/plugin/facts.ts
+const slot = globalThis[Symbol.for("ogygia.facts.v2")] ??= {
+	by_request: /* @__PURE__ */ new WeakMap(),
+	current: null
+};
+/** This request's facts (made on first touch). */
+function facts_of(request) {
+	let facts = slot.by_request.get(request);
+	if (!facts) slot.by_request.set(request, facts = {
+		storable: false,
+		perVisitor: null,
+		streamed: false,
+		private: false,
+		answerForm: false,
+		sources: null,
+		assignments: {}
+	});
+	return facts;
+}
+/** Core only (hooks.ts): how the running code's Request is found. */
+function set_current_request(fn) {
+	slot.current = fn;
+}
+/** The facts of the request the running code belongs to, or null outside one (the client, a test). */
+function current_facts() {
+	try {
+		const request = slot.current?.();
+		return request ? facts_of(request) : null;
+	} catch {
+		return null;
+	}
+}
+/** Name the first reason a render is per-visitor (later reasons do not replace it). */
+function mark_per_visitor(facts, reason) {
+	if (facts.perVisitor === null) facts.perVisitor = reason;
+}
+export { current_facts, facts_of, mark_per_visitor, set_current_request };

package/dist/plugin/hooks.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SHARED HOOKS — how plugins (and core) talk to each other: the same way core talks to them. A
+ * plugin implements a hook as a method of its server half; anyone calls it through `app`:
+ *
+ *   app.notify.invalidate(tags)        every implementation runs (resolves when all are done)
+ *   app.ask.lastBuild(version)         the first answer that is not `undefined`, in plugin order
+ *
+ * Nobody implementing a hook is normal: `notify` does nothing, `ask` answers `undefined`. Core owns
+ * the common names below; a plugin's own hooks carry its name (`federationThaw`), added by
+ * declaration merging:
+ *
+ *   declare module 'ogygia/plugin' { interface ServerHooks { myThing(x: number): void } }
+ *
+ * One global slot: every module instance dispatches over the same implementations.
+ */
+/** The shared hooks. Each is optional on a plugin; the signature is the contract. */
+export interface ServerHooks {
+  /** Drop every stored page carrying any of `tags` (a peer said they are stale). Never re-announced. */
+  invalidate(tags: string[]): void | Promise<void>;
+  /** Stored pages were dropped: `tags` names what (`p:<path>`, `s:<source>:<fp>`), or `'all'`. */
+  invalidated(tags: string[] | "all"): void | Promise<void>;
+  /** Record `version` as the build the shared store last saw; answer the one before (or undefined). */
+  lastBuild(version: string): string | undefined | Promise<string | undefined>;
+}
+/** Core only: a set of hook implementations joins (a plugin's server half, or core's own). Keyed by
+ *  identity; returns the leave. */
+export declare function register_hooks(impl: object): () => void;
+export type Notify = { [K in keyof ServerHooks]: (...args: Parameters<ServerHooks[K]>) => Promise<void>; };
+export type Ask = { [K in keyof ServerHooks]: (...args: Parameters<ServerHooks[K]>) => Promise<Awaited<ReturnType<ServerHooks[K]>> | undefined>; };
+/** Every implementation of the named hook runs; a failing one is logged, never thrown. */
+export declare const notify: Notify;
+/** The first implementation that answers something other than `undefined`. */
+export declare const ask: Ask;

package/dist/plugin/hooks.js

@@ -0,0 +1,38 @@
+// src/plugin/hooks.ts
+const implementations = globalThis[Symbol.for("ogygia.server-hooks.v1")] ??= [];
+/** Core only: a set of hook implementations joins (a plugin's server half, or core's own). Keyed by
+*  identity; returns the leave. */
+function register_hooks(impl) {
+	const entry = impl;
+	if (!implementations.includes(entry)) implementations.push(entry);
+	return () => {
+		const at = implementations.indexOf(entry);
+		if (at !== -1) implementations.splice(at, 1);
+	};
+}
+/** Every implementation of the named hook runs; a failing one is logged, never thrown. */
+const notify = new Proxy({}, { get: (_, name) => async (...args) => {
+	for (const impl of implementations.slice()) {
+		const fn = impl[name];
+		if (typeof fn !== "function") continue;
+		try {
+			await fn.apply(impl, args);
+		} catch (e) {
+			console.warn(`[ogygia] a \`${name}\` hook failed —`, e);
+		}
+	}
+} });
+/** The first implementation that answers something other than `undefined`. */
+const ask = new Proxy({}, { get: (_, name) => async (...args) => {
+	for (const impl of implementations.slice()) {
+		const fn = impl[name];
+		if (typeof fn !== "function") continue;
+		try {
+			const answer = await fn.apply(impl, args);
+			if (answer !== void 0) return answer;
+		} catch (e) {
+			console.warn(`[ogygia] a \`${name}\` hook failed —`, e);
+		}
+	}
+} });
+export { ask, notify, register_hooks };

package/dist/plugin/index.d.ts

@@ -0,0 +1,127 @@
+import { RequestFacts } from "./facts.js";
+import { Ask, Notify, ServerHooks } from "./hooks.js";
+import { DevtoolsEventInput } from "../events/schema.js";
+import { DeferredRegion, og_html_region, region } from "../region.js";
+import { RouteConfig, RouteConfigMatcher, register_route_config } from "./routes.js";
+import { LateRegion, open_late_scope, take_late_regions } from "../late-region-registry.js";
+import { LATE_BOOT_SCRIPT, late_chunk, late_slot } from "../server/late-wire.js";
+import { Handle, RequestEvent } from "@sveltejs/kit";
+/** The server process, as one plugin sees it (handed to `setup`, and on every `ctx.app`). */
+export interface ServerApp<Options = undefined> {
+  /** The plugin's name (its package name). */
+  readonly name: string;
+  /** The options the app gave the plugin in vite.config (JSON). */
+  readonly options: Options;
+  /** Call a shared hook on every plugin that has it. */
+  readonly notify: Notify;
+  /** Ask a shared hook: the first answer that is not `undefined`, in plugin order. */
+  readonly ask: Ask;
+  /** A request's facts (made on first touch) — for the plugin's own code outside a hook. */
+  facts(request: Request): RequestFacts;
+  /** The facts of the request the running code belongs to (a load, a render), or null outside one. */
+  current(): RequestFacts | null;
+  /** Sign `message` with the app's region key (HMAC): a capability only this app can mint. */
+  sign(message: string): string;
+  /** Check a signature `sign` made (constant-time). */
+  verify(message: string, signature: string): boolean;
+  /** Signed capabilities for an endpoint the plugin serves, held to the rules of region holes. */
+  readonly capability: PluginCapabilities;
+  /** Record a server-realm event into the current request's devtools stream (a no-op unless
+   *  devtools is on for that browser). */
+  devtools(event: DevtoolsEventInput): void;
+  /** Warn once per message, prefixed with the plugin's name. */
+  warn(message: string): void;
+}
+/**
+ * A capability URL for an endpoint the plugin serves (a hole the browser fetches later), held to the
+ * rules of the app's own region holes: the same lifetime, expiry in unix seconds, and the same answer
+ * once one has expired, so the runtime renews it the way it renews a region hole. The URL carries the
+ * plugin's own fields first, then `exp` and `sig`.
+ */
+export interface PluginCapabilities {
+  /** Sign a capability minted now: its `exp` (long on a page a plugin may store or a shared cache
+   *  keeps, else the app's `ttl`) and the `sig` over `message(exp)`. */
+  mint(message: (exp: string) => string): {
+    exp: string;
+    sig: string;
+  };
+  /** Check a request for a capability `mint` made, by its URL's `exp` and `sig` (with `renew=1`, the
+   *  runtime's one retry of an expired one). Refused: the response to answer with, the 403 a region
+   *  request gets. Accepted: headers to send with the answer (a renewal's carry the fresh URL). */
+  open(url: URL, message: (exp: string) => string): CapabilityOpened;
+}
+/** What `capability.open` decided. */
+export type CapabilityOpened = {
+  ok: true;
+  headers: Record<string, string>;
+} | {
+  ok: false;
+  response: Response;
+};
+/** One request, as one plugin sees it. */
+export interface RequestContext<Options = undefined, State = undefined> {
+  /** Kit's own event, untouched. */
+  readonly event: RequestEvent;
+  /** The decoded pathname. */
+  readonly path: string;
+  /** This plugin's per-request state, from its `state()`. */
+  readonly state: State;
+  readonly options: Options;
+  readonly app: ServerApp<Options>;
+  /** The request's shared facts. */
+  readonly facts: RequestFacts;
+  /** This request's value for a key this plugin claimed inside Kit's `config` page option
+   *  (`b.routeConfig(key)`: `export const config = { <key>: … }` on a Kit page or layout, merged the
+   *  way Kit merges it, or a programmatic router's `config`), or `undefined` when nothing declares it. */
+  routeConfig(key: string): unknown;
+  /** Render one signed hole in place, with this request's event (its cookies ride in): the hole's
+   *  HTML, or null when it cannot render now (the stored fallback stays, the browser fetches). */
+  renderHole(endpoint: string): Promise<string | null>;
+  /** Name the first reason this render is per-visitor (later reasons do not replace it). */
+  perVisitor(reason: string): void;
+}
+type MaybePromise<T> = T | Promise<T>;
+/** Kit's `resolve()` options (a `transformPageChunk`, `filterSerializedResponseHeaders`, …). */
+export type ResolveOptions = NonNullable<Parameters<Parameters<Handle>[0]["resolve"]>[1]>;
+/** A request as an AROUND hook sees it: before anything is decided about it. */
+export interface HandleContext<Options = undefined> {
+  /** Kit's own event, untouched. */
+  readonly event: RequestEvent;
+  readonly options: Options;
+  readonly app: ServerApp<Options>;
+}
+/** A plugin's server half: lifecycle hooks plus any shared hooks it implements. */
+export type ServerPlugin<Options = undefined, State = undefined> = Partial<ServerHooks> & {
+  /** Once, when the server starts. */
+  setup?(app: ServerApp<Options>): void;
+  /** Fresh per-request state, handed back on `ctx.state`. */
+  state?(): State;
+  /**
+   * AROUND — the whole request, shaped like Kit's `handle`: `next()` runs the rest (the later plugins'
+   * `handle`, then ogygia) and returns its response; return it, or your own. The first plugin's is the
+   * outermost. `next(options)` passes Kit `resolve()` options: a `transformPageChunk` sees the finished
+   * document, after ogygia's own. Most plugins want the stages below instead; this is for what must
+   * wrap everything (a profiler timing the render, serving its own UI).
+   */
+  handle?(ctx: HandleContext<Options>, next: (options?: ResolveOptions) => Promise<Response>): MaybePromise<Response>;
+  /** FIRST — every request, before anything else in the handle (above the page / hole split).
+   *  A Response answers it. */
+  request?(ctx: RequestContext<Options, State>): MaybePromise<void | Response>;
+  /** FIRST — a PAGE request (not a hole, not a page-facts lookup), before Kit renders it. A
+   *  Response answers it (a stored copy). */
+  page?(ctx: RequestContext<Options, State>): MaybePromise<void | Response>;
+  /** SEQUENTIAL — the page's response, before it streams out. A Response replaces it. */
+  response?(ctx: RequestContext<Options, State>, response: Response): MaybePromise<void | Response>;
+  /** PARALLEL — the request's end, always (an answered, failed or streamed request included). Must
+   *  not throw; must not await anything slow. */
+  done?(ctx: RequestContext<Options, State>): void;
+};
+/** Typed identity: a plugin's server half. */
+export declare function defineServer<Options = undefined, State = undefined>(plugin: ServerPlugin<Options, State>): ServerPlugin<Options, State>;
+/** Stamped into a document served FROM a store (not the render that just happened): the browser
+ *  runtime then treats `render: 'live'` lakes as stale on first mount and revalidates them. */
+export declare const STORED_DOCUMENT_META = "<meta name=\"ogygia-stored\" content=\"hit\">";
+/** A deferred region value whose HTML the browser fetches from `url` (a capability the plugin minted,
+ *  `''` for an inert one). HTML only: whatever islands the answer carries wake themselves. */
+export declare function deferredRegion(id: string, url: string): DeferredRegion;
+export { type DevtoolsEventInput, LATE_BOOT_SCRIPT, type LateRegion, type RequestFacts, type RouteConfig, type RouteConfigMatcher, type ServerHooks, og_html_region as htmlRegion, late_chunk as lateChunk, late_slot as lateSlot, open_late_scope as openLateScope, region, register_route_config as registerRouteConfig, take_late_regions as takeLateRegions };

package/dist/plugin/index.js

@@ -0,0 +1,26 @@
+import { og_html_region, region } from "../region.js";
+import { register_route_config } from "./routes.js";
+import { open_late_scope, take_late_regions } from "../late-region-registry.js";
+import { LATE_BOOT_SCRIPT, late_chunk, late_slot } from "../server/late-wire.js";
+import { REGION_BRAND } from "../region-brand.js";
+// src/plugin/index.ts
+/** Typed identity: a plugin's server half. */
+function defineServer(plugin) {
+	return plugin;
+}
+/** Stamped into a document served FROM a store (not the render that just happened): the browser
+*  runtime then treats `render: 'live'` lakes as stale on first mount and revalidates them. */
+const STORED_DOCUMENT_META = "<meta name=\"ogygia-stored\" content=\"hit\">";
+/** A deferred region value whose HTML the browser fetches from `url` (a capability the plugin minted,
+*  `''` for an inert one). HTML only: whatever islands the answer carries wake themselves. */
+function deferredRegion(id, url) {
+	return {
+		[REGION_BRAND]: true,
+		kind: "deferred",
+		id,
+		props: {},
+		url,
+		module: ""
+	};
+}
+export { LATE_BOOT_SCRIPT, STORED_DOCUMENT_META, deferredRegion, defineServer, og_html_region as htmlRegion, late_chunk as lateChunk, late_slot as lateSlot, open_late_scope as openLateScope, region, register_route_config as registerRouteConfig, take_late_regions as takeLateRegions };

package/dist/plugin/routes.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ROUTE CONFIG — the keys a plugin reads inside Kit's own `config` page option
+ * (`export const config = { postrender: false }` in a `+page.ts`). Kit takes anything inside
+ * `config`, so nothing is stripped and no plugin invents an export in Kit's files. A plugin claims
+ * its keys once (`b.routeConfig(key)`); the compiler reads each page's merged `config` at build time
+ * the way Kit merges it (layouts root → leaf, then the page; at each level the server module, then
+ * the universal one; later wins, top level only) and bakes the claimed keys.
+ *
+ * Two worlds answer, in the order dispatch itself resolves a request:
+ * 1. A mounted programmatic `routes()` table that CLAIMS the pathname (it answers inside the
+ *    handle, ahead of any file route): its merged page > layout > table `config`.
+ * 2. A Kit page route: its build-time merged value.
+ * Anything else (an endpoint, a request no route claimed) answers `undefined`: the plugin's own
+ * default applies.
+ *
+ * One global slot: dist entries and plugin packages must share the registry.
+ */
+/** A route's merged `config`, as far as the claimed keys go. */
+export type RouteConfig = Readonly<Record<string, unknown>>;
+/** Per matcher: `undefined` = not mine (ask the next one, then the file world) · an object = mine,
+ *  with this merged config (a claimed key it lacks answers `undefined`, never the file world). */
+export type RouteConfigMatcher = (pathname: string) => RouteConfig | undefined;
+/** A `routes()` table joins (keyed: dev re-evaluates hooks.server.ts and calls `routes()` again; a
+ *  matcher with the same key REPLACES its stale twin instead of shadowing it). */
+export declare function register_route_config(key: string, matcher: RouteConfigMatcher): void;
+/** Core only (hooks.ts): the Kit pages' merged config, baked by the compiler. */
+export declare function set_page_route_config(pages: Record<string, RouteConfig>): void;
+/** Tests only. */
+export declare function clear_route_config(): void;
+/** This request's value for `key` in its route's merged `config`, or `undefined` (use the plugin's
+ *  default). A null `routeId` is never normalized to `/` — that would be a different route. */
+export declare function route_config(key: string, route_id: string | null | undefined, pathname: string): unknown;

package/dist/plugin/routes.js

@@ -0,0 +1,35 @@
+// src/plugin/routes.ts
+const slot = globalThis[Symbol.for("ogygia.route-config.v1")] ??= {
+	routers: /* @__PURE__ */ new Map(),
+	pages: /* @__PURE__ */ new Map()
+};
+/** A `routes()` table joins (keyed: dev re-evaluates hooks.server.ts and calls `routes()` again; a
+*  matcher with the same key REPLACES its stale twin instead of shadowing it). */
+function register_route_config(key, matcher) {
+	slot.routers.delete(key);
+	slot.routers.set(key, matcher);
+}
+/** Core only (hooks.ts): the Kit pages' merged config, baked by the compiler. */
+function set_page_route_config(pages) {
+	slot.pages = new Map(Object.entries(pages));
+}
+/** Tests only. */
+function clear_route_config() {
+	slot.routers.clear();
+	slot.pages.clear();
+}
+/** Kit's `(group)` segments dropped from a `route.id` (the compiler keys pages the same way). */
+function strip_route_groups(id) {
+	return "/" + id.split("/").filter(Boolean).filter((s) => !(s.startsWith("(") && s.endsWith(")"))).join("/");
+}
+/** This request's value for `key` in its route's merged `config`, or `undefined` (use the plugin's
+*  default). A null `routeId` is never normalized to `/` — that would be a different route. */
+function route_config(key, route_id, pathname) {
+	for (const matcher of slot.routers.values()) {
+		const config = matcher(pathname);
+		if (config !== void 0) return config[key];
+	}
+	if (route_id == null) return void 0;
+	return slot.pages.get(strip_route_groups(route_id))?.[key];
+}
+export { clear_route_config, register_route_config, route_config, set_page_route_config };

package/dist/plugin/server.d.ts

@@ -0,0 +1,27 @@
+import { RequestContext, ResolveOptions, ServerApp, ServerPlugin } from "./index.js";
+import { RequestFacts } from "./facts.js";
+import { CapabilitySigner } from "./capability.js";
+import { Handle, RequestEvent } from "@sveltejs/kit";
+/** One plugin's server half as the build lists it (`virtual:ogygia/server-plugins`). */
+export interface ServerPluginEntry {
+  name: string;
+  options: unknown;
+  server: ServerPlugin<unknown, unknown>;
+}
+/** A live plugin: its definition and its app. */
+export interface LivePlugin {
+  def: ServerPlugin<unknown, unknown>;
+  app: ServerApp<unknown>;
+}
+/** The app's signer, handed in by the handle (it holds the region key, and answers a refused
+ *  capability the way it answers a refused region request). */
+export type AppSigner = CapabilitySigner;
+/** Make each plugin live, in order: app, shared hooks, `setup`. */
+export declare function start_plugins(entries: readonly ServerPluginEntry[], signer: AppSigner): LivePlugin[];
+/** Two `resolve()` option sets as one: the inner transform (ogygia's document injection) runs first,
+ *  the outer (a plugin's `handle`) sees the finished chunk; the other options merge, outer last. */
+export declare function compose_resolve_options(inner?: ResolveOptions, outer?: ResolveOptions): ResolveOptions | undefined;
+/** The plugins' `handle` hooks nested around `core`, first plugin outermost. No hook: `core` itself. */
+export declare function around(plugins: readonly LivePlugin[], core: Handle): Handle;
+/** The per-plugin contexts of one request. */
+export declare function request_contexts(plugins: readonly LivePlugin[], event: RequestEvent, path: string, facts: RequestFacts, render_hole: (endpoint: string) => Promise<string | null>): RequestContext<unknown, unknown>[];

package/dist/plugin/server.js

@@ -0,0 +1,92 @@
+import { current_facts, facts_of, mark_per_visitor } from "./facts.js";
+import { ask, notify, register_hooks } from "./hooks.js";
+import { route_config } from "./routes.js";
+import { plugin_capabilities } from "./capability.js";
+import { record_server_event } from "../events/server-registry.js";
+// src/plugin/server.ts
+/** Make each plugin live, in order: app, shared hooks, `setup`. */
+function start_plugins(entries, signer) {
+	return entries.map(({ name, options, server }) => {
+		const warned = /* @__PURE__ */ new Set();
+		const app = {
+			name,
+			options,
+			notify,
+			ask,
+			facts: facts_of,
+			current: current_facts,
+			sign: signer.sign,
+			verify: signer.verify,
+			capability: plugin_capabilities(name, signer),
+			devtools: record_server_event,
+			warn(message) {
+				if (warned.has(message)) return;
+				warned.add(message);
+				console.warn(`[${name}] ${message}`);
+			}
+		};
+		register_hooks(server);
+		server.setup?.(app);
+		return {
+			def: server,
+			app
+		};
+	});
+}
+/** Two `resolve()` option sets as one: the inner transform (ogygia's document injection) runs first,
+*  the outer (a plugin's `handle`) sees the finished chunk; the other options merge, outer last. */
+function compose_resolve_options(inner, outer) {
+	if (!inner) return outer;
+	if (!outer) return inner;
+	const a = inner.transformPageChunk;
+	const b = outer.transformPageChunk;
+	return {
+		...inner,
+		...outer,
+		transformPageChunk: !a ? b : !b ? a : async (input) => {
+			const first = await a(input);
+			if (first === void 0) return first;
+			return b({
+				...input,
+				html: first
+			});
+		}
+	};
+}
+/** The plugins' `handle` hooks nested around `core`, first plugin outermost. No hook: `core` itself. */
+function around(plugins, core) {
+	let inner = core;
+	for (let i = plugins.length - 1; i >= 0; i--) {
+		const { def, app } = plugins[i];
+		const handle = def.handle;
+		if (!handle) continue;
+		const next_handle = inner;
+		inner = async ({ event, resolve }) => handle({
+			event,
+			options: app.options,
+			app
+		}, (outer) => Promise.resolve(next_handle({
+			event,
+			resolve: (ev, opts) => resolve(ev, compose_resolve_options(opts, outer))
+		})));
+	}
+	return inner;
+}
+/** The per-plugin contexts of one request. */
+function request_contexts(plugins, event, path, facts, render_hole) {
+	const route_id = event.route?.id;
+	const route_cfg = (key) => route_config(key, route_id, path);
+	const per_visitor = (reason) => mark_per_visitor(facts, reason);
+	return plugins.map(({ def, app }) => ({
+		event,
+		path,
+		state: def.state?.(),
+		options: app.options,
+		app,
+		facts,
+		routeConfig: route_cfg,
+		renderHole: render_hole,
+		perVisitor: per_visitor
+	}));
+}
+export { around, compose_resolve_options, request_contexts, start_plugins };

package/dist/plugin/standard-schema.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The Standard Schema interface (standardschema.dev): the `~standard` spec Zod / Valibot / ArkType all
+ * implement, the very thing Kit's remote functions consume. Validate a value with any schema library.
+ * Types only.
+ */
+export interface StandardSchemaV1<Output = unknown> {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+    readonly types?: {
+      readonly output: Output;
+    };
+  };
+}
+export type StandardResult<Output> = {
+  readonly value: Output;
+  readonly issues?: undefined;
+} | {
+  readonly issues: ReadonlyArray<StandardIssue>;
+};
+export interface StandardIssue {
+  readonly message: string;
+  readonly path?: ReadonlyArray<PropertyKey | {
+    readonly key: PropertyKey;
+  }>;
+}

package/dist/plugin/testing.d.ts

@@ -0,0 +1,13 @@
+import { RequestContext, ServerApp, ServerPlugin } from "./index.js";
+import { clear_route_config, route_config, set_page_route_config } from "./routes.js";
+import { RequestEvent } from "@sveltejs/kit";
+export interface StartedPlugin<Options, State> {
+  app: ServerApp<Options>;
+  /** A request context for `request` (a bare event: url, request, cookies that read nothing). */
+  ctx(request: Request, event?: Partial<RequestEvent>): RequestContext<Options, State>;
+}
+export declare function startPlugin<Options = undefined, State = undefined>(server: ServerPlugin<Options, State>, { name, options }?: {
+  name?: string;
+  options?: Options;
+}): StartedPlugin<Options, State>;
+export { clear_route_config as clearRouteConfig, route_config as routeConfig, set_page_route_config as setPageRouteConfig };

package/dist/plugin/testing.js

@@ -0,0 +1,54 @@
+import { facts_of } from "./facts.js";
+import { request_contexts, start_plugins } from "./server.js";
+import { capability_lifetime } from "../server/capability-lifetime.js";
+import { RENEW_WINDOW_SEC } from "../server/shared-cache.js";
+import { clear_route_config, route_config, set_page_route_config } from "./routes.js";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+// src/plugin/testing.ts
+/** A real HMAC under a key made for this test process. */
+const TEST_KEY = randomBytes(32);
+const TEST_SIGNER = {
+	sign: (message) => createHmac("sha256", TEST_KEY).update(message).digest("base64url"),
+	verify(message, signature) {
+		const want = Buffer.from(createHmac("sha256", TEST_KEY).update(message).digest("base64url"));
+		const got = Buffer.from(signature);
+		return want.length === got.length && timingSafeEqual(want, got);
+	},
+	lifetime: capability_lifetime({
+		building: false,
+		region_ttl: 3600,
+		renew_window: RENEW_WINDOW_SEC,
+		request: () => null
+	}),
+	deny: (why) => new Response("Forbidden", {
+		status: 403,
+		headers: { "x-ogygia-deny": why }
+	})
+};
+function startPlugin(server, { name = "test-plugin", options } = {}) {
+	const [live] = start_plugins([{
+		name,
+		options,
+		server
+	}], TEST_SIGNER);
+	return {
+		app: live.app,
+		ctx(request, event = {}) {
+			const url = new URL(request.url);
+			const full = {
+				request,
+				url,
+				route: { id: null },
+				cookies: {
+					get: () => void 0,
+					getAll: () => []
+				},
+				locals: {},
+				...event
+			};
+			const [ctx] = request_contexts([live], full, url.pathname, facts_of(request), async () => null);
+			return ctx;
+		}
+	};
+}
+export { clear_route_config as clearRouteConfig, route_config as routeConfig, set_page_route_config as setPageRouteConfig, startPlugin };