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>

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
-  // wires real remote writes.
+  // editor save path works with no backend (a dev/test aid). The real remote
+  // 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
-  // dir): the symbol-editor save path stat()s the lib file after saving
+  // Every lib gets an empty placeholder FILE at its URI (not just the mount dir):
+  // 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
-        .filter((l) => l.writable)
-        .map((l) => libUri(l.id, true));
+      libPlaceholderUris = libsList.map((l) => libUri(l.id));
       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
-    // 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).
+    // libs: the mount point that pcbjam lib URIs (/mnt/pcbjam/<lib>) live under.
+    // A real dir so any incidental existence/backup check on the URI passes; the
+    // lib contents themselves are served virtually via window.kicadLibs.
     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) {
+    // Empty placeholder file per lib so the editor's post-save file-times stat
+    // succeeds (the real bytes are served via window.kicadLibs).
+    for (const uri of libPlaceholderUris) {
       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;
- * item bodies stream from the raw text route `GET /api/libs/:lib/items/:kind/:name`
- * (binary/text does not round-trip ts-rest — same as file-byte download).
+ * server, or the GPL example backend). Read list ops go through the ts-rest
+ * client; item bodies stream from the raw text route
+ * `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 {
-  const client = initClient(contract, { baseUrl: apiBase, baseHeaders: {} });
+export function remoteLibsSource(apiBase: string, owner?: string): LibsSource {
+  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 =
-        `${apiBase}/api/libs/${encodeURIComponent(libId)}/items/` +
-        `${encodeURIComponent(kind)}/${encodeURIComponent(name)}`;
-      const res = await fetch(url);
+      const res = await fetch(itemUrl(libId, kind, name), {
+        headers: ownerHeaders,
+      });
       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. */
-  writable?: boolean;
+  /** 'origin' | 'mirror' | 'user' — drives "ensure a user lib exists" at boot. */
+  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
- * 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.
+ * pcbjam lib URIs are absolute POSIX paths under a single mount. 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
+ * One mount for every lib: the fork reports them all writable and the
+ * provider/server decides what a save means (write a user lib, mirror an
+ * origin, reject). The fork stays agnostic to origin/user.
  */
 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). */
-export function libUri(id: string, writable = false): string {
-  return `${writable ? PCBJAM_LIB_RW_PREFIX : PCBJAM_LIB_PREFIX}${id}`;
+/** The lib-table URI for a lib id. */
+export function libUri(id: string): string {
+  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.slice(PCBJAM_LIB_RW_PREFIX.length);
-  if (uri.startsWith(PCBJAM_LIB_PREFIX))
-    return uri.slice(PCBJAM_LIB_PREFIX.length);
-  return null;
+  return uri.startsWith(PCBJAM_LIB_PREFIX)
+    ? uri.slice(PCBJAM_LIB_PREFIX.length)
+    : null;
 }