feat(scopes): migrate GPL open backend + web e2e to scope grammar

backend-example (open ref backend): USER_HEADER, scope on the project DTO, raw routes under /api/scopes/:scope, no-op reportDrift + DOM lib (was red on main → now typecheck-green). GPL web specs (tools-open, symbol/footprint-write-remote, global-setup-web): /p/demo/:tool/* → /:scope/projects/demo/(file | -/:tool), direct API fetches scoped + x-pcbjam-owner → x-pcbjam-user. Reference backend keeps lib type 'user' (cosmetic vs closed 'org').

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tests/web/footprint-write-remote.spec.ts

@@ -1,8 +1,10 @@
 import { test, expect, type Page } from '@playwright/test';
 import { waitForRegistry, clickByTooltip } from '../e2e/utils/element-tracker';
 
-// Mirrors @pcbjam/shared OWNER_HEADER (tests/ doesn't depend on the shared pkg).
+// Mirrors @pcbjam/shared USER_HEADER (tests/ doesn't depend on the shared pkg).
-const OWNER_HEADER = 'x-pcbjam-owner';
+const USER_HEADER = 'x-pcbjam-user';
+// The reference backend serves its single project/libs under any scope.
+const SCOPE = 'default';
 
 /**
  * 0009-C: the FULL remote footprint write round-trip — no in-memory spike. Boot
@@ -51,7 +53,7 @@ test('footprint editor save persists to the backend (remote write round-trip)',
   page.on('console', (m) => logs.push(`[${m.type()}] ${m.text()}`));
   page.on('pageerror', (e) => logs.push(`[pageerror] ${e.message}`));
 
-  await page.goto(`/p/demo/footprint_editor/?libowner=${owner}`);
+  await page.goto(`/default/projects/demo/-/footprint_editor?libowner=${owner}`);
   await expect(page.locator('#canvas')).toBeVisible({ timeout: 180000 });
   await waitForRegistry(page, 180000);
   await page.waitForFunction(
@@ -64,8 +66,8 @@ test('footprint editor save persists to the backend (remote write round-trip)',
   await page.screenshot({ path: SHOT('01-boot'), scale: 'css' });
 
   // Boot's ensure-user-lib created the writable container for this owner.
-  const ownerHeaders = { [OWNER_HEADER]: owner };
+  const ownerHeaders = { [USER_HEADER]: owner };
-  const libsRes = await fetch(`${BACKEND}/api/libs?kind=footprint`, { headers: ownerHeaders });
+  const libsRes = await fetch(`${BACKEND}/api/scopes/${SCOPE}/libs?kind=footprint`, { headers: ownerHeaders });
   const libsBody = (await libsRes.json()) as { id: string; type: string }[];
   logs.push(`[spec] libs: ${JSON.stringify(libsBody)}`);
   expect(libsBody.some((l) => l.type === 'user' && l.id === USER_LIB), 'user lib created at boot').toBe(true);
@@ -89,7 +91,7 @@ test('footprint editor save persists to the backend (remote write round-trip)',
   await expect
     .poll(
       async () => {
-        const r = await fetch(`${BACKEND}/api/libs/${USER_LIB}/items`, { headers: ownerHeaders });
+        const r = await fetch(`${BACKEND}/api/scopes/${SCOPE}/libs/${USER_LIB}/items`, { headers: ownerHeaders });
         items = r.ok ? ((await r.json()) as { kind: string; name: string }[]) : [];
         return items.filter((i) => i.kind === 'footprint').length;
       },
@@ -103,7 +105,7 @@ test('footprint editor save persists to the backend (remote write round-trip)',
 
   // The persisted body is a well-formed fork-native footprint (native version).
   const bodyRes = await fetch(
-    `${BACKEND}/api/libs/${USER_LIB}/items/footprint/${encodeURIComponent(saved.name)}`,
+    `${BACKEND}/api/scopes/${SCOPE}/libs/${USER_LIB}/items/footprint/${encodeURIComponent(saved.name)}`,
     { headers: ownerHeaders },
   );
   const body = await bodyRes.text();

tests/web/global-setup-web.ts

@@ -11,6 +11,9 @@ import type { FullConfig } from '@playwright/test';
  */
 
 const API_BASE = process.env.BACKEND_URL ?? 'http://localhost:3060';
+// The reference backend serves its single project under any scope; the editor
+// addresses it as /:scope/projects/:name, so the specs use a fixed scope.
+const SCOPE = 'default';
 const DEMO_SLUG = 'demo';
 const DEMO_FILES = ['demo.kicad_sch', 'demo.kicad_pcb', 'demo.kicad_wks'];
 // Origin libs the remote-lib specs browse/place (symbol-write/footprint-browse).
@@ -41,10 +44,10 @@ async function waitForApi(timeoutMs = 60000): Promise<void> {
 }
 
 async function verifyDemoProject(): Promise<void> {
-  const r = await fetch(`${API_BASE}/api/projects/${DEMO_SLUG}`);
+  const r = await fetch(`${API_BASE}/api/scopes/${SCOPE}/projects/${DEMO_SLUG}`);
   if (!r.ok) {
     throw new Error(
-      `GET /api/projects/${DEMO_SLUG} -> HTTP ${r.status}; ` +
+      `GET /api/scopes/${SCOPE}/projects/${DEMO_SLUG} -> HTTP ${r.status}; ` +
         `is the backend's PROJECT_DIR pointing at tests/fixtures/demo?`
     );
   }
@@ -58,9 +61,9 @@ async function verifyDemoProject(): Promise<void> {
 
 async function verifyLibs(): Promise<void> {
   for (const kind of ['symbol', 'footprint'] as const) {
-    const r = await fetch(`${API_BASE}/api/libs?kind=${kind}`);
+    const r = await fetch(`${API_BASE}/api/scopes/${SCOPE}/libs?kind=${kind}`);
     if (!r.ok) {
-      throw new Error(`GET /api/libs?kind=${kind} -> HTTP ${r.status}`);
+      throw new Error(`GET /api/scopes/${SCOPE}/libs?kind=${kind} -> HTTP ${r.status}`);
     }
     const libs = (await r.json()) as { id: string }[];
     const have = new Set(libs.map((l) => l.id));

tests/web/symbol-write-remote.spec.ts

@@ -1,8 +1,10 @@
 import { test, expect, type Page } from '@playwright/test';
 import { waitForRegistry, clickByTooltip } from '../e2e/utils/element-tracker';
 
-// Mirrors @pcbjam/shared OWNER_HEADER (tests/ doesn't depend on the shared pkg).
+// Mirrors @pcbjam/shared USER_HEADER (tests/ doesn't depend on the shared pkg).
-const OWNER_HEADER = 'x-pcbjam-owner';
+const USER_HEADER = 'x-pcbjam-user';
+// The reference backend serves its single project/libs under any scope.
+const SCOPE = 'default';
 
 /**
  * 0004-D: the FULL remote write round-trip — no in-memory spike. Boot ensures a
@@ -30,7 +32,7 @@ test('symbol editor save persists to the backend (remote write round-trip)', asy
   page.on('console', (m) => logs.push(`[${m.type()}] ${m.text()}`));
   page.on('pageerror', (e) => logs.push(`[pageerror] ${e.message}`));
 
-  await page.goto(`/p/demo/symbol_editor/?libowner=${owner}`);
+  await page.goto(`/default/projects/demo/-/symbol_editor?libowner=${owner}`);
   await expect(page.locator('#canvas')).toBeVisible({ timeout: 150000 });
   await waitForRegistry(page, 150000);
   await page.waitForFunction(
@@ -43,8 +45,8 @@ test('symbol editor save persists to the backend (remote write round-trip)', asy
   await page.screenshot({ path: SHOT('01-boot'), scale: 'css' });
 
   // Boot's ensure-user-lib created "My Symbols" (slug my-symbols) for this owner.
-  const ownerHeaders = { [OWNER_HEADER]: owner };
+  const ownerHeaders = { [USER_HEADER]: owner };
-  const libsRes = await fetch(`${BACKEND}/api/libs`, { headers: ownerHeaders });
+  const libsRes = await fetch(`${BACKEND}/api/scopes/${SCOPE}/libs`, { headers: ownerHeaders });
   const libsBody = (await libsRes.json()) as { id: string; type: string }[];
   expect(libsBody.some((l) => l.type === 'user' && l.id === 'my-symbols'), 'user lib created at boot').toBe(true);
 
@@ -96,7 +98,7 @@ test('symbol editor save persists to the backend (remote write round-trip)', asy
   await expect
     .poll(
       async () => {
-        const r = await fetch(`${BACKEND}/api/libs/my-symbols/items`, { headers: ownerHeaders });
+        const r = await fetch(`${BACKEND}/api/scopes/${SCOPE}/libs/my-symbols/items`, { headers: ownerHeaders });
         items = r.ok ? ((await r.json()) as { kind: string; name: string }[]) : [];
         return items.length;
       },
@@ -110,7 +112,7 @@ test('symbol editor save persists to the backend (remote write round-trip)', asy
 
   // The persisted body is a well-formed fork-native kicad_symbol_lib.
   const bodyRes = await fetch(
-    `${BACKEND}/api/libs/my-symbols/items/symbol/${encodeURIComponent(saved.name)}`,
+    `${BACKEND}/api/scopes/${SCOPE}/libs/my-symbols/items/symbol/${encodeURIComponent(saved.name)}`,
     { headers: ownerHeaders },
   );
   const body = await bodyRes.text();

tests/web/tools-open.spec.ts

@@ -11,8 +11,12 @@ import { test, expect, type Page } from '@playwright/test';
  * ensured by global-setup-web.ts.
  */
 
+/** Scope segment for the demo project (the reference backend serves it for any). */
+const SCOPE = 'default';
+
 interface ToolCase {
-  /** URL path after /p/demo/ */
+  /** URL tail after /:scope/projects/demo/ — a file path (tool inferred from the
+   *  extension) for file tools, or `-/<tool>` for a file-less boot. */
   route: string;
   /** title the document settles on once the tool is up / file is open */
   titleRe: RegExp;
@@ -21,13 +25,13 @@ interface ToolCase {
 }
 
 const CASES: Record<string, ToolCase> = {
-  eeschema: { route: 'eeschema/demo.kicad_sch', titleRe: /demo — Schematic Editor/i, fileless: false },
+  eeschema: { route: 'demo.kicad_sch', titleRe: /demo — Schematic Editor/i, fileless: false },
-  pcbnew: { route: 'pcbnew/demo.kicad_pcb', titleRe: /demo — PCB Editor/i, fileless: false },
+  pcbnew: { route: 'demo.kicad_pcb', titleRe: /demo — PCB Editor/i, fileless: false },
-  pl_editor: { route: 'pl_editor/demo.kicad_wks', titleRe: /demo — Drawing Sheet Editor/i, fileless: false },
+  pl_editor: { route: 'demo.kicad_wks', titleRe: /demo — Drawing Sheet Editor/i, fileless: false },
-  calculator: { route: 'calculator/', titleRe: /Calculator Tools/i, fileless: true },
+  calculator: { route: '-/calculator', titleRe: /Calculator Tools/i, fileless: true },
-  symbol_editor: { route: 'symbol_editor/', titleRe: /Symbol Editor/i, fileless: true },
+  symbol_editor: { route: '-/symbol_editor', titleRe: /Symbol Editor/i, fileless: true },
-  footprint_editor: { route: 'footprint_editor/', titleRe: /Footprint Editor/i, fileless: true },
+  footprint_editor: { route: '-/footprint_editor', titleRe: /Footprint Editor/i, fileless: true },
-  gerbview: { route: 'gerbview/', titleRe: /Gerber Viewer/i, fileless: true },
+  gerbview: { route: '-/gerbview', titleRe: /Gerber Viewer/i, fileless: true },
 };
 
 /** Console text that must never appear (wizard-crash + URL-regex modal markers). */
@@ -38,7 +42,7 @@ async function bootAndAssert(page: Page, tc: ToolCase): Promise<void> {
   page.on('console', (m) => consoleLines.push(m.text()));
   page.on('pageerror', (e) => consoleLines.push(`pageerror: ${e.message}`));
 
-  await page.goto(`/p/demo/${tc.route}`);
+  await page.goto(`/${SCOPE}/projects/demo/${tc.route}`);
 
   // boot.ts mounts the Emscripten <canvas id="canvas"> once the runtime starts.
   await expect(page.locator('#canvas')).toBeVisible({ timeout: 120000 });

web/backend/src/server.ts

@@ -16,7 +16,7 @@ import Fastify from "fastify";
 import { initServer } from "@ts-rest/fastify";
 import {
   contract,
-  OWNER_HEADER,
+  USER_HEADER,
   type Project,
   type ProjectFile,
 } from "@pcbjam/shared";
@@ -39,11 +39,13 @@ import {
   writeUserItem,
 } from "./user-libs.js";
 
-/** The (thin, pre-auth) owner from OWNER_HEADER; absent ⇒ the default owner. */
+/** The (thin, pre-auth) user from USER_HEADER; absent ⇒ the default. User libs
-function ownerOf(
+ *  are namespaced by this slug (this reference backend serves one project off the
+ *  filesystem regardless of the URL scope). */
+function userOf(
   headers: Record<string, string | string[] | undefined>,
 ): string {
-  const v = headers[OWNER_HEADER];
+  const v = headers[USER_HEADER];
   const s = Array.isArray(v) ? v[0] : v;
   return (s && String(s).trim()) || DEFAULT_OWNER;
 }
@@ -131,10 +133,13 @@ async function walk(dir: string, prefix = ""): Promise<ProjectFile[]> {
   return out;
 }
 
-async function project(): Promise<Project> {
+// The reference backend serves one project for any scope; it echoes back the
+// requested scope so the editor's links stay consistent.
+async function project(scope: string): Promise<Project> {
   const st = await fs.stat(PROJECT_DIR);
   return {
     id: PROJECT_ID,
+    scope,
     slug: SLUG,
     name: path.basename(PROJECT_DIR) || SLUG,
     createdAt: st.birthtime.toISOString(),
@@ -161,14 +166,20 @@ async function main(): Promise<void> {
 
   const s = initServer();
   const router = s.router(contract, {
-    listProjects: async () => ({ status: 200, body: [await project()] }),
+    listProjects: async ({ params }) => ({
+      status: 200,
+      body: [await project(params.scope)],
+    }),
     getProject: async ({ params }) => {
       if (params.project !== SLUG) {
         return { status: 404 as const, body: { message: "project not found" } };
       }
       return {
         status: 200 as const,
-        body: { project: await project(), files: await walk(PROJECT_DIR) },
+        body: {
+          project: await project(params.scope),
+          files: await walk(PROJECT_DIR),
+        },
       };
     },
     listFiles: async ({ params }) => {
@@ -178,7 +189,7 @@ async function main(): Promise<void> {
       return { status: 200 as const, body: await walk(PROJECT_DIR) };
     },
     listLibs: async ({ headers, query }) => {
-      const owner = ownerOf(headers);
+      const owner = userOf(headers);
       // Origins filtered by item kind (?kind); user libs are kind-agnostic
       // containers → always listed.
       const [origins, user] = await Promise.all([
@@ -189,7 +200,7 @@ async function main(): Promise<void> {
     },
     listLibItems: async ({ params, headers }) => {
       // User libs win over origins on an id clash (the editor's writable lib).
-      const user = await listUserItems(userLibs, ownerOf(headers), params.lib);
+      const user = await listUserItems(userLibs, userOf(headers), params.lib);
       const items = user ?? (await listLibItems(libs, params.lib));
       if (items === null) {
         return { status: 404 as const, body: { message: "library not found" } };
@@ -198,7 +209,7 @@ async function main(): Promise<void> {
     },
     createLib: async ({ body, headers }) => {
       try {
-        const lib = await createUserLib(userLibs, ownerOf(headers), body.name);
+        const lib = await createUserLib(userLibs, userOf(headers), body.name);
         return { status: 201 as const, body: lib };
       } catch (e) {
         if (e instanceof UserLibError && e.status === 409) {
@@ -210,16 +221,23 @@ async function main(): Promise<void> {
         };
       }
     },
+    // The reference backend has no drift store; collaboration here is tab-only
+    // (BroadcastChannel). Accept-and-ignore: the editor reports drift best-effort
+    // and ignores failures, so a 404 is harmless and needs no storage.
+    reportDrift: async () => ({
+      status: 404 as const,
+      body: { message: "drift reporting not supported by the reference backend" },
+    }),
   });
   await app.register(s.plugin(router));
 
   // Streamed item-body fetch (text; intentionally not a ts-rest endpoint).
   // User libs are resolved first (owner-scoped), then read-only origins.
-  app.get<{ Params: { lib: string; kind: string; name: string } }>(
+  app.get<{ Params: { scope: string; lib: string; kind: string; name: string } }>(
-    "/api/libs/:lib/items/:kind/:name",
+    "/api/scopes/:scope/libs/:lib/items/:kind/:name",
     async (req, reply) => {
       const { lib, kind, name } = req.params;
-      const userPath = userItemBodyPath(userLibs, ownerOf(req.headers), lib, kind, name);
+      const userPath = userItemBodyPath(userLibs, userOf(req.headers), lib, kind, name);
       const userExists =
         userPath && (await fs.stat(userPath).then((st) => st.isFile()).catch(() => false));
       const abs = userExists ? userPath! : itemBodyPath(libs, lib, kind, name);
@@ -235,8 +253,8 @@ async function main(): Promise<void> {
   );
 
   // Item-body WRITE (text; the mirror of the GET above). Owner from OWNER_HEADER.
-  app.put<{ Params: { lib: string; kind: string; name: string } }>(
+  app.put<{ Params: { scope: string; lib: string; kind: string; name: string } }>(
-    "/api/libs/:lib/items/:kind/:name",
+    "/api/scopes/:scope/libs/:lib/items/:kind/:name",
     async (req, reply) => {
       const { lib, kind, name } = req.params;
       const body = typeof req.body === "string" ? req.body : "";
@@ -244,7 +262,7 @@ async function main(): Promise<void> {
       try {
         const item = await writeUserItem(
           userLibs,
-          ownerOf(req.headers),
+          userOf(req.headers),
           lib,
           kind,
           name,
@@ -261,8 +279,8 @@ async function main(): Promise<void> {
   );
 
   // Streamed file-byte download (binary; intentionally not a ts-rest endpoint).
-  app.get<{ Params: { project: string; "*": string } }>(
+  app.get<{ Params: { scope: string; project: string; "*": string } }>(
-    "/api/projects/:project/files/*",
+    "/api/scopes/:scope/projects/:project/files/*",
     async (req, reply) => {
       if (req.params.project !== SLUG) {
         return reply.code(404).send({ message: "project not found" });

web/backend/tsconfig.json

@@ -1,7 +1,7 @@
 {
   "extends": "../tsconfig.base.json",
   "compilerOptions": {
-    "lib": ["ES2022"],
+    "lib": ["ES2022", "DOM"],
     "types": ["node"],
     "moduleResolution": "Bundler",
     "noEmit": true,