Local notes with Automerge support + publish to your own PDS
README.md

scn-local #

A standalone Automerge scene-notes editor. Local first, Atmosphere-native, and it publishes to the PDS only when you say so. A prototype, explicitly — see Corliss#67 for the brief it answers.

  • Repo: https://tangled.org/bmann.ca/scn-local — a personal Tangled repo, bmann.ca@tangled.org:did:plc:opmsqmhrvbjosk7wr6v44ul3. It lives under bmann.ca, not the scnorg.tngl.sh organization, because it is a personal prototype; it moves if it becomes SCN's.
  • TypeScript, no framework, Vite.
  • Atmosphere login via atproto OAuth (loopback client).
  • Runs on 127.0.0.1 and works with no SCN infrastructure at all: Public notes are records in your own repository.
  • Automerge in the browser, continuously syncing with an optional sync server (notes.sharedcomputer.network).
  • Explicit save publishes to the PDS. Syncing and publishing are different verbs and stay that way.
  • Folder mirror through Chrome's File System Access API: pick a folder per workspace, and notes land on disk as markdown with YAML front matter. A stored handle does not keep its permission across a reload: the folder control doubles as the re-grant button, and the chip says · grant when it needs one.
npm install
npm run dev        # http://127.0.0.1:5173

Chrome or Edge for the folder half. Everything else works in any browser that supports atproto OAuth.

The shape of a note #

One record, network.sharedcomputer.notes, body as at.markpub.markdown:

{
  "$type": "network.sharedcomputer.notes",
  "noteId": "3mabc…",
  "path": "Obsidian-flavored Markdown.md",
  "title": "Obsidian-flavored Markdown",
  "body": {
    "$type": "at.markpub.markdown",
    "flavor": "gfm",
    "extensions": ["obsidian"],
    "renderingRules": "obsidian-markdown",
    "text": { "$type": "at.markpub.text", "markdown": "---\ntitle: …\n---\n\n…" }
  },
  "createdAt": "2026-11-15T…",
  "updatedAt": "2026-11-15T…",
  "textHash": "…",
  "tags": ["obsidian"],
  "status": "live"
}

src/notes.ts is the second implementation of the lexicon — the first is corliss/scene_notes.py. That duplication is the point. If these two disagree about what a note is, a third app built by someone else will disagree worse, and the fix belongs in the lexicon rather than in either client.

Publishing (Save) and syncing are different verbs, and the difference is the design:

  • Sync is continuous. Every change lands in an Automerge document, which any attached peer sees immediately through the relay.
  • Publish is explicit. The PDS record is written when Save is pressed, and a note that was never saved does not exist anywhere but your browser and your devices.

The lexicons, in progress #

The Scene Notes schema lives on the scene-notes branch of Corliss rather than main — it is being written alongside this client, and it moves:

I'm working on this as a way to work with the Scene Notes lexicon and a standalone client that doesn't require Obsidian. See the in-progress lexicon development. Feedback welcome.

Deploying it — Tangled Sites #

Tangled serves static files from a git branch: it does not build. So the built app is committed to a deploy branch, and Tangled republishes on every push to it.

./scripts/deploy.sh          # build, commit dist/ to `deploy`, push

In the repository's Settings → Sites:

Setting Value
Branch deploy
Deploy directory /
Site type Sub-path — boris.tngl.io/scn-local/

Tangled Sites has no custom domains, and a sub-path site is served under the repository name, so vite.config.ts sets base: "/scn-local/" — every asset and the two metadata documents resolve under that prefix.

The app is its own OAuth client when deployed #

That is the point of deploying rather than tunnelling: an https origin can serve client metadata, so public/client-metadata.json is the client id.

  • client-metadata.json — the atproto client, so the PDS can log you in.
  • corliss-client-metadata.json — the Corliss client, for the sync server.

Both name https://boris.tngl.io/scn-local/ as the redirect. On 127.0.0.1 the app still uses the loopback client id instead — clientId() in auth.ts picks.

This is why deploying changes the shape of a problem: a local app needs a document hosted elsewhere (Corliss#68), and a deployed one hosts its own. What a browser cannot do is read the relay's discovery or /v1/workspaces without CORS headers — Corliss#69 — so the deployed app signs in and reads and writes Public notes, but cannot attach to a sync server until that lands.

The pattern, for anyone writing their own client #

This repo exists to be read by someone building a different one. Four things are worth copying, and the fourth is the one people get wrong.

1. The record is the note. src/notes.ts: one network.sharedcomputer.notes record per note, a markpub markdown body, front matter inside the text. No sidecar, no database, no export step. Any atproto client can read it.

2. The document is one string, edited by splicing. src/document.ts. An Automerge document holds { text }, and every edit — a keystroke, a whole file rewritten elsewhere — is a splice of the difference against what the document holds now:

const operations = diff(current, next);        // fast-diff
handle.change((d) => {
  let index = 0;
  for (const [op, text] of operations) {
    if (op === diff.EQUAL) index += text.length;
    else if (op === diff.DELETE) splice(d, ["text"], index, text.length, "");
    else if (op === diff.INSERT) { splice(d, ["text"], index, 0, text); index += text.length; }
  }
});

Do not write doc.text = next. It is simpler, it looks like it works, and it turns the CRDT into a last-writer-wins register: two clients that both assign leave whichever ran later, and the merge you were paying for never happens. This is the single most common way an Automerge app ends up with no merge.

3. Remember the base. src/mirror.ts. What the file held when you last wrote it, per file. Without it, "the file changed" and "we never saw this file" are the same observation, and reconciling a folder becomes a guess.

4. Reconcile three ways, and refuse when two moved. On a scan, compare the file, the remembered base, and the document:

file document meaning action
= base = base nothing —
≠ base = base edited outside this app splice the file's edit into the document
= base ≠ base edited here or on another device write the document out
≠ base ≠ base concurrent refuse, show the conflict

The refusal is the design. Applying either side would silently discard the other; saying so is the only honest option without a three-way text merge.

Two more, briefly: syncing and publishing are different verbs (sync is continuous, the record changes when Save is pressed), and the handle's permission does not survive a reload — see the folder section.

The three pieces #

File Does
src/notes.ts The record shape, both directions: front-matter split/compose, title and tag resolution, record ↔ note.
src/automerge.ts One document per note in IndexedDB; optional WebSocket adapter to a relay.
src/fs.ts The folder mirror: showDirectoryPicker, handle persisted in IndexedDB, one .md per note.
src/auth.ts Two sign-ins, deliberately separate — see below.

Connecting to a sync server #

A field, defaulted to https://notes.sharedcomputer.network, plus Connect. It follows the plugin's discovery:

  1. GET {relay}/.well-known/oauth-protected-resource → authorization_servers;
  2. GET {issuer}/.well-known/oauth-authorization-server → endpoints.

The SCN relay answers the first with https://sharedcomputer.network, which answers the second with /oidc/authorize, /oidc/token, PKCE S256, and client_id_metadata_document_supported: true — the server expects a client id that is an https URL serving client metadata (CIMD).

That is not a wall — it is a document to add. The plugin's client id is https://sharedcomputer.network/clients/scn-obsidian.json, which Corliss serves itself:

{"client_id": "https://sharedcomputer.network/clients/scn-obsidian.json",
 "client_name": "SCN Sync",
 "redirect_uris": ["obsidian://scn-obsidian"],
 "grant_types": ["authorization_code", "refresh_token"],
 "response_types": ["code"], "token_endpoint_auth_method": "none"}

So a "registered client" here is a JSON document on the authorization server, and a browser client needs one too — with a loopback redirect in it:

https://sharedcomputer.network/clients/scn-local.json
{ "redirect_uris": ["http://127.0.0.1:5173/"] }

The authorization request then carries resource=https://notes.sharedcomputer.network (RFC 8707), which is what gives the token the relay as its audience. Between them that is the whole flow: https client id, http loopback redirect, PKCE S256, and a resource parameter. Until that document exists the token field is the way in, and the status bar says so.

Two sign-ins, and why #

  • Atmosphere (atproto OAuth) is the member's account. It reads and writes their own repository. Everything the prototype promises about Public works with only this.
  • Corliss is the sync server's authorization server. The relay accepts a Corliss-issued JWT, not a PDS token, so attaching to a sync server is a second consent. The prototype asks for it as a pasted token rather than hiding it behind a flow that does not exist yet.

The sign-in asks for write access to one collection. atproto alone authenticates; it does not permit a write. The request carries repo:network.sharedcomputer.notes?action=create&action=update&action=delete, the same term Corliss asks for. A session approved before that term existed is still a valid session and still cannot save — the fix is to sign out and in, not to debug the writer.

Handles are completed by typeahead. A community-run, unauthenticated, CORS-enabled actor search; it also serves the profile card (handle, displayName, avatar) for the signed-in DID, so the header can show a person rather than a DID. Requests carry an X-Client header — that is how the operator attributes traffic — and the index is rate limited at 60 requests a minute, so the field debounces.

The loopback client id is the client metadata, and it is easy to get wrong:

http://localhost?scope=atproto+repo%3Anetwork.sharedcomputer.notes%3Faction%3D…&redirect_uri=http%3A%2F%2F127.0.0.1%3A5173%2F
  • the host is localhost even when the app runs on 127.0.0.1;
  • the redirect carries the path, and must equal the origin the page is served from character for character;
  • the scope lives here, because a loopback client has no client-metadata.json for it — this string is the metadata. Leave it out and the app declares no scope at all: sign-in succeeds, and the first write is refused.

Build it with buildAtprotoLoopbackClientId({ scope, redirect_uris }) from @atproto/oauth-types. The browser package's buildLoopbackClientId emits only the redirect, which is the trap in one line.

The sync contract is the one scn-obsidian already implements — that plugin is the tested reference, not this:

  • socket: ${https → wss}/v1/sync?access_token=… (a browser WebSocket cannot set an Authorization header, so the token rides in the query string);
  • discovery: GET ${syncUrl}/.well-known/oauth-protected-resource → authorization_servers → ${issuer}/.well-known/oauth-authorization-server;
  • listing: GET ${syncUrl}/v1/workspaces with a Bearer token;
  • deps pinned as the plugin pins them: @automerge/automerge 3.5.0, @automerge/automerge-repo 2.5.6, -network-websocket 2.5.6, -storage-indexeddb 2.5.6.

Success criteria #

  1. Read and write Public from the PDS. Sign in, list, edit, Save, and see the change from another client (pdsls.dev is enough).
  2. Attach to a sync server and sync with it. Two tabs, or two devices, converge through the relay while the PDS record waits for Save.

What is deliberately unfinished #

Honest list, because a prototype that hides its seams is a demo:

  • The editor is a textarea, not a bound CRDT editor. The text is written into an Automerge document on every keystroke, but character-level concurrent editing needs the Text object and cursors. This proves the loop, not the merge.
  • noteId → Automerge URL lives in localStorage. It has to survive a reload or every visit forks the document. It belongs in the record as docId — issue #63.
  • The CRDT is not in the record. No automerge blob, no heads. That is #63; this repo stays on the local loop until then.
  • No delete, no spaces, no membership. A Public note needs none of it.
  • The Corliss token is pasted, not obtained. A real client would run the discovery above and sign in.
  • The folder is written back as you type, and read on boot (not watched). Files already on disk are listed and can be opened and published — that makes the folder a copy rather than an export — but there is no FileSystemObserver yet, so a file dropped in while the app is open appears after a re-scan (pick or re-grant the folder), not immediately.
  • No conflict handling between the folder mirror and the record. Local files are matched to records by filename; a file that disagrees with its record is not reconciled, it is just a file.

Open questions #

  • Does the folder mirror come before or after sync? Today the mirror is a one-way copy on save. Watching the folder (the way scn-obsidian does) is the bigger job, and the CRDT is what makes it safe.
  • Does this move to scnorg.tngl.sh? If the prototype becomes SCN's, yes — the organization is where gel.chat lives. Until then a personal repo is the honest home.