- TypeScript 92%
- CSS 5%
- Shell 2%
- HTML <1%
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 underbmann.ca, not thescnorg.tngl.shorganization, 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
· grantwhen 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:
- https://github.com/Z-Space-Society/Corliss/tree/scene-notes/lexicons — the
two lexicons:
network.sharedcomputer.notes(the note record) andnetwork.sharedcomputer.workspace(the space type that holds a workspace's notes). - https://github.com/Z-Space-Society/Corliss/blob/scene-notes/lexicons/README.md — why the schemas are on a branch instead of Corliss proper.
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:
GET {relay}/.well-known/oauth-protected-resource→authorization_servers;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
localhosteven when the app runs on127.0.0.1; - the redirect carries the path, and must equal the origin the page is served from character for character;
- the
scopelives here, because a loopback client has noclient-metadata.jsonfor 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 anAuthorizationheader, 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/workspaceswith a Bearer token; - deps pinned as the plugin pins them:
@automerge/automerge3.5.0,@automerge/automerge-repo2.5.6,-network-websocket2.5.6,-storage-indexeddb2.5.6.
Success criteria #
- Read and write Public from the PDS. Sign in, list, edit, Save, and see the
change from another client (
pdsls.devis enough). - 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
Textobject and cursors. This proves the loop, not the merge. noteId → Automerge URLlives in localStorage. It has to survive a reload or every visit forks the document. It belongs in the record asdocId— issue #63.- The CRDT is not in the record. No
automergeblob, noheads. 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
FileSystemObserveryet, 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-obsidiandoes) 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 wheregel.chatlives. Until then a personal repo is the honest home.