Uploads and link previews

Saving and loading documents stays a small endpoint in your own app, the same place your permission check already lives. That endpoint remains the record. It is what lands in your backups, and it is what you clean when someone asks you to delete their data.

Live collaboration adds one moving part. While people edit together, the service keeps a working copy of the open document, in storage you point it at. Every few seconds it writes what people type back to your endpoint.

Losing that working copy costs at most the few seconds of changes not yet written back. The next open starts fresh from your endpoint.

Those same few seconds are a lag in the other direction too. Your record trails what the people in the document are looking at. So an export, a report or another service reading your database sees the document as of the last write-back. It does not see the keystroke someone just typed.

A write-back your endpoint refuses is retried with a growing delay rather than dropped. A document whose last write-back has not landed stays loaded until it does, even after everybody has left it. So a short outage at your endpoint costs time, not edits.

That cadence belongs to the working copy alone. Register an operation journal and the document keeps no working copy at all. The entry below on retry-safe outside edits says how.

With a journal, an edit becomes durable in the journal. The record at your endpoint is then refreshed from a published checkpoint. That refresh happens on eviction and on drain, not on a timer. The lag above is then no longer a few seconds, and the entry on the rollback boundary prices it.

You cannot combine the editor's own persistence option with collaboration. That option is the pair of load and save callbacks a single-player editor uses to talk to your endpoint.

The editor refuses the pair the moment it is created, and it says which one to drop. Otherwise the document would have two owners writing the same record from two places.

Nothing is lost in the trade. The service loads the document from your document endpoint and writes it back to the same route. So it is your endpoint either way, called from the service instead of from the browser.

The same goes for saving by hand. onChange and onSave keep firing while people edit together, including for the edits other people make. That is deliberate, so a form bound to the editor stays current.

Do not write what they hand you back into your record. That is the service's job now, and a second writer only fights it.

Read it the other way round too. The persistence option writes the whole document JSON on a debounce. When saves pile up, only the newest payload goes out.

Every save carries the whole document, so nothing anybody typed is lost: the newest payload carries it. What is never recorded anywhere is the document states in between. It is the compatibility route for a build with no service, not a record of what happened.

Where durable saving is the point, collaboration is the path. The entry on the save state below says what saved means there.

While people edit together, the working copy lives in the folder you name with --collab-dir. It can also live under the S3 prefix you set with --collab-s3-prefix. It holds document content, so it must not be publicly readable.

Uploaded files are meant to be served to anyone with the link. The working copy is meant for the service alone. That is also why the service refuses to put it inside the uploads directory: everything there is served.

Two things about the folder --collab-dir names.

• A file the service cannot read is renamed beside itself with an .unreadable- suffix.
  • The document is then loaded fresh from your endpoint, so one damaged file never wedges a document.
• Temporary files left behind by a writer that died mid-write are deleted when the service starts.

Wherever the working copy lives, one written in a format this service does not read fails the open instead of being guessed at. The log names the format, and the file has to be removed before that document opens again.

Two promises about POST /sync/{doc}/edit hold only where the service has an operation journal.

• Retrying the same Blok-Idempotency-Key returns the first result instead of applying the edit a second time.
• Reusing that key for different work is refused with 409.

The working copy is not a journal. Neither the folder named by --collab-dir nor the prefix named by --collab-s3-prefix keeps the history of what it holds. There are two ways to get one.

• On the standalone host, add --collab-journal, or set BLOK_COLLAB_JOURNAL=true.
  • It keeps the built-in journal on local disk, beside the working copy under --collab-dir.
  • It needs --collab. It is refused with --collab-s3-prefix, because a second instance sharing the bucket would not see a journal on this machine's disk.
  • So it serves one instance. In-process, the same switch is options.CollabJournal.
• For more than one instance, write your own store.
  • Inside your own ASP.NET Core app, implement ICollabOperationStore over storage you already trust with transactions.
  • Register it with AddBlokServer(...).UseCollabOperationStore<YourStore>().
  • A store you register replaces the built-in one.

Either way, the first open of each document adopts the working copy it had as the journal's starting point, then deletes it. Nothing the working copy held is lost.

Document purge needs one more interface. Your store must also implement ICollabOperationPurgeStore. Otherwise PurgeDocumentAsync throws NotSupportedException before it removes anything. The built-in journal already does.

With no journal the service is working-copy-only. An outside edit then behaves like any other request you can retry. It is applied, answered 204, and applied again if you send it twice.

With a journal, every accepted change is committed to your journal before anybody is told about it. So a change that reached a tab is a change that survived the process dying. And an edit the journal cannot commit is answered 503 with nothing relayed, instead of a 204 for a save that did not happen.

What the service asks of a store you write is strict.

• It needs one live writer per document.
• It needs a read that sees every earlier commit.
• It must be durable before the call returns.
• The duplicate check and the sequence assignment happen in one step.
• Any failure must be thrown rather than swallowed.

The server package's README states the whole list beside a working registration.

Registering an operation store is close to one-way, per document. A journal-backed document keeps no working copy at all. The whole-JSON record your endpoint holds is refreshed by three things only: a published checkpoint, an eviction, and a drain. It is never refreshed once per edit window.

Read that as a ceiling, not a promise. The check below is what tells you how fresh the record actually is.

Between those moments the journal is ahead of everything else, so the last edits the service acknowledged sit nowhere a build without your store can read. Unregister the store, or go back to a binary that never had it, and the document lands on whatever else it has.

• A document that has been journal-backed from the start has no working copy.
  • It is loaded fresh from your endpoint, and it comes back as the last record that endpoint accepted.
  • Every operation acknowledged since then is still in your journal, and nothing serves it.
• The first open under the journal adopts a document's working copy as its starting point, then deletes it.
• A document that ran under --collab-dir or --collab-s3-prefix and has not been opened since you registered the store still holds the working copy it had that day.
  • A working copy with anything in it wins the open, and your endpoint is never consulted.
  • That document comes back as it was on the day you switched, with no error and nothing in the log to say so.

Blok does not keep a second whole-document copy beside the journal to make the switch back instant. The journal is the record, and the JSON is a projection of it.

Run this before you roll back.

• Drain the service, which flushes every open room's record.
  • The standalone host drains on a graceful stop.
  • An in-process app calls ICollabRoomManager.DrainAsync.
• Then check, per document, that the last write-back your endpoint accepted carries a Blok-Doc-Sequence equal to your journal head's durable-through on the same Blok-Doc-Lineage.
  • Anything short of that is what the rollback drops.
• For every document that comes up short, open it once on the new build.
  • A read-only join is enough.
  • Then run the drain and the check again.
  • Loading a journal-backed room marks its record owed, and a document whose process crashed with one owed had no room for the drain to flush.
• Only then start the old build, and keep clients held off while you do.

A room hydrated from a working copy carries no document version yet. Its first write-back goes out with no Blok-Doc-Version, so your endpoint has nothing to answer 409 on. One character typed by one user before the reset lands writes the day-of-switch document over the record you just verified.

Finish with one POST /sync/{doc}/reset for every document that had a working copy before you registered the store. That empties the copy, and the next open seeds from your endpoint. Let clients back in after the last reset has returned, not before.

The way forward is one-way too. Register the store again and the journal wins the open, so whatever was typed while the old build was serving is not in it.

While a document is open for live collaboration, the working copy wins. A change written straight into your own records will be overwritten the next time the service writes the document back. So there are two ways in from the outside, and both take a write pass for that document.

To change a few blocks, call POST /sync/{doc}/edit with a list of what to insert, update or remove. That fits a status flipped by a workflow, or a field filled in by a job.

• The change lands in the document.
• It appears in everybody's tab within moments.
• It gets written back to your records like any other edit.

The whole request is one step: if any part of it is refused, nothing is applied. Every edit also needs a Blok-Idempotency-Key header with 1 to 128 printable ASCII characters.

• With an operation journal, retrying the same key with the same request returns the first result without applying it again.
• Reusing that key for different work returns 409.
• A 204 follows the durable commit.
  • It includes Blok-Doc-Lineage and Blok-Doc-Sequence response headers.
• If that commit cannot finish, the service returns 503 and does not relay the change.

A working-copy-only service does not deduplicate the key, and it never answers 409 for reusing one. Retrying it there has ordinary retry behavior, and its 204 still starts the existing write-back retry path. Either way, your own records trail by the write-back delay.

An edit can also be guarded. Send If-Match: "<lineage>:<sequence>", written exactly as those two response headers print them. The edit then applies only while the document is still at that head.

• A different head returns 412 and applies nothing. The 412 carries the current Blok-Doc-Lineage and Blok-Doc-Sequence, so you can retry the same key with a fresh tag.
• A key that is already committed still returns its first result, even when its tag is now stale.
• A working-copy-only service has no head to check, so any If-Match returns 428 and applies nothing.
• A list, *, a weak tag or any other shape returns 400.

To read before you edit, call GET /sync/{doc}/state. It returns the live document as JSON, edits made a moment ago included, and it needs only a read pass for that document. With an operation journal it also sends Blok-Doc-Lineage, Blok-Doc-Sequence and ETag: "<lineage>:<sequence>" for the exact head it reflects. Send that ETag back as If-Match, and the edit applies only if nothing changed in between.

Plan for two refusals. Both return 422 and apply nothing.

• Placing a block under a parent that has no children list.
• An after the parent's children list does not hold.

Each answer names the step and the block:

• collab: op 0: block "p1" has no children list, so nothing can be placed under it.
• collab: op 0: block "b7" is not in the document order, so nothing can be placed after it.

Inserts apply one after another against the document as it stands. So two inserts naming the same after land in reverse order. To append in order, chain them, each naming the one before it.

To replace a document wholesale, for a migration or a support fix, save your version to your own records first. Then call POST /sync/{doc}/reset.

• The service throws its working copy away.
• It loads the document fresh from your endpoint.
• Then it tells every open tab to drop what it had and pick up the new version.

Nobody has to close anything either way. Editing a document nobody has open works too, because the service loads it for the occasion.

One more thing closes the gap between your save and the reset. Once your endpoint answers with a version, every write-back carries the last one it gave in a Blok-Doc-Version header. That header is your optimistic-concurrency handle.

Bump the version on your own save, and answer a stale PUT with 409. The service treats it as a failed write-back and retries. It stays refused until the reset loads your version. So a write already on the wire when you save cannot land over it.

Your host owns grants, trash, restore, retention and permanent deletion. Blok supplies recheck, purge and offline-scope operations, but no access-settings UI.

For revocation, this C# is host pseudocode. Inject ICollabRoomManager as rooms and ICollabDocumentPurger as purger. Commit the ACL before asking Blok to recheck live members.

• await host.CommitRevocationAsync(documentId, userId);
• await rooms.RecheckAccessAsync(documentId);

A revoked tab closes with 4403 forbidden. Allowed peers remain connected and can keep writing. Make new admissions read the committed ACL too. Call RecheckAccessAsync on each server instance serving the document. Do not use reset for an ACL change.

Trash keeps the document ID, body, working set and journal for your retention period. Restore changes only host state and access. Neither action calls purge.

For permanent deletion, this C# is host pseudocode. Commit a durable host tombstone before purging sidecar state.

• await host.CommitPermanentTombstoneAsync(documentId);
• var result = await purger.PurgeDocumentAsync(documentId, token => host.CanPurgeAsync(operatorUser, documentId, token));

Host authorization and consumer GET/PUT must deny the tombstoned ID after the commit, even with a journal. DocumentOpenElsewhere means another instance holds the document, so retry after quiescing it. A partial failure keeps this process barred; keep the host tombstone and retry the purge. After your policy checks, remove the canonical page record and parent pointer separately. Never reuse an opaque page ID.

Without a journal, quiesce every sidecar instance and make consumer GET/PUT durably refuse the tombstoned ID. The in-process gate alone cannot protect another instance or a restart. A journal tombstone blocks re-seeding even if the consumer GET still holds stale content.

For logout or account switch, this TypeScript is host pseudocode. Import inspectOfflineScope and forgetOfflineScope from @bloklabs/core. showDiscardWarning and closeEditorsAndSwitchScope are functions in your app.

• const report = await inspectOfflineScope(oldScope);
• showDiscardWarning(report);
• await closeEditorsAndSwitchScope(oldScope);
• await forgetOfflineScope(oldScope, { discardPending: true });

Inspect the pending outbox, adoptable updates and quarantine before explicitly discarding the whole offline scope. Close or switch every active tab first, or it may recreate that scope. A blocked or failed delete is not success. An already-offline device cannot be remotely erased until it reconnects.

Deleting sidecar data is not physical erasure from backups, replicas or S3 versions. Your host retention policy must handle those copies.

The service calls your document endpoint in two cases. It loads a document the first time someone opens it, and it writes changes back while people edit.

If that endpoint requires login, and it should, put the header value it already expects into the BLOK_DOC_ENDPOINT_AUTH environment variable, Bearer and all. The service sends it verbatim on every call. Your route, your auth scheme, nothing new to build.

One rule on the value: it must be a single line. A carriage return or newline in it stops the service from starting, and it says so. The usual cause is a trailing newline from echo or from a file. A header carrying one would be dropped from every call, with nothing to see anywhere.

The same value can be passed as --doc-endpoint-auth instead, but the service warns against that: a flag puts the credential in the machine's process list.

When the first person opens a document, the service asks your document endpoint for it. For a document you have never saved, answer 200 with null (or { "data": null }). That means "nothing yet", and the editor starts empty.

A 404, a 5xx or an unreachable endpoint is treated as a failure, not as "new". The editor shows a reconnecting notice and nobody can start editing.

Seeding an empty document over a record that merely failed to load would later overwrite it. It also means a mistyped --doc-endpoint path fails loudly at the first open, instead of quietly emptying your documents.

The service writes rich text fields to your document endpoint as segments. GET /sync/{doc}/state answers the same way. Before, data.text was an HTML string such as a <b>b</b>. Now it is a list such as [{ "text": "a " }, { "text": "b", "marks": { "bold": true } }].

• Your endpoint must accept segments when the service writes a document back.
• It may keep serving HTML. The service still accepts HTML from your endpoint and from POST /sync/{doc}/edit, and writes segments back.
• The built-in paragraph, header, quote, toggle and list text fields are always rich.

Your own tools' rich fields need listing. On the standalone host, pass --rich-text-fields as JSON, such as {"callout":["title"]}, or set BLOK_RICH_TEXT_FIELDS. In-process, the same list is options.RichTextFields. List exactly what each tool's richTextFields declares on the client.

Upgrade the service and the editor together. A document stored by an older service is moved to the new format the first time it opens. An older editor refuses the new service, and a new editor refuses an older one.

A file someone uploads is served by whatever hostname you put it on, and a browser trusts a page by its hostname. So if uploads are served from the same hostname as your app, an uploaded file can act as if it were one of your own pages. It can read the signed-in user's session and call your API as them.

The service sends Content-Disposition: attachment and X-Content-Type-Options: nosniff, so a browser downloads such a file instead of running it. But the only complete answer is to put uploads on a different hostname from your app, such as uploads.myapp.com or an S3 bucket's own address.

Five things in the editor read an uploaded file back after it is stored.

• The audio player fetches the track to draw its waveform.
• The image block fetches a GIF before turning it into a video, and an SVG to read its real size.
• The file block fetches a document to show a preview.
• The image download button fetches the picture so the browser saves it rather than opening it.

Once uploads are served from their own hostname, every one of those is a cross-origin request. The browser refuses it unless the response carries Access-Control-Allow-Origin for your app.

Each of them is written to give up quietly rather than break the block. So you get no error.

• The player has no waveform.
• The GIF stays a still image.
• The SVG is the wrong size.
• The preview never appears.
• The download opens the file instead of saving it.

Nothing in Blok reports why. Allow your app's origin on the bucket or hostname the files are served from.

Uploading to S3-compatible storage is built and covered by tests. But those tests check the request against our own reading of the specification. It has never been run against a real bucket, at AWS or anywhere else. Try it on a throwaway bucket before you rely on it.

If the storage refuses a request, the service passes the storage's own explanation through. The message you see is the one that endpoint sent.

Every request that carries an Origin must match an address listed with --allow-origin, in every auth mode. In none and proxy modes, an originless request marked Sec-Fetch-Site: cross-site is also refused. A genuine server-to-server backend request that carries neither header still works.

Ticket mode always requires an allowed Origin. Preflight requests follow the same allowlist.

POST /upload-by-url requires Content-Type: application/json. Parameters such as charset=utf-8 are allowed. Other media types, including application/problem+json, receive 415 before the service fetches the URL.

The service limits how often a caller may make it fetch a URL.

• When --rate-limit is omitted, ticket mode allows 60 requests a minute per caller.
• Otherwise the limit is 0, which turns it off.
• Any explicit value must be zero or greater.

The service tells callers apart by the address the request came from. When your app forwards every request, every request arrives from the same address. So the whole deployment shares one allowance, and one busy user can use it up.

Limiting per user belongs in your own app, on the forwarding route, where you already know who is signed in. This does not apply on the third path, where the pass names the user and each user is counted separately.

A pass always says who is holding it and whether they may write. For uploads and link previews that is all the service reads.

Those routes do not confine the holder to one document. So a pass handed to someone who opened a single page works for every upload and every preview that page can make, for as long as the pass lives.

Live collaboration is stricter.

• A collaboration pass also names the document it may open, and the service checks that name at the door.
  • A pass that names no document, or a different one, is turned away.
• It has to name its user as well, because the connection cap and the per-minute allowance both key on that name.
  • A collaboration pass with an empty user is refused, not pooled with every other anonymous one.

Keep the life short either way. Hand a pass out only from a route that has already checked who is signed in. Keep the per-document check for uploads in your own app, where you know which document is open.

An upload pass is checked on every request, so a few minutes of life is right for it. A collaboration pass is checked once, when the connection opens, and the connection then outlives it. So the pass has to be alive at the moments the editor connects and reconnects.

Around 30 minutes is the balance.

• It is short enough that a leaked pass ages out quickly.
• It is long enough that a laptop waking up or a network blip does not fail because the pass died in between.

Taking someone's access away works the same way. It applies the next time they reconnect, not mid-connection.

In ticket mode, where the browser carries a pass, one person may hold up to eight open collaboration connections to one document. Every tab counts as one. The ninth is refused with "too many connections" (HTTP 429) until one of them closes.

A collaboration pass has to name a user. A pass that names none is turned away at the door with "pass names no user" (close code 4401).

Behind a proxy every such pass would share one cap and one rate window with all the others. When the service runs inside your own ASP.NET app and your login check has named the user, that user is what is counted.

Behind your own app or proxy, in the none and proxy modes of the standalone service, there is no cap at all. Nothing there names the person. Every connection arrives from the one proxy address, and a shared cap would throttle everyone together.

If you need a limit there, put it in the proxy, where you already know who is signed in.

The cap above counts one person. This ceiling counts everybody together, in every auth mode.

With --collab on, the standalone service holds at most 1,024 open collaboration connections per process. So a flood of connections that are opened and then only held open cannot use up every connection the process can hold. The service keeps that count itself.

Past the ceiling a new connection is refused with "too many connections on this server" (HTTP 503), until one of the open ones closes. The refusal comes before the document is loaded, so nothing is fetched from your endpoint for a connection that will not run.

Inside your own ASP.NET app there is no ceiling unless you set CollabMaxConnections, where 0 means none. Give it the same number as Kestrel's MaxConcurrentUpgradedConnections. Kestrel stays the backstop underneath, and it refuses later and less usefully: it lets the document load first and then answers 500.

While a document is open, exactly one service process holds its working copy in memory. Every connection to that document must reach that same process.

Two processes opening the same document would each keep a copy of their own. They would take turns overwriting each other's work in storage. So more processes only help if each document belongs to one of them.

The split is simple, because the document id is right in the connection address. Route by the document id, so every request whose path starts with /sync/{doc} lands on the same process. Anything deterministic works, from "ids starting with a through m go to the first process" to a hash of the id.

• The reset call lives under the same path, so it automatically reaches the process that owns the document.
• Each process then carries its own share of the documents, with its own connection ceiling.
• All of them may share one storage folder or bucket and one document endpoint, because no two of them ever open the same document.
• Uploads and link previews hold nothing in memory, so those requests may go to any process.

There is no built-in coordination behind this. The processes do not know about each other, and nothing in the service stops a routing mistake from opening one document twice. The routing rule is the guarantee, and it is yours to keep.

The service puts no cap on how many documents one person may have open. It puts no cap on how large a document may grow. It puts no cap on how often an unknown document id makes the service ask your document endpoint for a seed.

Those are your records and your rules. If you need such limits, put them in your own backend, where the permission check already lives.

What the service does bound is one connection, in five ways.

• A single message is at most 1 MiB. A bigger one closes the connection.
• A browser can stop taking messages, for example a frozen tab or a dead network.
  • It is closed once the messages waiting for it pass 8 MiB.
  • It catches up when it reconnects.
  • Inside your own ASP.NET app, CollabMaxMessageBytes moves both numbers together.
• A connection that floods the service is closed with "inbound rate exceeded" (code 1008), and the editor reconnects.
  • Flooding means more than about 50 messages a second once a burst of 100 is used up.
  • It also means more than 60 requests a minute to resend the whole document or to ask everyone present to re-announce themselves.
  • And it means one message split into an absurd number of pieces. The allowance is sixteen pieces plus one more for every 64 bytes the message carries. So a flood of empty fragments ends at the seventeenth.
• Presence is counted in bytes as well: about 128 KiB a second per connection after a burst of about 512 KiB.
  • Flooding it earns that same close.
  • Inside your own ASP.NET app the knobs are CollabInboundFramesPerSecond, CollabInboundBurstFrames, CollabInboundResyncsPerMinute and CollabInboundAwarenessBytesPerSecond.
  • A value of 0 turns any of the rates off.
• Opening a connection spends the same per-minute --rate-limit budget as every other route.

Beyond those five, an open connection is not limited. The service tells the editor the message-size limit when it connects. So the editor refuses to send something too big instead of being disconnected for it.

One rule is about shape rather than size. The sync wire is binary, so a text message closes the connection with "binary frames only" (code 1003). Blok's editor never sends one, so that close means something else is talking to the route.

The service checks the shape of what a write pass sends, not its meaning. Three things pass through as a result, and they are worth knowing.

• A lone surrogate becomes U+FFFD on the wire. That is half of a UTF-16 pair, which typing never produces but a script can. Every replica then reads the replacement character, including that browser's own copy after a reload.
• An update can integrate nothing because the changes it depends on never arrive. It is not refused. It is relayed and persisted like any other.
  • From outside, a duplicate delivery and a legitimately out-of-order change look the same. So a writer who keeps sending them grows the working copy until the document is evicted from memory, and nothing else bounds it.
• Anything arriving through the document, another browser or an edit request, can place a block under a container whose childTools denies it. The editor places it where the document says, and logs a warning naming the child and the container. It does not demote it, because demoting would write back and loop against the peer.

The one thing that does not pass through is a block the reader cannot make sense of. A block whose id or type is not text is left out of the saved document. So is a block whose data is not a set of fields. Each one gets a warning naming it.

A value nested more than 256 levels deep is saved as null. The editor and the service do exactly the same thing here. So what a browser saves and what the service writes back to your records agree block for block.

A document opens read-only and stays that way until the first sync arrives. The editor never starts from a copy of its own. Two browsers each starting from their own copy and then syncing would duplicate every block.

Once that first sync lands the document becomes editable. This holds as long as the pass grants write and your app has not put the editor in read-only itself.

After that the behaviour is deliberately asymmetric. If the connection drops, the document stays editable. What gets typed piles up in that tab. It is shipped the moment that tab reconnects. So a tunnel or a sleeping laptop does not freeze the page under someone's hands.

The editor reports each step on the collaboration:status event. The steps are connecting, connected, offline while it keeps retrying, and error. error means it has stopped for good and will not reconnect by itself.

The event carries the list of people present, so you can render your own indicator in the shape your product already uses. Blok does not paint one for you.

None of those four says the work is saved. They describe the socket, not the queue behind it. The next entry is the one that says what has been taken.

Connecting, connected and offline describe the socket. None of them says the work has been taken. The same collaboration:status event carries a second block that does say it: save.

Its state is one of five.

• saved means nothing is waiting.
• pending means edits are queued in this tab and not acknowledged yet.
  • A connected session reports pending too, because a socket that is up is not a save.
• blocked means the local queue broke and nothing more may be sent, with the reason local-storage-failed.
  • Editing stops for the rest of the session.
• quarantined means edits were taken out of the queue and will never be sent, and quarantinedOperations counts them.
  • With the offline option on they stay in this browser's copy.
  • Without it only that count survives.
• unavailable means no durable save can be reported at all.
  • That is what a service without an operation journal answers, with the reason legacy-protocol once it has said so.

Beside the state, pendingOperations and pendingBytes size the queue. serverSequence is where the journal put the last acknowledged edit. It is a decimal string, because the ceiling does not fit a JavaScript number.

• Draw connected with pending as saving, and saved as saved.
• Draw quarantined as an error somebody has to be told about.
• Draw unavailable as no save indicator at all, rather than a green one.

The event carries this whether or not the connection changed. A save state that moves on its own publishes one. An identical payload publishes nothing. One replay lands shortly after the editor is ready, so a listener attached late still learns where it stands.

One caution about the counts: a local queue that cannot be read at all reports zero rows. So zero under blocked means unknown, not nothing waiting.

The boundary is exact. An edit counts as saved once the service has committed it to your operation journal. That append has to return before anybody else is shown the edit.

• A socket send is not it.
• A peer seeing the change is not it.
• Neither is the whole-JSON write-back to your endpoint, which happens later and can fail on its own.

This is also why one person on their own should use it. A single-user editor pointed at the service gets the same queue, the same journal and the same receipt as ten people do. Here too, save is what an indicator should read.

Without an operation journal none of it is reachable. No flag registers one, so a stock service negotiates the legacy protocol and reports unavailable for the life of every session.

By default those offline edits live in that tab and nowhere else until it reconnects. Reload the tab, close it or lose the browser before that happens, and they are gone. The tab was holding the only copy, and nothing had reached the working copy or your records yet.

Turning on the editor's offline option changes that. It keeps a copy of the document in that browser. A reload then picks the work back up and sends it on the next connection.

The option is off unless you ask for it. It writes document content into the visitor's browser storage. That is a decision about your data rather than about the editor.

Two things to know about the copy.

• Nothing is kept until the first successful sync. So an editor that never reached the service still cannot start from a copy of its own.
• The copy is thrown away whenever the service says its history no longer matches, after a reset for instance. That way a stale copy can never be mistaken for the live document.

Turning the option on requires one more thing: an offlineScope, a stable id for whoever is signed in. Browser storage belongs to the browser rather than to a person. That id is what keeps each person's copy to themselves.

The editor refuses to start with the offline option on and no offlineScope. So there is no unpartitioned copy left to get wrong.

Make that id opaque and stable: the same string every time that person signs in, on every device. Anything that rotates, such as a ticket or a session id, mints a fresh partition on every refresh. It strands every copy behind it, offline edits included.

The copy is also not a backup. Blok never asks the browser to keep it, so a browser short of space may drop it without telling anyone. Clearing site data does the same on purpose.

If you do not turn the offline option on, the guidance stays the plain one. While the editor says it is offline, leave the tab alone and let it reconnect.

Edits to different blocks merge cleanly, and so do edits to different fields of the same block. One person retitling a heading while another ticks a checklist item never collide, and neither loses anything.

Inside one field it is coarser. Two people typing in the same paragraph at the same moment do not get their letters woven together. Whichever change lands last is the one everybody keeps, and the other is dropped.

Notion behaves the same way, and so does every editor that syncs whole fields rather than characters. Character-by-character merging is a later phase. In practice two people rarely type in one sentence at once, and presence is there so they can see when they are about to.

Blok draws presence itself.

• You get small avatars for the people in the document.
• You get a colored cursor where each of them is typing.
• You get a small face with their initials parked in the margin beside the block they are in.

The cursor pulses once they stop moving. Hover the face for the full name. The cursor itself carries no name tag, so a document with four people in it never becomes a wall of them.

Both read the display identity you pass in the editor's collaboration option. That identity is a name, plus an optional color used for that person's avatar, face and cursor.

Leave it out and the person still shows up as a space silhouette, such as a comet, a rocket or a satellite. The silhouette comes with a matching name in the reader's own language. So nobody is a blank disc, and no two people in a document wear the same one.

This is display only. It is independent of the separate user option that stamps who last edited a block.

One answers "whose cursor is that", the other answers "who gets the credit for this edit". Set either, both or neither.

When somebody else selects text within a single block, that run is tinted in their color too. The tint is a translucent wash laid over the text, not behind it. It never intercepts a click, so you can still put your own cursor anywhere inside it. A selection that spans several blocks is not drawn at all, cursor included.

The small avatars and cursors that show who is in the document are relayed exactly as each browser sends them. The service never reads what they say, like every collaboration server built on the same sync protocol.

It does check their shape. A presence message the receiving browsers cannot read ends their session, so every one is walked and each person's state has to be valid JSON.

• A state that is not valid is dropped and written to the log.
• The third bad one from a single connection closes it with "malformed awareness" (code 1008), and the editor reconnects as it always does.

What is never checked is what presence claims. Any participant, including one holding a read-only pass, can announce any name and any position. Document content is what the pass protects: who may open a document and who may change it is checked at the door.

Presence is a courtesy signal for the people in the room, not an identity check. Never build permissions or an audit trail on it.

A document relays presence for up to 256 people at once. Presence means the avatars, and the cursor showing where each person is typing.

Past that the presence updates are dropped instead of passed on, and the service writes a line to its log saying so. That is a drop and nothing more: a crowded room costs nobody their connection, unlike a presence message the service cannot parse at all.

Editing is untouched. Everyone keeps typing, and every change still merges and reaches your records as usual. So if a document ever gets that crowded, what breaks is people seeing each other, not people working.

This is a presence-only degradation, not a limit on how many may edit one document. There is no setting for the number. It is fixed inside the service.

The document id travels in the connection address (/sync/{doc}) and inside the pass, and the two must match character for character. The core rule follows from that: the id has to be one path segment.

Letters, digits, dashes, underscores and dots are safe. A slash, even an encoded one, is refused at the door with a clear message, "document ids must be a single path segment". It does not fail later as a pass that mysteriously names another document.

Use your own opaque ids. If your records are addressed by paths, map each path to a token on your side and hand the editor the token.

The standalone host speaks plain HTTP. It does not terminate TLS or manage certificates. An internet-facing deployment must sit behind a reverse proxy or hosting platform that accepts HTTPS and forwards HTTP over a private or loopback connection. Never send a ticket over plain internet traffic.