@thatopen/services 0.7.0 → 0.8.0

package/dist/cli/lib/revit-addin.d.ts

@@ -10,6 +10,14 @@ export interface AddinInfo {
     token: string;
     pid: number;
 }
+/** The add-in's discovery file, or null. Unlike discoverAddin this never exits. */
+export declare function tryDiscoverAddin(): AddinInfo | null;
+/** Is there an add-in listening right now? Asks it, rather than trusting the file:
+ *  Revit exiting leaves the file behind. */
+export declare function addinAlive(): Promise<boolean>;
+/** Waits for Revit to finish starting. Revit takes its time, and the add-in's
+ *  listener comes up well before the splash screen goes away. */
+export declare function waitForAddin(timeoutMs: number): Promise<boolean>;
 export declare function discoverAddin(): AddinInfo;
 export declare function callAddin(cmd: string, body?: Record<string, unknown>): Promise<Record<string, unknown>>;
 /**

package/dist/cli.js

@@ -8120,7 +8120,7 @@ const libVersion = (() => {
   }
 })();
 const templatesDir = require$$2.join(__dirname, "..", "src", "cli", "templates");
-const createCommand = new Command2("create").argument("<project-name>", 'Name of the project to create (use "." for current directory)').option("-t, --template <template>", `Template (${TEMPLATES.join(", ")})`, "app").option("--beta", "Use beta engine libraries (@thatopen-platform/*-beta)").description("Scaffold a new ThatOpen app or cloud component project").action(async (projectName, opts) => {
+const createCommand = new Command2("create").argument("<project-name>", 'Name of the project to create (use "." for current directory)').option("-t, --template <template>", `Template (${TEMPLATES.join(", ")})`, "app").option("--beta", "Use beta engine libraries (@thatopen-platform/*-beta)").option("--history", "App only: include the revit-flow commit history panel, already wired").description("Scaffold a new ThatOpen app or cloud component project").action(async (projectName, opts) => {
   const template = opts.template;
   if (!TEMPLATES.includes(template)) {
     console.error(`Unknown template "${opts.template}". Available: ${TEMPLATES.join(", ")}`);
@@ -8159,6 +8159,16 @@ The templates currently require the beta engine libraries. Public (non-beta) eng
   if (isCloud) {
     require$$3.renameSync(require$$2.join(targetDir, "_thatopen"), require$$2.join(targetDir, ".thatopen"));
   }
+  if (!isCloud) {
+    const variant = require$$2.join(targetDir, "src", "main.history.ts");
+    if (require$$3.existsSync(variant)) {
+      if (opts.history) require$$3.renameSync(variant, require$$2.join(targetDir, "src", "main.ts"));
+      else require$$3.rmSync(variant);
+    }
+  } else if (opts.history) {
+    console.error("--history applies to the app template only.");
+    process.exit(1);
+  }
   const pkgPath = require$$2.join(targetDir, "package.json");
   const pkgContent = require$$3.readFileSync(pkgPath, "utf-8").replace(/\{\{PROJECT_NAME\}\}/g, packageName).replace(/\{\{VERSION\}\}/g, libVersion).replace(/"@thatopen\/services": "file:[^"]*"/, `"@thatopen/services": "^${libVersion}"`);
   require$$3.writeFileSync(pkgPath, pkgContent);
@@ -11733,6 +11743,38 @@ function discoveryFile() {
   const appData = process.env.APPDATA || require$$2.join(node_os.homedir(), "AppData", "Roaming");
   return require$$2.join(appData, "ThatOpen", "revit-addin.json");
 }
+function tryDiscoverAddin() {
+  const file = discoveryFile();
+  if (!require$$3.existsSync(file)) return null;
+  try {
+    return JSON.parse(require$$3.readFileSync(file, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+async function addinAlive() {
+  const info = tryDiscoverAddin();
+  if (!info) return false;
+  try {
+    const res = await fetch(`http://127.0.0.1:${info.port}/status`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-RevitFlow-Token": info.token },
+      body: "{}",
+      signal: AbortSignal.timeout(4e3)
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+async function waitForAddin(timeoutMs) {
+  const until = Date.now() + timeoutMs;
+  while (Date.now() < until) {
+    if (await addinAlive()) return true;
+    await new Promise((r) => setTimeout(r, 2e3));
+  }
+  return false;
+}
 function discoverAddin() {
   const file = discoveryFile();
   if (!require$$3.existsSync(file)) {
@@ -11789,6 +11831,28 @@ async function configureAddin(apiUrl, accessToken) {
     key: accessToken
   });
 }
+function isRevitRunning() {
+  if (process.platform !== "win32") return false;
+  try {
+    return require$$1.execSync('tasklist /FI "IMAGENAME eq Revit.exe" /NH', { encoding: "utf-8" }).toLowerCase().includes("revit.exe");
+  } catch {
+    return false;
+  }
+}
+function startRevit() {
+  const roots = ["C:\\Program Files\\Autodesk"];
+  for (const root of roots) {
+    if (!require$$3.existsSync(root)) continue;
+    for (const dir of require$$3.readdirSync(root)) {
+      if (!/^Revit \d{4}$/.test(dir)) continue;
+      const exe = require$$2.join(root, dir, "Revit.exe");
+      if (!require$$3.existsSync(exe)) continue;
+      require$$1.spawn(exe, [], { detached: true, stdio: "ignore" }).unref();
+      return;
+    }
+  }
+  console.log("      Could not find Revit.exe. Start Revit yourself and this will pick it up.");
+}
 const REVIT_ADDIN_PACKAGE = "@thatopen-platform/flow-revit";
 const revitCommand = new Command2("revit").description(
   "Revit collaboration — drive the That Open Revit add-in from the CLI"
@@ -11815,6 +11879,64 @@ revitCommand.command("inspect").description("Check whether a .rvt is already a w
     console.log("Ask the user for consent, then run publish-central with --convert.");
   }
 });
+revitCommand.command("share").description("Share a .rvt with your team: install if needed, publish the central, open your local").requiredOption("--file <path>", "Absolute path to the .rvt on this machine").requiredOption("--project <id>", "Platform project id (or the dashboard URL)").option("--doc <name>", "Short name for the shared central (default: from the file name)").action(async (opts) => {
+  const cfg = requireResolvedConfig();
+  const file = require$$2.resolve(opts.file);
+  if (!require$$3.existsSync(file)) {
+    console.error(`No such file: ${file}`);
+    process.exit(1);
+  }
+  const project = opts.project.match(/projects\/([a-f0-9]{24})/i)?.[1] ?? opts.project;
+  const doc = opts.doc ?? require$$2.basename(file, ".rvt").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  console.log(`Sharing "${require$$2.basename(file)}" as "${doc}" in project ${project}.
+`);
+  if (!await addinAlive()) {
+    if (!isRevitRunning()) {
+      console.log("[1/5] Installing the Revit add-in...");
+      const client = new EngineServicesClient(cfg.accessToken, cfg.apiUrl);
+      const { dir, cleanup } = await fetchPluginPackage(client, REVIT_ADDIN_PACKAGE, "latest");
+      try {
+        const installer = require$$2.join(dir, "install.ps1");
+        if (!require$$3.existsSync(installer)) throw new Error("The package has no install.ps1.");
+        require$$1.execFileSync("powershell", ["-ExecutionPolicy", "Bypass", "-File", installer], {
+          stdio: "inherit"
+        });
+      } finally {
+        cleanup();
+      }
+      console.log("[2/5] Starting Revit...");
+      startRevit();
+    } else {
+      console.log("[1/5] Waiting for Revit...");
+    }
+    if (!await waitForAddin(3e5)) {
+      console.error(
+        '\nRevit did not report in. If it is open, the add-in may not be installed:\n  close Revit, run "thatopen revit install", and start it again.'
+      );
+      process.exit(1);
+    }
+  } else {
+    console.log("[1/5] Revit is open and the add-in is answering.");
+  }
+  await configureAddin(cfg.apiUrl, cfg.accessToken);
+  console.log("[3/5] Checking the file...");
+  const info = await callAddin("inspect", { file });
+  console.log(
+    info.isCentral ? "      Already a workshared central. Publishing a copy of it." : "      Not a central yet. Converting a COPY. Your file is not modified."
+  );
+  console.log("[4/5] Publishing to the platform (Revit is saving the central, this takes a bit)...");
+  const pub = await callAddin("publish-central", { project, doc, file, convert: true });
+  console.log("[5/5] Creating and opening your local...");
+  const joined = await callAddin("join", { project, doc });
+  console.log(`
+Shared. Central "${doc}" is v${pub.version} in project ${project}.`);
+  console.log(`Your local, now open in Revit:
+  ${joined.local}`);
+  console.log(`
+Teammates join with:
+  thatopen revit join --project ${project} --doc ${doc}`);
+  console.log(`From here, Revit's own Synchronize with Central publishes to the team.`);
+});
 revitCommand.command("publish-central").description("Turn a .rvt into a shared central and upload it to a project").requiredOption("--project <id>", "Platform project id").requiredOption("--doc <name>", "A short name for this central (e.g. tower-central)").requiredOption("--file <path>", "Absolute path to the source .rvt on this machine").option("--convert", "Allow converting a non-central .rvt into one (on a copy; original untouched)").action(async (opts) => {
   await connect();
   console.log(`Publishing "${opts.file}" as central "${opts.doc}"...`);

package/docs/ai-quickstart.md

@@ -87,6 +87,16 @@ thatopen create my-app --beta
 cd my-app
 ```
 
+**[app, showing a Revit model's commit history]** If what they asked for is a viewer of the
+revit-flow history, scaffold it directly. Do not build it by hand: the wiring is four additions in
+three places and the ORDER of them is load-bearing (see the boot order section below). This ships
+it already correct, opening on the History layout.
+
+```bash
+thatopen create my-app --beta --history
+cd my-app
+```
+
 **[component]**
 ```bash
 thatopen create my-component -t cloud-component --beta
@@ -110,6 +120,17 @@ npm run dev
 Serves the app and opens it inside the platform. **You now have a complete, working viewer** —
 model loading, spatial tree, properties, measurement, sectioning, and more.
 
+If it does not open by itself, or the user closes the tab, the app you are serving from this
+machine lives at:
+
+```
+https://platform.thatopen.com/dashboard/projects/<PROJECT_ID>/apps/local-app
+```
+
+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.
+
 > **`npx tsc --noEmit` reports errors in a fresh beta scaffold, and they are not real.** You will see
 > a handful of `Cannot find module '@thatopen/components'` and friends. A beta project aliases those
 > imports to the `@thatopen-platform/*-beta` packages in `vite.config.js`, which bare `tsc` does not
@@ -126,6 +147,101 @@ npm run run        # executes the component locally against the platform (no bro
 ```
 Runs `main()` in a local emulation of the cloud engine so you can iterate before publishing.
 
+## THE BOOT ORDER. Read this before you write a line of an app.
+
+**This is where apps break, and the error never names the real cause.** An app boots in four
+stages, and a built-in that touches models or the 3D scene must be initialised in the LAST one.
+Call it where it reads naturally, right after `client.setup`, and you get:
+
+```
+Error: FragmentsManager not initialized. Call init() first.
+Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'onHighlight')
+Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'onClear')
+```
+
+None of which says "you called this too early". The app renders, the panel mounts, and it sits
+there inert.
+
+**Why.** `FragmentsManager` is initialised inside `top-app`'s own `setup` callback, and the 3D
+world does not exist until `<top-app>` has been added to the DOM and `top-viewer` has built it.
+Both of those happen well after `client.setup` returns. Any manager that reads model files or
+colours elements reaches for them the moment it starts.
+
+**The order, and it is not negotiable:**
+
+1. `client.setup(...)` with every built-in you need, then `components.get(UIManager).init()`
+2. `app.setup = ...`, which is where `FragmentsManager.init` goes, and append `<top-app>`
+3. `await firstWorld(...)`, so the world exists
+4. **only now**, `init(client)` on the model-facing managers
+
+Copy this skeleton. It is the boot of an app that works.
+
+```ts
+async function main() {
+  const client = PlatformClient.fromPlatformContext();
+
+  // 1 ── built-ins registered, UI shell up
+  const { components } = await client.setup<OBC.Components>(
+    { OBC, OBF, BUI, THREE, FRAGS, MARKERJS },
+    { uuid: UIManager.uuid },
+    { uuid: GitHistoryManager.uuid },        // and any other built-in you use
+  );
+  components.get(UIManager).init();
+
+  const viewerEl = document.createElement("top-viewer");
+  const app = document.createElement("top-app") as any;
+
+  // 2 ── this callback is what initialises FragmentsManager. Nothing that needs
+  //      fragments may run before it has resolved.
+  app.setup = (waitUntil: (p: Promise<void>, label?: string) => void) => {
+    waitUntil(
+      (async () => {
+        const fragments = components.get(OBC.FragmentsManager);
+        const workerUrl = await FRAGS.FragmentsModels.getWorker();
+        fragments.init(await FRAGS.toClassicWorker(workerUrl), { classicWorker: true });
+      })(),
+      "Fragments Core",
+    );
+    return { components, client };
+  };
+
+  app.elements = { viewer: () => BUI.html`${viewerEl}` };
+  app.layouts = { Main: { template: `"viewer" 1fr / 1fr` } };
+  app.layout = "Main";
+  (document.getElementById("that-open-app") ?? document.body).appendChild(app);
+
+  // 3 ── the world is created asynchronously by top-viewer. Wait for it.
+  await firstWorld(components.get(OBC.Worlds));
+
+  // 4 ── ONLY NOW. Everything above had to have happened first.
+  await components.get(GitHistoryManager).init(client);
+
+  // ...and from here, the real layouts, panels and elements.
+}
+
+/** Resolves with the first world once it exists (top-viewer creates it async). */
+function firstWorld(worlds: any): Promise<any> {
+  const existing = [...worlds.list.values()][0];
+  if (existing) return Promise.resolve(existing);
+  return new Promise((resolve) => {
+    const handler = ({ value }: any) => {
+      worlds.list.onItemSet.remove(handler);
+      resolve(value);
+    };
+    worlds.list.onItemSet.add(handler);
+  });
+}
+```
+
+**Two more traps in the same family:**
+
+- **One stable `top-viewer` node, held in a variable and returned by reference** from every
+  `elements.viewer()` call. Creating a fresh element on each render disposes the world and
+  builds another one, and everything wired to the old one goes quiet.
+- **Registering a built-in is not the same as initialising it.** `client.setup` makes
+  `<top-git-history>` resolvable; `init(client)` is what fills it. A panel that mounts and stays
+  empty is usually the second one missing, not the first.
+
 ## 5. Then build — read the in-project agent guide
 
 The scaffold is real, working code — a complete viewer **[app]** or a runnable `main()`
@@ -163,5 +279,8 @@ component, once added to a project, is then triggered by an app or an automation
 - **Platform token only.** Never introduce, request, or store an npm token.
 - **Never echo or persist the user's token.** It belongs only in `~/.thatopen/config.json` /
   `.npmrc`, both of which the CLI manages and git-ignores.
-- **Propose a short plan and get the user's OK** before changing files.
+- **Do the thing they asked for.** If the request already says what to build, build it. Proposing a
+  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.
 - The scaffold already works — **extend it, don't replace it.**

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.8.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`.

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

@@ -0,0 +1,191 @@
+import * as THREE from "three";
+import * as OBC from "@thatopen/components";
+import * as OBF from "@thatopen/components-front";
+import * as FRAGS from "@thatopen/fragments";
+// Inlines the fragments worker so it runs inside the platform's sandboxed iframe.
+import "@thatopen/fragments/inline";
+import * as BUI from "@thatopen/ui";
+import * as MARKERJS from "@markerjs/markerjs3";
+import {
+  PlatformClient,
+  UIManager,
+  GitHistoryManager,
+} from "@thatopen/services";
+import { setAppContext } from "./app";
+
+// The standard app, plus the revit-flow commit history: a History layout with the
+// timeline beside the viewer. Scaffolded by `thatopen create <name> --beta --history`.
+//
+// THE BOOT ORDER IS THE WHOLE TRICK, and it is why this ships as a file rather than
+// as instructions. GitHistoryManager reads the commit .frag files and colours the
+// elements of a commit, so it reaches for FragmentsManager and for the 3D world the
+// moment it starts. FragmentsManager is initialised inside top-app's own `setup`
+// below, and the world does not exist until <top-app> is in the DOM and top-viewer
+// has built it. Call `init(client)` where it reads naturally, right after
+// `client.setup`, and you get "FragmentsManager not initialized" plus a pair of
+// undefined `onHighlight` / `onClear` errors, none of which say "too early".
+async function main() {
+  const client = PlatformClient.fromPlatformContext();
+
+  // Brand accent (purple) — drives layout-selector active state, dividers, etc.
+  document.documentElement.style.setProperty("--bim-ui_accent-base", "#6528d7");
+
+  // The dev `thatopen serve` wrapper HTML doesn't zero the UA body margin (8px),
+  // which insets the whole app inside the platform iframe. Kill it here so it's
+  // fixed in both dev and production regardless of the host page.
+  document.body.style.margin = "0";
+
+  // 1 ── UIManager registers the platform web components (top-app, top-viewer, …)
+  // before the DOM renders. GitHistoryManager is the headless half of the history
+  // panel: <top-git-history> is intent-only and asks the registry for it by uuid,
+  // so without this registration the panel mounts and stays inert.
+  const { components } = await client.setup<OBC.Components>(
+    { OBC, OBF, BUI, THREE, FRAGS, MARKERJS },
+    { uuid: UIManager.uuid },
+    { uuid: GitHistoryManager.uuid },
+  );
+  components.get(UIManager).init();
+
+  // One STABLE top-viewer node, returned by reference so re-rendering top-app
+  // reuses it instead of disposing and recreating its world.
+  const viewerEl = document.createElement("top-viewer");
+  viewerEl.style.border = "1px solid var(--bim-ui_bg-contrast-20)";
+  viewerEl.style.borderRadius = "0.75rem";
+  viewerEl.style.boxSizing = "border-box";
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const app = document.createElement("top-app") as any;
+
+  // 2 ── this callback is what initialises FragmentsManager. Nothing that needs
+  // fragments may run before it has resolved.
+  app.setup = (waitUntil: (p: Promise<void>, label?: string) => void) => {
+    waitUntil(
+      (async () => {
+        const fragments = components.get(OBC.FragmentsManager);
+        const workerUrl = await FRAGS.FragmentsModels.getWorker();
+        fragments.init(await FRAGS.toClassicWorker(workerUrl), {
+          classicWorker: true,
+        });
+      })(),
+      "Fragments Core",
+    );
+    return { components, client };
+  };
+
+  // Mount minimally first (viewer only) so top-viewer creates the world.
+  app.elements = { viewer: () => BUI.html`${viewerEl}` };
+  app.layouts = {
+    Main: {
+      label: "Main",
+      icon: "solar:3d-square-bold",
+      template: `"viewer" 1fr / 1fr`,
+    },
+  };
+  app.layout = "Main";
+
+  const container = document.getElementById("that-open-app") ?? document.body;
+  container.appendChild(app);
+
+  // 3 ── the world is created asynchronously by top-viewer. Wait for it.
+  await firstWorld(components.get(OBC.Worlds));
+
+  // Platform client + project data for the AppManager-shim consumers.
+  const projectId: string | undefined = client?.context?.projectId;
+  let projectData;
+  try {
+    if (projectId) projectData = await client.getProjectData(projectId);
+  } catch {
+    /* dev/no-project → consumers degrade gracefully */
+  }
+  setAppContext(client, projectData);
+
+  // 4 ── ONLY NOW. Everything above had to have happened first. Read the comment
+  // at the top of this file before moving this line.
+  await components.get(GitHistoryManager).init(client);
+
+  // Pluggable loaders for <top-models-list>. Heavy, app-specific loaders are
+  // registered here so they stay OUT of the built-in's bundle.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let rcViewer: any = null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const modelLoaders: Record<string, any> = {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    "3tz": async (fileId: string, ctx: any) => {
+      if (!rcViewer) {
+        const { realityCaptureViewer } = await import(
+          "./setups/reality-capture-viewer"
+        );
+        rcViewer = realityCaptureViewer(ctx.components, client);
+      }
+      const saved = ctx.getAlignment(fileId) as number[] | undefined;
+      await rcViewer.loadIntoWorld(fileId, {
+        keepPostproduction: true,
+        transform: saved ? new THREE.Matrix4().fromArray(saved) : undefined,
+        onTransformChange: (m: THREE.Matrix4) =>
+          ctx.setAlignment(fileId, m.toArray()),
+      });
+    },
+  };
+
+  // The stable viewer + the panels, under named layouts with the activity-bar
+  // sidebar. All panels are built-ins that self-wire from top-app's contexts.
+  app.elements = {
+    viewer: () => BUI.html`${viewerEl}`,
+    tree: () => BUI.html`<top-model-tree></top-model-tree>`,
+    properties: () => BUI.html`<top-properties-panel></top-properties-panel>`,
+    files: () =>
+      BUI.html`<top-models-list .loaders=${modelLoaders}></top-models-list>`,
+    dataTable: () => BUI.html`<top-data-table-panel></top-data-table-panel>`,
+    objects: () => BUI.html`<top-objects-panel></top-objects-panel>`,
+    settings: () => BUI.html`<top-settings-panel></top-settings-panel>`,
+    history: () => BUI.html`<top-git-history></top-git-history>`,
+  };
+  app.layouts = {
+    Explorer: {
+      icon: "mdi:file-tree",
+      template: `"tree viewer" 1fr "properties viewer" 1fr / 22rem 1fr`,
+    },
+    Assets: {
+      icon: "mdi:folder-multiple-outline",
+      template: `"files viewer" 1fr "objects viewer" 1fr / 22rem 1fr`,
+    },
+    Data: {
+      icon: "mdi:table",
+      template: `"dataTable viewer" 1fr / 22rem 1fr`,
+    },
+    Settings: {
+      icon: "mdi:cog",
+      template: `"settings viewer" 1fr / 22rem 1fr`,
+    },
+    // Same side, same width and same shape as the others: this only swaps the panel.
+    History: {
+      icon: "at-icons:git-branch",
+      template: `"history viewer" 1fr / 22rem 1fr`,
+    },
+  };
+  // Opens on History, because that is what this app was scaffolded for.
+  app.layout = "History";
+  app.sidebar = true;
+
+  viewerEl.appendChild(document.createElement("top-viewer-toolbar"));
+
+  // The history panel lights up once a revit-flow model is loaded. Load it from the
+  // Assets panel, or auto-load it here if this app only ever shows one model.
+}
+
+/** Resolves with the first world once it exists (top-viewer creates it async). */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function firstWorld(worlds: any): Promise<any> {
+  const existing = [...worlds.list.values()][0];
+  if (existing) return Promise.resolve(existing);
+  return new Promise((resolve) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const handler = ({ value }: any) => {
+      worlds.list.onItemSet.remove(handler);
+      resolve(value);
+    };
+    worlds.list.onItemSet.add(handler);
+  });
+}
+
+main().catch(console.error);