@ogygia/core 0.0.0 → 0.11.0

package/dist/events/schema.d.ts

@@ -0,0 +1,389 @@
+/**
+ * Devtools event schema v1 — the UI-agnostic wire vocabulary the whole Observatory rides on
+ * (internal/notes/devtools.md, Rung 0). Every event is JSON-serializable and keyed on the
+ * identities the framework already mints — region fingerprints (`data-og-fp`), island entry ids,
+ * hub Ref ids — so a region's compile, server render, wire payload, client wake, and nav-reconcile
+ * decision CORRELATE by id with zero new identity machinery. That is what turns a log into a story.
+ *
+ * Laws (from the note):
+ *  - **Versioned from day one.** `DEVTOOLS_SCHEMA_VERSION` is stamped on every event; the trace
+ *    format is a public artifact eventually, so a consumer can refuse a version it doesn't know.
+ *  - **Sizes always, payload bodies lazy.** Events carry byte COUNTS (cheap — a length already in
+ *    hand), never the bytes themselves. A sink that wants the body subscribes to the DOM/network.
+ *  - **Don't invent events the code can't cheaply produce.** Every name below maps to a real seam
+ *    (see the per-domain comments); nothing here needs an extra serialization pass to emit.
+ *
+ * Naming: internal, so snake_case is the house style — but these strings travel on the wire and name
+ * user-facing instruments, so event NAMES use the `domain.thing.verb` dotted form (stable ids), while
+ * the TS field names stay terse. Domains mirror the note's Schema-v1 table.
+ */
+/** Bump only on a breaking shape change; a trace stamps this so a reader can gate on it. */
+export declare const DEVTOOLS_SCHEMA_VERSION = 1;
+/** The six event domains (note's Schema-v1 table). */
+export type DevtoolsDomain = "compile" | "server" | "wire" | "runtime" | "hub" | "nav";
+/** Fields the bus stamps on EVERY event — the caller never sets these. */
+export interface DevtoolsEnvelope {
+  /** Schema version ({@link DEVTOOLS_SCHEMA_VERSION}) — copied onto every event for trace gating. */
+  v: number;
+  /** Monotonic per-session sequence number (ordering that survives equal timestamps). */
+  seq: number;
+  /** Timestamp: `performance.now()` (ms, sub-ms precision) when available, else `Date.now()`. */
+  t: number;
+  /** Which realm emitted it — a trace merges client + server streams, so it must be labelled. */
+  realm: "client" | "server";
+}
+/** What a call site passes to `emit` — the envelope is added by the bus. */
+export type DevtoolsEventInput = CompileEventInput | ServerEventInput | WireEventInput | RuntimeEventInput | HubEventInput | NavEventInput;
+/** A fully-stamped event as it sits in the ring buffer / trace / on a sink. */
+export type DevtoolsEvent = DevtoolsEventInput & DevtoolsEnvelope;
+export type CompileEventInput = {
+  domain: "compile";
+  name: "compile.island.discovered";
+  /** Region identity (the transform's stable id / iid). */
+  iid: string;
+  /** Client entry chunk specifier (`entry="…"`). */
+  entry?: string;
+  /** The two-dial strategy key (`render`+`wake`), e.g. `island:load`, `defer:visible`, `lake`. */
+  strategy: string;
+  /** csr decision at discovery: does this host ship the ogygia runtime at all. */
+  csr: boolean;
+} | {
+  domain: "compile";
+  name: "compile.chunk.emitted";
+  /** Deduped wrapper/entry chunk filename. */
+  entry: string;
+  /** Emitted source size (bytes) — a length already in hand at emit. */
+  bytes: number;
+};
+export type ServerEventInput = {
+  domain: "server";
+  name: "server.region.rendered";
+  /** `data-og-fp` — the exact key the client wake / reconcile correlate on. */
+  fp: string;
+  /** island | server | lake | held-inline | held-defer | held-live. */
+  mode: string;
+  entry?: string;
+  /** Rendered HTML size (bytes). */
+  htmlBytes?: number;
+  /** devalue props sidecar size (bytes). */
+  propsBytes?: number;
+  /** Wall-clock ms for the component's server render, when measured. */
+  ms?: number;
+} | {
+  domain: "server";
+  name: "server.capability.minted";
+  /** Signed hole id. */
+  id: string;
+  /** Capability TTL (seconds). */
+  ttl?: number;
+} | {
+  domain: "server";
+  name: "server.delta.skip";
+  /** A region the client already has live (`x-ogygia-known`) — server SKIPPED re-rendering it. */
+  fp: string;
+} | {
+  domain: "server";
+  name: "server.seed.injected";
+  /** page | remote — which document side-channel seed the handle wrote. */
+  kind: "page" | "remote";
+  bytes: number;
+} | {
+  domain: "server";
+  name: "server.postrender";
+  /** hit | join | stored | skip | invalidate | invalidate-where | self-evict. */
+  op: string;
+  /** Store key (URL pathname), or the prefix for the bulk op. */
+  url?: string;
+  /** Named refusal for `skip` — the same string the dev note prints. */
+  reason?: string;
+  /** Stored html size (bytes) for `stored`. */
+  bytes?: number;
+};
+export type WireEventInput = {
+  domain: "wire";
+  name: "wire.props";
+  entry?: string;
+  /** devalue payload size (bytes). */
+  bytes: number;
+} | {
+  domain: "wire";
+  name: "wire.context";
+  bytes: number;
+} | {
+  domain: "wire";
+  name: "wire.frame.batch";
+  /** Regions in the single-flight parcel. */
+  count: number;
+  bytes?: number;
+} | {
+  domain: "wire";
+  name: "wire.known.sent";
+  /** Fingerprints the client claimed via `x-ogygia-known`. */
+  count: number;
+  bytes: number;
+};
+export type RuntimeEventInput = {
+  domain: "runtime";
+  name: "runtime.boot";
+  /** Feature installers that ran (router, lakes, live, interaction, …). */
+  features: string[];
+} | {
+  domain: "runtime";
+  name: "region.connected";
+  entry?: string;
+  fp?: string;
+  /** wake attribute (load | idle | visible | interaction | media | none). */
+  wake?: string;
+  /** True for a `render="defer"` hole (HTML fetched, not inline). */
+  deferred: boolean;
+  /** True when this region rides an awake ancestor (nested — self-run skipped). */
+  nested: boolean;
+} | {
+  domain: "runtime";
+  name: "wake.scheduled";
+  entry?: string;
+  fp?: string;
+  /** The schedule armed (load | idle | visible | interaction | media). */
+  when: string;
+} | {
+  domain: "runtime";
+  name: "wake.fired";
+  entry?: string;
+  fp?: string;
+  when: string;
+} | {
+  domain: "runtime";
+  /** A deferred hole's `prefetch` schedule fired: its HTML is being warmed into the frame
+   *  store ahead of its `when` (no swap yet — the wake joins this frame later). */
+  name: "region.prefetch";
+  entry?: string;
+  fp?: string;
+} | {
+  domain: "runtime";
+  name: "region.hydrate.start";
+  entry?: string;
+  fp?: string;
+} | {
+  domain: "runtime";
+  name: "region.hydrate.done";
+  entry?: string;
+  fp?: string;
+  /** Wall-clock ms from hydrate start to mounted: its `$effect`s and onMount included (they
+   *  run in a microtask after Svelte's `hydrate()`; the event is sent after them). */
+  ms: number;
+} | {
+  domain: "runtime";
+  name: "region.hydrate.failed";
+  entry?: string;
+  fp?: string;
+  message: string;
+} | {
+  domain: "runtime";
+  /** Svelte's silent mismatch RECOVERY discarded this region's entire server DOM and
+   *  re-rendered it client-side — something mutated the region between SSR and wake
+   *  (post-SSR transform, A/B tool, DSD injector). See internal/notes/foreign-dom.md. */
+  name: "region.hydrate.recovered";
+  entry?: string;
+  fp?: string;
+  /** The specific first divergence between the server markup and the mutated live DOM (e.g.
+   *  "an injected <style>", "scoped web-component hydration marks", "whitespace stripped") —
+   *  the WHY, when the runtime could name it. Absent when the recovery had no sequence drift
+   *  the walk sees. */
+  reason?: string;
+} | {
+  domain: "runtime";
+  /** The island's live DOM had drifted from its server markup while it slept (another
+   *  script edited it); the runtime put the server markup back and hydrated THAT instead of
+   *  letting Svelte re-render the island client-side. */
+  name: "region.hydrate.healed";
+  entry?: string;
+  fp?: string;
+  /** The first divergence the runtime repaired — same "why" as the recovered event. */
+  reason?: string;
+} | {
+  domain: "runtime";
+  /** A download ogygia started on its own left the load scheduler's queue
+   *  (runtime/load-scheduler.ts): its class, what it fetches, and how long it waited for its
+   *  slot (the page's critical resources, the background window). */
+  name: "load.started";
+  class: "user" | "visible" | "ahead" | "speculative";
+  kind: "code" | "content";
+  label?: string;
+  waited_ms: number;
+} | {
+  domain: "runtime";
+  /** The load scheduler stopped waiting for the page's critical resources (the images and
+   *  preloads marked `fetchpriority="high"`): they `arrived`, the visitor's first `input`, the
+   *  `cap` ran out, or `none` were pending. */
+  name: "load.critical";
+  outcome: "arrived" | "input" | "cap" | "none";
+  resources: number;
+  waited_ms: number;
+} | {
+  domain: "runtime";
+  /** Two owners wanted the same nodes (runtime/ownership.ts): a web component changed its own
+   *  children in a position Svelte's hydration reads, and the repair removed what it added so
+   *  the island could hydrate. `reason` names the element and the way out ({@html} / static
+   *  markup / a lake / data-ogygia-keep). */
+  name: "region.hydrate.conflict";
+  entry?: string;
+  fp?: string;
+  reason?: string;
+} | {
+  domain: "runtime";
+  /** Svelte's own dev warning that the server and the browser disagreed while hydrating
+   *  (`hydration_html_changed`, `hydration_attribute_changed`, `hydration_mismatch`…) */
+  name: "svelte.hydration.warning";
+  /** Svelte's code, e.g. `hydration_html_changed` */
+  code: string;
+  message: string;
+  /** the component file the warning names, when it names one */
+  file?: string;
+  /** the island that was hydrating when it was raised */
+  fp?: string;
+} | {
+  domain: "runtime";
+  name: "region.server.applied";
+  entry?: string;
+  endpoint?: string;
+  /** Fetched hole HTML size (bytes). */
+  bytes: number;
+  /** True for an SWR/live re-apply (not the first paint). */
+  revalidate: boolean;
+  /** The first answer: ms from the fetch's start to the swap (how long the fallback showed). */
+  wait_ms?: number;
+} | {
+  /** Holes went out as ONE batch request (runtime/frame-nav.ts): the page's holes that
+   *  started together, or a navigation's. One request, a part per hole as each renders. */
+  domain: "runtime";
+  name: "region.batch.sent";
+  /** this batch, on this page (its parts and its end carry it) */
+  batch: number;
+  /** `page`: holes that started together; `nav`: an in-app navigation's */
+  kind: "page" | "nav";
+  /** the holes' endpoints */
+  endpoints: string[];
+} | {
+  /** One hole's answer landed out of its batch (when it rendered: out of order). */
+  domain: "runtime";
+  name: "region.batch.part";
+  batch: number;
+  endpoint: string;
+} | {
+  /** A batch request ended. The holes it did not carry fetch on their own right after. */
+  domain: "runtime";
+  name: "region.batch.done";
+  batch: number;
+  sent: number;
+  /** holes whose answer it carried */
+  delivered: number;
+  /** the response's status (0: the request itself failed) */
+  status: number;
+  /** what answered, when it was not the batch: redirected to another URL, or a whole document */
+  refused?: "redirected" | "document";
+  final_url?: string;
+} | {
+  /** A hole's answer did not arrive. Without this the page keeps the fallback and nothing
+   *  anywhere says why (in a build the runtime is silent). */
+  domain: "runtime";
+  name: "region.server.failed";
+  entry?: string;
+  endpoint?: string;
+  /** refused: redirected / a whole document answered / the capability refused (403); error:
+   *  the request failed */
+  reason: "redirected" | "document" | "forbidden" | "error";
+  /** what answered instead (a refused answer) */
+  final_url?: string;
+  /** the error's first line (a failed request), or the server's reason (a refused capability) */
+  message?: string;
+  /** this attempt (1-based) */
+  attempt: number;
+  /** no retry follows: the fallback stays */
+  final: boolean;
+} | {
+  /** An island's LOCATION (its content-hashed file) failed to load, and it woke — or tried
+   *  to — through its IDENTITY fetched fresh: the page's HTML came from a build whose files
+   *  are gone (a cache outlived it). Its code is now the current build's. */
+  domain: "runtime";
+  name: "entry.fallback";
+  /** the identity (the stable URL) */
+  entry: string;
+  /** the location that failed */
+  src: string;
+  /** the fresh identity loaded (false: it failed too, the island stays asleep) */
+  recovered: boolean;
+} | {
+  domain: "runtime";
+  name: "interaction.replay";
+  entry?: string;
+  fp?: string;
+  /** Queued clicks replayed after the wake. */
+  clicks: number;
+  /** Form fields whose typed value was restored. */
+  fields: number;
+};
+export type HubEventInput = {
+  domain: "hub";
+  name: "hub.mint";
+  /** Kind discriminator (wire | store | snippet | region | fn | …). */
+  kind: string;
+  /** Minted Ref id. */
+  id: string;
+  tag?: string;
+} | {
+  domain: "hub";
+  name: "hub.resolve";
+  kind: string;
+  id: string;
+  scope: string;
+  /** Registration tag `<module>#<ExportName>` (wire classes) — the hub inspector's name. */
+  tag?: string;
+  /** True when an existing instance was reunited (memo hit), false on a fresh decode. */
+  hit: boolean;
+} | {
+  domain: "hub";
+  name: "hub.dispose";
+  /** page | session | ids — which scope (or a selective id sweep) was torn down. */
+  scope: string;
+  /** Instances disposed. */
+  count: number;
+};
+export type NavEventInput = {
+  domain: "nav";
+  name: "nav.start";
+  from: string;
+  to: string;
+  /** link | goto | popstate | enter. */
+  type: string;
+} | {
+  domain: "nav";
+  name: "nav.finish";
+  to: string;
+  /** Wall-clock ms from nav start to swap committed. */
+  ms: number;
+  /** True on the reconcile (in-place diff) path, false on the full-swap fallback. */
+  reconciled: boolean;
+  /** True when the swap ran inside a View Transition. */
+  vt: boolean;
+} | {
+  domain: "nav";
+  name: "nav.reconcile";
+  /** The reconcile key: `k\0<keepName>` (keep marker) / `p\0<sig>` (persist) / `r\0<fp>` (props fp). */
+  key: string;
+  /** keep | patch | mount | remove — the per-region delta decision. */
+  decision: "keep" | "patch" | "mount" | "remove";
+  /** The region's `entry` module URL — lets the nav lab label the decision by component NAME. */
+  entry?: string;
+  /** The region's wake strategy, for the nav lab row. */
+  wake?: string;
+} | {
+  domain: "nav";
+  name: "nav.batch";
+  /** Deferred holes single-flighted into one request. */
+  count: number;
+} | {
+  domain: "nav";
+  name: "nav.fallback";
+  /** Why the reconcile path was skipped (shadow-dom / reconcile-off). */
+  reason: string;
+};

package/dist/events/schema.js

@@ -0,0 +1,23 @@
+// src/events/schema.ts
+/**
+* Devtools event schema v1 — the UI-agnostic wire vocabulary the whole Observatory rides on
+* (internal/notes/devtools.md, Rung 0). Every event is JSON-serializable and keyed on the
+* identities the framework already mints — region fingerprints (`data-og-fp`), island entry ids,
+* hub Ref ids — so a region's compile, server render, wire payload, client wake, and nav-reconcile
+* decision CORRELATE by id with zero new identity machinery. That is what turns a log into a story.
+*
+* Laws (from the note):
+*  - **Versioned from day one.** `DEVTOOLS_SCHEMA_VERSION` is stamped on every event; the trace
+*    format is a public artifact eventually, so a consumer can refuse a version it doesn't know.
+*  - **Sizes always, payload bodies lazy.** Events carry byte COUNTS (cheap — a length already in
+*    hand), never the bytes themselves. A sink that wants the body subscribes to the DOM/network.
+*  - **Don't invent events the code can't cheaply produce.** Every name below maps to a real seam
+*    (see the per-domain comments); nothing here needs an extra serialization pass to emit.
+*
+* Naming: internal, so snake_case is the house style — but these strings travel on the wire and name
+* user-facing instruments, so event NAMES use the `domain.thing.verb` dotted form (stable ids), while
+* the TS field names stay terse. Domains mirror the note's Schema-v1 table.
+*/
+/** Bump only on a breaking shape change; a trace stamps this so a reader can gate on it. */
+const DEVTOOLS_SCHEMA_VERSION = 1;
+export { DEVTOOLS_SCHEMA_VERSION };

package/dist/events/server-registry.d.ts

@@ -0,0 +1,7 @@
+import { DevtoolsEventInput } from "./schema.js";
+/** A recorder receives the un-stamped event input; hooks.ts stamps + buffers it per request. */
+export type ServerDevtoolsRecorder = (input: DevtoolsEventInput) => void;
+/** Server (`hooks.ts`) installs a request-scoped, ALS-backed recorder. Passing `null` clears it. */
+export declare function set_server_devtools_recorder(fn: ServerDevtoolsRecorder | null): void;
+/** SSR render seams call this; the client (recorder unset) is a no-op, and the whole call DCEs off. */
+export declare function record_server_event(input: DevtoolsEventInput): void;

package/dist/events/server-registry.js

@@ -0,0 +1,13 @@
+// src/events/server-registry.ts
+const DEVTOOLS = typeof __OGYGIA_DEVTOOLS__ !== "undefined" ? __OGYGIA_DEVTOOLS__ : false;
+let recorder = null;
+/** Server (`hooks.ts`) installs a request-scoped, ALS-backed recorder. Passing `null` clears it. */
+function set_server_devtools_recorder(fn) {
+	recorder = fn;
+}
+/** SSR render seams call this; the client (recorder unset) is a no-op, and the whole call DCEs off. */
+function record_server_event(input) {
+	if (!DEVTOOLS) return;
+	recorder?.(input);
+}
+export { record_server_event, set_server_devtools_recorder };

package/dist/events/sinks.d.ts

@@ -0,0 +1,64 @@
+import { DevtoolsEvent } from "./schema.js";
+/** The global the {@link install_window_sink window sink} publishes. Distinct from the compile-time
+ *  `__OGYGIA_DEVTOOLS__` define (a bare identifier the bundler replaces) — this is a real runtime
+ *  object on `window`, read by Playwright `page.evaluate` across the script boundary. */
+declare const WINDOW_HOOK = "__ogygia_devtools";
+/** Shape of `window.__ogygia_devtools` (the e2e / instrument entry point). */
+export interface DevtoolsWindowHook {
+  /** Schema version, so a reader can gate. */
+  version: number;
+  /** Every buffered event, oldest → newest (a fresh copy each call). */
+  events(): DevtoolsEvent[];
+  /** Subscribe to events from now on; returns an unsubscribe fn. */
+  on(cb: (event: DevtoolsEvent) => void): () => void;
+  /** Drop the buffer (between e2e scenarios). */
+  clear(): void;
+  /** Serialize the buffer to a portable trace. */
+  trace(): DevtoolsTrace;
+}
+declare global {
+  interface Window {
+    [WINDOW_HOOK]?: DevtoolsWindowHook;
+  }
+}
+/**
+ * Publish `window.__ogygia_devtools` so an out-of-page reader (Playwright, a devtools panel, a REPL
+ * host) can pull buffered events, subscribe to new ones, and drain a trace — WITHOUT importing any
+ * framework module. Idempotent. No-op off the browser. Returns the hook (or undefined on the server).
+ *
+ * This is what lets our e2e assert on the ISLAND LIFECYCLE directly ("interaction island fired its
+ * wake, replayed exactly one click") instead of polling the DOM behind a `waitForTimeout` — the
+ * bus pays for itself in our own tests first (the note's proof-of-value).
+ */
+export declare function install_window_sink(): DevtoolsWindowHook | undefined;
+/**
+ * Forward every event to a `postMessage` target (the REPL's tab ↔ worker ↔ iframe channel). Pass a
+ * `Worker` / `MessagePort` / `Window`; each event is posted as `{ __ogygia_devtools: event }`.
+ * Returns the unregister fn.
+ */
+export declare function install_postmessage_sink(target: {
+  postMessage: (message: unknown) => void;
+}): () => void;
+/** Log every event to the console (debugging). `filter` limits by domain/name substring. */
+export declare function install_console_sink(filter?: (event: DevtoolsEvent) => boolean): () => void;
+/** A portable trace — a versioned bag of events, attachable to a bug report and replayable in the
+ *  REPL later (the note's "CPU-profile energy, but for the islands lifecycle"). */
+export interface DevtoolsTrace {
+  /** Marker so a consumer knows what it's holding. */
+  kind: "ogygia-devtools-trace";
+  /** {@link DEVTOOLS_SCHEMA_VERSION}. */
+  version: number;
+  /** Events in emission order. */
+  events: DevtoolsEvent[];
+}
+/** Serialize the current buffer into a {@link DevtoolsTrace}. */
+export declare function to_trace(): DevtoolsTrace;
+/**
+ * Read the server realm's `<script type="application/ogygia-devtools">` side-channel (injected by the
+ * handle on a devtools build) and INGEST its events into the unified stream, so a region's server
+ * render sits in the same `window.__ogygia_devtools` timeline as its client wake — correlated by
+ * fingerprint. Idempotent per document via a marker attribute; no-op off the browser or when the
+ * script is absent. Returns how many server events were ingested.
+ */
+export declare function ingest_server_events(): number;
+export {};

package/dist/events/sinks.js

@@ -0,0 +1,85 @@
+import { add_sink, clear, ingest, snapshot } from "./bus.js";
+import "./schema.js";
+// src/events/sinks.ts
+/**
+* Built-in sinks + the trace format (internal/notes/devtools.md, Rung 0). Each sink is a plain
+* listener over {@link ./bus.js the bus}; none touches framework internals. Load only what you use —
+* the REPL wants `postMessage`, our e2e wants the `window` hook, a bug report wants a trace.
+*/
+/** The global the {@link install_window_sink window sink} publishes. Distinct from the compile-time
+*  `__OGYGIA_DEVTOOLS__` define (a bare identifier the bundler replaces) — this is a real runtime
+*  object on `window`, read by Playwright `page.evaluate` across the script boundary. */
+const WINDOW_HOOK = "__ogygia_devtools";
+/**
+* Publish `window.__ogygia_devtools` so an out-of-page reader (Playwright, a devtools panel, a REPL
+* host) can pull buffered events, subscribe to new ones, and drain a trace — WITHOUT importing any
+* framework module. Idempotent. No-op off the browser. Returns the hook (or undefined on the server).
+*
+* This is what lets our e2e assert on the ISLAND LIFECYCLE directly ("interaction island fired its
+* wake, replayed exactly one click") instead of polling the DOM behind a `waitForTimeout` — the
+* bus pays for itself in our own tests first (the note's proof-of-value).
+*/
+function install_window_sink() {
+	if (typeof window === "undefined") return void 0;
+	const existing = window[WINDOW_HOOK];
+	if (existing) return existing;
+	const hook = {
+		version: 1,
+		events: () => snapshot(),
+		on: (cb) => add_sink(cb),
+		clear: () => clear(),
+		trace: () => to_trace()
+	};
+	window[WINDOW_HOOK] = hook;
+	return hook;
+}
+/**
+* Forward every event to a `postMessage` target (the REPL's tab ↔ worker ↔ iframe channel). Pass a
+* `Worker` / `MessagePort` / `Window`; each event is posted as `{ __ogygia_devtools: event }`.
+* Returns the unregister fn.
+*/
+function install_postmessage_sink(target) {
+	const sink = (event) => target.postMessage({ [WINDOW_HOOK]: event });
+	return add_sink(sink);
+}
+/** Log every event to the console (debugging). `filter` limits by domain/name substring. */
+function install_console_sink(filter) {
+	const sink = (event) => {
+		if (filter && !filter(event)) return;
+		console.debug(`[ogygia:dt] ${event.domain}.${event.name}`, event);
+	};
+	return add_sink(sink);
+}
+/** Serialize the current buffer into a {@link DevtoolsTrace}. */
+function to_trace() {
+	return {
+		kind: "ogygia-devtools-trace",
+		version: 1,
+		events: snapshot()
+	};
+}
+/**
+* Read the server realm's `<script type="application/ogygia-devtools">` side-channel (injected by the
+* handle on a devtools build) and INGEST its events into the unified stream, so a region's server
+* render sits in the same `window.__ogygia_devtools` timeline as its client wake — correlated by
+* fingerprint. Idempotent per document via a marker attribute; no-op off the browser or when the
+* script is absent. Returns how many server events were ingested.
+*/
+function ingest_server_events() {
+	if (typeof document === "undefined") return 0;
+	let total = 0;
+	for (const el of document.querySelectorAll("script[type=\"application/ogygia-devtools\"]:not([data-og-dt-ingested])")) {
+		el.setAttribute("data-og-dt-ingested", "");
+		const text = el.textContent;
+		if (!text) continue;
+		try {
+			const events = JSON.parse(text);
+			if (Array.isArray(events) && events.length) {
+				ingest(events);
+				total += events.length;
+			}
+		} catch {}
+	}
+	return total;
+}
+export { ingest_server_events, install_console_sink, install_postmessage_sink, install_window_sink, to_trace };

package/dist/fn-transport.d.ts

@@ -0,0 +1,33 @@
+/** Register a hoisted-function factory under its build tag (module path + export name).
+ *  Called by the generated module; runs wherever that chunk loads (server AND island bundles). */
+export declare function __register_fn(tag: string, factory: unknown): void;
+/** Is this a transportable (og.$-branded) function? The drop-in setContext bridges these —
+ *  the "functions never cross" law applies to BARE functions only. */
+export declare function is_branded_fn(value: unknown): boolean;
+/**
+ * The call-site rewrite target: build the LIVE function for this side (the factory's module is
+ * imported right there, so it is always registered) and brand it with its travel handle. The
+ * host renders with a real function; if it crosses a boundary, the brand is what travels.
+ */
+export declare function fn_handle(tag: string, bound: unknown[]): (...args: unknown[]) => unknown;
+/** The hub kind: a branded hoisted function. Bare functions are NEVER claimed (the snippet kind
+ *  owns SSR-freezable snippets; an unmarked function at a boundary must keep failing loudly). */
+export declare function register_fn_kind(): void;
+/** Devalue reducer (legacy-shaped wrapper, mirrors the other kinds). */
+export declare function reduce_fn(value: unknown): {
+  t: string;
+  i: string;
+  d: unknown;
+} | undefined;
+/** Devalue reviver. Functions never memoize; `remember` rides through for capture resolution. */
+export declare function revive_fn(payload: {
+  t: string;
+  i: string;
+  d: unknown;
+}, remember: boolean): unknown;
+/**
+ * The `import.meta.og.$` rewrite target: register the hoisted factory (pull-registration —
+ * the call site IS the moment the code exists) and return the LIVE bound function, branded
+ * with its travel handle. One expression, no import-time side effects.
+ */
+export declare function __og_$(tag: string, bound: unknown[], factory: (...b: unknown[]) => unknown): (...args: unknown[]) => unknown;