(paths draft)

.changeset/codeql-sw-logging.md

@@ -0,0 +1,5 @@
+---
+"@inkandswitch/patchwork-bootloader": patch
+---
+
+The service worker and resolvers no longer put request URLs or paths into a console format string, where a `%c` or `%s` in a URL was interpreted. Error responses carry the error's message, not its stack; the stack goes to the console.

.changeset/handoff-accept-timeout-module.md

@@ -0,0 +1,5 @@
+---
+"@inkandswitch/patchwork-bootloader": patch
+---
+
+The service worker's tab accept timeout (250ms) moves into its own module, `handoff-timing.ts`, so the node test harness can widen it. Its in-process fake tabs share the service worker's event loop, so on a loaded machine their "accepted" could miss the window and the test would wait out a 35-second broadcast. Behaviour in browsers is unchanged.

.changeset/nested-renames-keep-pinned-urls.md

@@ -0,0 +1,8 @@
+---
+"@inkandswitch/patchwork-filesystem": patch
+"@inkandswitch/patchwork-bootloader": patch
+---
+
+A pinned URL to a file in a package's nested folder keeps working after the file, or a folder above it, is renamed. A file list now records `via` for such a file: the heads of each nested folder doc on the way to it. The service worker passes those on with `heads` when it asks a resolver for the file, and `readPath` reads any document it reaches by a link without heads at whichever of them it has. Before, the walk read nested folders as they are now, so a renamed file answered nothing when its bytes weren't already stored.
+
+Lists with no nested folders leave `via` out and hash as before. A package with nested folders gets a new list, and so a new pinned URL, once.

.changeset/open-document-path.md

@@ -0,0 +1,6 @@
+---
+"@inkandswitch/patchwork-elements": patch
+"@inkandswitch/patchwork": patch
+---
+
+`patchwork:open-document` (and `openDocument`, `patchwork.open`, `<patchwork-view path>`) can say where a document was opened from: `path` is the live path it was opened at, like a cwd, e.g. `<acctHash>/Projects/foo` with each segment `encodeURIComponent`-encoded. A `<patchwork-view>` hands a new path to its tool without remounting it.

.changeset/packages-discovered-off-thread.md

@@ -0,0 +1,8 @@
+---
+"@inkandswitch/patchwork-filesystem": patch
+"@inkandswitch/patchwork-bootloader": patch
+---
+
+`/packages` packages are discovered off the main thread, like module-settings packages. The pinned `/@/` URL a `/packages` lookup answers with now goes through the ModuleWatcher's `importAutomergePackage` hook, so the browser's module-loader worker reads its plugin descriptors, and a plugin's `load()` re-imports the same pinned URL on the main thread. Before, those packages' entry points were imported on the main thread to register them.
+
+`importPluginFromPackage(url, type, id)` takes a folder doc pinned to heads or a pinned `/@/` URL. `importPluginFromFolderDocUrl` is kept as a deprecated alias for it.

.changeset/path-provider-plugins.md

@@ -0,0 +1,19 @@
+---
+"@inkandswitch/patchwork-filesystem": patch
+"@inkandswitch/patchwork-plugins": patch
+"@inkandswitch/patchwork-bootloader": patch
+"@inkandswitch/patchwork": patch
+---
+
+Packages can now say what a document of their type contains. A `patchwork:path-provider` plugin is a `PathProvider` with `supportedDatatypes`. The built-in providers (account, directory, folder, branches) are always asked first and can't be overridden. After them come plugins, in registration order. The one exception is a typed document that also has a folder's `docs` array (a tldraw canvas): a plugin declared for its type walks it, and the folder provider walks it otherwise (`yieldsToPackage`).
+
+- `patchwork-filesystem`:
+  - a `Child` can be `{ name, sub: [...segments] }`, a value inside the document offered as a sub-document. A walk that ends at one reports it as `WalkEnd.sub`, and `resolveLivePath` returns `handle.sub(...segments)`;
+  - `PathProvider` gains the optional `add`, `rename` and `remove`, for whoever shows a provider's children to edit them;
+  - walks take `WalkOptions.providers` (an `ExtraProviders`), asked after the built-ins, as do `listChildren` and `listUnion`. A provider that throws is treated as having no children.
+  - extra providers apply only to a document a walk goes on through. Whether a document a path ends at is a container, and what a file list counts as a file, are the built-ins' call, so installing a provider doesn't change what an existing pinned URL means;
+  - a link with path segments (to a sub-document) isn't walked or listed as the whole document.
+  - a name a provider spreads over several path segments is written as the file list writes it, so every spelling of it pins to a tail the list covers.
+- `patchwork-plugins`: the plugin type `PathProviderDescription`/`PathProviderPlugin`, with `pathProviderFor(doc)` (built-ins, then plugins), `packagePathProviders` (plugins only, for `WalkOptions.providers`), and `pathProviderTypes()`. `"*"` in `supportedDatatypes` is ignored.
+- `patchwork-bootloader`: `createResolver` takes `providers`. A tab's resolver passes the registered plugins, and the automerge worker's passes none, since it never loads package code.
+- `patchwork`: `&path=` resolves through registered path providers too, and a path that ends at a sub-document opens it at its sub-handle's URL. A `path=` that names a different part of the document `doc=` names is dropped, as one naming a different document already was.

.changeset/paths-content-store.md

@@ -0,0 +1,8 @@
+---
+"@inkandswitch/patchwork-filesystem": patch
+"@inkandswitch/patchwork-bootloader": patch
+"@inkandswitch/patchwork": patch
+"@inkandswitch/patchwork-e2e": patch
+---
+
+The service worker serves `/@/` paths. A live path (`/@/<acctHash>/Projects/foo/x.js`) redirects to its pinned form. A pinned one names its folder's file list by hash (`…/<idhash>@<heads>~<listHash>/x.js`): the list records each file's content hash and the heads it was read at, so the service worker checks the list against the URL and the bytes against the list, and serves a pinned URL's old bytes even after the file changes. Lists and bytes are kept in a content-addressed store (`patchwork-content-<acctHash>`) that anything on the origin can write and that is checked on every read. Links no longer need heads to pin what they point at, and no document id appears in a URL, a file list or a store key (a stored folder's own JSON still holds its children's URLs). A pinned URL whose list has been lost is rebuilt from its pinned heads, trying the one-file list a redirect hands out before the whole folder's; `pinPath` refuses to pin a list it couldn't read every file for (`IncompleteFileListError`). Resolvers no longer write the cache: they hand bytes back and the service worker decides what to keep, so legacy `/automerge%3A…` URLs are now cached by the service worker itself. New in `@inkandswitch/patchwork-bootloader`: `registerAccount` (patchwork calls it at boot) and `clearAccountStore`. New in `@inkandswitch/patchwork-filesystem`: `buildFileList`, `canonicalJson`, `parseFileList`, `contentHash`, `toBytes`, `readPath` (optionally at given heads), `listFiles`, `readNode`, `WalkOptions.find`, `WalkEnd.container` and `WalkEnd.tail`. The e2e suite gains a test that a forged store entry is never served.

.changeset/paths-grammar-providers.md

@@ -0,0 +1,6 @@
+---
+"@inkandswitch/patchwork-filesystem": patch
+"@inkandswitch/patchwork-plugins": patch
+---
+
+Add paths. `idhash`, `livePath` and `parsePath` read and write live paths (`<acctHash>/Projects/foo`) and pinned ones (`<acctHash>@<heads>/<idhash>@<heads>~<listHash>/…`), where a container's step may name a hash of its file list. `resolveLivePath`, `pinnedPath`, `pinPath`, `listChildren` and `listUnion` walk an account's namespace to find a document or pin a path; `pinnedPath` and `pinPath` return the pinned path or URL together with the file list it names. Path providers (`PathProvider`, `accountProvider`, `directoryProvider`, `folderProvider`, `branchesProvider`, `providerFor`) replace `FolderStrategy`, which is now a deprecated alias of `PathProvider`. `resolvePath` now also follows a branches doc to its default branch. `AccountDoc` gains an optional `namespace` mount table; without one, `/` is `rootFolderUrl`. `isKeyhiveDoc` in `@inkandswitch/patchwork-plugins` now goes through filesystem's new `isKeyhiveDocumentId`, so the rule lives in one place.

.changeset/paths-packages.md

@@ -0,0 +1,8 @@
+---
+"@inkandswitch/patchwork-filesystem": patch
+"@inkandswitch/patchwork-bootloader": patch
+"@inkandswitch/patchwork-plugins": patch
+"@inkandswitch/patchwork": patch
+---
+
+Package management is whatever is bound at `/packages` in the account's namespace. New accounts bind `/` to their root folder and `/packages` to a new Packages folder; an older account gets a Packages folder at boot, linking each automerge package its module-settings doc lists, by its `package.json` name. The ModuleWatcher loads every package in the `/packages` union (`addPackagesFolder`, `watchPackagesFolder`), keyed by document so a rename reloads nothing, and looks each one up as a pinned `/@/` URL (`trackPackagesFolder`) that it imports and the service worker checks against the package's file list. A package's list now covers everything under it, nested folders included, and a redirect to a folder carries the folder's whole list. New accounts, and migrated ones, also get a `packages` link in their root folder to that folder, so `/packages` shows in the tree like any other folder. The ModuleWatcher reports each package's status (`packageStatus(url)`: loading, loaded with its plugins, or failed with why) and fires a `"status"` event when one changes; it is now an `EventTarget`. `AccountDoc.moduleSettingsUrl` is deprecated in favour of the `/packages` binding; it's still read, deduplicated against `/packages`, since the Packages UI installs into it.

.changeset/paths-review-fixes.md

@@ -0,0 +1,23 @@
+---
+"@inkandswitch/patchwork-filesystem": patch
+"@inkandswitch/patchwork-bootloader": patch
+"@inkandswitch/patchwork": patch
+---
+
+Fixes to paths, packages and the content store from review.
+
+- File lists: a file named `__proto__` is listed like any other. A tail named like an `Object.prototype` member (`constructor`, `toString`) that the list doesn't name answers 404.
+- Pinning through a package's container (a path provider's doc) lists that container, so the URL serves. A doc named by a doc step is walked with package providers; one a path ends at by name is still a container or a file by the built-ins.
+- A value held by a doc below a package's root (a nested directory doc) is listed with that doc's heads, and read back at them.
+- `/packages`:
+  - a package that's a branches doc reloads when its default branch's code changes, and follows the branch when it moves;
+  - a member folder that can't be found doesn't hold up the others: the first listing waits up to 3s, then lists what it has, and the rest arrive as they're found;
+  - migration records the entries it moved in the module-settings doc (`movedToPackages`). This build loads those only through `/packages`, so removing a package there removes it. Builds that predate `/packages` still read `modules` as before;
+  - migration never gives two packages one name, and a `/packages` binding that syncs in mid-migration wins;
+  - boot waits at most a second for migration.
+- Routing:
+  - a `doc=`/`path=` check that finishes after the hash moved on leaves the new hash alone;
+  - opening another part of the same document drops the path;
+  - a path-only hash that doesn't resolve is walked again when path providers register, so a cold boot opens a path through a package's datatype.
+- The service worker opens an account's content store only to write to it, so a `/@/` link naming an unknown account leaves no cache behind.
+- `ModuleWatcher.packageFor(importUrl)` says which package doc an import url was loaded for. A `/packages` package's plugins are registered under its pinned `/@/` url; this maps it back, so a tool like Packages can tell what's installed.

.changeset/paths-routing.md

@@ -0,0 +1,6 @@
+---
+"@inkandswitch/patchwork": patch
+"@inkandswitch/patchwork-e2e": patch
+---
+
+The router keeps `&path=` in the hash: the live path a document was opened at (`<acctHash>/Projects/foo`), written whenever `patchwork:open-document` carries one and its segments kept exactly as encoded. A hash with `path=` and no `doc=` opens what the path names; one that doesn't resolve (yet) opens nothing and stays in the address bar. When `path=` names a different document than `doc=`, because something moved or was renamed, `doc=` wins and `path=` is dropped with a console warning. `path=` survives a tool switch on the same document. Paths under the site's own account resolve, and so do share links. The e2e suite gains a test that opens a document from `&path=` alone.

.changeset/subdoc-opens-in-its-documents-tool.md

@@ -0,0 +1,5 @@
+---
+"@inkandswitch/patchwork-elements": patch
+---
+
+`<patchwork-view>` opens part of a document (`automerge:<id>/<path>`, a sub-handle) that has no `@patchwork` type of its own in the tool for the document it's part of, and hands that tool the sub-handle. Before, such a part, like a tldraw shape opened from the sidebar, failed with "missing @patchwork metadata".

.github/workflows/spike-sw-sharedworker.yml

@@ -0,0 +1,53 @@
+name: spike sw-sharedworker
+
+# Records how each browser lets a service worker and a module SharedWorker
+# message each other, and what it tells the service worker about the sender.
+# See packages/e2e/spikes/sw-sharedworker. The JSON lands in the job summary.
+
+permissions:
+  contents: read
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - packages/e2e/spikes/sw-sharedworker/**
+      - .github/workflows/spike-sw-sharedworker.yml
+
+jobs:
+  spike:
+    name: spike (${{ matrix.browser }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        browser: [chromium, firefox, webkit]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          run_install: false
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: install the e2e package
+        run: pnpm install --frozen-lockfile --filter @inkandswitch/patchwork-e2e
+
+      - name: install ${{ matrix.browser }}
+        working-directory: packages/e2e
+        run: pnpm exec playwright install --with-deps ${{ matrix.browser }}
+
+      - name: run the spike
+        working-directory: packages/e2e
+        run: pnpm exec playwright test -c spikes/sw-sharedworker/playwright.config.mjs --project=${{ matrix.browser }}
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: spike-sw-sharedworker-${{ matrix.browser }}
+          path: packages/e2e/spikes/sw-sharedworker/results/
+          retention-days: 14

core/bootloader/package.json

@@ -113,6 +113,7 @@
   },
   "scripts": {
     "build": "tsc && cp src/global.css dist/global.css",
-    "dev": "tsc -w --preserveWatchOutput"
+    "dev": "tsc -w --preserveWatchOutput",
+    "test": "vitest run"
   }
 }

core/bootloader/src/automerge-protocol-handler.ts

@@ -17,9 +17,12 @@ import initSubduction from "@automerge/automerge-subduction/slim";
 
 import {
   Repo,
+  parseAutomergeUrl,
+  type AutomergeUrl,
   type DocumentId,
   type PeerId,
 } from "@automerge/automerge-repo/slim";
+import { idhash } from "@inkandswitch/patchwork-filesystem";
 
 import { IndexedDBStorageAdapter } from "@automerge/automerge-repo-storage-indexeddb";
 import type {
@@ -37,6 +40,7 @@ import {
   HANDOFF_CHANNEL,
   type HandoffOnlineMessage,
   type HandoffRequestMessage,
+  type RegisterAccountMessage,
 } from "./types.js";
 
 declare const __SYNC_SERVER__: {
@@ -50,11 +54,30 @@ const syncServer =
     ? __SYNC_SERVER__
     : { url: "wss://subduction.sync.inkandswitch.com" };
 
+// acctHash → account url: the accounts whose `/@/` paths this worker resolves.
+// Tabs tell us theirs; the hash is computed here, so no tab can name an
+// account by the wrong one.
+const accounts = new Map<string, AutomergeUrl>();
+
+async function registerAccount({ url }: RegisterAccountMessage) {
+  try {
+    const { documentId } = parseAutomergeUrl(url as AutomergeUrl);
+    accounts.set(await idhash(documentId), url as AutomergeUrl);
+  } catch (error) {
+    console.warn("ignoring a register-account for %s", url, error);
+  }
+}
+
 const control = startWorkerControl("automerge-protocol-handler-worker", {
   onRestart: drainForRestart,
   // Held only so the tabs and the service worker can tell whether this
   // instance is still around; nothing here waits for it.
   lock: AUTOMERGE_WORKER_LOCK,
+  onMessage(data) {
+    if (data?.type === "register-account") {
+      void registerAccount(data as RegisterAccountMessage);
+    }
+  },
 });
 const log = control.log;
 
@@ -169,7 +192,7 @@ async function buildKeyhiveRepo(
 // them can (one still booting, one from an older build, a site that brings
 // its own Repo).
 
-const resolver = createResolver(getRepo, log);
+const resolver = createResolver(getRepo, log, () => accounts);
 const handoffChannel = new BroadcastChannel(HANDOFF_CHANNEL);
 
 const EVICT_IDLE_MS = 5_000;

core/bootloader/src/content-store.ts

@@ -0,0 +1,64 @@
+// Bytes by their hash, in CacheStorage. Nothing here is trusted: any code on the origin can
+// write these caches, so every read is hashed and checked against the hash a pinned URL vouches
+// for, through its file list, before it's served (see pinned.ts). Reads and writes go through this one interface so the bytes can be
+// encrypted at rest later.
+
+export interface ContentStore {
+  get(hash: string): Promise<Uint8Array | undefined>;
+  put(hash: string, bytes: Uint8Array): Promise<void>;
+  delete(hash: string): Promise<void>;
+}
+
+export const CONTENT_CACHE_PREFIX = "patchwork-content-";
+
+/** One store per account, apart from the `patchwork` cache of site pages and assets. */
+export const contentCacheName = (acctHash: string) =>
+  `${CONTENT_CACHE_PREFIX}${acctHash}`;
+
+/** A store in `cache`, keyed by `<origin>/.content/<hash>`: an internal key, never fetched. */
+export function cacheStore(cache: Cache, origin: string): ContentStore {
+  const key = (hash: string) => `${origin}/.content/${hash}`;
+  return {
+    async get(hash) {
+      const response = await cache.match(key(hash));
+      return response ? new Uint8Array(await response.arrayBuffer()) : undefined;
+    },
+    async put(hash, bytes) {
+      await cache.put(key(hash), new Response(bytes as BlobPart));
+    },
+    async delete(hash) {
+      await cache.delete(key(hash));
+    },
+  };
+}
+
+/**
+ * {@link cacheStore} in the cache `name`, opened only when something is stored: a read or a
+ * delete of a cache that doesn't exist finds nothing, and creates nothing. Any `/@/` URL names an
+ * account, so opening on every request would leave a cache behind for each made-up one.
+ */
+export function lazyCacheStore(storage: CacheStorage, name: string, origin: string): ContentStore {
+  let opened: Promise<ContentStore> | undefined;
+  const open = () => (opened ??= storage.open(name).then((cache) => cacheStore(cache, origin)));
+  const existing = async () => (opened || (await storage.has(name)) ? open() : undefined);
+  return {
+    async get(hash) {
+      return (await existing())?.get(hash);
+    },
+    async put(hash, bytes) {
+      await (await open()).put(hash, bytes);
+    },
+    async delete(hash) {
+      await (await existing())?.delete(hash);
+    },
+  };
+}
+
+/**
+ * Forget everything stored for an account. There's no sign-out flow; a site calls this from its
+ * own. File lists the service worker holds in memory may still name these hashes, which then
+ * read as misses.
+ */
+export function clearAccountStore(acctHash: string): Promise<boolean> {
+  return caches.delete(contentCacheName(acctHash));
+}

core/bootloader/src/handoff-timing.ts

@@ -0,0 +1,9 @@
+// How long the service worker gives a tab to say it'll resolve a request before
+// asking the next one. A tab that hasn't been handed its Repo yet says it can't
+// at once, so this is for one that can't answer at all: a frozen background
+// tab, or one from a build before tabs resolved.
+//
+// Its own module so the node test harness can widen it: there, a fake tab runs
+// on the service worker's own event loop, and its "accepted" can wait behind
+// its own resolving on a loaded machine.
+export const ACCEPT_TIMEOUT_MS = 250;