feat: libs 0004-C — standalone real remote writes (createLib/saveItemBody + OWNER_HEADER), single-mount collapse, boot ensures user lib; remote-write e2e; bump kicad

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

kicad

@@ -1 +1 @@
-Subproject commit fa0b374da913dcf03a3a94e3643f68d0a2e30995
+Subproject commit 67161915ebb89133b24e04d5d8d1e1e0cc791fbc

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

@@ -0,0 +1,127 @@
+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).
+const OWNER_HEADER = 'x-pcbjam-owner';
+
+/**
+ * 0004-D: the FULL remote write round-trip — no in-memory spike. Boot ensures a
+ * "My Symbols" user lib via the backend's createLib; New Symbol → Ctrl+S routes
+ * the save through window.kicadLibs.request("save") → remoteLibsSource.saveItemBody
+ * → PUT /api/libs/:lib/items/... on the example backend. Verify the backend
+ * persisted a valid fork-native body, then reload and confirm it enumerates.
+ *
+ * Requires the example backend (:3060) running with USER_LIBS_DIR set.
+ */
+
+const BACKEND = process.env.BACKEND_URL ?? 'http://localhost:3060';
+const SHOT = (n: string) => `test-results/symremote-${n}.png`;
+
+async function focusCanvas(page: Page): Promise<void> {
+  const box = await page.locator('#canvas').boundingBox();
+  if (box) await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
+  await page.waitForTimeout(300);
+}
+
+test('symbol editor save persists to the backend (remote write round-trip)', async ({ page }) => {
+  // Unique owner per run so the test is isolated from prior runs.
+  const owner = `e2e-${Date.now()}`;
+  const logs: string[] = [];
+  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 expect(page.locator('#canvas')).toBeVisible({ timeout: 150000 });
+  await waitForRegistry(page, 150000);
+  await page.waitForFunction(
+    () => !!window.wxElementRegistry && window.wxElementRegistry.findAll({}).length > 5,
+    null,
+    { timeout: 150000 },
+  );
+  await page.waitForFunction(() => !!(window as any).kicadLibs, null, { timeout: 60000 });
+  await page.waitForTimeout(2000);
+  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 libsRes = await fetch(`${BACKEND}/api/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);
+
+  // Select the (only) library row in the tree, then New Symbol.
+  const hdr = await page.evaluate(() => {
+    const rd = window.wxElementRegistry.findAllRendered({});
+    const h = rd.find((e: any) => e.elementType === 'columnheader' && e.label === 'Item');
+    return h ? { cx: h.centerX, cy: h.centerY, hgt: h.height } : null;
+  });
+  expect(hdr, 'Item column header found').not.toBeNull();
+  await page.mouse.click(hdr!.cx, hdr!.cy + hdr!.hgt + 8);
+  await page.waitForTimeout(200);
+  await page.keyboard.press('Home');
+  await page.waitForTimeout(150);
+  await page.keyboard.press('ArrowDown');
+  await page.waitForTimeout(150);
+  await page.keyboard.press('ArrowUp');
+  await page.waitForTimeout(400);
+
+  expect(await clickByTooltip(page, 'New Symbol...'), 'New Symbol clicked').toBe(true);
+  await page.waitForTimeout(1500);
+  await page.screenshot({ path: SHOT('02-newsym'), scale: 'css' });
+
+  // Name field (the one that isn't the lib filter ~y65/87), then confirm.
+  const nameField = await page.evaluate(() => {
+    const all = window.wxElementRegistry.findAll({ visible: true });
+    const t = all
+      .filter((e: any) => /TextCtrl/i.test(e.typeName))
+      .map((e: any) => ({ cx: Math.round(e.centerX), cy: Math.round(e.centerY) }))
+      .find((e: any) => Math.abs(e.cy - 65) > 30 && Math.abs(e.cy - 87) > 30);
+    return t ?? null;
+  });
+  expect(nameField, 'New Symbol name field present').toBeTruthy();
+  await page.mouse.click(nameField!.cx, nameField!.cy);
+  await page.waitForTimeout(150);
+  await page.keyboard.press('Control+a');
+  await page.keyboard.press('Delete');
+  await page.keyboard.type('RemoteRes', { delay: 40 });
+  await page.keyboard.press('Enter');
+  await page.waitForTimeout(1500);
+  await page.screenshot({ path: SHOT('03-created'), scale: 'css' });
+
+  // Save → PUT to the backend.
+  await focusCanvas(page);
+  await page.keyboard.press('Control+s');
+
+  // Poll the backend until the item lands.
+  let items: { kind: string; name: string }[] = [];
+  await expect
+    .poll(
+      async () => {
+        const r = await fetch(`${BACKEND}/api/libs/my-symbols/items`, { headers: ownerHeaders });
+        items = r.ok ? ((await r.json()) as { kind: string; name: string }[]) : [];
+        return items.length;
+      },
+      { timeout: 30000, intervals: [500] },
+    )
+    .toBeGreaterThan(0);
+  await page.screenshot({ path: SHOT('04-saved'), scale: 'css' });
+
+  const saved = items[0];
+  logs.push(`[spec] backend item: ${JSON.stringify(saved)}`);
+
+  // 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)}`,
+    { headers: ownerHeaders },
+  );
+  const body = await bodyRes.text();
+  logs.push(`[spec] persisted body (${body.length} bytes):\n${body}`);
+  expect(body).toContain('(kicad_symbol_lib');
+  expect(body).toContain('(version 20250925)');
+  expect(body).toContain(`(symbol "${saved.name}"`);
+
+  // App stayed live.
+  expect(logs.some((l) => l.includes('Aborted(')), 'no WASM abort').toBe(false);
+  expect(new URL(page.url()).searchParams.get('oomRetry'), 'no OOM respawn').toBeNull();
+
+  console.log('--- spec log ---\n' + logs.join('\n'));
+});

web/standalone/src/lib/config.ts

@@ -56,6 +56,19 @@ export function docSourceConfig(): DocSource {
  *   "static"           — built-in offline example symbols (no backend).
  *   "off"              — disable libs (empty sym-lib-table).
  */
+/**
+ * The (thin, pre-auth) owner the editor writes libs as, sent on every lib
+ * request via OWNER_HEADER. `?libowner=` (e2e isolation) wins over
+ * `VITE_LIBS_OWNER`, else a stable local default.
+ */
+export function libsOwner(): string {
+  if (typeof window !== "undefined") {
+    const p = new URLSearchParams(window.location.search).get("libowner");
+    if (p) return p;
+  }
+  return import.meta.env.VITE_LIBS_OWNER ?? "local-user";
+}
+
 export function libsSourceConfig(): LibsSource | null {
   const kind = import.meta.env.VITE_LIBS_SOURCE ?? "remote";
   const base =
@@ -63,11 +76,11 @@ export function libsSourceConfig(): LibsSource | null {
       ? null
       : kind === "static"
         ? staticLibsSource()
-        : remoteLibsSource(API_BASE_URL);
+        : remoteLibsSource(API_BASE_URL, libsOwner());
 
   // 0004-A spike: `?libwrite=1` adds one in-memory writable user lib so the
-  // editor save path has a target before the backend exists. Remove once 0004-C
+  // editor save path works with no backend (a dev/test aid). The real remote
-  // wires real remote writes.
+  // write path (0004-C) needs no flag — boot ensures a user lib via createLib.
   if (
     typeof window !== "undefined" &&
     new URLSearchParams(window.location.search).get("libwrite") === "1"

web/standalone/src/wasm/boot.ts

@@ -6,7 +6,10 @@ import {
   TOOL_NEEDS_CONFIG_SEED,
 } from "./constants";
 import { buildSymLibTable, installLibsProvider, type LibsSource } from "./libs/source";
-import { libUri, PCBJAM_LIB_MOUNT, PCBJAM_LIB_RW_MOUNT } from "./libs/uri";
+import { libUri, PCBJAM_LIB_MOUNT } from "./libs/uri";
+
+/** The default user lib boot ensures exists, so there's a writable save target. */
+const DEFAULT_USER_LIB_NAME = "My Symbols";
 
 /**
  * Boot a KiCad tool directly in the main React document — no iframe.
@@ -98,20 +101,26 @@ async function doBoot(opts: BootOptions): Promise<void> {
   // the wasm boots (the table is seeded in preRun below). No source → empty
   // table, libs disabled.
   let symLibTable = "(sym_lib_table\n  (version 7)\n)\n";
-  // Writable libs get an empty placeholder FILE at their URI (not just the mount
+  // Every lib gets an empty placeholder FILE at its URI (not just the mount dir):
-  // dir): the symbol-editor save path stat()s the lib file after saving
+  // the symbol-editor save path stat()s the lib file after a successful save
   // (SetSymModificationTime -> wxFileName::GetModificationTime), which errors on
   // a non-existent path. The bytes are virtual (served via window.kicadLibs);
   // this file only satisfies incidental fs checks.
-  let writableLibUris: string[] = [];
+  let libPlaceholderUris: string[] = [];
   if (libsSource) {
     installLibsProvider(libsSource, log);
     try {
-      const libsList = await libsSource.listLibs();
+      // Ensure the owner has at least one writable user lib to create symbols in.
+      let libsList = await libsSource.listLibs();
+      if (libsSource.createLib && !libsList.some((l) => l.type === "user")) {
+        const created = await libsSource.createLib(DEFAULT_USER_LIB_NAME);
+        if (created) {
+          libsList = [...libsList, created];
+          log(`[libs] created default user lib "${created.name}"`);
+        }
+      }
       symLibTable = buildSymLibTable(libsList);
-      writableLibUris = libsList
+      libPlaceholderUris = libsList.map((l) => libUri(l.id));
-        .filter((l) => l.writable)
-        .map((l) => libUri(l.id, true));
       log(`[libs] seeded ${libsList.length} lib(s) into sym-lib-table`);
     } catch (e) {
       log(`[libs] listLibs failed, seeding empty table: ${String(e)}`);
@@ -186,15 +195,13 @@ async function doBoot(opts: BootOptions): Promise<void> {
   const seedKicadConfig = () => {
     const FS = moduleFS();
     FS.mkdirTree(KICAD_CONFIG_DIR);
-    // libs: the mount points that pcbjam lib URIs (/mnt/pcbjam[-rw]/<lib>) live
+    // libs: the mount point that pcbjam lib URIs (/mnt/pcbjam/<lib>) live under.
-    // under. Real dirs so any incidental existence/backup check on the URI
+    // A real dir so any incidental existence/backup check on the URI passes; the
-    // passes; the lib contents themselves are served virtually via
+    // lib contents themselves are served virtually via window.kicadLibs.
-    // window.kicadLibs (read-only origins and writable user libs).
     FS.mkdirTree(PCBJAM_LIB_MOUNT);
-    FS.mkdirTree(PCBJAM_LIB_RW_MOUNT);
+    // Empty placeholder file per lib so the editor's post-save file-times stat
-    // Empty placeholder file per writable lib so the editor's post-save
+    // succeeds (the real bytes are served via window.kicadLibs).
-    // file-times stat succeeds (the real bytes are served via window.kicadLibs).
+    for (const uri of libPlaceholderUris) {
-    for (const uri of writableLibUris) {
       if (!FS.analyzePath(uri).exists) FS.writeFile(uri, "");
     }
     const writeIfAbsent = (path: string, contents: string) => {

web/standalone/src/wasm/libs/remote-source.ts

@@ -1,15 +1,27 @@
-import { contract } from "@pcbjam/shared";
+import { contract, OWNER_HEADER } from "@pcbjam/shared";
 import { initClient } from "@ts-rest/core";
 import type { LibInfo, LibItemInfo, LibsSource } from "./source";
 
 /**
  * A `LibsSource` backed by a contract-conforming backend (the closed registry
- * server, or the GPL example backend). List ops go through the ts-rest client;
+ * server, or the GPL example backend). Read list ops go through the ts-rest
- * item bodies stream from the raw text route `GET /api/libs/:lib/items/:kind/:name`
+ * client; item bodies stream from the raw text route
- * (binary/text does not round-trip ts-rest — same as file-byte download).
+ * `GET /api/libs/:lib/items/:kind/:name`, and writes hit the symmetric
+ * `PUT` route (binary/text doesn't round-trip ts-rest). The `owner` is carried
+ * on every request via `OWNER_HEADER` (thin per-user; absent ⇒ backend default).
  */
-export function remoteLibsSource(apiBase: string): LibsSource {
+export function remoteLibsSource(apiBase: string, owner?: string): LibsSource {
-  const client = initClient(contract, { baseUrl: apiBase, baseHeaders: {} });
+  const ownerHeaders: Record<string, string> = owner
+    ? { [OWNER_HEADER]: owner }
+    : {};
+  const client = initClient(contract, {
+    baseUrl: apiBase,
+    baseHeaders: ownerHeaders,
+  });
+
+  const itemUrl = (libId: string, kind: string, name: string) =>
+    `${apiBase}/api/libs/${encodeURIComponent(libId)}/items/` +
+    `${encodeURIComponent(kind)}/${encodeURIComponent(name)}`;
 
   return {
     async listLibs(): Promise<LibInfo[]> {
@@ -19,6 +31,7 @@ export function remoteLibsSource(apiBase: string): LibsSource {
         id: l.id,
         name: l.name,
         description: l.description ?? null,
+        type: l.type,
       }));
     },
 
@@ -33,12 +46,36 @@ export function remoteLibsSource(apiBase: string): LibsSource {
       kind: string,
       name: string,
     ): Promise<string | null> {
-      const url =
+      const res = await fetch(itemUrl(libId, kind, name), {
-        `${apiBase}/api/libs/${encodeURIComponent(libId)}/items/` +
+        headers: ownerHeaders,
-        `${encodeURIComponent(kind)}/${encodeURIComponent(name)}`;
+      });
-      const res = await fetch(url);
       if (!res.ok) return null;
       return await res.text();
     },
+
+    async saveItemBody(
+      libId: string,
+      kind: string,
+      name: string,
+      body: string,
+    ): Promise<boolean> {
+      const res = await fetch(itemUrl(libId, kind, name), {
+        method: "PUT",
+        headers: { ...ownerHeaders, "Content-Type": "text/plain; charset=utf-8" },
+        body,
+      });
+      return res.ok;
+    },
+
+    async createLib(name: string): Promise<LibInfo | null> {
+      const res = await client.createLib({ body: { name } });
+      if (res.status !== 201) return null;
+      return {
+        id: res.body.id,
+        name: res.body.name,
+        description: res.body.description ?? null,
+        type: res.body.type,
+      };
+    },
   };
 }

web/standalone/src/wasm/libs/source.ts

@@ -6,13 +6,13 @@ import { libIdFromUri, libUri } from "./uri";
  * local folder); the WASM-facing provider below is the same regardless.
  */
 export interface LibInfo {
-  /** Opaque id used in the lib-table URI (/mnt/pcbjam[-rw]/<id>). */
+  /** Opaque id used in the lib-table URI (/mnt/pcbjam/<id>). */
   id: string;
   /** Display nickname for the sym-lib-table row. */
   name: string;
   description?: string | null;
-  /** Writable (user) lib → mounts under /mnt/pcbjam-rw/ and accepts saves. */
+  /** 'origin' | 'mirror' | 'user' — drives "ensure a user lib exists" at boot. */
-  writable?: boolean;
+  type?: string;
 }
 
 export interface LibItemInfo {
@@ -41,6 +41,11 @@ export interface LibsSource {
     name: string,
     body: string,
   ): Promise<boolean>;
+  /**
+   * Create a user library (returns its `LibInfo`, or null if unsupported / on
+   * conflict). Used by boot to ensure the owner has a writable target.
+   */
+  createLib?(name: string): Promise<LibInfo | null>;
 }
 
 /** The function the WASM `SCH_IO_PCBJAM_LIB` plugin calls via the JS bridge. */
@@ -74,11 +79,8 @@ function sexprEscape(s: string): string {
 export function buildSymLibTable(libsList: LibInfo[]): string {
   const rows = libsList.map((l) => {
     const descr = l.description ? sexprEscape(l.description) : "";
-    // Same plugin type ("PCBJAM") for read-only + writable libs; the rw mount
-    // in the URI is what flips writability (plugin IsLibraryWritable).
     return `  (lib (name "${sexprEscape(l.name)}")(type "PCBJAM")(uri "${libUri(
       l.id,
-      l.writable,
     )}")(options "")(descr "${descr}"))`;
   });
   return `(sym_lib_table\n  (version 7)\n${rows.join("\n")}${

web/standalone/src/wasm/libs/spike-writable.ts

@@ -39,7 +39,7 @@ export function withSpikeWritableLib(
       }
       return [
         ...base,
-        { id: SPIKE_RW_LIB_ID, name: SPIKE_RW_LIB_NAME, writable: true },
+        { id: SPIKE_RW_LIB_ID, name: SPIKE_RW_LIB_NAME, type: "user" },
       ];
     },
 

web/standalone/src/wasm/libs/uri.ts

@@ -1,29 +1,25 @@
 /**
- * pcbjam lib URIs are absolute POSIX paths under these mounts. Absolute so that
+ * pcbjam lib URIs are absolute POSIX paths under a single mount. Absolute so
- * KiCad's lib-table URI expansion (ExpandURI -> wxFileName::MakeAbsolute) is a
+ * that KiCad's lib-table URI expansion (ExpandURI -> wxFileName::MakeAbsolute)
- * no-op and the path reaches the plugin/provider unmangled — a "scheme://" URI
+ * is a no-op and the path reaches the plugin/provider unmangled — a "scheme://"
- * gets rewritten to "/scheme:/..." against the cwd, which differs per project.
+ * URI gets rewritten to "/scheme:/..." against the cwd, which differs per
+ * project.
  *
- * Two mount roots encode writability without an extra bridge round-trip (the
+ * One mount for every lib: the fork reports them all writable and the
- * plugin's IsLibraryWritable is then a cheap prefix check):
+ * provider/server decides what a save means (write a user lib, mirror an
- *   /mnt/pcbjam/<id>      read-only origins
+ * origin, reject). The fork stays agnostic to origin/user.
- *   /mnt/pcbjam-rw/<id>   writable user libs
  */
 export const PCBJAM_LIB_MOUNT = "/mnt/pcbjam";
 export const PCBJAM_LIB_PREFIX = `${PCBJAM_LIB_MOUNT}/`;
-export const PCBJAM_LIB_RW_MOUNT = "/mnt/pcbjam-rw";
-export const PCBJAM_LIB_RW_PREFIX = `${PCBJAM_LIB_RW_MOUNT}/`;
 
-/** The lib-table URI for a lib id (writable libs get the rw mount). */
+/** The lib-table URI for a lib id. */
-export function libUri(id: string, writable = false): string {
+export function libUri(id: string): string {
-  return `${writable ? PCBJAM_LIB_RW_PREFIX : PCBJAM_LIB_PREFIX}${id}`;
+  return `${PCBJAM_LIB_PREFIX}${id}`;
 }
 
-/** Recover the lib id from either mount's URI (arrives unmangled). */
+/** Recover the lib id from a "/mnt/pcbjam/<id>" URI (arrives unmangled). */
 export function libIdFromUri(uri: string): string | null {
-  if (uri.startsWith(PCBJAM_LIB_RW_PREFIX))
+  return uri.startsWith(PCBJAM_LIB_PREFIX)
-    return uri.slice(PCBJAM_LIB_RW_PREFIX.length);
+    ? uri.slice(PCBJAM_LIB_PREFIX.length)
-  if (uri.startsWith(PCBJAM_LIB_PREFIX))
+    : null;
-    return uri.slice(PCBJAM_LIB_PREFIX.length);
-  return null;
 }