esoul-sdk 0.25.0 → 0.25.2

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 Releases before 0.20.0 are recorded in the repository history only.
 
+**Versions say whether an app must change** (from the release after 0.25.0). A *breaking* release
+moves the leftmost non-zero number (0.25.x → 0.26.0; after 1.0, 1.x → 2.0.0) and lists every change under
+`### Breaking`: one bullet per API, the API in backticks first, then what an app must do. Every
+other release — features, fixes — moves the last number. The Forge reads this: a compatible update
+is offered with one Update button; a breaking one is reviewed by the agent against the app before
+anything is installed. The release check refuses a version that does not match its notes
+(src/lib/forge/release-notes.pure.ts).
+
+## 0.25.2
+
+### Added
+
+- `EventDefinition.resolveConcurrent(state, eventData, { theirsSess })`: an event that writes a PATCH (sub-items with the version each built on — a CAD edit's per-node sets with their bases, a notes page's paragraphs) merges a concurrent write itself before it becomes a conflict. Called by the fence only when the write would land as a conflict; returns the rewritten event, with `detail` naming what could not be merged (kept on the conflict marker for the app's own resolution UI), or `null` to keep the plain conflict. The hook block notes merges paragraphs with, now declarable by any SDK app (docs/17 §4).
+
+## 0.25.1
+
+### Added
+
+- `headlessBridge(ctx, { url, boot, calls, viewport })` (esoul-sdk/server): a web page opened in a
+  headless browser ON THE PLATFORM and driven over `postMessage`, for an app whose engine only
+  exists as a page (a WebAssembly CAD kernel, a canvas renderer). The person's open tab is one
+  place such a page can run; this is the other — on Vercel, with nobody's tab open, so an agent on
+  a phone or over MCP gets the same work done. The page is loaded top-level and is its own
+  `parent`, so an iframe bridge answers unchanged; the browser and the loaded page stay warm on the
+  platform between calls for the same url (the first call pays the launch, later ones only the
+  calls). `url` must be https and public; at most 32 calls; a Forge box has no browser, so there
+  the call throws and says so (docs/06-server.md, "The headless bridge").
+
 ## 0.25.0
 
 ### Added

package/api-reference.md

@@ -1812,6 +1812,11 @@ interface EventDefinition<StateType extends ApplicationIdentifier> {
   conflictScope?: (eventData: any) => string[] | null | undefined;
   merge?: MergeDescription;
   baseMerge?: BaseMerge;
+  resolveConcurrent?: (
+    state: any,
+    eventData: any,
+    ctx: { theirsSess: string | null },
+  ) => { eventData: any; detail?: unknown } | null;
 }
 ```
 
@@ -2515,11 +2520,11 @@ interface UsesDecl {
 ```
 
 ==============================================================================
-## `esoul-sdk/server` — 115 exports
+## `esoul-sdk/server` — 119 exports
 
 Server code only (server.ts, ops, routes, tasks): the viewer, the app's database, files, connections, machines, charts, route tokens.
 
-### Functions and values (36)
+### Functions and values (37)
 
 #### `APPROVAL_WAIT` — const · src/computer.ts
 
@@ -2617,6 +2622,14 @@ Read the sealed credentials of a plugin-declared connection (auto- refreshes exp
 function getPluginConnectionCredentials( _connectionId: string, _pluginId: string, ): Promise<PluginConnectionCredentials>
 ```
 
+#### `headlessBridge` — function · src/server.ts
+
+Run a web page in the platform's headless browser and drive it over `postMessage` — see the `HeadlessBridgeArgs` note above: `url` (https, public), `boot` (the page's ready message), `calls` (each posted to the page's window, answered by the first message whose `[replyField]` equals its `id`). Warm between calls for the same url; not available in a Forge box.
+
+```ts
+function headlessBridge(_ctx: { pluginId: string; nodeId: string; origin?: string }, _args: HeadlessBridgeArgs): Promise<HeadlessBridgeResult>
+```
+
 #### `isCredentialUnavailable` — function · src/server.ts
 
 True for a `CredentialUnavailable`, also across bundle boundaries where `instanceof` fails.
@@ -2809,7 +2822,7 @@ WHO IS THIS, IN WORDS. The caller's own name and email, for an app with a reason
 function viewerProfile(_viewer: PluginViewer): Promise<ViewerProfile | null>
 ```
 
-### Types (79)
+### Types (82)
 
 #### `AppQuestion` — interface · src/server.ts
 
@@ -3304,6 +3317,41 @@ interface GeneratedAppImage {
 }
 ```
 
+#### `HeadlessBridgeArgs` — interface · src/server.ts
+
+```ts
+interface HeadlessBridgeArgs {
+  url: string;
+  boot?: { field: string; oneOf: string[]; timeoutMs?: number };
+  calls: HeadlessBridgeCall[];
+  viewport?: { width: number; height: number };
+}
+```
+
+#### `HeadlessBridgeCall` — interface · src/server.ts
+
+The headless bridge — a page opened in a headless browser ON THE PLATFORM and driven over `postMessage`, for an app whose engine only exists as a web page (a WebAssembly CAD kernel, a canvas renderer). "No computer should be required": the person's tab is one place the page can run; this is the other, on Vercel, with nobody's tab open.
+
+```ts
+interface HeadlessBridgeCall {
+  id: string;
+  message: Record<string, unknown>;
+  replyField?: string;
+  timeoutMs?: number;
+}
+```
+
+#### `HeadlessBridgeResult` — interface · src/server.ts
+
+```ts
+interface HeadlessBridgeResult {
+  boot: Record<string, unknown> | null;
+  replies: (Record<string, unknown> | null)[];
+  timings: Record<string, number>;
+  warm: boolean;
+}
+```
+
 #### `JsonOutcome` — interface · src/computer.ts
 
 Flat, like every outcome here. `ok` with `json`; otherwise `error` in words.

package/dist/server.d.ts

@@ -681,6 +681,56 @@ export declare function mintRouteToken(_ctx: {
     ttlSeconds?: number;
     label?: string;
 }): Promise<RouteTokenGrant>;
+/**
+ * The headless bridge — a page opened in a headless browser ON THE PLATFORM and driven over
+ * `postMessage`, for an app whose engine only exists as a web page (a WebAssembly CAD kernel, a
+ * canvas renderer). "No computer should be required": the person's tab is one place the page
+ * can run; this is the other, on Vercel, with nobody's tab open.
+ *
+ * `url` must be https and public. The page is loaded top-level, so it is its own `parent`: a
+ * bridge written for an iframe (`?parent=<origin>` + `window.parent.postMessage`) answers
+ * unchanged when the url names the page's own origin as the parent. `boot` waits for the page's
+ * ready message; each call posts `message` to the page's window and returns the first message
+ * whose `[replyField]` (default "id") equals the call's `id`. The page stays warm on the platform
+ * between calls for the same url — the first call pays the launch, later ones only the calls.
+ * Not available in a Forge preview (the box has no browser): keep the app open there instead.
+ */
+export interface HeadlessBridgeCall {
+    id: string;
+    message: Record<string, unknown>;
+    replyField?: string;
+    timeoutMs?: number;
+}
+export interface HeadlessBridgeArgs {
+    url: string;
+    boot?: {
+        field: string;
+        oneOf: string[];
+        timeoutMs?: number;
+    };
+    calls: HeadlessBridgeCall[];
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+export interface HeadlessBridgeResult {
+    boot: Record<string, unknown> | null;
+    replies: (Record<string, unknown> | null)[];
+    timings: Record<string, number>;
+    warm: boolean;
+}
+/**
+ * Run a web page in the platform's headless browser and drive it over `postMessage` — see the
+ * `HeadlessBridgeArgs` note above: `url` (https, public), `boot` (the page's ready message),
+ * `calls` (each posted to the page's window, answered by the first message whose `[replyField]`
+ * equals its `id`). Warm between calls for the same url; not available in a Forge box.
+ */
+export declare function headlessBridge(_ctx: {
+    pluginId: string;
+    nodeId: string;
+    origin?: string;
+}, _args: HeadlessBridgeArgs): Promise<HeadlessBridgeResult>;
 /** A question for the person (questions(ctx).ask). */
 export interface AppQuestion {
     /** Stable per question within this app instance: asking twice with one key is one question. */

package/dist/server.js

@@ -266,6 +266,15 @@ export function renderChartImage(_ctx, _args) {
 export function mintRouteToken(_ctx, _args) {
     return hostOnly("mintRouteToken");
 }
+/**
+ * Run a web page in the platform's headless browser and drive it over `postMessage` — see the
+ * `HeadlessBridgeArgs` note above: `url` (https, public), `boot` (the page's ready message),
+ * `calls` (each posted to the page's window, answered by the first message whose `[replyField]`
+ * equals its `id`). Warm between calls for the same url; not available in a Forge box.
+ */
+export function headlessBridge(_ctx, _args) {
+    return hostOnly("headlessBridge");
+}
 /**
  * THE PLATFORM'S QUESTIONS BELL. A question an app needs the person to answer
  * (an agent waiting on a decision) reaches them wherever they are — the bell,

package/dist/types.d.ts

@@ -140,6 +140,21 @@ export interface EventDefinition<StateType extends ApplicationIdentifier> {
      * back to the normal conflict record. Pure. See docs/17-editing-and-merging.md.
      */
     baseMerge?: BaseMerge;
+    /**
+     * MERGE A CONCURRENT WRITE BEFORE IT BECOMES A CONFLICT. Called by the fence only when this event would be
+     * applied as a conflict — the sub-items it writes (`merge.scope`) were changed by a writer it never saw. The
+     * event knows its data: it merges what it can against the base it carries and the state it lands on, and
+     * returns the rewritten event. `detail` undefined → everything merged, no conflict marker; `detail` set → what
+     * could not be merged, stored on the marker for the resolution UI (the app's own shape); `null` → cannot reason
+     * about it (the plain conflict stands: applied and marked). Pure and deterministic — it runs in every fold.
+     * See docs/17-editing-and-merging.md §4.
+     */
+    resolveConcurrent?: (state: any, eventData: any, ctx: {
+        theirsSess: string | null;
+    }) => {
+        eventData: any;
+        detail?: unknown;
+    } | null;
 }
 export interface BaseMerge<V = any> {
     /** The value this event writes, as the state holds it right now (theirs). `undefined` → nothing to merge. */

package/docs/06-server.md

@@ -313,3 +313,31 @@ your own nodeId) for your timeline; a route context has no `emit` of its own.
 the example stops streaming — nothing durable happened unless the handler wrote events. A
 task (docs/07) survives everything and costs seconds per hop. The stopwatch ships both and
 records which one drove each run; measure before you choose.
+
+## The headless bridge — a browser on the platform, for a page-shaped engine
+
+Some engines exist only as a web page: a WebAssembly CAD kernel, a canvas renderer. The
+person's open tab can run it; `headlessBridge(ctx, …)` runs it on the platform too, so an agent
+with nobody's tab open (a phone with the app closed, an agent network, MCP) gets the same work
+done — no computer of the person's involved.
+
+```ts
+import { headlessBridge } from "esoul-sdk/server";
+
+const r = await headlessBridge(ctx, {
+  url: "https://my-runtime.example/page.html?parent=https%3A%2F%2Fmy-runtime.example",
+  boot: { field: "type", oneOf: ["ready", "error"] },            // the page's own ready message
+  calls: [{ id: "replay", message: { myBridge: 1, id: "replay", method: "replay", args: { … } } }],
+});
+r.boot;            // the ready message
+r.replies[0];      // the first message whose `id` equals "replay"
+r.timings;         // launchMs / bootMs (cold only), per-call ms, totalMs
+r.warm;            // true when the page was already open on the platform
+```
+
+The page is loaded top-level, so it is its own `parent`: a bridge written for an iframe answers
+unchanged when `?parent=` names the page's own origin. The browser and the loaded page stay warm
+on the platform between calls for the same url; the first call pays the launch and the page's
+download, later calls only the calls. `url` must be https and public; at most 32 calls; replies
+up to 24 MB. A Forge box has no browser: there the call throws and says so — keep the app open
+in the preview and let the tab do the work.

package/docs/17-editing-and-merging.md

@@ -153,3 +153,25 @@ recorded as a conflict. `baseMerge` runs in every fold: keep it pure, exactly li
   platform and needs no merge — prefer operations to whole-value saves where you can.
 - Device view state (which page is open, scroll, selection) belongs in component state or
   `sessionStorage`, never in a shared event another device would follow.
+
+## 4. Declare `resolveConcurrent` for patch-shaped events
+
+`baseMerge` is for events that write one whole value. An event that writes a PATCH — a list of sub-items it
+changed, each with the version it built on — can do better: declare `merge` with `scope` (the sub-item ids),
+and `resolveConcurrent`. The platform calls it only when the patch would land as a conflict (a writer it never
+saw changed one of its sub-items), with the state it lands on; it merges what it can against the bases it
+carries and returns the rewritten event:
+
+```ts
+merge: { item: (_d, ctx) => `${ctx.applicationId}:cad:model`, scope: (d) => d.delta.ops.map(keyOf), describe: (d) => d.label },
+resolveConcurrent: (state, eventData, { theirsSess }) => {
+  const r = resolveEdit(state, eventData);          // pure: three-way per sub-item against the base each op carries
+  if (!r) return null;                              // cannot reason about it → the plain conflict (applied and marked)
+  return r.clashes.length === 0
+    ? { eventData: r.eventData }                    // everything merged: applied, no marker
+    : { eventData: r.eventData, detail: { kind: "cad-edit", clashes: r.clashes, theirsSess } };
+},
+```
+
+What it returns is what the fold applies, on every device and on the server. Keep it pure and symmetric; a
+property test over randomised edit pairs is the cheapest proof.

package/llms-full.txt

@@ -1669,6 +1669,34 @@ the example stops streaming — nothing durable happened unless the handler wrot
 task (docs/07) survives everything and costs seconds per hop. The stopwatch ships both and
 records which one drove each run; measure before you choose.
 
+## The headless bridge — a browser on the platform, for a page-shaped engine
+
+Some engines exist only as a web page: a WebAssembly CAD kernel, a canvas renderer. The
+person's open tab can run it; `headlessBridge(ctx, …)` runs it on the platform too, so an agent
+with nobody's tab open (a phone with the app closed, an agent network, MCP) gets the same work
+done — no computer of the person's involved.
+
+```ts
+import { headlessBridge } from "esoul-sdk/server";
+
+const r = await headlessBridge(ctx, {
+  url: "https://my-runtime.example/page.html?parent=https%3A%2F%2Fmy-runtime.example",
+  boot: { field: "type", oneOf: ["ready", "error"] },            // the page's own ready message
+  calls: [{ id: "replay", message: { myBridge: 1, id: "replay", method: "replay", args: { … } } }],
+});
+r.boot;            // the ready message
+r.replies[0];      // the first message whose `id` equals "replay"
+r.timings;         // launchMs / bootMs (cold only), per-call ms, totalMs
+r.warm;            // true when the page was already open on the platform
+```
+
+The page is loaded top-level, so it is its own `parent`: a bridge written for an iframe answers
+unchanged when `?parent=` names the page's own origin. The browser and the loaded page stay warm
+on the platform between calls for the same url; the first call pays the launch and the page's
+download, later calls only the calls. `url` must be https and public; at most 32 calls; replies
+up to 24 MB. A Forge box has no browser: there the call throws and says so — keep the app open
+in the preview and let the tab do the work.
+
 
 
 ==============================================================================
@@ -3598,6 +3626,28 @@ recorded as a conflict. `baseMerge` runs in every fold: keep it pure, exactly li
 - Device view state (which page is open, scroll, selection) belongs in component state or
   `sessionStorage`, never in a shared event another device would follow.
 
+## 4. Declare `resolveConcurrent` for patch-shaped events
+
+`baseMerge` is for events that write one whole value. An event that writes a PATCH — a list of sub-items it
+changed, each with the version it built on — can do better: declare `merge` with `scope` (the sub-item ids),
+and `resolveConcurrent`. The platform calls it only when the patch would land as a conflict (a writer it never
+saw changed one of its sub-items), with the state it lands on; it merges what it can against the bases it
+carries and returns the rewritten event:
+
+```ts
+merge: { item: (_d, ctx) => `${ctx.applicationId}:cad:model`, scope: (d) => d.delta.ops.map(keyOf), describe: (d) => d.label },
+resolveConcurrent: (state, eventData, { theirsSess }) => {
+  const r = resolveEdit(state, eventData);          // pure: three-way per sub-item against the base each op carries
+  if (!r) return null;                              // cannot reason about it → the plain conflict (applied and marked)
+  return r.clashes.length === 0
+    ? { eventData: r.eventData }                    // everything merged: applied, no marker
+    : { eventData: r.eventData, detail: { kind: "cad-edit", clashes: r.clashes, theirsSess } };
+},
+```
+
+What it returns is what the fold applies, on every device and on the server. Keep it pure and symmetric; a
+property test over randomised edit pairs is the cheapest proof.
+
 
 
 ==============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esoul-sdk",
-  "version": "0.25.0",
+  "version": "0.25.2",
   "description": "Build a full product on ExternalSoul: your own tables with per-person rules, a viewer on every seam, app roles, access levels, realtime with audiences, durable tasks, and bindings to other apps.",
   "license": "UNLICENSED",
   "type": "module",