fix(backend): reviewer-page form and point cloud, store-sync paths

backend/scripts/sync_from_store.sh

@@ -22,6 +22,11 @@ if [[ -z "${STORE:-}" || ! -d "$STORE/internal" ]]; then
   exit 1
 fi
 
+# Before the port into the BaseScanning monorepo the git toplevel was this
+# package, so the toplevel held packet/, eval/ and the rest. The toplevel is
+# now the monorepo root one level above backend/: git operations still run at
+# the toplevel, but every copied file anchors under the package root.
+PACKAGE="$(cd "$(dirname "$0")/.." && pwd)"
 REPO="$(git -C "$(dirname "$0")" rev-parse --show-toplevel)"
 cd "$REPO"
 
@@ -44,16 +49,16 @@ RSYNC_OPTS=(-a --delete --max-size=5m
   --exclude=.pytest_cache --exclude=.ruff_cache --exclude=.DS_Store)
 
 mirror() {  # mirror <store-relative-src-dir> <repo-dst-dir> [extra rsync args]
-  local src="$STORE/$1" dst="$REPO/$2"
+  local src="$STORE/$1" dst="$PACKAGE/$2"
   shift 2
   if [[ ! -d "$src" ]]; then echo "skip: $src missing"; return; fi
   mkdir -p "$dst"
   rsync "${RSYNC_OPTS[@]}" "$@" "$src/" "$dst/"
-  echo "synced $src -> ${dst#"$REPO"/}"
+  echo "synced $src -> ${dst#"$PACKAGE"/}"
 }
 
 copy_file() {  # copy_file <store-relative-src> <repo-dst>
-  local src="$STORE/$1" dst="$REPO/$2"
+  local src="$STORE/$1" dst="$PACKAGE/$2"
   if [[ ! -f "$src" ]]; then echo "skip: $src missing"; return; fi
   mkdir -p "$(dirname "$dst")"
   cp "$src" "$dst"

backend/server/api/routes/result.py

@@ -5,7 +5,7 @@
 import json
 
 from fastapi import FastAPI, Request
-from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.responses import HTMLResponse, JSONResponse, Response
 from pydantic import ValidationError
 
 from server.api.deps import get_deps, load_owned, require_principal
@@ -121,3 +121,22 @@ def get_review(capture_id: str, request: Request):
         except FileNotFoundError as exc:
             raise fail(404, "result_not_ready", "/", "review is not ready") from exc
         return HTMLResponse(html)
+
+    @app.get("/v1/captures/{capture_id}/preview.ply")
+    def get_preview(capture_id: str, request: Request):
+        """Serve the run's result/preview.ply so the review page's relative fetch works."""
+        principal = require_principal(request)
+        deps = get_deps(request)
+        deps.charge(principal.label, "get", 120)
+        if deps.settings.HSS_AUTH_MODE != "none" and not principal.reviewer:
+            raise fail(403, "forbidden", "/", "review is for reviewers")
+        load_owned(deps, capture_id, principal)
+        run = _latest(deps, capture_id)
+        key = _artifacts(deps, run).get("result/preview.ply") if run else None
+        if not key:
+            raise fail(404, "result_not_ready", "/", "preview is not ready")
+        try:
+            data = deps.storage.get_bytes(key)
+        except FileNotFoundError as exc:
+            raise fail(404, "result_not_ready", "/", "preview is not ready") from exc
+        return Response(content=data, media_type="application/octet-stream")

backend/server/api/tests/test_auth_none.py

@@ -105,6 +105,105 @@ def test_missing_authorization_is_the_demo_device(tmp_path) -> None:
     assert b"decision: reject" in review.content
 
 
+def test_review_page_preview_ply_is_served_and_reviewer_gated(tmp_path) -> None:
+    """The review page's relative fetch("preview.ply") must resolve through the API.
+
+    Served at GET /v1/captures/{id}/review, the browser resolves the page's
+    relative preview fetch to /v1/captures/{id}/preview.ply — PR #249 review
+    finding 1: nothing served that, so the point cloud never drew.
+    """
+
+    ply_bytes = (
+        b"ply\nformat binary_little_endian 1.0\nelement vertex 1\n"
+        b"property float x\nproperty float y\nproperty float z\nend_header\n"
+    ) + b"\x00" * 12
+    device_token = "d" * 40
+    reviewer_token = "r" * 40
+
+    def _boot(settings: Settings):
+        app = create_app(settings=settings)
+        return app, TestClient(app)
+
+    def _stage_preview(app, capture_id: str) -> None:
+        deps = app.state.deps
+        html_key = f"captures/{capture_id}/result/review.html"
+        ply_key = f"captures/{capture_id}/result/preview.ply"
+        deps.storage.put_bytes(html_key, b"<p>review</p>", "text/html")
+        deps.storage.put_bytes(ply_key, ply_bytes, "application/octet-stream")
+        deps.state.put_run(
+            RunRecord(
+                run_id=f"run_{capture_id}",
+                capture_id=capture_id,
+                packet_sha256="c" * 64,
+                status="done",
+                branch="image",
+                flow="photo",
+                tier="photo_only",
+                profile_default="C",
+                created_at="2026-09-26T00:00:00.000Z",
+                deadline_at="2026-09-26T01:00:00.000Z",
+                artifacts={"result/review.html": html_key, "result/preview.ply": ply_key},
+            )
+        )
+        deps.state.upsert_stage(
+            StageRecord(
+                run_id=f"run_{capture_id}",
+                stage="result",
+                status="done",
+                attempt=1,
+                heartbeat="2026-09-26T00:00:00.000Z",
+            )
+        )
+
+    # Auth-none demo mode: the page and its relative preview fetch both resolve.
+    app, client = _boot(_settings(tmp_path))
+    created = client.post(
+        "/v1/captures",
+        json=create_body("packet-preview"),
+        headers={"Idempotency-Key": "packet-preview"},
+    )
+    assert created.status_code == 201, created.text
+    capture_id = created.json()["captureId"]
+    _stage_preview(app, capture_id)
+
+    review = client.get(f"/v1/captures/{capture_id}/review")
+    assert review.status_code == 200, review.text
+    preview = client.get(f"/v1/captures/{capture_id}/preview.ply")
+    assert preview.status_code == 200, preview.text
+    assert preview.content == ply_bytes
+    assert preview.headers["content-type"] == "application/octet-stream"
+
+    # Static mode: the artifact is reviewer-gated, same as the page that links it.
+    static_settings = _settings(
+        tmp_path,
+        HSS_AUTH_MODE="static",
+        CAPTURE_API_TOKENS=f"dev:{device_token},reviewer:rev:{reviewer_token}",
+    )
+    app, client = _boot(static_settings)
+    created = client.post(
+        "/v1/captures",
+        json=create_body("packet-preview-static"),
+        headers={"Idempotency-Key": "packet-preview-static", "Authorization": f"Bearer {device_token}"},
+    )
+    assert created.status_code == 201, created.text
+    capture_id = created.json()["captureId"]
+    _stage_preview(app, capture_id)
+
+    anonymous = client.get(f"/v1/captures/{capture_id}/preview.ply")
+    assert anonymous.status_code == 401, anonymous.text
+    device = client.get(
+        f"/v1/captures/{capture_id}/preview.ply",
+        headers={"Authorization": f"Bearer {device_token}"},
+    )
+    assert device.status_code == 403, device.text
+    reviewer = client.get(
+        f"/v1/captures/{capture_id}/preview.ply",
+        headers={"Authorization": f"Bearer {reviewer_token}"},
+    )
+    assert reviewer.status_code == 200, reviewer.text
+    assert reviewer.content == ply_bytes
+
+
 def test_replay_mini_arkit_without_a_token(tmp_path) -> None:
     app = create_app(settings=_settings(tmp_path))
     client = TestClient(app)

backend/server/result/review/template.html

@@ -112,14 +112,58 @@ <h2>Views needed</h2>
 <section>
   <h2>Meter</h2>
   <p>Status {{ meter.status }} · value {{ meter.value }} · candidates {{ meter.candidates }}</p>
-  <form method="post" action="/captures/{{ capture_id }}/confirmations">
+  <form id="meter-confirm" method="post" action="/v1/captures/{{ capture_id }}/confirmations">
     <input type="hidden" name="fieldId" value="meter_number">
     <input type="hidden" name="kind" value="confirmed">
     <input type="hidden" name="imageId" value="{{ meter.evidence.image if meter.evidence else "" }}">
     <label>Value <input name="value" value="{{ meter.value or "" }}"></label>
     <label>Client time <input name="clientAt" value="2026-09-26T00:00:00Z"></label>
+    <label>API token <input type="password" id="confirm-token" autocomplete="off" placeholder="reviewer token"></label>
     <button type="submit">Confirm meter number</button>
+    <p id="confirm-status" hidden></p>
   </form>
+  <script>
+    (() => {
+      const form = document.getElementById("meter-confirm");
+      if (!form) return;
+      const tokenInput = document.getElementById("confirm-token");
+      const status = document.getElementById("confirm-status");
+      const tokenKey = "hss-review-token";
+      if (tokenInput && sessionStorage.getItem(tokenKey)) tokenInput.value = sessionStorage.getItem(tokenKey);
+      const report = (message) => {
+        if (!status) return;
+        status.textContent = message;
+        status.hidden = false;
+      };
+      form.addEventListener("submit", async (event) => {
+        event.preventDefault();
+        const headers = { "Content-Type": "application/json" };
+        const token = tokenInput ? tokenInput.value.trim() : "";
+        if (token) {
+          headers["Authorization"] = "Bearer " + token;
+          sessionStorage.setItem(tokenKey, token);
+        }
+        const payload = {
+          fieldId: form.elements.fieldId.value,
+          kind: form.elements.kind.value,
+          value: form.elements.value.value || null,
+          imageId: form.elements.imageId.value,
+          clientAt: form.elements.clientAt.value,
+        };
+        try {
+          const res = await fetch(form.action, { method: "POST", headers, body: JSON.stringify(payload) });
+          const body = await res.json().catch(() => null);
+          if (res.ok) {
+            report("Confirmed" + (body && body.confirmationId ? " (" + body.confirmationId + ")" : ""));
+          } else {
+            report("Rejected: " + ((body && body.errors && body.errors[0] && body.errors[0].message) || ("HTTP " + res.status)));
+          }
+        } catch {
+          report("Network error: the confirmation did not reach the API.");
+        }
+      });
+    })();
+  </script>
 </section>
 
 <section>
@@ -129,9 +173,151 @@ <h2>Preview</h2>
   <script type="module">
     import * as THREE from "{{ three_url }}";
     const note = document.getElementById("three-offline");
-    if (note) note.hidden = true;
-    const renderer = new THREE.WebGLRenderer();
-    document.getElementById("cloud").appendChild(renderer.domElement);
+    const cloud = document.getElementById("cloud");
+    const fail = (message) => {
+      if (!note) return;
+      note.hidden = false;
+      note.textContent = message;
+    };
+    // Binary little-endian PLY as written by server.result.preview: one vertex
+    // element, fixed-width rows, properties of float/double/int/uchar.
+    function parseBinaryPly(buffer) {
+      const bytes = new Uint8Array(buffer);
+      const marker = "end_header";
+      let headerEnd = -1;
+      let headerText = "";
+      const limit = Math.min(bytes.length, 64 * 1024);
+      for (let i = 0; i < limit - marker.length; i++) {
+        if (bytes[i] === 101 && bytes[i + 1] === 110 && bytes[i + 2] === 100
+          && bytes[i + 3] === 95 && bytes[i + 4] === 104 && bytes[i + 5] === 101
+          && bytes[i + 6] === 97 && bytes[i + 7] === 100 && bytes[i + 8] === 101
+          && bytes[i + 9] === 114) {
+          headerEnd = i + marker.length;
+          break;
+        }
+      }
+      if (headerEnd < 0) throw new Error("no end_header");
+      headerText = new TextDecoder("ascii").decode(bytes.subarray(0, headerEnd));
+      if (!headerText.startsWith("ply") || !headerText.includes("binary_little_endian")) {
+        throw new Error("only binary_little_endian PLY is supported");
+      }
+      const lines = headerText.split("\n").map((line) => line.trim()).filter(Boolean);
+      const vertexIndex = lines.findIndex((line) => /^element vertex \d+$/.test(line));
+      if (vertexIndex < 0) throw new Error("no vertex element");
+      const count = Number(lines[vertexIndex].split(" ")[2]);
+      const sizes = { float: 4, double: 8, int: 4, uint: 4, short: 2, ushort: 2, uchar: 1, char: 1 };
+      const props = [];
+      let stride = 0;
+      for (const line of lines.slice(vertexIndex + 1)) {
+        if (!line.startsWith("property ")) break;
+        const [, , type, name] = line.split(/\s+/);
+        if (!(type in sizes)) throw new Error("unsupported property type " + type);
+        props.push({ name, type, offset: stride });
+        stride += sizes[type];
+      }
+      const read = {
+        float: (view, at) => view.getFloat32(at, true),
+        double: (view, at) => view.getFloat64(at, true),
+        int: (view, at) => view.getInt32(at, true),
+        uint: (view, at) => view.getUint32(at, true),
+        short: (view, at) => view.getInt16(at, true),
+        ushort: (view, at) => view.getUint16(at, true),
+        uchar: (view, at) => view.getUint8(at),
+        char: (view, at) => view.getInt8(at),
+      };
+      if (buffer.byteLength < headerEnd + 1 + count * stride) {
+        throw new Error("vertex data truncated");
+      }
+      const view = new DataView(buffer, headerEnd + 1);
+      const positions = new Float32Array(count * 3);
+      const generated = new Uint8Array(count);
+      let hasGenerated = false;
+      for (const prop of props) {
+        if (prop.name === "generated") hasGenerated = true;
+      }
+      for (let v = 0; v < count; v++) {
+        const base = v * stride;
+        for (const prop of props) {
+          const value = read[prop.type](view, base + prop.offset);
+          if (prop.name === "x") positions[v * 3] = value;
+          else if (prop.name === "y") positions[v * 3 + 1] = value;
+          else if (prop.name === "z") positions[v * 3 + 2] = value;
+          else if (prop.name === "generated") generated[v] = value;
+        }
+      }
+      return { positions, generated, hasGenerated };
+    }
+    try {
+      const res = await fetch("preview.ply");
+      if (!res.ok) throw new Error("preview.ply request failed with HTTP " + res.status);
+      const cloudData = parseBinaryPly(await res.arrayBuffer());
+      if (cloudData.positions.length === 0) throw new Error("preview.ply holds no points");
+      const geometry = new THREE.BufferGeometry();
+      geometry.setAttribute("position", new THREE.BufferAttribute(cloudData.positions, 3));
+      const colors = new Float32Array(cloudData.positions.length);
+      for (let v = 0; v < cloudData.generated.length; v++) {
+        if (cloudData.generated[v]) {
+          colors[v * 3] = 0.85; colors[v * 3 + 1] = 0.6; colors[v * 3 + 2] = 0.1;
+        } else {
+          colors[v * 3] = 0.16; colors[v * 3 + 1] = 0.5; colors[v * 3 + 2] = 0.66;
+        }
+      }
+      geometry.setAttribute("color", new THREE.BufferAttribute(colors, 3));
+      geometry.computeBoundingBox();
+      const bounds = geometry.boundingBox;
+      const center = new THREE.Vector3();
+      bounds.getCenter(center);
+      const radius = bounds.getSize(new THREE.Vector3()).length() / 2 || 1;
+      const scene = new THREE.Scene();
+      const material = new THREE.PointsMaterial({
+        size: radius / 80, vertexColors: true, sizeAttenuation: true,
+      });
+      scene.add(new THREE.Points(geometry, material));
+      const camera = new THREE.PerspectiveCamera(60, 1, radius / 500, radius * 20);
+      camera.position.set(center.x + radius * 1.6, center.y + radius * 1.2, center.z + radius * 1.6);
+      camera.lookAt(center);
+      const renderer = new THREE.WebGLRenderer({ antialias: true });
+      const width = Math.max(cloud.clientWidth || 640, 240);
+      const height = Math.max(Math.round(width * 0.5), 180);
+      renderer.setSize(width, height);
+      renderer.setPixelRatio(window.devicePixelRatio || 1);
+      cloud.appendChild(renderer.domElement);
+      let azimuth = 0;
+      let elevation = 0.35;
+      let distance = radius * 2.4;
+      const draw = () => {
+        const sinAz = Math.sin(azimuth);
+        camera.position.set(
+          center.x + distance * Math.cos(elevation) * Math.cos(azimuth),
+          center.y + distance * Math.sin(elevation),
+          center.z + distance * Math.cos(elevation) * sinAz,
+        );
+        camera.lookAt(center);
+        renderer.render(scene, camera);
+      };
+      let dragging = null;
+      renderer.domElement.addEventListener("pointerdown", (event) => {
+        dragging = { x: event.clientX, y: event.clientY };
+        renderer.domElement.setPointerCapture(event.pointerId);
+      });
+      renderer.domElement.addEventListener("pointermove", (event) => {
+        if (!dragging) return;
+        azimuth -= (event.clientX - dragging.x) / 200;
+        elevation = Math.min(1.5, Math.max(-1.5, elevation + (event.clientY - dragging.y) / 200));
+        dragging = { x: event.clientX, y: event.clientY };
+        draw();
+      });
+      renderer.domElement.addEventListener("pointerup", () => { dragging = null; });
+      renderer.domElement.addEventListener("wheel", (event) => {
+        event.preventDefault();
+        distance = Math.min(radius * 10, Math.max(radius * 0.5, distance * (1 + Math.sign(event.deltaY) * 0.1)));
+        draw();
+      }, { passive: false });
+      draw();
+      if (note) note.hidden = true;
+    } catch (error) {
+      fail("Point cloud preview unavailable: " + (error instanceof Error ? error.message : error));
+    }
   </script>
 </section>
 

backend/server/result/tests/test_compose.py

@@ -302,7 +302,7 @@ def test_review_page_lists_profiles_criteria_and_offline_notice(tmp_path):
         assert name in html
     assert "three.js" in html
     assert "offline" in html
-    assert 'action="/captures/cap_test/confirmations"' in html
+    assert 'action="/v1/captures/cap_test/confirmations"' in html
     assert "TODO queue" in html
     assert ("SS" + "R") not in html