feat: libs 0004-A — symbol write-path spike (provider save op, writable lib + MEMFS placeholder files, rw mount); fix symbol_editor embind link; e2e write-bridge test; bump kicad

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

kicad

@@ -1 +1 @@
-Subproject commit 7932b3ace1e5e21fb6ab38ece2dc1faa41a25a12
+Subproject commit fa0b374da913dcf03a3a94e3643f68d0a2e30995

scripts/kicad/build-kicad-target.sh

@@ -66,6 +66,16 @@ case "$APP_NAME" in
         ;;
 esac
 
+# Which app's embind bindings to compile + link. Most apps use their own; the
+# symbol_editor is the eeschema kiface launched at a different TOP_FRAME and has
+# no embind of its own, so it reuses eeschema's — whose bindings (kicadCollabOnSave
+# et al.) the shared kiface objects reference. Without this the symbol_editor link
+# fails with "undefined symbol: kicadCollabOnSave" (the placeholder defines nothing).
+case "$APP_NAME" in
+    symbol_editor) EMBIND_APP="eeschema" ;;
+    *)             EMBIND_APP="$APP_NAME" ;;
+esac
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/../common/env.sh"
 source "${SCRIPT_DIR}/../common/versions.sh"
@@ -319,8 +329,8 @@ log_info "KiCad WASM support verified"
 # linker line below references "${STUBS_BUILD}/${APP_NAME}_embind.o" so we
 # create an empty placeholder when the source is missing, to keep the link
 # line stable across apps.
-EMBIND_OBJ="${STUBS_BUILD}/${APP_NAME}_embind.o"
-EMBIND_SRC="${PROJECT_ROOT}/wasm/bindings/${APP_NAME}_embind.cpp"
+EMBIND_OBJ="${STUBS_BUILD}/${EMBIND_APP}_embind.o"
+EMBIND_SRC="${PROJECT_ROOT}/wasm/bindings/${EMBIND_APP}_embind.cpp"
 
 # Step 7: Configure KiCad with CMake
 # We use CMAKE_MODULE_PATH to inject our compatibility layer

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

@@ -0,0 +1,152 @@
+import { test, expect, type Page } from '@playwright/test';
+import { waitForRegistry, clickByTooltip } from '../e2e/utils/element-tracker';
+
+/**
+ * 0004-A write-path spike: does the symbol editor's SaveSymbol path route through
+ * the pcbjam write bridge, on the MAIN thread, without wedging?
+ *
+ * Boots the fileless symbol_editor with `?libwrite=1` (an in-memory writable
+ * "My Symbols (spike)" lib), creates a new symbol in it, and Ctrl+S saves. The
+ * plugin's SaveSymbol serializes a kicad_symbol_lib and calls
+ * window.kicadLibs.request("save", …) on the main thread (EM_ASYNC_JS), which the
+ * spike captures onto window.__pcbjamSaved. Assert: the body is well-formed
+ * fork-native s-expr, and the app stays live (no abort / no OOM respawn).
+ */
+
+const SHOT = (name: string) => `test-results/symwrite-${name}.png`;
+
+async function bootSymbolEditor(page: Page): Promise<void> {
+  await page.goto('/p/demo/symbol_editor/?libwrite=1');
+  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);
+}
+
+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 routes through the pcbjam write bridge (main thread)', async ({ page }) => {
+  const logs: string[] = [];
+  page.on('console', (m) => logs.push(`[${m.type()}] ${m.text()}`));
+  page.on('pageerror', (e) => logs.push(`[pageerror] ${e.message}`));
+
+  await bootSymbolEditor(page);
+  await page.screenshot({ path: SHOT('01-boot'), scale: 'css' });
+
+  // Spike provider is active.
+  expect(await page.evaluate(() => !!(window as any).__pcbjamSaved), 'spike marker present').toBe(true);
+
+  // Select the writable lib in the tree so New Symbol targets it. The
+  // dataviewitem's registry y sits on the column header, so anchor off the
+  // "Item" column header and click one row below it (the lib is the only row).
+  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();
+  // Click focuses the tree row but doesn't always select it; drive the keyboard
+  // to make the first (only) library row the SELECTED item (GetTargetLibId).
+  await page.mouse.click(hdr!.cx, hdr!.cy + hdr!.hgt + 8); // focus the tree
+  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);
+  await page.screenshot({ path: SHOT('02-lib-selected'), scale: 'css' });
+
+  // New Symbol via the toolbar button (tooltip), proven-clickable in the harness.
+  const clicked = await clickByTooltip(page, 'New Symbol...');
+  expect(clicked, 'New Symbol toolbar button clicked').toBe(true);
+  await page.waitForTimeout(1500);
+  await page.screenshot({ path: SHOT('03-newsym-dialog'), scale: 'css' });
+
+  // Diagnostics: what dialog/controls are present now.
+  const dlg = await page.evaluate(() => {
+    const all = window.wxElementRegistry.findAll({ visible: true });
+    const pick = (re: RegExp) => all.filter((e: any) => re.test(e.typeName))
+      .map((e: any) => ({ type: e.typeName, name: e.name, label: e.label, cx: Math.round(e.centerX), cy: Math.round(e.centerY), en: e.enabled }));
+    return { dialogs: pick(/Dialog/i), texts: pick(/TextCtrl/i), buttons: pick(/Button/i) };
+  });
+  logs.push(`[spec] after New Symbol: ${JSON.stringify(dlg)}`);
+
+  // The New Symbol dialog: clear its name field (it pre-fills a default) and type
+  // our name, then confirm with Enter (the dialog's default button).
+  const SYM = 'SpikeRes';
+  const nameField = dlg.texts.find((t) => Math.abs(t.cy - 65) > 30 && Math.abs(t.cy - 87) > 30);
+  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(SYM, { delay: 40 });
+  await page.waitForTimeout(300);
+  await page.screenshot({ path: SHOT('04-name-typed'), scale: 'css' });
+  await page.keyboard.press('Enter');
+  await page.waitForTimeout(1500);
+  await page.screenshot({ path: SHOT('05-symbol-created'), scale: 'css' });
+
+  // Title should reflect the new symbol now being edited.
+  const titleAfterCreate = await page.title();
+  logs.push(`[spec] title after create: ${titleAfterCreate}`);
+
+  // Save: focus the canvas, Ctrl+S (the proven save trigger).
+  await focusCanvas(page);
+  await page.keyboard.press('Control+s');
+
+  // Wait for the bridge to capture the saved body (name-agnostic — the New Symbol
+  // dialog may massage the typed name, e.g. a trailing default digit).
+  await page.waitForFunction(
+    () => {
+      const saved = (window as any).__pcbjamSaved as Record<string, string> | undefined;
+      return !!saved && Object.values(saved).some((v) => typeof v === 'string' && v.length > 0);
+    },
+    null,
+    { timeout: 30000 },
+  );
+  await page.screenshot({ path: SHOT('06-saved'), scale: 'css' });
+
+  const { savedName, body } = await page.evaluate(() => {
+    const saved = (window as any).__pcbjamSaved as Record<string, string>;
+    const k = Object.keys(saved).find((n) => saved[n]?.length)!;
+    return { savedName: k, body: saved[k] };
+  });
+  logs.push(`[spec] saved "${savedName}" (${body.length} bytes):\n${body}`);
+
+  // The captured body is a well-formed fork-native kicad_symbol_lib carrying the
+  // saved symbol.
+  expect(body).toContain('(kicad_symbol_lib');
+  expect(body).toContain('(version 20250925)');
+  expect(body).toContain(`(symbol "${savedName}"`);
+
+  // No post-save error dialog (the placeholder-file fix for GetModificationTime).
+  await page.waitForTimeout(500);
+  const errDialog = await page.evaluate(() =>
+    window.wxElementRegistry
+      .findAll({ visible: true })
+      .some((e: any) => /Dialog/i.test(e.typeName) && /Error/i.test(e.label || '')),
+  );
+  expect(errDialog, 'no post-save error dialog').toBe(false);
+  expect(
+    logs.some((l) => l.includes('Failed to retrieve file times')),
+    'no file-times error',
+  ).toBe(false);
+
+  // App stayed live: no abort, no OOM respawn.
+  expect(logs.some((l) => l.includes('Aborted(')), 'no WASM abort').toBe(false);
+  expect(new URL(page.url()).searchParams.get('oomRetry'), 'no OOM respawn').toBeNull();
+
+  // Dump logs for the record.
+  console.log('--- console + spec log ---\n' + logs.join('\n'));
+});

web/standalone/src/lib/config.ts

@@ -11,6 +11,7 @@ export const WASM_ASSET_BASE_URL =
 import type { ProviderConfig, ProviderKind } from "@/wasm/collab";
 import { remoteLibsSource } from "@/wasm/libs/remote-source";
 import type { LibsSource } from "@/wasm/libs/source";
+import { withSpikeWritableLib } from "@/wasm/libs/spike-writable";
 import { staticLibsSource } from "@/wasm/libs/static-source";
 
 /**
@@ -57,7 +58,22 @@ export function docSourceConfig(): DocSource {
  */
 export function libsSourceConfig(): LibsSource | null {
   const kind = import.meta.env.VITE_LIBS_SOURCE ?? "remote";
-  if (kind === "off") return null;
-  if (kind === "static") return staticLibsSource();
-  return remoteLibsSource(API_BASE_URL);
+  const base =
+    kind === "off"
+      ? null
+      : kind === "static"
+        ? staticLibsSource()
+        : remoteLibsSource(API_BASE_URL);
+
+  // 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
+  // wires real remote writes.
+  if (
+    typeof window !== "undefined" &&
+    new URLSearchParams(window.location.search).get("libwrite") === "1"
+  ) {
+    return withSpikeWritableLib(base, (m) => console.log(m));
+  }
+
+  return base;
 }

web/standalone/src/wasm/boot.ts

@@ -6,7 +6,7 @@ import {
   TOOL_NEEDS_CONFIG_SEED,
 } from "./constants";
 import { buildSymLibTable, installLibsProvider, type LibsSource } from "./libs/source";
-import { PCBJAM_LIB_MOUNT } from "./libs/uri";
+import { libUri, PCBJAM_LIB_MOUNT, PCBJAM_LIB_RW_MOUNT } from "./libs/uri";
 
 /**
  * Boot a KiCad tool directly in the main React document — no iframe.
@@ -98,11 +98,20 @@ 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
+  // dir): the symbol-editor save path stat()s the lib file after saving
+  // (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[] = [];
   if (libsSource) {
     installLibsProvider(libsSource, log);
     try {
       const libsList = await libsSource.listLibs();
       symLibTable = buildSymLibTable(libsList);
+      writableLibUris = libsList
+        .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)}`);
@@ -177,10 +186,17 @@ async function doBoot(opts: BootOptions): Promise<void> {
   const seedKicadConfig = () => {
     const FS = moduleFS();
     FS.mkdirTree(KICAD_CONFIG_DIR);
-    // libs: the mount point that pcbjam lib URIs (/mnt/pcbjam/<lib>) live under.
-    // A real dir so any incidental existence check on the URI passes; the lib
-    // contents themselves are served virtually via window.kicadLibs.
+    // libs: the mount points that pcbjam lib URIs (/mnt/pcbjam[-rw]/<lib>) live
+    // under. Real dirs so any incidental existence/backup check on the URI
+    // passes; the lib contents themselves are served virtually via
+    // window.kicadLibs (read-only origins and writable user libs).
     FS.mkdirTree(PCBJAM_LIB_MOUNT);
+    FS.mkdirTree(PCBJAM_LIB_RW_MOUNT);
+    // Empty placeholder file per writable lib so the editor's post-save
+    // file-times stat succeeds (the real bytes are served via window.kicadLibs).
+    for (const uri of writableLibUris) {
+      if (!FS.analyzePath(uri).exists) FS.writeFile(uri, "");
+    }
     const writeIfAbsent = (path: string, contents: string) => {
       if (FS.analyzePath(path).exists) return;
       FS.writeFile(path, contents);

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

@@ -6,11 +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/<id>). */
+  /** Opaque id used in the lib-table URI (/mnt/pcbjam[-rw]/<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. */
+  writable?: boolean;
 }
 
 export interface LibItemInfo {
@@ -28,6 +30,17 @@ export interface LibsSource {
    * null if absent. `kind` is 'symbol' for now.
    */
   getItemBody(libId: string, kind: string, name: string): Promise<string | null>;
+  /**
+   * Persist one item body into a writable (user) lib. Optional: read-only
+   * sources omit it (a save into a non-writable source resolves false).
+   * `body` is a complete fork-native `kicad_symbol_lib` s-expr.
+   */
+  saveItemBody?(
+    libId: string,
+    kind: string,
+    name: string,
+    body: string,
+  ): Promise<boolean>;
 }
 
 /** The function the WASM `SCH_IO_PCBJAM_LIB` plugin calls via the JS bridge. */
@@ -61,8 +74,11 @@ 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")}${
@@ -72,9 +88,10 @@ export function buildSymLibTable(libsList: LibInfo[]): string {
 
 /**
  * Install `window.kicadLibs` backed by a `LibsSource`. The plugin calls
- * `request(op, "/mnt/pcbjam/<id>", arg)`:
+ * `request(op, "/mnt/pcbjam[-rw]/<id>", arg)`:
  *   "list" -> JSON {"symbols":[...]}   (symbol names in the lib)
- *   "get"  -> the item body s-expr     (arg = symbol name)
+ *   "get"  -> the item body s-expr     (arg = symbol name; null if absent)
+ *   "save" -> "ok" / null              (arg = JSON {"name":..,"body":..})
  */
 export function installLibsProvider(
   source: LibsSource,
@@ -100,6 +117,27 @@ export function installLibsProvider(
         }
         case "get":
           return await source.getItemBody(id, "symbol", arg);
+        case "save": {
+          let parsed: { name?: string; body?: string };
+          try {
+            parsed = JSON.parse(arg) as { name?: string; body?: string };
+          } catch {
+            log(`[libs] save: bad JSON arg`);
+            return null;
+          }
+          if (!parsed.name || !parsed.body) return null;
+          if (!source.saveItemBody) {
+            log(`[libs] save: source has no write support (lib=${id})`);
+            return null;
+          }
+          const ok = await source.saveItemBody(
+            id,
+            "symbol",
+            parsed.name,
+            parsed.body,
+          );
+          return ok ? "ok" : null;
+        }
         default:
           return null;
       }

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

@@ -0,0 +1,78 @@
+import type { LibInfo, LibItemInfo, LibsSource } from "./source";
+
+/**
+ * 0004-A write-path spike (no backend). Wraps a `LibsSource` with ONE in-memory
+ * writable user lib so the editor's save-symbol flow has a target and we can
+ * exercise the full save → enumerate → load round-trip through the same WASM
+ * bridge — without committing to the backend design first. Gated by
+ * `?libwrite=1`. Saved bodies are mirrored onto `window.__pcbjamSaved` so the
+ * Playwright probe can inspect them. Replaced in 0004-C by real remote writes.
+ */
+const SPIKE_RW_LIB_ID = "spike-user";
+const SPIKE_RW_LIB_NAME = "My Symbols (spike)";
+
+declare global {
+  interface Window {
+    __pcbjamSaved?: Record<string, string>;
+  }
+}
+
+export function withSpikeWritableLib(
+  inner: LibsSource | null,
+  log: (msg: string) => void,
+): LibsSource {
+  const store = new Map<string, string>(); // symbol name -> body
+  window.__pcbjamSaved = Object.create(null) as Record<string, string>;
+
+  const isSpike = (libId: string) => libId === SPIKE_RW_LIB_ID;
+
+  return {
+    async listLibs(): Promise<LibInfo[]> {
+      // Resilient to a missing backend: the spike must boot standalone (the
+      // writable lib is in-memory), so an unreachable inner source just yields
+      // no origins rather than failing the whole table.
+      let base: LibInfo[] = [];
+      try {
+        base = inner ? await inner.listLibs() : [];
+      } catch (e) {
+        log(`[libs] spike: inner listLibs failed, origins omitted: ${String(e)}`);
+      }
+      return [
+        ...base,
+        { id: SPIKE_RW_LIB_ID, name: SPIKE_RW_LIB_NAME, writable: true },
+      ];
+    },
+
+    async listItems(libId: string): Promise<LibItemInfo[]> {
+      if (isSpike(libId))
+        return [...store.keys()].map((name) => ({ kind: "symbol", name }));
+      return inner ? inner.listItems(libId) : [];
+    },
+
+    async getItemBody(
+      libId: string,
+      kind: string,
+      name: string,
+    ): Promise<string | null> {
+      if (isSpike(libId)) return store.get(name) ?? null;
+      return inner ? inner.getItemBody(libId, kind, name) : null;
+    },
+
+    async saveItemBody(
+      libId: string,
+      kind: string,
+      name: string,
+      body: string,
+    ): Promise<boolean> {
+      if (!isSpike(libId)) {
+        return inner?.saveItemBody
+          ? inner.saveItemBody(libId, kind, name, body)
+          : false;
+      }
+      store.set(name, body);
+      window.__pcbjamSaved![name] = body;
+      log(`[libs] spike saved symbol "${name}" (${body.length} bytes)`);
+      return true;
+    },
+  };
+}

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

@@ -1,20 +1,29 @@
 /**
- * pcbjam lib URIs are absolute POSIX paths under this mount. Absolute so that
+ * pcbjam lib URIs are absolute POSIX paths under these mounts. Absolute so that
  * KiCad's lib-table URI expansion (ExpandURI -> wxFileName::MakeAbsolute) is a
  * no-op and the path reaches the plugin/provider unmangled — a "scheme://" URI
  * gets rewritten to "/scheme:/..." against the cwd, which differs per project.
+ *
+ * Two mount roots encode writability without an extra bridge round-trip (the
+ * plugin's IsLibraryWritable is then a cheap prefix check):
+ *   /mnt/pcbjam/<id>      read-only origins
+ *   /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. */
-export function libUri(id: string): string {
-  return `${PCBJAM_LIB_PREFIX}${id}`;
+/** The lib-table URI for a lib id (writable libs get the rw mount). */
+export function libUri(id: string, writable = false): string {
+  return `${writable ? PCBJAM_LIB_RW_PREFIX : PCBJAM_LIB_PREFIX}${id}`;
 }
 
-/** Recover the lib id from a "/mnt/pcbjam/<id>" URI (arrives unmangled). */
+/** Recover the lib id from either mount's URI (arrives unmangled). */
 export function libIdFromUri(uri: string): string | null {
-  return uri.startsWith(PCBJAM_LIB_PREFIX)
-    ? uri.slice(PCBJAM_LIB_PREFIX.length)
-    : null;
+  if (uri.startsWith(PCBJAM_LIB_RW_PREFIX))
+    return uri.slice(PCBJAM_LIB_RW_PREFIX.length);
+  if (uri.startsWith(PCBJAM_LIB_PREFIX))
+    return uri.slice(PCBJAM_LIB_PREFIX.length);
+  return null;
 }