@floless/app 0.43.0 → 0.45.1

package/dist/templates/tekla-watch-logger.flo

@@ -0,0 +1,57 @@
+app:           tekla-watch-logger
+version:       0.1.0
+display-name:  Tekla Watch → file log
+description: |
+  Event-triggered demo: a tekla.watch source streams every model change, and a
+  downstream exec node appends each event's details (mark, type, change, guid,
+  timestamp) to ~/Documents/floless-watch-log.txt — one line per event. Proves the
+  "On trigger" chain end-to-end and leaves a durable, app-closed-verifiable record.
+  self_test:true drives 5 synthetic events with no live Tekla; against a real model
+  it logs forever while the routine is enabled.
+exposes-as-agent: false
+layout: linear
+requires:
+  - tekla@0.1.x
+nodes:
+  - id: watch                       # SOURCE — streaming lifecycle:start; one fire per change
+    agent: tekla
+    command: watch
+    config:
+      filter: all
+      self_test: true
+      include_deleted: true
+  - id: log                         # SINK — append this event's details to the file
+    agent: tekla
+    command: exec
+    mode: read                      # author intent; AWARE defaults exec→write (issue #165), cosmetic
+    config:
+      version: "2025.0"
+      # Per-event payload bound by the streaming runtime as {{ inputs.<field> }}
+      # (orchestrator.propagate_from → execute_and_chain inserts the fired event
+      # under `inputs`). Fields: mark, type, change, guid, host, delivered_at.
+      args:
+        mark:  "{{ inputs.mark }}"
+        type:  "{{ inputs.type }}"
+        change: "{{ inputs.change }}"
+        guid:  "{{ inputs.guid }}"
+        at:    "{{ inputs.delivered_at }}"
+      code: |
+        // Append one line per fired event to ~/Documents/floless-watch-log.txt.
+        // System.IO is available in exec (System.Net / System.Diagnostics.Process are not).
+        string Get(string k) => args != null && args.ContainsKey(k) && args[k] != null
+          ? args[k].ToString() : "";
+        string mark = Get("mark");
+        string type = Get("type");
+        string change = Get("change");
+        string guid = Get("guid");
+        string at = Get("at");
+
+        string dir = System.Environment.GetFolderPath(System.Environment.SpecialFolder.MyDocuments);
+        string path = System.IO.Path.Combine(dir, "floless-watch-log.txt");
+        string stampedAt = string.IsNullOrEmpty(at) ? System.DateTime.UtcNow.ToString("o") : at;
+        string line = string.Format("{0}\t{1}\t{2}\t{3}\tguid={4}", stampedAt, change, type, mark, guid);
+        System.IO.File.AppendAllText(path, line + System.Environment.NewLine);
+
+        return new { ok = true, logged = line, path = path };
+connections:
+  - { from: watch, to: log }

package/dist/templates/tekla-watch-smoke.flo

@@ -0,0 +1,20 @@
+app:           tekla-watch-smoke
+version:       0.1.0
+display-name:  Tekla Watch (smoke)
+description: |
+  Minimal tekla.watch event-source app for capturing the streaming run-trace
+  shape (self_test:true drives synthetic events with no live Tekla). Used to
+  ground floless.app's "On trigger" fire-detection.
+exposes-as-agent: false
+layout: linear
+requires:
+  - tekla@0.1.x
+nodes:
+  - id: watch
+    agent: tekla
+    command: watch
+    config:
+      filter: all
+      self_test: true
+      include_deleted: true
+connections: []

package/dist/templates/trimble-list-projects.flo

@@ -0,0 +1,41 @@
+app:           trimble-list-projects
+version:       0.1.0
+display-name:  Trimble — list my projects
+description: |
+  Lists the Trimble Connect projects you can access (read-only) and renders them
+  as an HTML report. Uses the connected `trimble-connect` credential — AWARE
+  attaches the stored OAuth token as a Bearer automatically, floless.app never sees
+  it — then html-report's generic auto-render turns the result into a table the
+  in-app Viewer shows. Foundation demo for Trimble workflow support.
+exposes-as-agent: false
+requires:
+  - trimble-connect@0.2.x
+  - html-report@0.2.x
+requires-permissions:
+  network:
+    - https://app.connect.trimble.com
+layout: linear
+# Explicit edge so `report` waits for `projects`. As of AWARE 0.59.0 (#208) a ref
+# like `{{ projects.body }}` auto-derives this edge, so it's belt-and-suspenders now —
+# kept for clarity.
+connections:
+  - from: projects
+    to: report
+nodes:
+  - id: projects
+    agent: trimble-connect
+    command: list-projects
+    config:
+      top: 100
+  - id: report
+    agent: html-report
+    command: render
+    config:
+      data: '{{ projects.body }}'
+      title: My Trimble Connect projects
+      # The API returns ~20 columns (incl. raw thumbnail URLs + createdBy JSON blobs);
+      # keep a clean, useful set and lead with the most recently modified.
+      # (html-report columns + sort, AWARE 0.61.0 / #210.)
+      columns: [name, location, modifiedOn, filesCount, foldersCount, access]
+      sort: modifiedOn
+      sort-desc: true

package/dist/templates/viewer-3d-demo.flo

@@ -0,0 +1,65 @@
+app:           viewer-3d-demo
+version:       0.1.0
+display-name:  3D Viewer Demo
+description: |
+  A self-contained demo of the viewer-3d agent — renders a small steel portal frame as an
+  interactive 3D model in the in-app viewer (orbit/zoom, click a member to inspect, a legend
+  and a takeoff table). No Tekla model required: a single viewer-3d `render` node with an
+  inline, domain-agnostic scene. Use it to preview the interactive 3D surface end to end.
+exposes-as-agent: false
+requires:
+  - viewer-3d@0.1.x
+layout: linear
+nodes:
+  # The viewer-3d render node IS the terminal: it returns the interactive HTML the viewer shows.
+  - id: view
+    agent: viewer-3d
+    command: render
+    config:
+      scene:
+        meta: { name: "Sample portal frame — 20 m × 24 m", units: mm, up: z }
+        groups:
+          - { key: column, label: Columns, color: "#60a5fa" }
+          - { key: rafter, label: Rafters, color: "#38bdf8" }
+          - { key: beam,   label: Beams,   color: "#94a3b8" }
+          - { key: brace,  label: Bracing, color: "#818cf8" }
+        elements:
+          # columns (z 0 -> 6000)
+          - { id: COL-A1, group: column, kind: box, from: [0,0,0],      to: [0,0,6000],      section: { w: 310, d: 310 }, meta: { profile: "UC 305x305x97" } }
+          - { id: COL-C1, group: column, kind: box, from: [20000,0,0],  to: [20000,0,6000],  section: { w: 310, d: 310 }, meta: { profile: "UC 305x305x97" } }
+          - { id: COL-A2, group: column, kind: box, from: [0,6000,0],   to: [0,6000,6000],   section: { w: 310, d: 310 }, meta: { profile: "UC 305x305x97" } }
+          - { id: COL-C2, group: column, kind: box, from: [20000,6000,0], to: [20000,6000,6000], section: { w: 310, d: 310 }, meta: { profile: "UC 305x305x97" } }
+          - { id: COL-A3, group: column, kind: box, from: [0,12000,0],  to: [0,12000,6000],  section: { w: 310, d: 310 }, meta: { profile: "UC 305x305x97" } }
+          - { id: COL-C3, group: column, kind: box, from: [20000,12000,0], to: [20000,12000,6000], section: { w: 310, d: 310 }, meta: { profile: "UC 305x305x97" } }
+          # rafters (eave -> apex -> eave) per frame
+          - { id: RAF-L1, group: rafter, kind: box, from: [0,0,6000],      to: [10000,0,7500],     section: { w: 190, d: 460 }, meta: { profile: "UB 457x191x67" } }
+          - { id: RAF-R1, group: rafter, kind: box, from: [10000,0,7500],  to: [20000,0,6000],     section: { w: 190, d: 460 }, meta: { profile: "UB 457x191x67" } }
+          - { id: RAF-L2, group: rafter, kind: box, from: [0,6000,6000],   to: [10000,6000,7500],  section: { w: 190, d: 460 }, meta: { profile: "UB 457x191x67" } }
+          - { id: RAF-R2, group: rafter, kind: box, from: [10000,6000,7500], to: [20000,6000,6000], section: { w: 190, d: 460 }, meta: { profile: "UB 457x191x67" } }
+          - { id: RAF-L3, group: rafter, kind: box, from: [0,12000,6000],  to: [10000,12000,7500], section: { w: 190, d: 460 }, meta: { profile: "UB 457x191x67" } }
+          - { id: RAF-R3, group: rafter, kind: box, from: [10000,12000,7500], to: [20000,12000,6000], section: { w: 190, d: 460 }, meta: { profile: "UB 457x191x67" } }
+          # eaves beams (along Y, z 6000) + ridge (x 10000, z 7500)
+          - { id: EAV-A1, group: beam, kind: box, from: [0,0,6000],      to: [0,6000,6000],      section: { w: 170, d: 310 }, meta: { profile: "UB 305x165x40" } }
+          - { id: EAV-A2, group: beam, kind: box, from: [0,6000,6000],   to: [0,12000,6000],     section: { w: 170, d: 310 }, meta: { profile: "UB 305x165x40" } }
+          - { id: EAV-C1, group: beam, kind: box, from: [20000,0,6000],  to: [20000,6000,6000],  section: { w: 170, d: 310 }, meta: { profile: "UB 305x165x40" } }
+          - { id: EAV-C2, group: beam, kind: box, from: [20000,6000,6000], to: [20000,12000,6000], section: { w: 170, d: 310 }, meta: { profile: "UB 305x165x40" } }
+          - { id: RDG-1,  group: beam, kind: box, from: [10000,0,7500],   to: [10000,6000,7500],  section: { w: 170, d: 310 }, meta: { profile: "UB 305x165x40" } }
+          - { id: RDG-2,  group: beam, kind: box, from: [10000,6000,7500], to: [10000,12000,7500], section: { w: 170, d: 310 }, meta: { profile: "UB 305x165x40" } }
+          # vertical X-bracing (end bay, wall A)
+          - { id: BR-A1, group: brace, kind: box, from: [0,0,0],    to: [0,6000,6000], section: { w: 140, d: 140 }, meta: { profile: "CHS 139.7x5.0" } }
+          - { id: BR-A2, group: brace, kind: box, from: [0,0,6000], to: [0,6000,0],    section: { w: 140, d: 140 }, meta: { profile: "CHS 139.7x5.0" } }
+        grids:
+          - { label: A, at: [0,-2000,0] }
+          - { label: B, at: [10000,-2000,0] }
+          - { label: C, at: [20000,-2000,0] }
+          - { label: "1", at: [-2000,0,0] }
+          - { label: "3", at: [-2000,12000,0] }
+        panels:
+          - title: Takeoff
+            note: "Counted from the scene — no Tekla licence."
+            columns: [Section, "No.", Length]
+            rows:
+              - ["UC 305x305x97", 6, "36.0 m"]
+              - ["UB 457x191x67", 6, "60.7 m"]
+              - ["UB 305x165x40", 6, "36.0 m"]
+              - ["CHS 139.7x5.0", 2, "17.0 m"]

package/dist/web/app.css

@@ -1599,6 +1599,23 @@
   .app-update:hover { border-color: var(--accent); color: var(--accent); }
   .app-update[disabled] { opacity: 0.6; cursor: default; }
 
+  /* Workflow-update pill (a published workflow has a newer version) — mirrors the app-update pill. */
+  .wf-update-pill { display: none; border: 1px solid var(--accent-dim); background: var(--accent-soft); color: var(--accent-bright); font-size: 10px; padding: 1px 7px; border-radius: 999px; cursor: pointer; margin-left: 8px; line-height: 1.5; }
+  .wf-update-pill:not([hidden]) { display: inline-flex; align-items: center; gap: 4px; }
+  .wf-update-pill:hover { border-color: var(--accent); color: var(--accent); }
+  .wf-update-pill:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+  /* Changelog list inside the update modal — themed scroll container (no native bar leaks). */
+  .wf-update-changelog { max-height: 280px; overflow-y: auto; margin-bottom: 14px; display: flex; flex-direction: column; gap: 12px; scrollbar-width: thin; scrollbar-color: var(--border-strong) transparent; }
+  .wf-update-changelog::-webkit-scrollbar { width: 6px; }
+  .wf-update-changelog::-webkit-scrollbar-thumb { background: var(--border-strong); border-radius: 6px; }
+  .wf-update-changelog::-webkit-scrollbar-track { background: transparent; }
+  .wf-update-changelog .wf-ver-head { font-family: var(--mono); font-weight: 700; color: var(--text); font-size: 12px; }
+  .wf-update-changelog .wf-ver-sum { color: var(--text-muted); font-size: 11px; margin: 2px 0 6px; }
+  .wf-update-changelog ul { margin: 0; padding-left: 16px; }
+  .wf-update-changelog li { color: var(--text); font-size: 12px; margin: 2px 0; }
+  #wf-update-sub { color: var(--text-muted); }
+  .wf-update-note { font-size: 11px; color: var(--text-muted); margin: 0 0 16px; line-height: 1.5; padding-top: 12px; border-top: 1px solid var(--border); }
+
   /* Add/edit form */
   .modal.routine-edit { width: 540px; max-width: 92vw; max-height: 90vh; overflow-y: auto; }
   #rtn-workflow, .rtn-kind-select { min-width: 0; width: 100%; }

package/dist/web/aware.js

@@ -533,6 +533,8 @@
 
   // ── load / select / compile / run ───────────────────────────────────────────
 
+  let _wfUpdates = []; // workflow updates available, keyed by app id — polled by refreshWorkflowUpdates() below
+
   async function loadApp(id) {
     const { app } = await api(`/api/app/${encodeURIComponent(id)}`);
     apps.set(id, app);
@@ -554,6 +556,7 @@
     markSpecialNodes();
     paintGate(app);
     refreshDirtyIndicator(); // clean app → dot off; switched back to a dirty one → dot on
+    renderWfUpdatePill(); // show the "↑ Update to vX" pill when THIS app has a newer published version
   }
 
   async function loadApps() {
@@ -2826,6 +2829,82 @@
     setInterval(refreshUpdate, 60 * 60 * 1000); // hourly backstop; the focus re-check (below) is the fast path
   }
 
+  // ── Workflow update (module-shaped) ─────────────────────────────────────────────
+  // A FloLess-published workflow (e.g. steel-takeoff) has a newer bundled template. Poll GET
+  // /api/workflows/updates; when the OPEN app has one, show a pill → modal with the changelog →
+  // "Back up & update" POSTs /api/workflows/:id/update (backup → swap structure → re-bake the user's
+  // data from the contract store → recompile) → reload the app. No auto-update. `_wfUpdates` + the
+  // renderWfUpdatePill() call in loadApp() live earlier; renderWfUpdatePill queries the DOM so it's
+  // safe to call before this block initialises.
+  const $wfUpdate = document.getElementById('wf-update');
+  const $wfUpdateModal = document.getElementById('wf-update-modal');
+  let _wfUpdateApplying = false;
+  function wfUpdateFor(id) { return _wfUpdates.find((u) => u.id === id) || null; }
+  function renderWfUpdatePill() {
+    const el = document.getElementById('wf-update');
+    if (!el) return;
+    const u = currentId ? wfUpdateFor(currentId) : null;
+    if (u) {
+      el.textContent = '↑ Update to v' + u.available;
+      el.dataset.tip = 'A newer version of this workflow is available — see what changed';
+      el.hidden = false;
+    } else {
+      el.hidden = true;
+    }
+  }
+  async function refreshWorkflowUpdates() {
+    try {
+      const r = await fetch('/api/workflows/updates');
+      const d = await r.json();
+      _wfUpdates = (r.ok && d.ok && Array.isArray(d.updates)) ? d.updates : [];
+    } catch { _wfUpdates = []; }
+    renderWfUpdatePill();
+  }
+  function openWfUpdateModal(u) {
+    if (!$wfUpdateModal) return;
+    const a = apps.get(u.id);
+    const name = (a && a.displayName) || u.id;
+    document.getElementById('wf-update-title').textContent = `Update “${name}” to v${u.available}`;
+    document.getElementById('wf-update-sub').textContent = `You’re on v${u.installed}. What’s new:`;
+    const changelog = Array.isArray(u.changelog) ? u.changelog : [];
+    document.getElementById('wf-update-changelog').innerHTML = changelog.map((e) => {
+      const changes = Array.isArray(e.changes) && e.changes.length
+        ? '<ul>' + e.changes.map((c) => `<li>${escapeHtml(String(c))}</li>`).join('') + '</ul>' : '';
+      return `<div class="wf-ver"><div class="wf-ver-head">v${escapeHtml(String(e.version))}</div>`
+        + (e.summary ? `<div class="wf-ver-sum">${escapeHtml(String(e.summary))}</div>` : '') + changes + '</div>';
+    }).join('') || '<div class="wf-ver-sum">No changelog provided.</div>';
+    showModal($wfUpdateModal);
+  }
+  async function applyWfUpdate(u) {
+    if (_wfUpdateApplying) return;
+    _wfUpdateApplying = true;
+    const $ok = document.getElementById('wf-update-ok');
+    const prev = $ok ? $ok.textContent : '';
+    if ($ok) { $ok.disabled = true; $ok.textContent = 'Updating…'; }
+    try {
+      const r = await fetch(`/api/workflows/${encodeURIComponent(u.id)}/update`, { method: 'POST', headers: { 'content-type': 'application/json' } });
+      const d = await r.json().catch(() => ({}));
+      if (!r.ok || !d.ok) throw new Error(d.error || 'update failed');
+      hideModal($wfUpdateModal);
+      showToast(`Updated to v${d.toVersion} — your data is preserved, a backup was saved.`, 'ok');
+      await refreshWorkflowUpdates();
+      if (currentId === u.id) await loadApp(currentId); // reload to show the new structure
+    } catch (e) {
+      showToast('Workflow update failed — ' + String((e && e.message) || e).slice(0, 100), 'warn');
+    } finally {
+      _wfUpdateApplying = false;
+      if ($ok) { $ok.disabled = false; $ok.textContent = prev; }
+    }
+  }
+  if ($wfUpdate) {
+    $wfUpdate.onclick = () => { const u = currentId && wfUpdateFor(currentId); if (u) openWfUpdateModal(u); };
+    const $cancel = document.getElementById('wf-update-cancel'); if ($cancel) $cancel.onclick = () => hideModal($wfUpdateModal);
+    const $ok = document.getElementById('wf-update-ok'); if ($ok) $ok.onclick = () => { const u = currentId && wfUpdateFor(currentId); if (u) applyWfUpdate(u); };
+    if ($wfUpdateModal) onBackdropDismiss($wfUpdateModal, () => hideModal($wfUpdateModal));
+    refreshWorkflowUpdates();
+    setInterval(refreshWorkflowUpdates, 60 * 60 * 1000);
+  }
+
   // Dev-override helper — the ONLY forced-visible path. Reveals a pill with a fixed
   // version when localStorage['floless.dev.forceUpdate'] matches the component, so an
   // E2E can exercise the popover without a real pending update. Returns true if forced.

package/dist/web/index.html

@@ -54,6 +54,7 @@
           </div>
         </div>
         <select id="prompt-select" hidden></select>
+        <button id="wf-update" class="wf-update-pill" type="button" hidden aria-haspopup="dialog"></button>
         <!-- Agents (⊞) and Routines (⏱) buttons moved into the ≡ menu in #149
              (Ctrl+G / Ctrl+R); the toolbar keeps only the run-critical controls. -->
         <span class="ctl-sep" aria-hidden="true"></span>
@@ -241,6 +242,22 @@
     </div>
   </div>
 
+  <!-- Workflow update: a FloLess-published workflow has a newer version. The changelog (entries
+       newer than installed) renders into #wf-update-changelog; "Back up & update" swaps the
+       structure but keeps the user's data (re-baked from the contract store). -->
+  <div class="modal-backdrop" id="wf-update-modal">
+    <div class="modal">
+      <div class="modal-title" id="wf-update-title">Workflow update</div>
+      <div class="modal-sub" id="wf-update-sub"></div>
+      <div class="wf-update-changelog" id="wf-update-changelog"></div>
+      <div class="wf-update-note">Your work is safe — this updates the workflow's steps and keeps your data. A backup of the current version is saved first.</div>
+      <div class="modal-actions">
+        <button id="wf-update-cancel">Not now</button>
+        <button id="wf-update-ok" class="primary">↑ Back up &amp; update</button>
+      </div>
+    </div>
+  </div>
+
   <div class="menu" id="menu" role="menu">
     <button class="menu-item" data-action="open" role="menuitem">
       <span class="menu-icon" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="m6 14 1.5-2.9A2 2 0 0 1 9.24 10H20a2 2 0 0 1 1.94 2.5l-1.54 6a2 2 0 0 1-1.95 1.5H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h3.9a2 2 0 0 1 1.69.9l.81 1.2a2 2 0 0 0 1.67.9H18a2 2 0 0 1 2 2v2"/></svg></span>

package/dist/web/steel-3d-core.js

@@ -135,3 +135,22 @@ export function snapPoint(dragged, candidates, toScreen, tolPx) {
   }
   return best ? { snapped: bestPt, candidate: best } : { snapped: dragged, candidate: null };
 }
+
+/**
+ * 3D dimension geometry (pure). a,b are scene mm [x,y,z]. axis ∈ free|x|y|z.
+ * free → the straight segment a→b (valueMm = full 3D distance); x|y|z →
+ * axis-aligned from a, advancing only that one world component to b
+ * (valueMm = that component's length). Returns the drawn endpoints, the
+ * midpoint (where the label sits), and the measured length in mm.
+ */
+export function dim3dGeom(a, b, axis) {
+  const p1 = [a[0], a[1], a[2]];
+  let p2;
+  if (axis === 'x') p2 = [b[0], a[1], a[2]];
+  else if (axis === 'y') p2 = [a[0], b[1], a[2]];
+  else if (axis === 'z') p2 = [a[0], a[1], b[2]];
+  else p2 = [b[0], b[1], b[2]];                       // free (default for any unrecognised axis)
+  const valueMm = Math.hypot(p2[0] - p1[0], p2[1] - p1[1], p2[2] - p1[2]);
+  const mid = [(p1[0] + p2[0]) / 2, (p1[1] + p2[1]) / 2, (p1[2] + p2[2]) / 2];
+  return { p1, p2, mid, valueMm };
+}

package/dist/web/steel-3d-view.js

@@ -16,7 +16,7 @@
  */
 import * as THREE from 'three';
 import { OrbitControls } from 'three/addons/OrbitControls.js';
-import { snapCandidates, snapPoint, planPointToWp, memberGeometry, elevationLevels } from './steel-3d-core.js';
+import { snapCandidates, snapPoint, planPointToWp, memberGeometry, elevationLevels, dim3dGeom } from './steel-3d-core.js';
 
 let renderer, scene, perspCam, orthoCam, camera, controls, root, api, canvasEl, ro, rafId, grid, raycaster, downXY, lastPick = '(none)';
 let pending = null, dragging = null, marker = null, readout = null; // pending = member gesture; readout = drag dimension overlay
@@ -44,6 +44,18 @@ const SELECT_EMISSIVE = 0x3b82f6;     // --brand: selected members glow blue
 const EP_START = 0xfacc15;            // start endpoint (end 1) — yellow
 const EP_END = 0xf472b6;             // end endpoint (end 2) — magenta
 
+// ---- 3D dimension tool ----
+let dimMode3d = false;            // tool armed
+let dimAxis3d = 'free';           // sticky axis: free | x | y | z
+let dims3dVisibleFlag = true;     // show/hide placed dims
+let dimDraft3d = null;            // { a:[x,y,z] } once the first point is placed (awaiting the 2nd)
+let dimLastAlt = false;           // last-seen Alt state (the hover rAF rebuilds a synthetic event)
+let dims3dGroup = null;           // THREE.Group of placed-dim lines (+ the live preview line)
+let dimPreviewLine = null;        // reused preview line (point 1 → cursor)
+let dimLabelHost = null;          // fixed-position container for label overlays
+const dimLabelPool = [];          // reused <div> labels, one per placed dim, positioned in the loop
+let dimCandidates3d = null;       // snap candidates cached for the active placement gesture
+
 function init(canvas, theApi) {
   if (renderer) return;               // once
   canvasEl = canvas; api = theApi;
@@ -91,6 +103,14 @@ function init(canvas, theApi) {
   readout._type = document.createElement('span'); readout._type.style.color = 'var(--mut,#94a3b8)';
   readout.append(readout._dist, readout._type);
   document.body.appendChild(readout);
+  // 3D dimension tool: a group of placed-dim lines (over the steel) + a live preview line + an HTML
+  // overlay host for the midpoint labels (positioned each frame so they face the camera as screen text).
+  dims3dGroup = new THREE.Group(); scene.add(dims3dGroup);
+  dimPreviewLine = new THREE.Line(new THREE.BufferGeometry().setFromPoints([new THREE.Vector3(), new THREE.Vector3()]), new THREE.LineBasicMaterial({ color: 0x22d3ee }));
+  dimPreviewLine.material.depthTest = false; dimPreviewLine.renderOrder = 997; dimPreviewLine.visible = false; scene.add(dimPreviewLine);
+  dimLabelHost = document.createElement('div');
+  dimLabelHost.style.cssText = 'position:fixed;left:0;top:0;pointer-events:none;z-index:57';
+  document.body.appendChild(dimLabelHost);
   // persistent hover/selection status chip, bottom-centre of the canvas (mirrors the viewer's readout)
   hoverChip = document.createElement('div');
   hoverChip.style.cssText = 'position:fixed;display:none;pointer-events:none;z-index:55;background:var(--panel,#0f172a);color:var(--mut,#94a3b8);border:1px solid var(--line,#334155);border-radius:6px;padding:5px 12px;font:12px system-ui;white-space:nowrap;max-width:60vw;overflow:hidden;text-overflow:ellipsis;box-shadow:0 2px 8px rgba(0,0,0,.45)';
@@ -130,6 +150,7 @@ function loop() {
   rafId = requestAnimationFrame(loop);
   controls.update();
   sizeEndpoints();
+  positionDimLabels();
   renderer.render(scene, camera);
   if (cube) { syncCube(); cube.renderer.render(cube.scene, cube.cam); }
 }
@@ -328,6 +349,7 @@ async function rebuild(fit = false) {
   const sc = await api.fetchScene();   // editor POSTs the current contract to /scene
   if (seq !== rebuildSeq) return;      // a newer rebuild superseded this one → drop the stale scene (no out-of-order apply)
   if (sc) buildFromScene(sc);
+  refreshDims();                       // persisted dims appear + survive edit-rebuilds (re-coloured for the current selection)
 }
 
 // ---- Persp/Ortho + Solid/Wire/X-ray + group visibility (parity with the AWARE viewer) ----
@@ -406,12 +428,40 @@ function onKey(e) {
   if (!renderer || !canvasEl || canvasEl.style.display === 'none') return;     // only when 3D is active
   const ae = document.activeElement; if (ae && /^(INPUT|SELECT|TEXTAREA)$/.test(ae.tagName)) return;
   if ((e.key === ' ' && e.shiftKey) || ((e.key === 'z' || e.key === 'Z') && e.altKey)) { e.preventDefault(); frameSelection(); return; } // zoom-selected (Tekla Shift+Space / viewer Alt+Z)
+  const k = e.key.toLowerCase();
+  // Don't touch the dim tool while a member gesture (drag / box-select) owns the shared marker/readout —
+  // toggling would clear them mid-gesture. The gesture finishes on pointerup; the key is a no-op until then.
+  const midGesture = pending || dragging || boxSel;
+  if (k === 'd' && !e.ctrlKey && !e.metaKey && !e.altKey && !midGesture) { e.preventDefault(); toggleDimTool(); return; } // D arms/disarms the dimension tool
+  if (dimMode3d && !midGesture) {
+    if (k === 'escape') { e.preventDefault(); if (dimDraft3d) { dimDraft3d = null; dimPreviewLine.visible = false; readout.style.display = 'none'; } else toggleDimTool(); return; } // Esc: cancel the in-progress dim, else exit the tool
+    if (k === 'f' || k === 'x' || k === 'y' || k === 'z') { e.preventDefault(); setDimAxis(k === 'f' ? 'free' : k); reflectDimAxisBar(); return; } // sticky axis: Free / X / Y / Z
+  }
   const a = ARROWS[e.key]; if (!a) return;
   const [hx, hy] = a;
   if (e.ctrlKey || e.metaKey) { e.preventDefault(); rotateView(-hx * Math.PI / 12, hy * Math.PI / 12); }  // 15°
   else if (e.shiftKey) { e.preventDefault(); rotateView(-hx * Math.PI / 36, hy * Math.PI / 36); }          // 5°
   else { e.preventDefault(); panView(hx, hy); }                                                            // pan
 }
+// ---- 3D dimension tool controls (driven from the toolbar + the keyboard) ----
+function toggleDimTool() {
+  dimMode3d = !dimMode3d;
+  if (!dimMode3d) { dimDraft3d = null; dimCandidates3d = null; dimPreviewLine.visible = false; marker.visible = false; readout.style.display = 'none'; canvasEl.style.cursor = 'default'; }
+  else { controls.enabled = true; canvasEl.style.cursor = 'crosshair'; }  // show the crosshair on arm, before the first mousemove
+  reflectDimBar();
+  return dimMode3d;
+}
+function setDimAxis(a) { if (['free', 'x', 'y', 'z'].includes(a)) dimAxis3d = a; }
+function dimAxis() { return dimAxis3d; }
+function setDims3dVisible(on) { dims3dVisibleFlag = !!on; refreshDims(); }
+function dims3dVisible() { return dims3dVisibleFlag; }
+function reflectDimBar() {
+  const b = document.getElementById('m3dDim'); if (b) b.classList.toggle('on', dimMode3d);
+  const ax = document.getElementById('m3dDimAxis'); if (ax) ax.style.display = dimMode3d ? 'flex' : 'none';
+  const sh = document.getElementById('m3dDimShow'); if (sh) sh.style.display = dimMode3d ? 'inline-block' : 'none';
+  reflectDimAxisBar();
+}
+function reflectDimAxisBar() { document.querySelectorAll('#m3dDimAxis button').forEach((x) => x.classList.toggle('on', x.dataset.d3axis === dimAxis3d)); }
 // Tekla "set view point": double-click a member → make that point the orbit/zoom pivot.
 function onDblClick(e) {
   camera.updateMatrixWorld(); root.updateMatrixWorld(true);
@@ -479,6 +529,65 @@ function sizeEndpoints() {
   }
 }
 
+// ---- placed 3D dimensions ----
+// Rebuild the placed-dim lines from the editor's dims3d (the single source of truth). Lines render
+// depthTest:false so they're never buried; the selected dim draws amber. Labels are HTML overlays
+// (pool below), so only the line geometry is rebuilt here.
+function refreshDims() {
+  if (!dims3dGroup || !api || !api.getDims3d) return;
+  dimCandidates3d = null;               // a rebuild may follow a member edit → don't keep stale snap targets for the next click
+  for (const c of [...dims3dGroup.children]) { dims3dGroup.remove(c); c.geometry.dispose(); c.material.dispose(); }
+  const dims = api.getDims3d() || [];
+  const sel = api.selDim3d ? api.selDim3d() : null;
+  if (dims3dVisibleFlag) {
+    for (const d of dims) {
+      const g = dim3dGeom(d.a, d.b, d.axis);
+      const col = d.id === sel ? 0xf59e0b : 0x67e8f9;                 // amber (#f59e0b) when selected, else muted cyan-300 — a quieter tint of the 0x22d3ee preview/2D-dim cyan (intentional, not a stray value)
+      const line = new THREE.Line(new THREE.BufferGeometry().setFromPoints([new THREE.Vector3(...g.p1), new THREE.Vector3(...g.p2)]), new THREE.LineBasicMaterial({ color: col }));
+      line.material.depthTest = false; line.renderOrder = 996; line.userData.dimId = d.id;
+      dims3dGroup.add(line);
+    }
+  }
+  syncDimLabels(dims);
+}
+// Keep one themed label div per placed dim (reused across rebuilds). Click selects the dim.
+function syncDimLabels(dims) {
+  while (dimLabelPool.length < dims.length) {
+    const el = document.createElement('div');
+    el.style.cssText = 'position:absolute;transform:translate(-50%,-50%);pointer-events:auto;cursor:pointer;background:var(--panel,#0f172a);color:var(--text,#f8fafc);border:1px solid var(--line,#1e293b);border-radius:4px;padding:2px 6px;font:12px system-ui;white-space:nowrap;box-shadow:0 2px 8px rgba(0,0,0,.5)';
+    el.addEventListener('pointerdown', (e) => { e.stopPropagation(); const id = el._dimId; if (api && api.onSelectDim3d) { api.onSelectDim3d(id); refreshDims(); } });
+    dimLabelHost.appendChild(el); dimLabelPool.push(el);
+  }
+  for (let i = 0; i < dimLabelPool.length; i++) {
+    const el = dimLabelPool[i], d = dims[i];
+    if (!d || !dims3dVisibleFlag) { el.style.display = 'none'; el._dimId = null; el._mid = null; continue; }
+    el._dimId = d.id;
+    const g = dim3dGeom(d.a, d.b, d.axis);
+    el.textContent = api.fmtLen ? api.fmtLen(g.valueMm) : (g.valueMm / 304.8).toFixed(2) + ' ft';
+    el.style.borderColor = d.id === (api.selDim3d && api.selDim3d()) ? '#f59e0b' : 'var(--line,#1e293b)';
+    el.style.display = 'block'; el._mid = g.mid;
+  }
+}
+// project each visible label's 3D midpoint → screen px (called from the render loop). Hidden when the
+// midpoint is behind the camera (project z>1).
+function positionDimLabels() {
+  if (!dimLabelHost || canvasEl.style.display === 'none') { if (dimLabelHost) dimLabelHost.style.display = 'none'; return; }
+  dimLabelHost.style.display = 'block';
+  for (const el of dimLabelPool) {
+    if (el.style.display === 'none' || !el._mid) continue;
+    const [mx, my, mz] = el._mid;
+    const v = new THREE.Vector3(mx, my, mz).project(camera);
+    // hide when the midpoint is behind the camera (z>1) OR outside the canvas frustum (|x|,|y|>1):
+    // the labels are pointer-events:auto, so an off-canvas one would float over and intercept the
+    // surrounding editor UI (the inspector panel / toolbar).
+    if (v.z > 1 || v.x < -1 || v.x > 1 || v.y < -1 || v.y > 1) { el.style.visibility = 'hidden'; continue; }
+    const rect = canvasEl.getBoundingClientRect();
+    el.style.left = (rect.left + (v.x * 0.5 + 0.5) * rect.width) + 'px';
+    el.style.top = (rect.top + (-v.y * 0.5 + 0.5) * rect.height) + 'px';
+    el.style.visibility = 'visible';
+  }
+}
+
 // ---- ViewCube (parity with AWARE viewer-3d) — a small labelled cube; a face click snaps the view ----
 const CUBE_FACES = [
   { label: 'RIGHT', view: 'right' }, { label: 'LEFT', view: 'left' },   // +X, -X
@@ -593,8 +702,40 @@ function pxToWorldAt(px, pos) {
 }
 const markerSize = () => pxToWorldAt(8, marker && marker.position); // snap marker ~8px at its own depth
 
+// The snapped 3D point under the cursor for the dim tool. `anchor` (point 1) is set during the 2nd
+// pick: with Alt held the result is locked to the anchor's plan X/Y (a pure vertical / Z measurement,
+// the elevation-drag feel). Returns { p:[x,y,z], type } (type = the snap label, or null).
+function dimPointAt(e, anchor) {
+  if (anchor && e.altKey) {
+    const hit = rayToVerticalPlane(e.clientX, e.clientY, anchor); if (!hit) return null;
+    return { p: [anchor[0], anchor[1], hit[2]], type: 'vertical' };
+  }
+  let id = null; try { id = pickAt(e.clientX, e.clientY); } catch { id = null; }
+  let planeZ = sceneBox.isEmpty() ? 0 : sceneBox.min.z;
+  if (id) { const m = members().find((x) => x.id === id); if (m) { const g = memberGeometry(m, api.ptPerFt(), api.defaultTosMm()); planeZ = (g.line[0][2] + g.line[1][2]) / 2; } }
+  const hit = rayToPlane(e.clientX, e.clientY, planeZ); if (!hit) return null;
+  if (!dimCandidates3d) dimCandidates3d = snapCandidates(members(), api.ptPerFt(), api.defaultTosMm());
+  const r = snapPoint([hit[0], hit[1], hit[2]], dimCandidates3d, toScreen, SNAP_TOL_PX);
+  return { p: r.candidate ? r.snapped : hit, type: r.candidate ? r.candidate.type : null };
+}
+// The axis to measure on: Alt held during the 2nd pick forces a pure-vertical (Z) measurement,
+// overriding the sticky axis (else a sticky X/Y would collapse the Alt-locked point to zero length).
+function dimEffectiveAxis(alt) { return alt && dimDraft3d ? 'z' : dimAxis3d; }
+
 function onDown(e) {
   if (e.button !== 0) return;                 // RIGHT/MIDDLE → OrbitControls (orbit/pan)
+  if (dimMode3d) {                            // 2-click dimension placement (not a drag): pick A, then B → place
+    e.stopPropagation(); controls.enabled = true;
+    const r = dimPointAt(e, dimDraft3d && dimDraft3d.a); if (!r) return;
+    if (!dimDraft3d) { dimDraft3d = { a: r.p }; dimCandidates3d = null; }
+    else {
+      const a = dimDraft3d.a, b = r.p, axis = dimEffectiveAxis(e.altKey);
+      const g = dim3dGeom(a, b, axis);
+      dimDraft3d = null; dimPreviewLine.visible = false; marker.visible = false; readout.style.display = 'none'; dimCandidates3d = null;
+      if (g.valueMm > 1 && api && api.onAddDim3d) api.onAddDim3d({ id: api.newDim3dId(), a, b, axis });
+    }
+    return;
+  }
   downXY = [e.clientX, e.clientY];
   let id = null; try { id = pickAt(e.clientX, e.clientY); } catch { id = null; }
   // Geometry-edit mode (Trim/Extend or Split armed in the inspector): a click does the edit, no drag.
@@ -780,10 +921,25 @@ function closestOnSeg3(p, a, b) {
 // ---- hover: cursor + readout chip (no drag in progress) ----
 function onHoverMove(e) {
   lastHoverXY = [e.clientX, e.clientY];
+  dimLastAlt = e.altKey;                       // remembered so the rAF body can rebuild a synthetic event
   if (hoverRAF || pending || dragging || boxSel) return;
   hoverRAF = requestAnimationFrame(() => {
     hoverRAF = 0;
     if (!lastHoverXY || pending || dragging || boxSel) return;
+    if (dimMode3d) {                           // dim tool: snap marker + live preview line + readout (no member hover)
+      canvasEl.style.cursor = 'crosshair';
+      const ev = { clientX: lastHoverXY[0], clientY: lastHoverXY[1], altKey: dimLastAlt };
+      const r = dimPointAt(ev, dimDraft3d && dimDraft3d.a);
+      if (r) { marker.position.set(...r.p); marker.scale.setScalar(markerSize()); marker.visible = true; } else marker.visible = false;
+      if (dimDraft3d && r) {
+        const g = dim3dGeom(dimDraft3d.a, r.p, dimEffectiveAxis(dimLastAlt));
+        dimPreviewLine.geometry.setFromPoints([new THREE.Vector3(...g.p1), new THREE.Vector3(...g.p2)]); dimPreviewLine.visible = true;
+        readout._dist.textContent = api.fmtLen ? api.fmtLen(g.valueMm) : (g.valueMm / 304.8).toFixed(2) + ' ft';
+        readout._type.textContent = r.type ? ' · ' + r.type : (dimLastAlt ? ' ↕' : '');
+        readout.style.left = (lastHoverXY[0] + 14) + 'px'; readout.style.top = (lastHoverXY[1] + 14) + 'px'; readout.style.display = 'block';
+      } else { dimPreviewLine.visible = false; if (!dimDraft3d) readout.style.display = 'none'; }
+      return;
+    }
     let ep = null; try { ep = pickEndpoint(lastHoverXY[0], lastHoverXY[1]); } catch { ep = null; }
     if (ep) { // over an end node → ring + move cursor; keep its member's dots shown
       hoverEp = ep; canvasEl.style.cursor = 'move';
@@ -810,8 +966,12 @@ function updateStatusChip() {
   hoverChip.style.display = canvasEl.style.display === 'none' ? 'none' : 'block';
 }
 
-function show() { if (controls) controls.enabled = true; if (canvasEl) { canvasEl.style.display = 'block'; resize(); } if (!rafId) loop(); updateStatusChip(); } // resume the render loop (reset orbit in case a gesture was stranded by a mid-drag hide)
-function hide() { if (canvasEl) canvasEl.style.display = 'none'; if (hoverChip) hoverChip.style.display = 'none'; if (rafId) { cancelAnimationFrame(rafId); rafId = null; } }
+function show() { if (controls) controls.enabled = true; if (canvasEl) { canvasEl.style.display = 'block'; resize(); } if (!rafId) loop(); updateStatusChip(); refreshDims(); } // resume the render loop (reset orbit in case a gesture was stranded by a mid-drag hide)
+function hide() {
+  if (dimMode3d) toggleDimTool();              // disarm the dim tool + sync its toolbar (no stale draft/armed state on return)
+  if (dimLabelHost) dimLabelHost.style.display = 'none'; // the loop that hides labels is about to stop — hide synchronously so none are stranded
+  if (canvasEl) canvasEl.style.display = 'none'; if (hoverChip) hoverChip.style.display = 'none'; if (rafId) { cancelAnimationFrame(rafId); rafId = null; }
+}
 function isReady() { return built; }
 
 function dispose() {
@@ -822,14 +982,18 @@ function dispose() {
   window.removeEventListener('pointermove', onMove);
   window.removeEventListener('pointerup', onUp);
   window.removeEventListener('keydown', onKey);
-  for (const ovl of [readout, hoverChip, rubber]) if (ovl && ovl.parentNode) ovl.parentNode.removeChild(ovl);
+  for (const ovl of [readout, hoverChip, rubber, dimLabelHost]) if (ovl && ovl.parentNode) ovl.parentNode.removeChild(ovl);
+  dimLabelHost = null; dimLabelPool.length = 0;
   if (cube) {
     cube.scene.traverse((o) => { if (o.geometry) o.geometry.dispose(); const mm = Array.isArray(o.material) ? o.material : (o.material ? [o.material] : []); for (const m of mm) { if (m.map) m.map.dispose(); m.dispose(); } });
     cube.renderer.dispose(); if (cube.renderer.domElement.parentNode) cube.renderer.domElement.parentNode.removeChild(cube.renderer.domElement); cube = null;
   }
   if (epGeom) epGeom.dispose(); if (epMatStart) epMatStart.dispose(); if (epMatEnd) epMatEnd.dispose();
-  for (const o of [epRing, epPreview, refGroup]) if (o) { if (o.geometry) o.geometry.dispose(); if (o.material) o.material.dispose(); }
+  if (dims3dGroup) { if (scene) scene.remove(dims3dGroup); for (const c of dims3dGroup.children) { c.geometry.dispose(); c.material.dispose(); } } // placed-dim lines
+  if (dimPreviewLine && scene) scene.remove(dimPreviewLine);
+  for (const o of [epRing, epPreview, refGroup, dimPreviewLine]) if (o) { if (o.geometry) o.geometry.dispose(); if (o.material) o.material.dispose(); }
   epGeom = epMatStart = epMatEnd = epRing = epPreview = refGroup = null;
+  dims3dGroup = dimPreviewLine = null;
   clearRoot();
   if (renderer) renderer.dispose();
   renderer = scene = camera = perspCam = orthoCam = controls = root = api = canvasEl = ro = null; built = false;
@@ -879,5 +1043,8 @@ window.Steel3DView = {
   setProjection, projection, setDisplayMode, mode: () => displayMode, frameAll, frameSelection, applyView,
   setRefLine, refLine: () => refLineOn,
   toggleGroup, soloToggle, showAllGroups, groupState, getGroups,
+  toggleDimTool, setDimAxis, dimAxis, setDims3dVisible, dims3dVisible, refreshDims,
+  dims3dCount: () => (api && api.getDims3d ? (api.getDims3d() || []).length : 0),
+  dim3dLabelOf: (i) => { const el = dimLabelPool[i]; if (!el || el.style.display === 'none') return null; const r = el.getBoundingClientRect(); return { x: r.left + r.width / 2, y: r.top + r.height / 2, text: el.textContent }; },
   debug, probe, screenOf, centerOf,
 };