@ogygia/core 0.0.0 → 0.11.1

package/dist/runtime/wire-format.d.ts

@@ -0,0 +1,7 @@
+export declare const WIRE_FORMAT_ATTR = "data-og-format";
+export declare const WIRE_FORMAT_JSON = "json";
+/** Is this side-channel element's text the JSON lane? */
+export declare function wire_is_json(el: Element): boolean;
+/** Parse a side-channel's text in its lane: `JSON.parse` for the JSON lane (nothing to revive by
+ *  construction), devalue `parse` with the caller's revivers otherwise. */
+export declare function parse_wire_text(text: string, json: boolean, revivers?: Record<string, (value: never) => unknown>): unknown;

package/dist/runtime/wire-format.js

@@ -0,0 +1,22 @@
+import { parse } from "devalue";
+// src/runtime/wire-format.ts
+/**
+* THE WIRE FORMAT of a side-channel script, read back. The server emits two lanes
+* (server/props-wire.ts): plain JSON under `data-og-format="json"` (a payload with nothing devalue
+* exists for — the common CMS props and seed), and devalue otherwise. This is the ONE place the
+* client tells them apart: every seed / props / remote read goes through `parse_wire_text`.
+*
+* Pure (no DOM types beyond an attribute read) so the runtime, the shims and the tests share it.
+*/
+const WIRE_FORMAT_ATTR = "data-og-format";
+const WIRE_FORMAT_JSON = "json";
+/** Is this side-channel element's text the JSON lane? */
+function wire_is_json(el) {
+	return el.getAttribute(WIRE_FORMAT_ATTR) === WIRE_FORMAT_JSON;
+}
+/** Parse a side-channel's text in its lane: `JSON.parse` for the JSON lane (nothing to revive by
+*  construction), devalue `parse` with the caller's revivers otherwise. */
+function parse_wire_text(text, json, revivers) {
+	return json ? JSON.parse(text) : parse(text, revivers);
+}
+export { WIRE_FORMAT_ATTR, WIRE_FORMAT_JSON, parse_wire_text, wire_is_json };

package/dist/script.d.ts

@@ -0,0 +1,134 @@
+/** A JSON value (what `args` and the data payloads carry). */
+export type ScriptJson = string | number | boolean | null | ScriptJson[] | {
+  [key: string]: ScriptJson | undefined;
+};
+/** The attributes every kind of inline script may carry. `true` renders a bare attribute;
+ *  `false` / `null` / `undefined` leave it out. */
+export interface ScriptAttrs {
+  /** The element id (to find or replace the tag later). */
+  id?: string;
+  /** The page's CSP nonce, when its policy allows inline scripts by nonce. */
+  nonce?: string;
+  /** Any `data-*` attribute. */
+  [data: `data-${string}`]: string | number | boolean | null | undefined;
+}
+type NoPayload = {
+  json?: never;
+  ld?: never;
+  importmap?: never;
+  speculation?: never;
+};
+type NoRun = {
+  run?: never;
+  args?: never;
+  type?: never;
+  async?: never;
+  nomodule?: never;
+  imports?: never;
+};
+/** What survives the JSON trip unchanged. A `Date` would arrive as a string, a `Map` / `Set` as
+ *  `{}`, a function or class method not at all — those are `never`, so TypeScript refuses them. */
+export type JsonSafe<T> = T extends string | number | boolean | null | undefined ? T : T extends bigint | symbol | ((...a: never[]) => unknown) | Date | RegExp | Map<unknown, unknown> | Set<unknown> ? never : { [K in keyof T]: JsonSafe<T[K]>; };
+/** `run`'s parameters as they may be passed: inferred from the call, each one JSON-safe. */
+export type ScriptArgs<A extends unknown[]> = A & { [K in keyof A]: JsonSafe<A[K]>; };
+/** `args` is required exactly when `run` takes parameters. */
+type RunArgs<A extends unknown[]> = A extends [] ? {
+  args?: [];
+} : {
+  args: ScriptArgs<A>;
+};
+/**
+ * A CLASSIC inline script (the default): runs where it stands, before the parser goes on — so in
+ * `<head>` it runs before the first paint. (`async` / `defer` do nothing on an inline classic script,
+ * so they are not offered: use `type: 'module'`.)
+ */
+export type ClassicScript<A extends unknown[]> = ScriptAttrs & NoPayload & {
+  run: (...args: A) => unknown;
+  type?: "classic";
+  /** Skip it in browsers that run modules (a fallback for very old ones). */
+  nomodule?: boolean;
+  async?: never;
+  /** (static imports need a module: `type: 'module'`) */
+  imports?: never;
+} & RunArgs<A>;
+/**
+ * A MODULE inline script: its own scope, strict mode, `import()` available, and runs after the
+ * document is parsed (the first paint does not wait for it — code that must apply before paint is a
+ * classic script). An `async` `run` is awaited, so its rejection reports as the module's.
+ * (`blocking="render"` is not offered: measured, it does not hold the paint for an inline module.)
+ */
+export type ModuleScript<A extends unknown[]> = ScriptAttrs & NoPayload & {
+  run: (...args: A) => unknown;
+  type: "module";
+  /** Run as soon as it is ready, without waiting for the document to finish parsing. */
+  async?: boolean;
+  nomodule?: never;
+  imports?: never;
+} & RunArgs<A>;
+/** The module namespaces `imports` hands to `run`, by the names it declared. (Untyped: annotate the
+ *  parameter — `({ carousel }: { carousel: typeof import('…') })` — when you have the module's types.) */
+export type ScriptImports<I extends Record<string, string>> = { readonly [K in keyof I]: any; };
+/**
+ * A MODULE inline script that needs modules: `imports` are written as static `import * as …` before
+ * the call — data, not code, so no bundler rewrites them (an `import()` inside `run` would be: Vite's
+ * SSR transform turns it into `__vite_ssr_dynamic_import__`, which the browser does not have). `run`
+ * gets the namespaces as ONE object first, then `args`.
+ */
+export type ModuleImportsScript<I extends Record<string, string>, A extends unknown[]> = ScriptAttrs & NoPayload & {
+  /** Name → URL of each module to import (an absolute or root-relative URL, or a specifier the
+   *  page's import map resolves). */
+  imports: I;
+  run: (modules: ScriptImports<I>, ...args: A) => unknown;
+  type: "module";
+  async?: boolean;
+  nomodule?: never;
+} & RunArgs<A>;
+/** `<script type="application/json">` — data for code on the page to read (`JSON.parse(el.textContent)`). */
+export type JsonScript = ScriptAttrs & NoRun & {
+  json: ScriptJson;
+  ld?: never;
+  importmap?: never;
+  speculation?: never;
+};
+/** `<script type="application/ld+json">` — structured data for search engines. */
+export type LdScript = ScriptAttrs & NoRun & {
+  ld: ScriptJson;
+  json?: never;
+  importmap?: never;
+  speculation?: never;
+};
+/** `<script type="importmap">` — bare specifiers for the page's module scripts. */
+export type ImportMapScript = ScriptAttrs & NoRun & {
+  importmap: {
+    imports?: Record<string, string>;
+    scopes?: Record<string, Record<string, string>>;
+    integrity?: Record<string, string>;
+  };
+  json?: never;
+  ld?: never;
+  speculation?: never;
+};
+/** `<script type="speculationrules">` — the pages the browser may prefetch or prerender. */
+export type SpeculationScript = ScriptAttrs & NoRun & {
+  speculation: {
+    prefetch?: ScriptJson[];
+    prerender?: ScriptJson[];
+  } & {
+    [key: string]: ScriptJson | undefined;
+  };
+  json?: never;
+  ld?: never;
+  importmap?: never;
+};
+export type ScriptOptions<A extends unknown[] = unknown[]> = ClassicScript<A> | ModuleScript<A> | ModuleImportsScript<Record<string, string>, A> | JsonScript | LdScript | ImportMapScript | SpeculationScript;
+/**
+ * An inline `<script>` tag. Pass a function and its args (shortcut for `{ run: fn, args }`) or one
+ * options object; see
+ * the module doc. Throws on an object with no payload or more than one, and on an attribute name
+ * that is not one.
+ */
+export declare function script<A extends unknown[]>(run: (...args: A) => unknown, ...args: ScriptArgs<A>): string;
+export declare function script<A extends unknown[]>(options: ClassicScript<A> | ModuleScript<A>): string;
+export declare function script<I extends Record<string, string>, A extends unknown[] = []>(options: ModuleImportsScript<I, A>): string;
+export declare function script(options: JsonScript | LdScript | ImportMapScript | SpeculationScript): string;
+export {};

package/dist/script.js

@@ -0,0 +1,184 @@
+import { escape_attr, escape_script_text } from "./escape.js";
+// src/script.ts
+/**
+* `script()` — an inline `<script>` tag as a string, for the work a csr=false page must do in the
+* HTML itself: before the first paint (a no-flash theme), before any island wakes (an early flag),
+* or as data the page carries (JSON config, JSON-LD, an import map, speculation rules).
+*
+* ONE call shape: a plain object holding exactly one payload key — `run` (a function), `json`, `ld`,
+* `importmap` or `speculation` — beside the tag's attributes. It spreads, it builds from config, and
+* TypeScript refuses the combinations a browser silently ignores. A bare function (with any trailing
+* args) is the shortcut for a plain classic script: `script(fn, a, b)` = `{ run: fn, args: [a, b] }`.
+* The result is a string: `{@html}` it where the tag should land (usually `<svelte:head>`).
+*
+* ```svelte
+* <svelte:head>
+*   {@html script(() => { const t = localStorage.getItem('theme'); if (t) document.documentElement.dataset.theme = t; })}
+*   {@html script((k) => apply(localStorage.getItem(k)), 'theme')}
+*   {@html script({ run: (href) => loadFont(href), args: [fontUrl], type: 'module' })}
+*   {@html script({ ld: { '@context': 'https://schema.org', '@type': 'Article', headline } })}
+* </svelte:head>
+* ```
+*
+* A `run` function is inlined through `Function.prototype.toString`, so it must be SELF-CONTAINED:
+* browser globals only — no imports, no closed-over variables (they do not exist in the browser).
+* Pass what it needs as `args`; they are JSON-serialized and handed to it in order.
+*/
+/** The payload and option keys — everything else in the object is an attribute. */
+const RESERVED = /* @__PURE__ */ new Set([
+	"run",
+	"args",
+	"imports",
+	"json",
+	"ld",
+	"importmap",
+	"speculation",
+	"type"
+]);
+function script(input, ...rest) {
+	const o = typeof input === "function" ? {
+		run: input,
+		args: rest
+	} : input;
+	let type = null;
+	let body;
+	let kinds = 0;
+	if (o.run !== void 0) {
+		kinds++;
+		if (typeof o.run !== "function") throw new TypeError("[ogygia] script(): `run` must be a function");
+		const module = o.type === "module";
+		if (module) type = "module";
+		const args = o.args ?? [];
+		let call = "";
+		for (let i = 0; i < args.length; i++) {
+			const json = JSON.stringify(args[i]);
+			call += (i ? "," : "") + (json === void 0 ? "undefined" : escape_script_text(json));
+		}
+		let lines = "";
+		if (o.imports !== void 0) {
+			if (!module) throw new TypeError("[ogygia] script(): `imports` needs `type: 'module'` (a static import only works in a module)");
+			let mods = "";
+			let n = 0;
+			const imports = o.imports;
+			for (const name in imports) {
+				const url = imports[name];
+				if (typeof url !== "string" || !url) throw new TypeError(`[ogygia] script(): \`imports.${name}\` must be a URL string`);
+				lines += `import * as __og_m${n} from ${escape_script_text(JSON.stringify(url))};`;
+				mods += (n ? "," : "") + `${escape_script_text(JSON.stringify(name))}:__og_m${n}`;
+				n++;
+			}
+			call = `{${mods}}` + (call ? "," + call : "");
+		}
+		const src = fn_source(o.run);
+		if (src.indexOf("__vite_ssr_") !== -1) throw new TypeError("[ogygia] script(): `run` was rewritten by the bundler (it holds `__vite_ssr_…`): an `import()` or an imported binding inside it cannot cross into the browser. Declare the module in `imports` (with `type: 'module'`) and read it from `run`'s first parameter.");
+		body = `${lines}${module ? "await " : ""}(${close_safe(src)})(${call});`;
+	} else body = "";
+	for (const [key, kind] of DATA_KINDS) {
+		if (o[key] === void 0) continue;
+		kinds++;
+		type = kind;
+		const json = JSON.stringify(o[key]);
+		if (json === void 0) throw new TypeError(`[ogygia] script(): \`${key}\` must be JSON-serializable`);
+		body = escape_script_text(json);
+	}
+	if (kinds !== 1) throw new TypeError(`[ogygia] script(): pass exactly one of \`run\`, \`json\`, \`ld\`, \`importmap\`, \`speculation\` (got ${kinds})`);
+	let attrs = type ? ` type="${type}"` : "";
+	for (const key in o) {
+		if (RESERVED.has(key)) continue;
+		const v = o[key];
+		if (v === void 0 || v === null || v === false) continue;
+		if (!is_attr_name(key)) throw new TypeError(`[ogygia] script(): \`${key}\` is not an attribute name`);
+		attrs += v === true ? " " + key : ` ${key}="${escape_attr(String(v))}"`;
+	}
+	return `<script${attrs}>${body}<\/script>`;
+}
+const DATA_KINDS = [
+	["json", "application/json"],
+	["ld", "application/ld+json"],
+	["importmap", "importmap"],
+	["speculation", "speculationrules"]
+];
+/**
+* Code that cannot leave the tag it lives in. Two HTML tokenizer traps, both in strings, regexes or
+* comments of the code (where they are legal JS):
+*  - `<\/script` (any case) closes the tag → `<\/script` (the same text in a string, a template or a
+*    regex, with or without the `u` flag);
+*  - `<!--` switches the tokenizer into the escaped state, where a later `<script` makes the REAL
+*    `<\/script>` no longer close the tag — the rest of the page becomes script text → `\x3C!--`
+*    (the same text in a string, a template or a regex, `u` flag included).
+* (`a <!--b` as an expression — `a < !(--b)` — would no longer parse. Nobody writes it.)
+*/
+function close_safe(code) {
+	let out = "";
+	let last = 0;
+	for (let i = code.indexOf("<"); i !== -1; i = code.indexOf("<", i + 1)) if (code.startsWith("!--", i + 1)) {
+		out += code.slice(last, i) + "\\x3C";
+		last = i + 1;
+	} else if (code.charCodeAt(i + 1) === 47 && code.slice(i + 2, i + 8).toLowerCase() === "script") {
+		out += code.slice(last, i + 1) + "\\";
+		last = i + 1;
+	}
+	return last === 0 ? code : out + code.slice(last);
+}
+/**
+* A function's source as an EXPRESSION. `toString` of an arrow or a `function` already is one; a
+* method written in the options object (`{ run() { … } }`, `async run()`, `*run()`) is not —
+* `(run() {…})` is a syntax error — so a method is read back out of an object literal:
+* `Object.values({ run() {…} })[0]`.
+*/
+function fn_source(fn) {
+	const src = fn.toString();
+	let i = 0;
+	if (src.startsWith("async")) {
+		let j = 5;
+		while (is_ws(src.charCodeAt(j))) j++;
+		if (src.startsWith("=>", j)) return src;
+		if (src.charCodeAt(j) === 40) return src.startsWith("=>", skip_ws(src, after_parens(src, j))) ? src : `Object.values({${src}})[0]`;
+		if (j === 5) return `Object.values({${src}})[0]`;
+		i = j;
+	}
+	if (src.startsWith("function", i) && !is_ident(src.charCodeAt(i + 8))) return src;
+	const c = src.charCodeAt(i);
+	if (c === 40) return src;
+	if (is_ident(c)) {
+		let j = i;
+		while (is_ident(src.charCodeAt(j))) j++;
+		if (src.startsWith("=>", skip_ws(src, j))) return src;
+	}
+	return `Object.values({${src}})[0]`;
+}
+function is_ws(c) {
+	return c === 32 || c === 9 || c === 10 || c === 13;
+}
+function is_ident(c) {
+	return c >= 97 && c <= 122 || c >= 65 && c <= 90 || c >= 48 && c <= 57 || c === 95 || c === 36 || c > 127;
+}
+function skip_ws(s, i) {
+	while (is_ws(s.charCodeAt(i))) i++;
+	return i;
+}
+/** The index after the `)` that closes the `(` at `open` — strings skipped, nesting counted. */
+function after_parens(s, open) {
+	let depth = 0;
+	for (let i = open; i < s.length; i++) {
+		const c = s.charCodeAt(i);
+		if (c === 34 || c === 39 || c === 96) {
+			for (i++; i < s.length && s.charCodeAt(i) !== c; i++) if (s.charCodeAt(i) === 92) i++;
+		} else if (c === 40) depth++;
+		else if (c === 41 && --depth === 0) return i + 1;
+	}
+	return s.length;
+}
+/** An HTML attribute name we will write: letters, digits, `-`, `_`, `:`, `.`, starting with a letter. */
+function is_attr_name(s) {
+	if (s.length === 0) return false;
+	for (let i = 0; i < s.length; i++) {
+		const c = s.charCodeAt(i);
+		if (c >= 97 && c <= 122 || c >= 65 && c <= 90) continue;
+		if (i === 0) return false;
+		if (c >= 48 && c <= 57 || c === 45 || c === 95 || c === 58 || c === 46) continue;
+		return false;
+	}
+	return true;
+}
+export { script };

package/dist/seed-refs.d.ts

@@ -0,0 +1,105 @@
+/** The devalue type tag. */
+export declare const SEED_REF_KEY = "OgygiaSeedRef";
+export type SeedPath = (string | number)[];
+export interface SeedIndex {
+  /** node → its path from `page.data` (identity matches: the app passed the seed's own object).
+   *  The path is materialised on the first ask — an indexed node that no island references
+   *  never allocates one. */
+  readonly by_identity: {
+    get(node: object): SeedPath | undefined;
+    has(node: object): boolean;
+  };
+  /**
+   * The seed nodes with exactly this byte estimate — the only ones a props node of that size can
+   * be a clone of. Structure matching hashes just those few candidates (memoised per seed node)
+   * instead of the whole seed, so an app that passes the seed's own objects never hashes a seed
+   * node at all, and a cloning app hashes only what it has to. The buckets are built on the first
+   * ask — a page whose islands only pass seed objects by identity never builds them.
+   */
+  candidates(bytes: number): readonly object[];
+  /** Structural hash of an indexed seed node, memoised for the request. */
+  hash_of(node: object): string | null;
+  /** nodes indexed (for tests / devtools). */
+  readonly size: number;
+  /**
+   * SEED SHAPING: the top-level `page.data` keys under which a props node was matched
+   * (`plan_seed_refs` records the first path segment of every reference it plans). The handle
+   * renders the tail against the FULL index, then ships every touched key — a key no island's
+   * code reads but whose node an island's props point into still ships, so a reference always
+   * has something to point at.
+   */
+  readonly touched: Set<string>;
+}
+/** Exact structural equality for the shapes `hash_subtree` accepts — the check behind a hash hit. */
+export declare function deep_equal_plain(a: unknown, b: unknown): boolean;
+/** What one walk learns about a subtree. */
+export interface Measure {
+  /** Byte estimate of the subtree's serialized form (a threshold input, not an exact count). */
+  readonly bytes: number;
+  /** Referenceable: plain objects / arrays / plain leaves only, no cycle — a seed ref may point
+   *  at it and the client reads it back as the same plain data. */
+  readonly ref: boolean;
+  /** JSON-exact: `JSON.stringify` + `JSON.parse` reproduce it — no undefined, Date, bigint,
+   *  non-finite number, -0, class instance, Map/Set, cycle. What picks the JSON lane. */
+  readonly json: boolean;
+  /** A thenable somewhere inside (a streamed load promise the handle must stage or settle). */
+  readonly thenable: boolean;
+}
+/** Per-node measures: plain object / array → packed measure. Shared across every root measured in
+ *  one request (the handle installs a reader); a fresh one per root outside a request. */
+export type MeasureMemo = Map<object, number>;
+type MemoReader = () => MeasureMemo | null;
+/** Server (`hooks.ts`) installs a request-scoped reader: every root measured during one request
+ *  shares one memo, so a subtree reached from two roots (the seed and an island's props) is walked
+ *  once. `null` uninstalls; off-request (a hole endpoint, a test) each root gets its own memo. */
+export declare function set_measure_memo_reader(fn: MemoReader | null): void;
+/** What one walk says about a value (see {@link Measure}). */
+export declare function analyze(value: unknown): Measure;
+/**
+ * WHY a tree is not JSON-exact: the path of the first leaf that disqualifies it, with what it
+ * is — `config.updated (Date)`, `rows[3].price (NaN)`, `facets (Map)`, `meta (class Foo)`. A
+ * separate walk on purpose (the measuring walk carries no paths); the handle runs it only for a
+ * tree that left the JSON lane and only while the profiler records. `null` for a JSON tree.
+ */
+export declare function json_culprit(value: unknown, max_depth?: number): string | null;
+/**
+ * Index the seed's `data` for referencing: every referenceable node at or above `min_bytes`, by
+ * identity now and by structural hash on demand (first occurrence wins — the shortest path is not
+ * guaranteed, the first in key order is, which is deterministic). Cached per `data` object: one
+ * index per request, however many islands ask. It reads the one measuring walk (`analyze`) and
+ * prunes: a node below `min_bytes` cannot hold a child at or above it (a child is never larger
+ * than its parent), so its subtree is skipped BEFORE anything is materialised — on a CMS tree that
+ * is most of the nodes.
+ */
+export declare function index_seed(data: unknown, min_bytes?: number): SeedIndex;
+export interface SeedRefPlan {
+  /** The devalue reducer for the `OgygiaSeedRef` type: `(value) => path | undefined`. */
+  reducer: (value: unknown) => SeedPath | undefined;
+  /** How many props nodes will cross as references (0 = serialize the canonical text instead). */
+  count: number;
+  /** The top-level `page.data` keys the references point into (this island's share of `touched`). */
+  keys: Set<string>;
+}
+/**
+ * Plan one island's references: walk the props once, top-down, largest matching ancestor first —
+ * identity first (a pointer lookup per node, no hashing), then structure (hash + exact comparison,
+ * only for a large plain node the seed does not own, and only against the seed nodes of exactly the
+ * same byte size — usually none, or one). Nodes under a matched ancestor are never visited (they
+ * ride inside the reference), and neither is anything under a node below `min_bytes` (no child
+ * of it can be referenced). The props' own measures come from the request memo, so the plan adds
+ * no walk of its own beyond the pointer lookups.
+ */
+export declare function plan_seed_refs(index: SeedIndex, props: unknown, min_bytes?: number): SeedRefPlan;
+/** Client: the node a path points at, or `undefined` when the seed does not have it. */
+export declare function resolve_seed_ref(data: unknown, path: SeedPath): unknown;
+/**
+ * Client reviver for the devalue type: resolve BY REFERENCE. The island receives the seed's own
+ * node — the same object its `page.data` read would hand it, shared exactly the way `page.data`
+ * already is between islands. A deep copy per reference (129 of them on a measured page) bought
+ * nothing: island props are a snapshot either way, and the DEV mutation guard the runtime wraps
+ * every island's props in (`PropMutationGuard`) already warns on a write into them. `get_data` is
+ * called lazily, once per reviver — the first reference resolves the seed. A dangling path (no seed,
+ * or a seed that does not carry the node) revives to `undefined` and, in dev, says why.
+ */
+export declare function seed_ref_reviver(get_data: () => unknown): (path: SeedPath) => unknown;
+export {};