@thatopen/services 0.15.0 → 0.16.0

package/docs/ai-quickstart.md

@@ -127,6 +127,14 @@ machine lives at:
 https://platform.thatopen.com/dashboard/projects/<PROJECT_ID>/apps/local-app
 ```
 
+> **If the platform shows "failed to load application" and the console says
+> `Permission was denied for this request to access the `loopback` address space`**:
+> current Chrome blocks an https page from fetching `http://localhost` until the
+> user grants the **Local network access** permission. Tell the user: click the
+> icon left of the URL → Site settings → **Local network access** → **Allow**,
+> then reload. One-time, per browser profile. Verified 2026-09-22 — without the
+> grant the dev loop does not work at all; with it, everything below does.
+
 Substitute the project id. That is the local app running inside the platform's own UI, against
 the project's real data. Send the user there rather than to a bare localhost port, which is the
 app without the platform around it.
@@ -257,6 +265,54 @@ engine / UI example sets. Load those indexes before writing code. For an **app**
 must be built with Lit + `@thatopen/ui` (`BUI`)** — consult the design system first. Run the
 scaffold first, then extend it; don't rebuild from scratch.
 
+## 5b. The channel: drive the running app from outside, and multiplayer
+
+The scaffold is already listening. `src/setups/channel.ts` joins the platform
+channel at boot with two typed commands (`ping`, `get-loaded-models`), and a
+collaboration room shared by every open tab of the app. This is the bridge for
+"an LLM on the desktop drives the app" and for multiplayer, and it is the same
+system: the platform relays messages between app tabs and external tools.
+
+To command the app from outside (a script, an MCP server, your own tool):
+
+1. The user creates a **platform token** with the **API** permission
+   (dashboard → Account → Tokens). Same secrecy rules as always.
+2. Connect with `socket.io-client` and subscribe, then publish:
+
+```bash
+npm i socket.io-client   # in the external tool's own project, not the app
+```
+
+```js
+import { io } from "socket.io-client";
+
+const socket = io(`https://platform.thatopen.com?accessToken=${process.env.THATOPEN_TOKEN}`);
+// While iterating with `thatopen serve`, OMIT appId (the dev channel is keyed
+// to the account); pass the appId once the app is published.
+socket.emit("channelSubscribe", { projectId, appId, kind: "cli" });
+socket.on("channelMessage", (msg) => {
+  if (msg.type === "channel:subscribed") {
+    socket.emit(
+      "channelPublish",
+      { type: "ping", requestId: crypto.randomUUID(), payload: { echo: "hi" } },
+      (ack) => console.log(ack), // { delivered: 0 } = no app tab is listening
+    );
+  } else {
+    console.log("app says:", msg);
+  }
+});
+```
+
+A reply to your `requestId` reaches only your socket — a second tool connected
+at the same time never sees it. `{ delivered: 0 }` on the ack means no tab of
+that account's app has the channel joined: open the app first.
+
+To grow the app's command surface, extend `AppCommands` in
+`src/setups/channel.ts` and handle the new command — the handler's return value
+is the reply. The full walkthrough (typed contracts, collaboration events,
+presence) is `node_modules/@thatopen/services/src/core/examples/channel.ts`,
+indexed in the client API index you already loaded.
+
 ## 6. Publish (when ready)
 
 ```bash
@@ -283,8 +339,10 @@ component, once added to a project, is then triggered by an app or an automation
   four-point plan and waiting for approval to do what was just requested costs the user a whole turn
   and buys nothing. Stop and ask only when you are about to change files you did not create, when
   the request can be read two ways that mean different work, or when the next step is destructive.
-- **Never save to the platform on every change.** Drafts belong in `localStorage` /
-  IndexedDB; the platform gets an explicit save. Writes are capped at 30 per minute and a
+- **Never save to the platform on every change.** Drafts live in memory — the
+  production sandbox runs apps on an opaque origin where `localStorage`,
+  `sessionStorage`, IndexedDB and cookies all **throw** (they work in dev mode
+  and then break for every real user). The platform gets an explicit save. Writes are capped at 30 per minute and a
   `429` loses the write. See
   `node_modules/@thatopen/services/docs/rate-limits.md` before you write any save, sync or
   polling code.

package/docs/rate-limits.md

@@ -74,27 +74,36 @@ try {
 copy of the change was in that request, it is gone — which is the real reason
 the local-draft pattern below matters.
 
-## The pattern: local drafts, explicit saves
+## The pattern: drafts in memory, explicit saves
 
-Keep every intermediate state in the browser. Write to the platform only when
-the user asks for it.
+Keep every intermediate state in memory. Write to the platform only when the
+user asks for it, or on a slow timer.
+
+> **Why not `localStorage`?** Platform apps run in a sandboxed iframe on an
+> **opaque origin**, where `localStorage`, `sessionStorage`, IndexedDB and
+> cookies don't return empty — they **throw, on the property access itself**.
+> Dev mode grants `allow-same-origin`, so origin storage works on the machine
+> of whoever writes the app and fails for every user. This has shipped broken
+> at least once. Inside a platform app there are exactly two stores: memory,
+> and the platform through the client API.
 
 ```ts
-const draftKey = `draft:${fileId}`;
+const drafts = new Map<string, { state: unknown; at: number }>();
 
-function onChange(state: unknown) {
-  localStorage.setItem(draftKey, JSON.stringify({ state, at: Date.now() }));
+function onChange(fileId: string, state: unknown) {
+  drafts.set(fileId, { state, at: Date.now() });
 }
 
-async function onSave(state: unknown) {
+async function onSave(fileId: string, state: unknown) {
   const blob = new Blob([JSON.stringify(state)], { type: 'application/json' });
   await client.updateFile(fileId, { file: blob, versionTag: `v${Date.now()}` });
-  localStorage.removeItem(draftKey);
+  drafts.delete(fileId);
 }
 ```
 
-On load, if a draft exists for the file, offer to restore it. That gives crash
-recovery — the thing autosave was really for — at zero requests.
+A draft in memory does not survive a reload. If surviving one matters, the
+draft itself has to go to the platform — on the explicit save, or on the slow
+timer below — because there is nowhere else to put it.
 
 Rules of thumb:
 
@@ -104,10 +113,11 @@ Rules of thumb:
 - **Never save while a save is in flight.** Keep a flag per file, and drop or
   queue the second save. Overlapping writes also create versions that are hard
   to reconcile.
-- **Big or binary work-in-progress** belongs in IndexedDB, not `localStorage`
-  (about 5 MB per origin).
-- There is **no draft-write method in the client on purpose.** Local storage is
-  the draft store; the platform stores versions the user chose to keep.
+- **Big or binary work-in-progress** stays in memory too — there is no
+  IndexedDB fallback in the sandbox, so size is bounded by RAM, which is fine:
+  it is the same object the app is already editing.
+- There is **no draft-write method in the client on purpose.** Memory is the
+  draft store; the platform stores versions the user chose to keep.
 
 ## Retries
 

package/package.json

@@ -15,7 +15,7 @@
     "access": "public"
   },
   "private": false,
-  "version": "0.15.0",
+  "version": "0.16.0",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "types": "dist/index.d.ts",

package/resources/AGENTS.md

@@ -36,12 +36,19 @@ Once you have these, you know everything available on the platform. Only then fe
   **Run it first** (`npm run dev`) to see it work, *then* extend it — don't rebuild a viewer from scratch.
 - **Do the thing they asked for.** If the request already says what to build, build it. Stop and ask only when you are about to change files you did not create, when the request can be read two ways that mean different work, or when the next step is destructive.
 - If something already exists in the indexes, use it — don't reimplement it.
+- **The scaffold already listens on the platform channel** (`src/setups/channel.ts`):
+  external tools (an MCP server, a CLI) command the app through `AppCommands`, and
+  tabs collaborate through `AppCollabEvents`. Extend those maps instead of opening
+  sockets — apps cannot hold their own connection. Walkthrough:
+  `node_modules/@thatopen/services/src/core/examples/channel.ts`.
 
 ## Hard rules (always apply)
 
 1. **Never write to the platform on every change.** No autosave per keystroke,
-   per drag, or inside a render loop. Keep work in progress in `localStorage` /
-   IndexedDB and call the platform on an **explicit user save** (or a timer no
+   per drag, or inside a render loop. Keep work in progress **in memory** — the
+   production sandbox has NO origin storage (`localStorage`, `sessionStorage`,
+   IndexedDB and cookies **throw** on its opaque origin; dev mode hides this) —
+   and call the platform on an **explicit user save** (or a timer no
    faster than once every 30 seconds). Writes are capped at **30 per minute**;
    crossing that returns `429` and the write is **lost**, not queued.
    If the user asks for autosave, build it against local storage and say so.

package/src/cli/templates/app/README.md

@@ -209,6 +209,39 @@ client.onExecutionProgress(executionId, (data) => {
 client.localServerUrl = "http://localhost:4001";
 ```
 
+## The channel: external control + multiplayer
+
+This app ships listening on the platform channel (`src/setups/channel.ts`). Two
+things work out of the box:
+
+- **External tools can command it.** An MCP server, a CLI or a plugin
+  authenticated with a platform token of the same account can send the commands
+  declared in `AppCommands` (`ping`, `get-loaded-models`) and gets typed
+  replies back. This is how a desktop LLM drives the running app.
+- **Tabs of this app see each other.** Every open tab joins a collaboration
+  room shared across accounts (`AppCollabEvents`) — the base for cursors,
+  presence and live sync.
+
+To add a command, extend the map and handle it; whatever you return is the reply:
+
+```ts
+export type AppCommands = {
+  // ...existing commands...
+  "select-by-category": { payload: { category: string }; reply: { count: number } };
+};
+
+external.on("select-by-category", async ({ category }) => {
+  const count = await selectByCategory(category);
+  return { count };
+});
+```
+
+The app never opens a socket: the platform shell owns the connection and relays
+it, which is also the security boundary. Joining is opt-in per room — the
+scaffold joins at boot; move the `join()` calls behind a button to make it a
+user choice. Full walkthrough with a collab example:
+`node_modules/@thatopen/services/src/core/examples/channel.ts`.
+
 ## Configuration
 
 - `.thatopen` — local config (gitignored). Created by `npm run login`; also holds

package/src/cli/templates/app/src/main.ts

@@ -8,6 +8,7 @@ import * as BUI from "@thatopen/ui";
 import * as MARKERJS from "@markerjs/markerjs3";
 import { PlatformClient, UIManager } from "@thatopen/services";
 import { setAppContext } from "./app";
+import { setupChannel } from "./setups/channel";
 
 // ─── A2 migration — PHASES 1+2: boot on UIManager + re-dock panels ───────────
 // Juan consolidated the old AppManager (layout) + ViewportsManager (viewport)
@@ -102,6 +103,16 @@ async function main() {
   }
   setAppContext(client, projectData);
 
+  // The platform channel, pre-wired (see ./setups/channel.ts): external tools
+  // of this account (an MCP server, a CLI, a plugin) can command this app, and
+  // other open tabs of it are reachable for collaboration. It only exists
+  // inside the platform iframe, so a failure is a warning, never a boot error.
+  try {
+    setupChannel(client, components);
+  } catch (error) {
+    console.warn("[channel] unavailable outside the platform:", error);
+  }
+
   // Pluggable loaders for <top-models-list>. The built-in ships the lightweight
   // defaults (.frag load, IFC→fragments convert); heavy/app-specific loaders are
   // registered here so they stay OUT of the built-in's bundle. The reality-capture

package/src/cli/templates/app/src/setups/channel.ts

@@ -0,0 +1,76 @@
+/**
+ * The platform channel, pre-wired: typed commands that an external tool (an
+ * MCP server, a CLI, a desktop LLM, a plugin) can send this app while it runs,
+ * and a collaboration room where every open tab of this app hears the others.
+ *
+ * The app never opens a socket. The platform shell owns the one connection and
+ * relays over `postMessage`; `client.channel` is the typed layer on top. That
+ * also means this only works inside the platform iframe — `setupChannel` is
+ * called from a try/catch in `main.ts` so the app still boots anywhere else.
+ *
+ * To extend: add a command to {@link AppCommands} and handle it below. What a
+ * handler returns is sent back to whoever asked; throw and they get the error.
+ * Full walkthrough: `node_modules/@thatopen/services/src/core/examples/channel.ts`.
+ */
+import * as OBC from "@thatopen/components";
+import { PlatformClient } from "@thatopen/services";
+
+/**
+ * The contract with external tools. Each command names its payload and, when
+ * the caller waits for an answer, its reply. A command without `reply` is a
+ * notification. This type is the whole API an MCP server sees: keep it honest.
+ */
+export type AppCommands = {
+  /** Liveness check — answer whoever is probing that this app is listening. */
+  ping: { payload: { echo?: string } | undefined; reply: { pong: true; echo?: string } };
+  /** The ids of the models currently loaded in the viewer. */
+  "get-loaded-models": { payload: undefined; reply: { models: string[] } };
+};
+
+/** Events tabs of this app send each other. Events, so no replies. */
+export type AppCollabEvents = {
+  /** Sent once on join, so other tabs can log or greet. Replace with your own. */
+  hello: { at: number };
+};
+
+/**
+ * Wires both rooms and joins them at boot. Joining is what makes the app
+ * reachable — until then, nothing arrives. If you'd rather listen only when
+ * the user opts in, move the `join()` calls behind a button.
+ */
+export function setupChannel(
+  client: PlatformClient,
+  components: OBC.Components,
+) {
+  // Commands from every kind of external tool of this account. Narrow with
+  // `client.channel.external<AppCommands>("mcp")` to hear one kind only.
+  const external = client.channel.external<AppCommands>();
+
+  external.on("ping", (payload) => ({ pong: true as const, echo: payload?.echo }));
+
+  external.on("get-loaded-models", () => {
+    const fragments = components.get(OBC.FragmentsManager);
+    return { models: [...fragments.list.keys()] };
+  });
+
+  // Collaboration: other users' tabs of this same app, across accounts.
+  const collab = client.channel.collab<AppCollabEvents>();
+  collab.on("hello", (event, { from }) => {
+    console.log(`[channel] tab ${from} joined the collaboration`, event);
+  });
+  collab.onPeerLeft(({ from }) => {
+    console.log(`[channel] tab ${from} left the collaboration`);
+  });
+
+  // Fire-and-forget joins: the app is usable with or without the channel, so
+  // a failure is a warning, never a boot error.
+  external
+    .join()
+    .catch((error) => console.warn("[channel] external join failed:", error));
+  collab
+    .join()
+    .then(() => collab.send("hello", { at: Date.now() }))
+    .catch((error) => console.warn("[channel] collab join failed:", error));
+
+  return { external, collab };
+}