@thatopen/services 0.7.0 → 0.9.0

package/docs/cli/swap.md

@@ -1,30 +1,30 @@
----
-description: "Toggle or explicitly set the engine library mode between stable public packages (@thatopen/*) and private beta packages (@thatopen-platform/*-beta). Updates package.json and .thatopen, then runs npm install. Source code never changes — aliases handle resolution."
----
-
-## thatopen swap
-
-Switches the project between stable and beta engine libraries. Without flags, it toggles from the current state. Updates `package.json` dependencies and sets `beta` in `.thatopen` so `thatopen serve`, `thatopen local-server`, and `vite build` all pick up the change automatically.
-
-Source code stays unchanged — `@thatopen/components` imports resolve to the correct package via esbuild/vite aliases based on the `beta` flag in `.thatopen`.
-
-**Usage:**
-```bash
-thatopen swap           # toggle: stable → beta or beta → stable
-thatopen swap --beta    # force beta
-thatopen swap --stable  # force stable
-```
-
-**Flags:**
-
-- `--beta` — Switch to beta libraries (`@thatopen-platform/*-beta`).
-- `--stable` — Switch back to stable public libraries (`@thatopen/*`).
-
-**Examples:**
-```bash
-thatopen swap
-thatopen swap --beta
-thatopen swap --stable
-```
-
-> Beta packages are private and the access must be explicitly granted by That Open Company.
+---
+description: "Toggle or explicitly set the engine library mode between stable public packages (@thatopen/*) and private beta packages (@thatopen-platform/*-beta). Updates package.json and .thatopen, then runs npm install. Source code never changes — aliases handle resolution."
+---
+
+## thatopen swap
+
+Switches the project between stable and beta engine libraries. Without flags, it toggles from the current state. Updates `package.json` dependencies and sets `beta` in `.thatopen` so `thatopen serve`, `thatopen local-server`, and `vite build` all pick up the change automatically.
+
+Source code stays unchanged — `@thatopen/components` imports resolve to the correct package via esbuild/vite aliases based on the `beta` flag in `.thatopen`.
+
+**Usage:**
+```bash
+thatopen swap           # toggle: stable → beta or beta → stable
+thatopen swap --beta    # force beta
+thatopen swap --stable  # force stable
+```
+
+**Flags:**
+
+- `--beta` — Switch to beta libraries (`@thatopen-platform/*-beta`).
+- `--stable` — Switch back to stable public libraries (`@thatopen/*`).
+
+**Examples:**
+```bash
+thatopen swap
+thatopen swap --beta
+thatopen swap --stable
+```
+
+> Beta packages are private and the access must be explicitly granted by That Open Company.

package/docs/flow-plugin-guide.md

@@ -152,6 +152,32 @@ made every proposal declare its units, which looked careful and was a bug waitin
 an author state a unit while writing coordinates in an axis convention the target does not use, a
 mistake no declared unit can catch.
 
+### Who wrote it
+
+`author` is free text for a timeline to print. `userId` is the one that has to be right: it is what
+the platform's own member component resolves into a real name and face. Get it wrong and the
+proposal shows up under somebody else's avatar, which is worse than showing none.
+
+**In a browser app, take it from `getProjectData`.** It answers with `currentUser` already resolved
+server-side, and the members it lists are keyed by exactly the id the history panel indexes:
+
+```ts
+const { currentUser } = await client.getProjectData(projectId);
+const userId = currentUser?.user._id;      // what the avatar resolves against
+const author = currentUser?.user.fullName; // what the timeline prints
+```
+
+**Do not look for it on the client's context.** `client.context` is the four fields the platform
+injects into the iframe: `appId`, `projectId`, `accessToken`, `apiUrl`. Reading `context.userId` or
+`context.user.name` yields `undefined`, and both failures are silent: the envelope simply ships
+without a `userId`, and the panel falls back to passing `author` as the email, so the member
+component renders whatever it makes of a string that names nobody. A converter did exactly this, and
+it looked fine until somebody noticed the proposal was wearing another person's face.
+
+**In a native plug-in there is no such call**, so read the `u` claim out of the API key's JWT payload
+(base64url, no signature check, since this only decides which name to display). That is what the
+Revit add-in does.
+
 ### The verbs
 
 One per item, in the attribute `flow:op`:

package/docs/revit-collab-quickstart.md

@@ -46,6 +46,12 @@ the point.
 
 ## Step 0 — Ask what the user wants to do
 
+**Only if they have not already told you.** "I want to start a new collaborative project in Revit
+and here is my file" is (A), said plainly. Reading it back as a four-way menu costs the user a
+whole turn to answer something they just said, and that is the single most common way this guide
+wastes somebody's time. Work out which one it is, say which one you took it to be in one line, and
+carry on. Ask only for what is genuinely missing.
+
 > "What would you like to do?
 > (A) **Share** a Revit model with my team for the first time.
 > (B) **Connect** to a shared central a teammate already uploaded.
@@ -164,27 +170,30 @@ Re-run `thatopen revit status` every ten seconds or so until `"loaded": true`.
 
 ## Step 3 — Do the action
 
-### (A) Share a model — `inspect`, then `publish-central`
+### (A) Share a model — one command
 
 ```
-thatopen revit inspect --file "<FILE>"
+thatopen revit share --file "<FILE>" --project <PROJECT>
 ```
 
-- **`"isCentral": true`** → already a central. Tell the user you will upload a copy and their
-  original is untouched, then:
-  ```
-  thatopen revit publish-central --project <PROJECT> --doc <DOC> --file "<FILE>"
-  ```
-- **`"isCentral": false`** → a plain model. **Ask for consent first:** *"This file isn't a shared
-  central yet. To share it I need to turn it into one. I'll do that on a COPY, so your original
-  stays exactly as it is. Shall I go ahead?"* Only then:
-  ```
-  thatopen revit publish-central --project <PROJECT> --doc <DOC> --file "<FILE>" --convert
-  ```
-
-Publishing uploads the central and opens **the user's own local** in Revit. Success ends with
-`Published (…). Central: … (version N). Your original file was not modified.` Teammates connect with
-the folder id from the dashboard, or with `--project` and `--doc`.
+That is the whole of it. `share` installs the add-in if nothing is listening, starts Revit and
+waits for it, checks whether the file is already a central, publishes it, and opens the user's own
+local. It prints each of the five steps as it reaches them, so a long silence is always a step you
+can name.
+
+- **`--doc <name>`** is optional. Left out, it comes from the file name, kebab-cased.
+- **`--project`** takes the dashboard URL as happily as the id.
+- **The original file is never modified.** Everything happens on a copy, which is why `share` does
+  not need to ask before converting: there is nothing to lose. Say so rather than asking.
+- **It joins at the end on purpose.** Sharing a model and then carrying on in the original file is
+  the one reliable way to end up outside your own team.
+
+Steps 1 and 2 (CLI, login, add-in) still have to have happened: `share` installs the add-in but it
+cannot log in for somebody.
+
+If you need the pieces separately — a central that already exists, a different convert decision,
+scripting around it — they are still there: `thatopen revit inspect --file`, then
+`thatopen revit publish-central --project --doc --file [--convert]`, then `thatopen revit join`.
 
 ### (B) Connect to a central — `join`
 

package/docs/rhino-interop-quickstart.md

@@ -258,8 +258,25 @@ to `row.data(j)`.
 
 ### Units, and why the envelope has no units field
 
-A proposal's numbers are in the terms of **what the target published**. Read Revit's export metadata
-and it says so itself:
+**Print both files' metadata BEFORE you write a line of the converter.** This is an ordering
+instruction, not advice. The whole conversion rests on what those two files declare, and it takes
+thirty seconds to find out:
+
+```ts
+for (const id of [rhinoFileId, revitFileId]) {
+  const res = await client.downloadFile(id);
+  const m = FRAGS.EditUtils.getModelFromBuffer(new Uint8Array(await res.arrayBuffer()), false);
+  console.log(id, m.metadata());
+}
+```
+
+Measured on a live demo, 2026-08-05: a converter was written the other way round, four hundred lines
+first and the check afterwards, and the target's metadata turned out to be `{}`. Everything above the
+units gate was correct and none of it could run. Read the two files, then write the converter around
+what is actually in them.
+
+A proposal's numbers are in the terms of **what the target published**. When Revit's export declares
+anything, it says so itself:
 
 ```json
 "data": { "units": "ft", "axes": "z-up", "note": "Revit's own terms, untouched. Operations are written in these." }
@@ -269,12 +286,21 @@ Rhino publishes its document units in the same place, `model.metadata()`, under
 sample project that is `Millimeters`. So the converter divides by **304.8**, and it is the converter's
 job precisely because it is the only piece that knows both sides.
 
-Check the conversion against something real instead of trusting the constant. An existing column in
-the Revit export sits at `-30.19028688187479` ft. Times 304.8 that is **-9202 mm**, which is exactly
-the bay edge measured in Rhino. That is a conversion proved, not assumed.
+**When the target declares nothing.** Models published by add-in versions before 1.2.27 carry empty
+metadata on their first commit, so `{}` is a state you will meet on any project created before then.
+Revit's internal length unit is always decimal feet, so the factor is not actually in doubt; what is
+missing is the file saying so. Take feet, say out loud that you are taking it, and then **prove it
+from the data** rather than leaving it as an assumption:
+
+- Read one existing column's `Position` out of the target, and compare it against the same column
+  measured in the source. On the sample project: `-30.19028688187479` ft times 304.8 is **-9202 mm**,
+  which is exactly the bay edge measured in Rhino.
+- Keep a sanity check on every converted point: refuse anything landing more than about ten metres
+  from an existing element of the same category. That is what catches a factor-of-1000 error, and it
+  works whether or not the file declared anything.
 
-**Refuse unknown units.** Guessing a scale factor puts the columns a thousand times too far away, and
-nothing about the result says why.
+**What you must never do is guess silently.** A wrong factor puts the columns a thousand times too
+far away, and nothing about the result says why. Refusing is a worse demo and a better outcome.
 
 ### Building the payload
 
@@ -335,6 +361,38 @@ would have built a converter against a layer name nobody was using any more.
 The tables above are here so nobody has to do that. If you still want to see real bytes, publish
 something small and read it back inside the app.
 
+### What "it builds" does not tell you
+
+The dev build does not typecheck. `npm run build` said **111 modules, built clean** on a converter
+whose `tsc --noEmit` was red in four places, and the run that produced this guide read that line as
+proof and moved on. Run the typechecker separately, and read what it says.
+
+Its complaint was worth having. A file that does not exist yet is read with a fallback, and the
+fallback's shape becomes the type:
+
+```ts
+const history = await this._readJson(id, { commits: [] });   // commits: never[]
+const head = history.commits.at(-1);                          // head: never
+```
+
+Every field read off `head` is then an error, which is the typechecker pointing out that the empty
+case was never really thought about. Type the fallback, and decide what an empty history means.
+
+Three more that only fail once somebody presses the button:
+
+- **The published file name is a parameter, not a constant.** `/publish` takes `name`. A converter
+  that hardcodes `rhino-columns.frag` answers "publish from Rhino first" when the file is right
+  there under another name. If you cannot find it, list what the folder actually holds and say so.
+- **A loose folder match picks silently.** Falling back from an exact name to "any folder ending in
+  this" is fine with one project and wrong the first time there are two, with nothing on screen to
+  say which one it chose.
+- **The platform round trip is not exercised by anything above.** The two failures this cost were
+  `parentFolderId` and the version tag, and both compiled, read fine, and only spoke on the first
+  real click. Press it once yourself, on something small, before showing it to anybody.
+
+Not clicking it in front of the user is still the right call. Queuing a proposal writes into a
+shared project, and that is theirs to trigger. Press it in a scratch document instead.
+
 ## 6. Accept it in Revit
 
 The Revit add-in's local API, `%APPDATA%\ThatOpen\revit-addin.json`, header `X-RevitFlow-Token`.
@@ -389,3 +447,12 @@ lands in the history, with the new columns in it, viewable in the app like any o
 - **Version tags are timestamps, not counts.** Numbering by how many entries there are collides on
   the very first update.
 - **Stray `.frag` files on the machine are not the current format.** They are an earlier session.
+- **Read the two files' metadata before writing the converter, not after.** Everything the
+  conversion rests on is declared in them, or is not, and finding out costs thirty seconds at the
+  start and four hundred lines at the end.
+- **Build only what was asked for.** An extra button and an extra layout are minutes each, and they
+  come out of the same hour as the thing that has to work.
+- **A clean build is not a typecheck.** Vite does not run `tsc`. "Built clean" and "correct" are two
+  different sentences.
+- **Read these guides verbatim.** A fetch that summarises gives you the shape of the thing and none
+  of the numbers, and every number here was paid for. Use the raw URL.

package/package.json

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

package/resources/AGENTS.md

@@ -1,41 +1,41 @@
-# Building on the That Open Platform — Agent Guide
-
-You are an AI assistant helping a user build a **BIM app** or **cloud component** on the
-That Open Platform using **`@thatopen/services`** (the `thatopen` CLI + client library).
-
-**Read this file first, then immediately load all indexes listed below before doing anything else.**
-
-> This guide is tool-agnostic: it works with any AI (Claude, Codex, your own). All local docs it
-> references ship inside the `@thatopen/services` package under `docs/`.
-
----
-
-## Session start — load all indexes in parallel
-
-Do this before answering any question or writing any code. These are compact description indexes:
-
-| What | Where |
-|---|---|
-| Platform built-ins | `node_modules/@thatopen/services/docs/builtin/paths.json` |
-| Platform client API | `node_modules/@thatopen/services/docs/client/paths.json` |
-| CLI commands | `node_modules/@thatopen/services/docs/cli/paths.json` |
-| Engine components (`OBC`, `OBF`) | `https://raw.githubusercontent.com/ThatOpen/engine_components/refs/heads/main/examples/paths.json` |
-| Fragments (`FRAGS`) | `https://raw.githubusercontent.com/ThatOpen/engine_fragment/refs/heads/main/examples/paths.json` |
-| UI components (`BUI`) | `https://raw.githubusercontent.com/ThatOpen/engine_ui-components/refs/heads/main/examples/paths.json` — **skip** entries whose path contains `packages/obc` or `bim-grid` |
-
-Once you have these, you know everything available on the platform. Only then fetch a specific example file when you need implementation details.
-
-> **Path resolution:** all `path` entries inside the local indexes (`docs/`, `src/`) are relative to the `@thatopen/services` package root — prepend `node_modules/@thatopen/services/` when reading any of those files.
-
----
-
-## How to work
-
-- **The scaffold is already a complete, working viewer** (model loading, spatial tree, properties).
-  **Run it first** (`npm run dev`) to see it work, *then* extend it — don't rebuild a viewer from scratch.
-- **Propose a short plan and get the user's OK** before changing files. If scope is unclear, ask.
-- If something already exists in the indexes, use it — don't reimplement it.
-
-## Hard rules (always apply)
-
+# Building on the That Open Platform — Agent Guide
+
+You are an AI assistant helping a user build a **BIM app** or **cloud component** on the
+That Open Platform using **`@thatopen/services`** (the `thatopen` CLI + client library).
+
+**Read this file first, then immediately load all indexes listed below before doing anything else.**
+
+> This guide is tool-agnostic: it works with any AI (Claude, Codex, your own). All local docs it
+> references ship inside the `@thatopen/services` package under `docs/`.
+
+---
+
+## Session start — load all indexes in parallel
+
+Do this before answering any question or writing any code. These are compact description indexes:
+
+| What | Where |
+|---|---|
+| Platform built-ins | `node_modules/@thatopen/services/docs/builtin/paths.json` |
+| Platform client API | `node_modules/@thatopen/services/docs/client/paths.json` |
+| CLI commands | `node_modules/@thatopen/services/docs/cli/paths.json` |
+| Engine components (`OBC`, `OBF`) | `https://raw.githubusercontent.com/ThatOpen/engine_components/refs/heads/main/examples/paths.json` |
+| Fragments (`FRAGS`) | `https://raw.githubusercontent.com/ThatOpen/engine_fragment/refs/heads/main/examples/paths.json` |
+| UI components (`BUI`) | `https://raw.githubusercontent.com/ThatOpen/engine_ui-components/refs/heads/main/examples/paths.json` — **skip** entries whose path contains `packages/obc` or `bim-grid` |
+
+Once you have these, you know everything available on the platform. Only then fetch a specific example file when you need implementation details.
+
+> **Path resolution:** all `path` entries inside the local indexes (`docs/`, `src/`) are relative to the `@thatopen/services` package root — prepend `node_modules/@thatopen/services/` when reading any of those files.
+
+---
+
+## How to work
+
+- **The scaffold is already a complete, working viewer** (model loading, spatial tree, properties).
+  **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.
+
+## Hard rules (always apply)
+
 1. **All UI must be built with Lit**, using the web components from `@thatopen/ui` (`BUI`) — `bim-button`, `bim-panel`, `bim-panel-section`, `bim-toolbar`, `bim-dropdown`, `bim-input`, and the rest of `packages/core`. Always consult the design system before writing any UI: `https://raw.githubusercontent.com/ThatOpen/engine_ui-components/refs/heads/main/DESIGN.md`.