@thatopen/services 0.19.0 → 0.21.0

package/docs/ai-quickstart.md

@@ -297,8 +297,11 @@ 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 → Data → API Tokens). Same secrecy rules as always.
+1. The user creates a **platform token** (dashboard → Data → API Tokens). Same
+   secrecy rules as always. The token itself needs no special permission: what
+   the channel checks is the token owner's role in the project, which must allow
+   **API calls**. Project Admin and Member have it by default; a custom role
+   needs it ticked.
 2. Connect with `socket.io-client` and subscribe, then publish:
 
 ```bash
@@ -349,7 +352,36 @@ 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.
 
-## 5c. The desktop MCP server: `thatopen mcp`
+## 5c. History and recipes: documents, versions, change requests
+
+Three sentences hold the whole model. Every connected document (a Revit model,
+an AutoCAD drawing) has its version history: who synced, when, what changed.
+Nobody writes in somebody else's document: changes arrive as SUGGESTIONS
+(create/modify/delete native data) that the owner accepts or dismisses in the
+native app. A RECIPE is a script that writes suggestions in an application's
+own language, from whatever input.
+
+```ts
+const history = client.history(projectId);
+const docs = await history.docs();                 // the connected documents
+const doc = history.doc('revit', docs[0].docId);
+const timeline = await doc.timeline();             // versions, oldest first
+const pending = await doc.pendingSuggestions();    // waiting for the owner
+
+client.recipes.register(myRecipe);                 // manifest + one run()
+await client.recipes.run('my-recipe', {            // only QUEUES a suggestion:
+  projectId, target: { source: 'revit', docId },   // trying is always safe
+  input, settings, author,
+});
+```
+
+This surface is the only supported way in: the storage underneath is private
+and will move. Never list or write the `bimterop` files directly. The full
+walkthrough (manifest fields, StaleHistoryError on concurrent syncs, payloads)
+is `node_modules/@thatopen/services/src/core/examples/history.ts`, indexed in
+the client API index you already loaded.
+
+## 5d. The desktop MCP server: `thatopen mcp`
 
 The raw socket above is for tools you write. For an LLM on the desktop (Claude
 Desktop, Claude Code, anything that speaks MCP), the CLI ships the same bridge

package/docs/client/paths.json

@@ -35,6 +35,10 @@
     "path": "src/core/examples/hidden-files.ts",
     "description": "Hidden file lifecycle — create, get, list by parent, download, and delete."
   },
+  {
+    "path": "src/core/examples/history.ts",
+    "description": "History and recipes — a project's connected documents (Revit, AutoCAD…), their version timelines, change requests (suggestions), and recipes: scripts that write suggestions in an app's native language."
+  },
   {
     "path": "src/core/examples/icons.ts",
     "description": "Item icon management — upload, download, and remove icons on any item (file, app, or component)."

package/docs/flow-plugin-guide.md

@@ -3,6 +3,13 @@
 The concrete contract. [The architecture notes](https://raw.githubusercontent.com/ThatOpen/platform_services/main/docs/flow-architecture.md) say why any of this is
 shaped the way it is; this says what the bytes look like.
 
+> **Plug-ins only.** Since `@thatopen/services` 0.20, apps and scripts do not write this layout by
+> hand: `client.history(projectId)` reads and writes documents, version timelines and proposals,
+> and `client.recipes` runs the scripts that author them — see `src/core/examples/history.ts` in
+> the package. The bytes below are the contract for NATIVE PLUG-INS (which carry their own client),
+> and the reference for what the API does underneath. Anything else touching these files directly
+> will break when the layout moves behind the API, which is the plan.
+
 Nothing here is aspirational. Every rule below is what the Revit and Rhino plugins already do, and
 was written from their implementation rather than ahead of it — which is why the awkward parts are
 stated as plainly as the tidy ones. Where a rule exists because something broke, it says so.

package/docs/rhino-interop-quickstart.md

@@ -195,11 +195,17 @@ happened.
 Points count as items without geometry. That is correct: they are the data the converter reads, not
 something to draw.
 
-## 5. The converter
+## 5. The converter (a recipe)
 
 This is the part that is **not** in either plug-in, and should not be. It reads the published
 `.frag`, decides what it means, and queues a proposal.
 
+> A converter is one kind of **recipe**: a script that writes proposals in the target program's
+> own words. Since `@thatopen/services` 0.20, write it against the SDK instead of the raw files:
+> `client.history(projectId)` reads the queue and the timeline and queues the proposal
+> (`doc.suggest`), and `client.recipes` is the registry/runner apps use to list it, render its
+> settings form and run it safely. The four steps below are unchanged.
+
 The worked example is `RhinoColumnsConverter`: points on a named layer become Revit columns of a
 given family and type. It is written to be read and then rewritten — the next person wants walls
 from curves, or louvres from blocks — but four steps survive any rewrite:

package/package.json

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

package/src/built-in/GISManager/example.ts

@@ -85,8 +85,37 @@ await gis.enableTiles();
   makes the see-through effect possible. On other hosts they are added to the
   scene directly and stay opaque. You do not need to do anything for this: the
   component detects it.
+
+  On those deferred hosts the tiles also dissolve gradually near the camera's far
+  plane instead of ending in a hard edge. `horizonFade` is the fraction of the far
+  distance over which this happens: with the default `0.8` and a far plane at
+  1000, the tiles are fully visible up to 200 and fully transparent at 1000. It
+  combines with the see-through opacity, and `0` turns it off. While the map is
+  loaded the fade is a fraction of `mapFar` (see below), not of the camera's own
+  far plane.
+
+  While the tiles are loaded, the empty background behind them is also painted
+  as a sky: a gradient from `skyHorizonColor` (default `#d7e3ee`, a light hazy
+  blue) at the horizon to `skyZenithColor` (default `#6a9bd1`) straight up, so
+  the tiles dissolve into the horizon colour. Set `sky = false` to keep the
+  background as it is. Like the fade, it only exists on deferred hosts.
+
+  To let the map reach the horizon, `GISManager` takes over the far plane of the
+  world's cameras while the tiles are loaded: `mapFar`, `10000` by default. With
+  the default `horizonFade` of `0.8` the map is fully visible up to 2 km and
+  fades out until 10 km. A far plane the application or the user set is only
+  remembered while the map is loaded and comes back when `disableTiles()` runs
+  (a larger far set by code that grows it, for example when it loads a large
+  point cloud, is respected, and kept). Setting `mapFar` while the map is loaded
+  applies immediately. This works on every host, deferred or not.
 */
 
+gis.horizonFade = 0.4;
+gis.mapFar = 15000;
+gis.skyHorizonColor = "#e8d9c5";
+gis.skyZenithColor = new THREE.Color(0x4f86c6);
+gis.sky = true;
+
 gis.onStateChanged.add((state) => console.log("tiles visible:", state.tilesVisible));
 gis.setTilesOpacity(0.6);
 

package/src/built-in/UIManager/src/settings-panel/example.ts

@@ -79,7 +79,10 @@ components.get(UIManager).init();
   ### 🤖 What the default panel manages automatically
 
   **Graphics** — point/line/edge styling, background, shadows, ambient
-  occlusion — whatever `top-viewer` supports, persisted across reloads.
+  occlusion — whatever `top-viewer` supports, persisted across reloads. When the
+  app uses `GISManager`, a "GIS Map" group also appears, with the sky on/off, the
+  horizon fade (how far before the camera's far plane the map dissolves, 0 = hard
+  cut) and the sky's horizon and zenith colours.
 
   **Clip styling** — fill/edge color, opacity, width for the clip tool,
   shared live with `top-viewer-toolbar`'s clip button.

package/src/built-in/index.ts

@@ -30,9 +30,7 @@ export interface CDENamingSchema {
     separator: string;
     segments: CDENamingSegment[];
 }
-// `Base` now declares `createdBy` itself (the field the API actually
-// returns); this narrows it to the string the CDE panels render.
-export interface CDEFile extends Omit<Item, 'createdBy'> {
+export interface CDEFile extends Omit<Item, 'creatingUser'> {
     createdBy: string;
     metadata: Record<string, CDEMetadataValue>;
     versions?: ItemVersion[];
@@ -1668,6 +1666,64 @@ declare class _GISManager extends OBC.Component {
     private _tilesOpacity;
     private _fadeTarget;
     private _fadeQuad;
+    private _horizonTarget;
+    private _horizonQuad;
+    /**
+     * Fraction (0–1) of the camera's far distance over which the 3D tiles dissolve
+     * into what is behind them, instead of ending in a hard edge at the far plane:
+     * the tiles are fully visible up to `far * (1 - horizonFade)` and fully
+     * transparent at `far`. Default 0.8. `0` turns it off (opaque tiles are drawn
+     * straight into the frame at opacity 1, as before). Combines with
+     * `setTilesOpacity`: final alpha = opacity × fade. Deferred hosts only — where
+     * the tiles are added to the scene directly there is no fade. Vector layers
+     * are not faded.
+     */
+    horizonFade: number;
+    private readonly _far;
+    private _farCameras;
+    /**
+     * Far plane (distance) the world's cameras get while the 3D tiles are loaded, so
+     * the map reaches the horizon. Default `10000`. Changing it while the map is
+     * loaded takes effect immediately. `horizonFade` is a fraction of this far while
+     * the map is loaded (with `0.8`, the map fades from 2 km to 10 km).
+     *
+     * The camera's own far plane (e.g. the Settings panel's "Far plane") is
+     * overridden while the map is loaded: it is remembered, not applied, and comes
+     * back when the map is unloaded. Code that grows the far plane itself while the
+     * map is loaded still works: a larger far than `mapFar` is left alone, and is
+     * kept on unload.
+     */
+    get mapFar(): number;
+    set mapFar(far: number);
+    /** True while the map owns the cameras' far plane (the 3D tiles are loaded). */
+    get farOverridden(): boolean;
+    /** The far plane the user asked for, remembered while `farOverridden` (otherwise the cameras hold it). */
+    get userCameraFar(): number;
+    /** Records the far plane the user wants; not applied until the map is unloaded. Only meaningful while `farOverridden`. */
+    setUserCameraFar(far: number): void;
+    private _resolveFarCameras;
+    /**
+     * Shows a sky gradient behind everything while the 3D tiles are loaded: the
+     * empty background (pixels nothing has drawn to) goes from `skyHorizonColor` at
+     * the horizon to `skyZenithColor` straight up, so the tiles, dissolving with
+     * `horizonFade`, melt into the horizon colour. Below the horizon it is the
+     * horizon colour; an orthographic camera sees one flat colour. Default `true`;
+     * `false` leaves the background untouched. Deferred hosts only — elsewhere
+     * there is no sky. Drawn behind the vector layers and the tiles.
+     */
+    sky: boolean;
+    private readonly _skyHorizon;
+    private readonly _skyZenith;
+    private _skyHorizonColor;
+    private _skyZenithColor;
+    private _skyPass;
+    private static _setSkyRgb;
+    /** Sky colour at the horizon (any CSS colour string, hex number or `THREE.Color`). Default `"#d7e3ee"`, a light hazy blue. */
+    get skyHorizonColor(): THREE.ColorRepresentation;
+    set skyHorizonColor(color: THREE.ColorRepresentation);
+    /** Sky colour straight up. Default `"#6a9bd1"`, a deeper blue. */
+    get skyZenithColor(): THREE.ColorRepresentation;
+    set skyZenithColor(color: THREE.ColorRepresentation);
     private _passRegistered;
     private _ensureOcclusionPass;
     private readonly _occlusion;

package/src/core/examples/history.ts

@@ -0,0 +1,103 @@
+// description: "History and recipes — a project's connected documents (Revit, AutoCAD…), their version timelines, change requests (suggestions), and recipes: scripts that write suggestions in an app's native language."
+import { EngineServicesClient } from '../client';
+import type { Recipe } from '../recipes';
+
+// The mental model, in three sentences:
+// 1. Every connected document (a Revit model, an AutoCAD drawing) has its
+//    version history: who synced, when, what changed.
+// 2. Nobody writes in somebody else's document. Changes arrive as SUGGESTIONS
+//    (create / modify / delete native data) that the owner accepts or
+//    dismisses in the native app. That is why running any of this is safe.
+// 3. A RECIPE is a script that writes suggestions in an application's own
+//    language. Anything that wants to change a Revit document uses a Revit
+//    recipe to say it in Revit's words.
+
+export async function readTheProjectHistory(
+  client: EngineServicesClient,
+  projectId: string,
+) {
+  const history = client.history(projectId);
+
+  // Which documents are connected, and from which application.
+  const docs = await history.docs();
+  for (const { source, docId } of docs) {
+    const doc = history.doc(source, docId);
+
+    // The timeline is ordered by the version graph, oldest first, with
+    // `ordinal` filled in. The last entry is the head.
+    const timeline = await doc.timeline();
+    const head = timeline[timeline.length - 1];
+    console.log(
+      `${source}-${docId}: ${timeline.length} versions, head by ${head?.author}`,
+    );
+
+    // A version's geometry: full exports ARE the model file; ordinary
+    // versions carry a hidden delta.
+    if (head?.deltaId) await doc.delta(head);
+    else if (head?.full) await doc.model();
+
+    // The change requests waiting for the document's owner.
+    const pending = await doc.pendingSuggestions();
+    console.log(`${pending.length} suggestions pending`);
+  }
+}
+
+// A recipe is its manifest plus one function. The settingsSchema is what apps
+// render as a form — anything naming an EXISTING thing must be an enum the
+// app fills, so people pick instead of typing names.
+const pointsToBlocks: Recipe<{ layer: string; block: string }> = {
+  name: 'points-to-autocad-blocks',
+  description: 'Places an AutoCAD block on every input point.',
+  to: 'autocad',
+  inputs: ['points'],
+  runtime: 'browser',
+  settingsSchema: {
+    type: 'object',
+    properties: {
+      layer: { type: 'string' },
+      block: { type: 'string' },
+    },
+    required: ['layer', 'block'],
+  },
+  rules: [{ reads: 'input points', proposes: 'one block per point' }],
+  async run({ input, settings }) {
+    const points = input as { x: number; y: number; z: number }[];
+    // Build the suggestion payload (a .frag with envelope revitflow/op@2,
+    // one item per change, attributes in the TARGET's own vocabulary).
+    // The payload builder lives in the fragments toolkit; omitted here.
+    const payload = await buildOpFrag(points, settings);
+    return {
+      title: `Place ${points.length} ${settings.block} blocks`,
+      verb: 'add',
+      targets: points.length,
+      payload,
+      ruleTallies: [{ read: points.length, proposed: points.length }],
+    };
+  },
+};
+
+export async function runARecipe(
+  client: EngineServicesClient,
+  projectId: string,
+) {
+  client.recipes.register(pointsToBlocks);
+
+  // Catalogs filter by target application: "who can speak autocad?".
+  client.recipes.list({ to: 'autocad' });
+
+  // Running is always safe: it only queues a suggestion on the target
+  // document. Nothing changes in AutoCAD until its owner applies it there.
+  const { suggestion } = await client.recipes.run('points-to-autocad-blocks', {
+    projectId,
+    target: { source: 'autocad', docId: 'site-plan' },
+    input: [{ x: 0, y: 0, z: 0 }],
+    settings: { layer: 'DETECTORS', block: 'SIEMENS-FDO181' },
+    author: 'recipe:points-to-autocad-blocks',
+  });
+  console.log(`queued suggestion ${suggestion.opId}`);
+}
+
+declare function buildOpFrag(
+  points: { x: number; y: number; z: number }[],
+  settings: { layer: string; block: string },
+): Promise<Blob>;