@bradensbay/globals 0.2.0

package/README.md

@@ -0,0 +1,58 @@
+# @bradensbay/globals
+
+The Electron integration for [Globals](https://github.com/christianGRogers/globals) over the
+native transport ([ADR 0003](../../docs/adr/0003-native-transport.md)): the owner is a plain
+object in the main process, trusted windows map one shared memory region from their preloads
+and read synchronously, and windows that keep their sandbox get the asynchronous tier.
+
+The trade, first: **a window that maps the region runs with `sandbox: false`.** Context
+isolation stays on and the page gets no Node access, but the Chromium OS sandbox for that
+renderer is off. A window that must keep its sandbox uses the asynchronous tier and never
+maps anything.
+
+## Main process
+
+```ts
+import { startNativeOwner } from "@bradensbay/globals";
+
+const owner = await startNativeOwner({
+  initial: { count: 0, rows: [] },
+  operations: {
+    increment(draft, payload: { by: number }) {
+      draft.count += payload.by;
+    },
+  },
+  persistence: {}, // optional: rehydrate on boot, save commits under userData
+});
+
+owner.store.get();                 // the owner reads its own store synchronously
+await owner.update((draft) => …);  // or writes it directly
+```
+
+## A trusted window's preload, with `sandbox: false`
+
+```ts
+import { connectNative } from "@bradensbay/globals/preload";
+
+const store = await connectNative();
+store.get();                        // synchronous, never stale, never torn
+store.select(["rows", 3, "name"]);
+await store.dispatch("increment", { by: 1 });
+```
+
+Expose whole operations to the page through `contextBridge`, not per-property reads: a
+bridge crossing costs about a microsecond, so the decode layer belongs on the preload side.
+The [example application](../../examples/native-multi-window) shows the shape.
+
+## A sandboxed window
+
+```ts
+// main process
+import { asyncPreloadPath } from "@bradensbay/globals";
+new BrowserWindow({ webPreferences: { preload: asyncPreloadPath(), sandbox: true } });
+```
+
+The page receives `window.globalsAsync`: `read(path?)`, `dispatch(operation, payload)`, and
+`subscribe(listener)`. There is no synchronous `get` on this tier, deliberately.
+
+Full guide: [docs/electron.md](../../docs/electron.md).

package/dist/src/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @bradensbay/globals
+ *
+ * The Electron integration over the native transport. The owner is a plain object in the
+ * main process; each window that shares memory maps the region file from its preload; a
+ * window that keeps its sandbox gets the asynchronous tier instead. There is no hidden
+ * owner window, no privileged scheme, and no handshake: the machinery this package once
+ * carried for the window.open topology was deleted when ADR 0003 landed, and the history
+ * holds it.
+ *
+ * Two entry points, one per process side:
+ *
+ *   Main process   "@bradensbay/globals"           startNativeOwner, asyncPreloadPath
+ *   Preload        "@bradensbay/globals/preload"   connectNative, for sandbox: false windows
+ *
+ * A sandboxed window loads the shipped preload-async.cjs (located by asyncPreloadPath) and
+ * reads by asking; it never maps the region.
+ */
+export { startNativeOwner, asyncPreloadPath } from "./native/owner.js";
+export type { StartNativeOwnerOptions } from "./native/owner.js";
+export { createNativeOwner, restoreNativeOwner } from "./native/owner-core.js";
+export type { NativeOperation, NativeOwner, NativeOwnerOptions } from "./native/owner-core.js";
+export { SnapshotStore } from "./persistence.js";
+export type { PersistenceOptions } from "./persistence.js";
+export { NATIVE_CHANNEL, HELLO, DISPATCH, COMMIT, READ } from "./native/channel.js";
+export type { DispatchMessage, Hello } from "./native/channel.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,YAAY,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC/F,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AACpF,YAAY,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,23 @@
+/**
+ * @bradensbay/globals
+ *
+ * The Electron integration over the native transport. The owner is a plain object in the
+ * main process; each window that shares memory maps the region file from its preload; a
+ * window that keeps its sandbox gets the asynchronous tier instead. There is no hidden
+ * owner window, no privileged scheme, and no handshake: the machinery this package once
+ * carried for the window.open topology was deleted when ADR 0003 landed, and the history
+ * holds it.
+ *
+ * Two entry points, one per process side:
+ *
+ *   Main process   "@bradensbay/globals"           startNativeOwner, asyncPreloadPath
+ *   Preload        "@bradensbay/globals/preload"   connectNative, for sandbox: false windows
+ *
+ * A sandboxed window loads the shipped preload-async.cjs (located by asyncPreloadPath) and
+ * reads by asking; it never maps the region.
+ */
+export { startNativeOwner, asyncPreloadPath } from "./native/owner.js";
+export { createNativeOwner, restoreNativeOwner } from "./native/owner-core.js";
+export { SnapshotStore } from "./persistence.js";
+export { NATIVE_CHANNEL, HELLO, DISPATCH, COMMIT, READ } from "./native/channel.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEvE,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAE/E,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/src/native/channel.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The IPC channel names the native transport uses. A module of its own with no Electron
+ * import, because both process sides need the names and neither may load the other's
+ * modules.
+ */
+export declare const NATIVE_CHANNEL = "globals:native";
+export declare const HELLO = "globals:native:hello";
+export declare const DISPATCH = "globals:native:dispatch";
+export declare const COMMIT = "globals:native:commit";
+export declare const READ = "globals:native:read";
+/** What the main process answers a connecting window with. */
+export interface Hello {
+    regionPath: string;
+    version: number;
+}
+/** A write intent. The renderer never writes memory; it asks the owner to. */
+export interface DispatchMessage {
+    operation: string;
+    payload: unknown;
+}
+//# sourceMappingURL=channel.d.ts.map

package/dist/src/native/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../../src/native/channel.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,KAAK,yBAA4B,CAAC;AAC/C,eAAO,MAAM,QAAQ,4BAA+B,CAAC;AACrD,eAAO,MAAM,MAAM,0BAA6B,CAAC;AAIjD,eAAO,MAAM,IAAI,wBAA2B,CAAC;AAE7C,8DAA8D;AAC9D,MAAM,WAAW,KAAK;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB"}

package/dist/src/native/channel.js

@@ -0,0 +1,14 @@
+/**
+ * The IPC channel names the native transport uses. A module of its own with no Electron
+ * import, because both process sides need the names and neither may load the other's
+ * modules.
+ */
+export const NATIVE_CHANNEL = "globals:native";
+export const HELLO = `${NATIVE_CHANNEL}:hello`;
+export const DISPATCH = `${NATIVE_CHANNEL}:dispatch`;
+export const COMMIT = `${NATIVE_CHANNEL}:commit`;
+// The asynchronous tier: a sandboxed window cannot map the region, so it reads by asking.
+// The names are duplicated as literals in preload-async.cjs, which a sandboxed preload's
+// restricted require cannot share with this module; keep them in step.
+export const READ = `${NATIVE_CHANNEL}:read`;
+//# sourceMappingURL=channel.js.map

package/dist/src/native/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../../../src/native/channel.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAC;AAC/C,MAAM,CAAC,MAAM,KAAK,GAAG,GAAG,cAAc,QAAQ,CAAC;AAC/C,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAG,cAAc,WAAW,CAAC;AACrD,MAAM,CAAC,MAAM,MAAM,GAAG,GAAG,cAAc,SAAS,CAAC;AACjD,0FAA0F;AAC1F,yFAAyF;AACzF,uEAAuE;AACvE,MAAM,CAAC,MAAM,IAAI,GAAG,GAAG,cAAc,OAAO,CAAC"}

package/dist/src/native/owner-core.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The owner over the native transport, with no Electron import so it is testable in plain
+ * Node. The Electron glue in ./owner.js is a thin layer over this.
+ *
+ * The owner is the ordinary core OwnerStore writing a private SharedArrayBuffer, exactly as
+ * the worker-thread topology uses it. What this module adds is publication: after every
+ * commit, the arena bytes are flushed into the mapped region under the region's seqlock, so
+ * any process that syncs the region gets a consistent copy of a committed arena and decodes
+ * it with the untouched core reader.
+ *
+ * Growth is deliberately disabled: the region's size is fixed at creation, so the arena is
+ * created with maxByteLength equal to byteLength and a full arena raises ArenaFullError
+ * rather than growing past what readers mapped. A growable region is future work with a
+ * re-handshake, not a default.
+ */
+import { OwnerStore, type OwnerOptions } from "@bradensbay/globals-core";
+import { SnapshotStore, type PersistenceOptions } from "../persistence.js";
+/** A named write the owner is willing to apply. Everything a window may do is one of these. */
+export type NativeOperation<State, Payload = unknown> = (draft: State, payload: Payload) => void;
+export interface NativeOwnerOptions<State> {
+    /** Where the region file lives. Every window that connects maps this path. */
+    regionPath: string;
+    /** The state the store holds before the first operation. */
+    initial: State;
+    /** The writes windows may request, by name. */
+    operations?: Record<string, NativeOperation<State, any>>;
+    /** Arena and region size in bytes. Fixed for the life of the region. */
+    byteLength?: number;
+    /** Core arena options other than size, passed through. */
+    arena?: Omit<OwnerOptions, "byteLength" | "maxByteLength">;
+    /** An already constructed snapshot store to save every commit into. */
+    snapshots?: SnapshotStore;
+}
+export interface NativeOwner<State> {
+    /** The core store, for reads, subscriptions, and direct writes from the owning process. */
+    readonly store: OwnerStore;
+    readonly regionPath: string;
+    /** The snapshot store saving commits, when persistence is configured. */
+    readonly snapshots: SnapshotStore | undefined;
+    /** The region version: the number of commits flushed. */
+    version(): number;
+    /** Apply a named operation, the same call a window's dispatch arrives as. */
+    dispatch(operation: string, payload: unknown): Promise<number>;
+    /** A typed direct write from the owning process, without naming an operation. */
+    update(recipe: (draft: State) => void): Promise<number>;
+    close(): void;
+}
+export declare function createNativeOwner<State>(options: NativeOwnerOptions<State>): NativeOwner<State>;
+/**
+ * Create the owner with persistence: rehydrate the last saved snapshot if one exists, use
+ * the configured initial state otherwise, and save every commit from then on. Asynchronous
+ * because rehydration reads a file, and startup is the one place that wait belongs.
+ */
+export declare function restoreNativeOwner<State>(options: NativeOwnerOptions<State> & {
+    persistence: PersistenceOptions;
+}): Promise<NativeOwner<State>>;
+//# sourceMappingURL=owner-core.d.ts.map

package/dist/src/native/owner-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner-core.d.ts","sourceRoot":"","sources":["../../../src/native/owner-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAGzE,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE3E,+FAA+F;AAC/F,MAAM,MAAM,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;AAEjG,MAAM,WAAW,kBAAkB,CAAC,KAAK;IACvC,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,OAAO,EAAE,KAAK,CAAC;IACf,+CAA+C;IAE/C,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;IACzD,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,GAAG,eAAe,CAAC,CAAC;IAC3D,uEAAuE;IACvE,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW,CAAC,KAAK;IAChC,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,aAAa,GAAG,SAAS,CAAC;IAC9C,yDAAyD;IACzD,OAAO,IAAI,MAAM,CAAC;IAClB,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/D,iFAAiF;IACjF,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxD,KAAK,IAAI,IAAI,CAAC;CACf;AAID,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,kBAAkB,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAuD/F;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAC5C,OAAO,EAAE,kBAAkB,CAAC,KAAK,CAAC,GAAG;IAAE,WAAW,EAAE,kBAAkB,CAAA;CAAE,GACvE,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAQ7B"}

package/dist/src/native/owner-core.js

@@ -0,0 +1,83 @@
+/**
+ * The owner over the native transport, with no Electron import so it is testable in plain
+ * Node. The Electron glue in ./owner.js is a thin layer over this.
+ *
+ * The owner is the ordinary core OwnerStore writing a private SharedArrayBuffer, exactly as
+ * the worker-thread topology uses it. What this module adds is publication: after every
+ * commit, the arena bytes are flushed into the mapped region under the region's seqlock, so
+ * any process that syncs the region gets a consistent copy of a committed arena and decodes
+ * it with the untouched core reader.
+ *
+ * Growth is deliberately disabled: the region's size is fixed at creation, so the arena is
+ * created with maxByteLength equal to byteLength and a full arena raises ArenaFullError
+ * rather than growing past what readers mapped. A growable region is future work with a
+ * re-handshake, not a default.
+ */
+import { OwnerStore } from "@bradensbay/globals-core";
+import { OwnerRegion } from "@bradensbay/globals-shm";
+import { SnapshotStore } from "../persistence.js";
+const DEFAULT_BYTE_LENGTH = 1 << 20;
+export function createNativeOwner(options) {
+    const byteLength = options.byteLength ?? DEFAULT_BYTE_LENGTH;
+    const operations = options.operations ?? {};
+    const store = OwnerStore.create(options.initial, {
+        ...options.arena,
+        byteLength,
+        maxByteLength: byteLength,
+    });
+    const region = OwnerRegion.create(options.regionPath, store.buffer.byteLength);
+    // Whole-buffer flush per commit. The bump allocator makes dirty ranges cheap to compute
+    // and they are the planned refinement, but a megabyte costs about sixteen microseconds to
+    // publish, so correctness ships first.
+    const flush = () => region.flush(new Uint8Array(store.buffer));
+    // OwnerStore.create committed the initial state before anyone could subscribe.
+    flush();
+    const snapshots = options.snapshots;
+    const unsubscribe = store.subscribe(() => {
+        flush();
+        // The flush above published the bytes; this queues the debounced durable copy, which
+        // must never sit on the commit path.
+        snapshots?.save(store.snapshot().toJSON(), store.version);
+    });
+    return {
+        store,
+        regionPath: options.regionPath,
+        snapshots,
+        version: () => region.version(),
+        dispatch(operation, payload) {
+            const apply = operations[operation];
+            if (apply === undefined) {
+                return Promise.reject(new Error(`unknown operation "${operation}". The owner declares: ${Object.keys(operations).join(", ") || "none"}`));
+            }
+            // The store resolves with the arena's internal version, which is not the currency
+            // readers deal in: they see region commit counts. The flush subscriber has already
+            // run by the time update resolves, so the region version here includes this commit,
+            // and a caller can hand it to any reader meaningfully.
+            return store.update((draft) => apply(draft, payload)).then(() => region.version());
+        },
+        update(recipe) {
+            return store.update(recipe).then(() => region.version());
+        },
+        close() {
+            unsubscribe();
+            void snapshots?.flush();
+            store.close();
+            region.close();
+        },
+    };
+}
+/**
+ * Create the owner with persistence: rehydrate the last saved snapshot if one exists, use
+ * the configured initial state otherwise, and save every commit from then on. Asynchronous
+ * because rehydration reads a file, and startup is the one place that wait belongs.
+ */
+export async function restoreNativeOwner(options) {
+    const snapshots = new SnapshotStore(options.persistence);
+    const loaded = await snapshots.load();
+    return createNativeOwner({
+        ...options,
+        initial: (loaded?.value ?? options.initial),
+        snapshots,
+    });
+}
+//# sourceMappingURL=owner-core.js.map

package/dist/src/native/owner-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner-core.js","sourceRoot":"","sources":["../../../src/native/owner-core.ts"],"names":[],"mappings":"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"}

package/dist/src/native/owner.d.ts

@@ -0,0 +1,17 @@
+import type { PersistenceOptions } from "../persistence.js";
+import { type NativeOwner, type NativeOwnerOptions } from "./owner-core.js";
+export type { NativeOperation, NativeOwner, NativeOwnerOptions } from "./owner-core.js";
+export { asyncPreloadPath } from "./paths.js";
+export interface StartNativeOwnerOptions<State> extends Omit<NativeOwnerOptions<State>, "regionPath" | "snapshots"> {
+    /** Defaults to a file named globals.region under the app's userData directory. */
+    regionPath?: string;
+    /**
+     * Persist commits and rehydrate on start. The file defaults to globals.snapshot.json
+     * under the app's userData directory.
+     */
+    persistence?: Omit<PersistenceOptions, "file"> & {
+        file?: string;
+    };
+}
+export declare function startNativeOwner<State>(options: StartNativeOwnerOptions<State>): Promise<NativeOwner<State>>;
+//# sourceMappingURL=owner.d.ts.map

package/dist/src/native/owner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner.d.ts","sourceRoot":"","sources":["../../../src/native/owner.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACxB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,WAAW,uBAAuB,CAAC,KAAK,CAC5C,SAAQ,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,EAAE,YAAY,GAAG,WAAW,CAAC;IACnE,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACpE;AAOD,wBAAsB,gBAAgB,CAAC,KAAK,EAC1C,OAAO,EAAE,uBAAuB,CAAC,KAAK,CAAC,GACtC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CA+D7B"}

package/dist/src/native/owner.js

@@ -0,0 +1,78 @@
+/**
+ * The Electron glue for the native owner: main process only.
+ *
+ * The owner is a plain object in the main process. There is no hidden window, no privileged
+ * scheme, no isolation headers, and no handshake that hands a buffer to anyone: windows map
+ * the region file themselves from their preloads, and everything the main process owes them
+ * is the region's path and a content-free ping per commit.
+ */
+import { app, ipcMain } from "electron";
+import { join } from "node:path";
+import { COMMIT, DISPATCH, HELLO, READ } from "./channel.js";
+import { createNativeOwner, restoreNativeOwner, } from "./owner-core.js";
+export { asyncPreloadPath } from "./paths.js";
+function materialise(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    return JSON.parse(JSON.stringify(value));
+}
+export async function startNativeOwner(options) {
+    const regionPath = options.regionPath ?? join(app.getPath("userData"), "globals.region");
+    const owner = options.persistence
+        ? await restoreNativeOwner({
+            ...options,
+            regionPath,
+            persistence: {
+                file: join(app.getPath("userData"), "globals.snapshot.json"),
+                ...options.persistence,
+            },
+        })
+        : createNativeOwner({ ...options, regionPath });
+    const subscribers = new Set();
+    ipcMain.handle(HELLO, (event) => {
+        const sender = event.sender;
+        if (!subscribers.has(sender)) {
+            subscribers.add(sender);
+            sender.once("destroyed", () => subscribers.delete(sender));
+        }
+        return { regionPath, version: owner.version() };
+    });
+    ipcMain.handle(DISPATCH, (_event, message) => owner.dispatch(message.operation, message.payload));
+    // The asynchronous tier. The lazy view is a Proxy and structured clone refuses proxies,
+    // so what crosses the wire is materialised first. This path is for windows that keep
+    // their sandbox; it reads by request and pays a round trip, which is the documented trade.
+    ipcMain.handle(READ, (_event, message) => {
+        const value = message?.path === undefined
+            ? owner.store.snapshot().toJSON()
+            : materialise(owner.store.select(message.path));
+        return { version: owner.version(), value };
+    });
+    // The flush subscriber inside createNativeOwner registered first, so by the time this
+    // runs the commit is already in the region and the ping cannot arrive ahead of the bytes.
+    const unsubscribe = owner.store.subscribe(() => {
+        const version = owner.version();
+        for (const sender of subscribers) {
+            if (!sender.isDestroyed())
+                sender.send(COMMIT, version);
+        }
+    });
+    // A debounced snapshot that never gets its final write is a stale rehydrate next boot.
+    const onQuit = () => {
+        void owner.snapshots?.flush();
+    };
+    if (owner.snapshots)
+        app.on("before-quit", onQuit);
+    return {
+        ...owner,
+        close() {
+            unsubscribe();
+            app.removeListener("before-quit", onQuit);
+            ipcMain.removeHandler(HELLO);
+            ipcMain.removeHandler(DISPATCH);
+            ipcMain.removeHandler(READ);
+            subscribers.clear();
+            owner.close();
+        },
+    };
+}
+//# sourceMappingURL=owner.js.map

package/dist/src/native/owner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner.js","sourceRoot":"","sources":["../../../src/native/owner.ts"],"names":[],"mappings":"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"}

package/dist/src/native/paths.d.ts

@@ -0,0 +1,3 @@
+/** The shipped preload for the asynchronous tier: sandboxed windows that read by asking. */
+export declare function asyncPreloadPath(): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/src/native/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/native/paths.ts"],"names":[],"mappings":"AAOA,4FAA4F;AAC5F,wBAAgB,gBAAgB,IAAI,MAAM,CAGzC"}

package/dist/src/native/paths.js

@@ -0,0 +1,12 @@
+/**
+ * Filesystem locations the main process needs to hand to webPreferences. A module rather
+ * than a constant, because the path is only knowable relative to the installed package.
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+/** The shipped preload for the asynchronous tier: sandboxed windows that read by asking. */
+export function asyncPreloadPath() {
+    // dist/src/native/paths.js sits three directories below the package root.
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "preload-async.cjs");
+}
+//# sourceMappingURL=paths.js.map

package/dist/src/native/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/native/paths.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,4FAA4F;AAC5F,MAAM,UAAU,gBAAgB;IAC9B,0EAA0E;IAC1E,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,mBAAmB,CAAC,CAAC;AAC9F,CAAC"}

package/dist/src/native/reader-core.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The reading side over the native transport, with no Electron import. The preload glue in
+ * ./renderer.js is a thin layer over this.
+ *
+ * The read path: one native version check per read; when the region moved, one
+ * seqlock-consistent copy into a fresh private buffer, and the untouched core reader decodes
+ * that. A read can never observe a stale version and never a torn one. A snapshot pins the
+ * buffer it was taken from: superseded buffers stay alive exactly as long as something still
+ * reads them, and ordinary garbage collection is the whole reclamation story. Nothing here
+ * writes shared memory, and cross process epochs do not exist to manage.
+ */
+import { type ReadableStore, type Snapshot } from "@bradensbay/globals-core";
+export declare class NativeReaderSource implements ReadableStore {
+    #private;
+    private constructor();
+    static attach(regionPath: string): NativeReaderSource;
+    /** The live region version, one native call. */
+    get version(): number;
+    get(): unknown;
+    select(path: readonly (string | number)[]): unknown;
+    snapshot(): Snapshot;
+    subscribe(listener: () => void): () => void;
+    /**
+     * Tell the source a commit happened. The integration calls this off a notification
+     * message; nothing on the read path depends on it, it only drives rerenders.
+     */
+    notify(): void;
+    close(): void;
+}
+//# sourceMappingURL=reader-core.d.ts.map

package/dist/src/native/reader-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader-core.d.ts","sourceRoot":"","sources":["../../../src/native/reader-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAe,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAG1F,qBAAa,kBAAmB,YAAW,aAAa;;IAOtD,OAAO,eAEN;IAED,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,CAEpD;IAED,gDAAgD;IAChD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,GAAG,IAAI,OAAO,CAEb;IAED,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,OAAO,CAElD;IAED,QAAQ,IAAI,QAAQ,CAEnB;IAED,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG1C;IAED;;;OAGG;IACH,MAAM,IAAI,IAAI,CAKb;IAED,KAAK,IAAI,IAAI,CAIZ;CAsBF"}

package/dist/src/native/reader-core.js

@@ -0,0 +1,81 @@
+/**
+ * The reading side over the native transport, with no Electron import. The preload glue in
+ * ./renderer.js is a thin layer over this.
+ *
+ * The read path: one native version check per read; when the region moved, one
+ * seqlock-consistent copy into a fresh private buffer, and the untouched core reader decodes
+ * that. A read can never observe a stale version and never a torn one. A snapshot pins the
+ * buffer it was taken from: superseded buffers stay alive exactly as long as something still
+ * reads them, and ordinary garbage collection is the whole reclamation story. Nothing here
+ * writes shared memory, and cross process epochs do not exist to manage.
+ */
+import { ReaderStore } from "@bradensbay/globals-core";
+import { ReaderRegion } from "@bradensbay/globals-shm";
+export class NativeReaderSource {
+    #region;
+    #held = 0;
+    #store = null;
+    #notified = 0;
+    #listeners = new Set();
+    constructor(region) {
+        this.#region = region;
+    }
+    static attach(regionPath) {
+        return new NativeReaderSource(ReaderRegion.attach(regionPath));
+    }
+    /** The live region version, one native call. */
+    get version() {
+        return this.#region.version();
+    }
+    get() {
+        return this.#ensure().get();
+    }
+    select(path) {
+        return this.#ensure().select(path);
+    }
+    snapshot() {
+        return this.#ensure().snapshot();
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    /**
+     * Tell the source a commit happened. The integration calls this off a notification
+     * message; nothing on the read path depends on it, it only drives rerenders.
+     */
+    notify() {
+        const version = this.#region.version();
+        if (version === this.#notified)
+            return;
+        this.#notified = version;
+        for (const listener of this.#listeners)
+            listener();
+    }
+    close() {
+        this.#region.close();
+        this.#store = null;
+        this.#listeners.clear();
+    }
+    #ensure() {
+        const version = this.#region.version();
+        if (version === 0) {
+            throw new Error("the region holds no commit yet: the owner has not flushed");
+        }
+        if (this.#store === null || version !== this.#held) {
+            // A fresh private buffer per observed commit. The previous store is dropped, not
+            // closed: snapshots taken from it keep their buffer alive until they are collected.
+            //
+            // A plain ArrayBuffer, deliberately. Blink hides the SharedArrayBuffer constructor
+            // from a renderer that is not cross origin isolated, unsandboxed preloads included,
+            // and nothing here needs sharing: the buffer is this process's private copy. Atomics
+            // operate on non-shared buffers, and the read path never waits, so the core reader
+            // works unchanged; only its declared type expects the shared flavour.
+            const copy = new ArrayBuffer(this.#region.dataSize);
+            this.#held = this.#region.sync(new Uint8Array(copy));
+            this.#store = new ReaderStore(copy);
+        }
+        return this.#store;
+    }
+}
+//# sourceMappingURL=reader-core.js.map

package/dist/src/native/reader-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader-core.js","sourceRoot":"","sources":["../../../src/native/reader-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,WAAW,EAAqC,MAAM,0BAA0B,CAAC;AAC1F,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD,MAAM,OAAO,kBAAkB;IAC7B,OAAO,CAAe;IACtB,KAAK,GAAG,CAAC,CAAC;IACV,MAAM,GAAuB,IAAI,CAAC;IAClC,SAAS,GAAG,CAAC,CAAC;IACL,UAAU,GAAG,IAAI,GAAG,EAAc,CAAC;IAE5C,YAAoB,MAAoB;QACtC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,MAAM,CAAC,MAAM,CAAC,UAAkB;QAC9B,OAAO,IAAI,kBAAkB,CAAC,YAAY,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IACjE,CAAC;IAED,gDAAgD;IAChD,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAChC,CAAC;IAED,GAAG;QACD,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC;IAC9B,CAAC;IAED,MAAM,CAAC,IAAkC;QACvC,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC;IACnC,CAAC;IAED,SAAS,CAAC,QAAoB;QAC5B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9B,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChD,CAAC;IAED;;;OAGG;IACH,MAAM;QACJ,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACvC,IAAI,OAAO,KAAK,IAAI,CAAC,SAAS;YAAE,OAAO;QACvC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC;QACzB,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,UAAU;YAAE,QAAQ,EAAE,CAAC;IACrD,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;IAED,OAAO;QACL,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACvC,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;QAC/E,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YACnD,iFAAiF;YACjF,oFAAoF;YACpF,EAAE;YACF,mFAAmF;YACnF,oFAAoF;YACpF,qFAAqF;YACrF,mFAAmF;YACnF,sEAAsE;YACtE,MAAM,IAAI,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACpD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;YACrD,IAAI,CAAC,MAAM,GAAG,IAAI,WAAW,CAAC,IAAoC,CAAC,CAAC;QACtE,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF"}

package/dist/src/native/renderer.d.ts

@@ -0,0 +1,9 @@
+import type { ReadableStore } from "@bradensbay/globals-core";
+export type { NativeReaderSource } from "./reader-core.js";
+export interface NativeConnection extends ReadableStore {
+    /** Ask the owner to apply a named operation. Resolves with the committed version. */
+    dispatch(operation: string, payload?: unknown): Promise<number>;
+    close(): void;
+}
+export declare function connectNative(): Promise<NativeConnection>;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/src/native/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../../src/native/renderer.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,0BAA0B,CAAC;AAIxE,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,qFAAqF;IACrF,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAsB,aAAa,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAqB/D"}

package/dist/src/native/renderer.js

@@ -0,0 +1,32 @@
+/**
+ * The preload side of the native transport.
+ *
+ * This module runs in a preload with sandbox: false and context isolation on: a Node
+ * context that can load the addon, in a window whose page cannot. The decode layer lives
+ * here on purpose, because every contextBridge crossing costs about a microsecond; expose
+ * whole operations to the page, not per-property reads.
+ */
+import { ipcRenderer } from "electron";
+import { COMMIT, DISPATCH, HELLO } from "./channel.js";
+import { NativeReaderSource } from "./reader-core.js";
+export async function connectNative() {
+    const hello = (await ipcRenderer.invoke(HELLO));
+    const source = NativeReaderSource.attach(hello.regionPath);
+    const onCommit = () => source.notify();
+    ipcRenderer.on(COMMIT, onCommit);
+    return {
+        get: () => source.get(),
+        select: (path) => source.select(path),
+        snapshot: () => source.snapshot(),
+        subscribe: (listener) => source.subscribe(listener),
+        get version() {
+            return source.version;
+        },
+        dispatch: (operation, payload) => ipcRenderer.invoke(DISPATCH, { operation, payload }),
+        close() {
+            ipcRenderer.removeListener(COMMIT, onCommit);
+            source.close();
+        },
+    };
+}
+//# sourceMappingURL=renderer.js.map

package/dist/src/native/renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.js","sourceRoot":"","sources":["../../../src/native/renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAGvC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAc,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAUtD,MAAM,CAAC,KAAK,UAAU,aAAa;IACjC,MAAM,KAAK,GAAG,CAAC,MAAM,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAU,CAAC;IACzD,MAAM,MAAM,GAAG,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,GAAS,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;IAC7C,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAEjC,OAAO;QACL,GAAG,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE;QACvB,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;QACrC,QAAQ,EAAE,GAAa,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE;QAC3C,SAAS,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC;QACnD,IAAI,OAAO;YACT,OAAO,MAAM,CAAC,OAAO,CAAC;QACxB,CAAC;QACD,QAAQ,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,CAC/B,WAAW,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,CAAoB;QACzE,KAAK;YACH,WAAW,CAAC,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YAC7C,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/paths.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Serving logic with no Electron import in it.
+ *
+ * Kept separate for a practical reason. Outside an Electron process the `electron` module is
+ * a shim whose only export is the path to the binary, so anything that imports it cannot be
+ * loaded by a plain Node test runner. Putting the path resolution here means the security
+ * relevant part of serving files can be tested directly, which is worth more than keeping it
+ * next to the code that calls it.
+ */
+export declare const DEFAULT_SCHEME = "globals-app";
+/** The headers that make `crossOriginIsolated` true. */
+export declare const ISOLATION_HEADERS: {
+    readonly "cross-origin-opener-policy": "same-origin";
+    readonly "cross-origin-embedder-policy": "require-corp";
+    readonly "cross-origin-resource-policy": "same-origin";
+};
+export declare const MIME: Record<string, string>;
+/**
+ * Turn a request pathname into a file inside the served root, or undefined when it escapes.
+ *
+ * A traversal that reaches outside the root is not a missing file, it is a hole, so the
+ * segments are filtered after decoding and the result is checked against the root again.
+ *
+ * The rule that catches application authors is the ordinary one: **a page can only import
+ * what the served root contains.** An import that climbs above the root with `..` never
+ * reaches the filesystem above it, because the browser resolves the specifier against the
+ * scheme origin first and the climb is already collapsed by the time the request arrives.
+ * Serve a root that contains everything the pages import.
+ */
+export declare function resolveRequestPath(root: string, pathname: string, index: string): string | undefined;
+/** The URL a window should load for a page under the served root. */
+export declare function pageUrl(page: string, scheme?: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/src/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/paths.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,eAAO,MAAM,cAAc,gBAAgB,CAAC;AAE5C,wDAAwD;AACxD,eAAO,MAAM,iBAAiB;aAC5B,4BAA4B,EAAE,aAAa;aAC3C,8BAA8B,EAAE,cAAc;aAC9C,8BAA8B,EAAE,aAAa;CACrC,CAAC;AAEX,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAevC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,SAAS,CAYpB;AAED,qEAAqE;AACrE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAuB,GAAG,MAAM,CAE7E"}

package/dist/src/paths.js

@@ -0,0 +1,60 @@
+import { join, normalize, sep } from "node:path";
+/**
+ * Serving logic with no Electron import in it.
+ *
+ * Kept separate for a practical reason. Outside an Electron process the `electron` module is
+ * a shim whose only export is the path to the binary, so anything that imports it cannot be
+ * loaded by a plain Node test runner. Putting the path resolution here means the security
+ * relevant part of serving files can be tested directly, which is worth more than keeping it
+ * next to the code that calls it.
+ */
+export const DEFAULT_SCHEME = "globals-app";
+/** The headers that make `crossOriginIsolated` true. */
+export const ISOLATION_HEADERS = {
+    "cross-origin-opener-policy": "same-origin",
+    "cross-origin-embedder-policy": "require-corp",
+    "cross-origin-resource-policy": "same-origin",
+};
+export const MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".map": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+};
+/**
+ * Turn a request pathname into a file inside the served root, or undefined when it escapes.
+ *
+ * A traversal that reaches outside the root is not a missing file, it is a hole, so the
+ * segments are filtered after decoding and the result is checked against the root again.
+ *
+ * The rule that catches application authors is the ordinary one: **a page can only import
+ * what the served root contains.** An import that climbs above the root with `..` never
+ * reaches the filesystem above it, because the browser resolves the specifier against the
+ * scheme origin first and the climb is already collapsed by the time the request arrives.
+ * Serve a root that contains everything the pages import.
+ */
+export function resolveRequestPath(root, pathname, index) {
+    const normalisedRoot = normalize(root);
+    const segments = decodeURIComponent(pathname)
+        .split("/")
+        .filter((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+    const file = normalize(segments.length === 0 ? join(normalisedRoot, index) : join(normalisedRoot, ...segments));
+    if (file !== normalisedRoot && !file.startsWith(normalisedRoot + sep))
+        return undefined;
+    return file;
+}
+/** The URL a window should load for a page under the served root. */
+export function pageUrl(page, scheme = DEFAULT_SCHEME) {
+    return `${scheme}://app/${page.replace(/^\/+/u, "")}`;
+}
+//# sourceMappingURL=paths.js.map

package/dist/src/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEjD;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAC;AAE5C,wDAAwD;AACxD,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,4BAA4B,EAAE,aAAa;IAC3C,8BAA8B,EAAE,cAAc;IAC9C,8BAA8B,EAAE,aAAa;CACrC,CAAC;AAEX,MAAM,CAAC,MAAM,IAAI,GAA2B;IAC1C,OAAO,EAAE,0BAA0B;IACnC,KAAK,EAAE,gCAAgC;IACvC,MAAM,EAAE,gCAAgC;IACxC,MAAM,EAAE,yBAAyB;IACjC,OAAO,EAAE,iCAAiC;IAC1C,MAAM,EAAE,iCAAiC;IACzC,MAAM,EAAE,eAAe;IACvB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,OAAO,EAAE,YAAY;IACrB,OAAO,EAAE,WAAW;IACpB,QAAQ,EAAE,YAAY;CACvB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAY,EACZ,QAAgB,EAChB,KAAa;IAEb,MAAM,cAAc,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,kBAAkB,CAAC,QAAQ,CAAC;SAC1C,KAAK,CAAC,GAAG,CAAC;SACV,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,IAAI,CAAC,CAAC;IAElF,MAAM,IAAI,GAAG,SAAS,CACpB,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,EAAE,GAAG,QAAQ,CAAC,CACxF,CAAC;IAEF,IAAI,IAAI,KAAK,cAAc,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,cAAc,GAAG,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACxF,OAAO,IAAI,CAAC;AACd,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,MAAM,GAAW,cAAc;IACnE,OAAO,GAAG,MAAM,UAAU,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC;AACxD,CAAC"}

package/dist/src/persistence.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Persistence.
+ *
+ * A hook on commit and a rehydrate path on boot, with the temp file and rename discipline
+ * that makes a crash mid write leave either the old file or the new one, never half of
+ * either.
+ *
+ * Writes are debounced and coalesced. A store committing a thousand times a second must not
+ * produce a thousand disk writes, and the last one is the only one that matters.
+ */
+export interface PersistenceOptions {
+    /** Where the snapshot lives. The directory is created if it does not exist. */
+    file: string;
+    /** Milliseconds to wait for further commits before writing. */
+    debounceMs?: number;
+    /** Serialise. Defaults to JSON with a version envelope. */
+    serialise?: (value: unknown, version: number) => string;
+    /** Parse. Defaults to the matching JSON envelope reader. */
+    deserialise?: (text: string) => {
+        value: unknown;
+        version: number;
+    } | undefined;
+    /** Called when a write or a read fails. Persistence must never take the app down. */
+    onError?: (error: unknown, phase: "load" | "save") => void;
+}
+export declare class SnapshotStore {
+    #private;
+    constructor(options: PersistenceOptions);
+    get writeCount(): number;
+    /**
+     * Read the persisted value.
+     *
+     * A missing file is not an error: a first run has nothing to rehydrate. A corrupt file is
+     * reported through onError and treated as missing, because refusing to start is a worse
+     * outcome than starting empty.
+     */
+    load(): Promise<{
+        value: unknown;
+        version: number;
+    } | undefined>;
+    /** Queue a save. Coalesces with any save already queued. */
+    save(value: unknown, version: number): void;
+    /** Write whatever is queued now. Called on quit, and by tests. */
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=persistence.d.ts.map

package/dist/src/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../src/persistence.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACxD,4DAA4D;IAC5D,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAChF,qFAAqF;IACrF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,KAAK,IAAI,CAAC;CAC5D;AAyBD,qBAAa,aAAa;;IAQxB,YAAY,OAAO,EAAE,kBAAkB,EAEtC;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAUrE;IAED,4DAA4D;IAC5D,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAQ1C;IAED,kEAAkE;IAClE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAarB;CAwBF"}

package/dist/src/persistence.js

@@ -0,0 +1,100 @@
+import { readFile, rename, writeFile, mkdir, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+function defaultSerialise(value, version) {
+    const envelope = {
+        format: 1,
+        savedAt: new Date().toISOString(),
+        version,
+        value,
+    };
+    return JSON.stringify(envelope);
+}
+function defaultDeserialise(text) {
+    const parsed = JSON.parse(text);
+    if (parsed === null || typeof parsed !== "object" || parsed.format !== 1)
+        return undefined;
+    return { value: parsed.value, version: typeof parsed.version === "number" ? parsed.version : 0 };
+}
+export class SnapshotStore {
+    #options;
+    #timer;
+    #pending;
+    #writing = Promise.resolve();
+    #writes = 0;
+    constructor(options) {
+        this.#options = { debounceMs: 250, ...options };
+    }
+    get writeCount() {
+        return this.#writes;
+    }
+    /**
+     * Read the persisted value.
+     *
+     * A missing file is not an error: a first run has nothing to rehydrate. A corrupt file is
+     * reported through onError and treated as missing, because refusing to start is a worse
+     * outcome than starting empty.
+     */
+    async load() {
+        try {
+            const text = await readFile(this.#options.file, "utf8");
+            const parse = this.#options.deserialise ?? defaultDeserialise;
+            return parse(text);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "ENOENT")
+                this.#options.onError?.(error, "load");
+            return undefined;
+        }
+    }
+    /** Queue a save. Coalesces with any save already queued. */
+    save(value, version) {
+        this.#pending = { value, version };
+        if (this.#timer !== undefined)
+            return;
+        this.#timer = setTimeout(() => {
+            this.#timer = undefined;
+            void this.flush();
+        }, this.#options.debounceMs);
+        this.#timer.unref?.();
+    }
+    /** Write whatever is queued now. Called on quit, and by tests. */
+    flush() {
+        if (this.#timer !== undefined) {
+            clearTimeout(this.#timer);
+            this.#timer = undefined;
+        }
+        const pending = this.#pending;
+        this.#pending = undefined;
+        if (pending === undefined)
+            return this.#writing;
+        // Serialise writes against each other. Two overlapping renames onto the same path is a
+        // race with no upside.
+        this.#writing = this.#writing.then(() => this.#write(pending.value, pending.version));
+        return this.#writing;
+    }
+    async #write(value, version) {
+        const serialise = this.#options.serialise ?? defaultSerialise;
+        const target = this.#options.file;
+        // The temp file sits beside the target so the rename stays on one filesystem. A rename
+        // across devices is a copy, and a copy is not atomic.
+        const temporary = join(dirname(target), `.${version}.${process.pid}.tmp`);
+        try {
+            await mkdir(dirname(target), { recursive: true });
+            await writeFile(temporary, serialise(value, version), "utf8");
+            await rename(temporary, target);
+            this.#writes += 1;
+        }
+        catch (error) {
+            this.#options.onError?.(error, "save");
+            try {
+                await unlink(temporary);
+            }
+            catch {
+                // The temp file may not exist, which is the common case when writeFile is what
+                // failed. Nothing to report.
+            }
+        }
+    }
+}
+//# sourceMappingURL=persistence.js.map

package/dist/src/persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../src/persistence.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@bradensbay/globals",
+  "version": "0.2.0",
+  "description": "Electron integration over the native transport: the owner in the main process, preload-mapped regions for trusted windows, and the asynchronous tier for windows that keep their sandbox.",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./preload": {
+      "types": "./dist/src/native/renderer.d.ts",
+      "import": "./dist/src/native/renderer.js"
+    }
+  },
+  "files": [
+    "dist/src",
+    "preload-async.cjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "dependencies": {
+    "@bradensbay/globals-core": "0.2.0",
+    "@bradensbay/globals-shm": "0.2.0"
+  },
+  "peerDependencies": {
+    "electron": ">=28 <35"
+  },
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/christianGRogers/globals.git",
+    "directory": "packages/electron"
+  }
+}

package/preload-async.cjs

@@ -0,0 +1,56 @@
+// The asynchronous tier's preload, for windows that keep their sandbox.
+//
+// A sandboxed preload is CommonJS with a require that reaches only "electron", so this file
+// is self contained and the channel names are literals; src/native/channel.ts is the other
+// copy, and the comment there points back here. Nothing in this file maps the region or
+// loads native code: a sandboxed window reads by asking the owner, which is the documented
+// trade for keeping the Chromium sandbox.
+//
+// What the page gets is deliberately small and visibly asynchronous. There is no get() at
+// all: a synchronous read does not exist on this tier, and an API that pretended otherwise
+// would be the exact confusion the type system elsewhere works to prevent.
+const { contextBridge, ipcRenderer } = require("electron");
+
+const HELLO = "globals:native:hello";
+const DISPATCH = "globals:native:dispatch";
+const COMMIT = "globals:native:commit";
+const READ = "globals:native:read";
+
+// Subscribing early means the first commit ping can arrive before the page even asks.
+const hello = ipcRenderer.invoke(HELLO);
+
+const listeners = new Set();
+ipcRenderer.on(COMMIT, (_event, version) => {
+  for (const listener of listeners) {
+    try {
+      listener(version);
+    } catch {
+      // A throwing page listener must not take the bridge down.
+    }
+  }
+});
+
+contextBridge.exposeInMainWorld("globalsAsync", {
+  tier: "async",
+
+  /** Resolves with { version, value }: the whole state, or one path of it. */
+  read(path) {
+    return ipcRenderer.invoke(READ, path === undefined ? undefined : { path });
+  },
+
+  /** Ask the owner to apply a named operation. Resolves with the committed version. */
+  dispatch(operation, payload) {
+    return ipcRenderer.invoke(DISPATCH, { operation, payload });
+  },
+
+  /** Called with the new version after every commit. Returns an unsubscribe function. */
+  subscribe(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  },
+
+  /** Resolves once the connection to the owner exists. */
+  ready() {
+    return hello.then((h) => h.version);
+  },
+});