@brass-build/client 0.4.1 → 0.5.0

package/dist/session.js

@@ -6,8 +6,14 @@
 // registered canvas it also auto-captures the thumbnail. The app renders the
 // commands and draws from `session.document`. Every primitive the session
 // calls stays public, so an app can ignore the session and wire them directly.
+import { placeThroughHostedSurfaces } from './placement.js';
 import { BrassError } from './errors.js';
 import { makeLiveCommand } from './document-commands.js';
+import { appCallbackError } from './subscriber-delivery.js';
+// Thrown through a guest open whose link leads its claimant to sign in: the
+// open ends with no document and no error, on the signed-out surface.
+class SignInToFollowLink extends Error {
+}
 // Built-in orphan command labels (no active doc needed). Sentence case, ASCII
 // ellipsis, per the copy-style rules. Both stay bare: an app's own word for
 // what it holds is rarely "document" (a sketch, a model, a sheet), so a
@@ -15,6 +21,9 @@ import { makeLiveCommand } from './document-commands.js';
 const SESSION_LABELS = {
     new: 'New',
     open: 'Open...',
+    // Without an account there is nothing to browse, so Open takes a file from
+    // the reader's own machine.
+    upload: 'Upload...',
 };
 function toError(err) {
     return err instanceof Error ? err : new Error(String(err));
@@ -22,14 +31,17 @@ function toError(err) {
 // Fallback copy for a failed open with no server message to render (a
 // network drop, no HTTP response). The HTTP case carries the server's own
 // message instead, so the platform evolves the wording without an app change.
-const OPEN_FAILED_MESSAGE = 'This document could not be opened';
+const OPEN_FAILED_MESSAGE = 'This could not be opened';
+// The session holds a live copy, so a frozen one is opened beside it.
+const FROZEN_IN_SESSION = 'The session holds a live copy of its document. Open a frozen copy with Brass.openDocumentById';
+const PREPARING_MESSAGE = 'Preparing for editing...';
 // Copy parked on `session.error` when the open document is evicted remotely
 // (a `doc_gone` the local user did not initiate). Matches the wording a
-// post-eviction op frame degrades to ("the document is no longer available"),
+// post-eviction op frame degrades to ("this is no longer available"),
 // so a delete observed live and a fresh visit to the same deleted id read the
 // same. A reload re-opens the id, hits the server 404, and swaps in the
 // server-authored copy.
-const DOCUMENT_GONE_MESSAGE = 'This document is no longer available';
+const DOCUMENT_GONE_MESSAGE = 'This is no longer available';
 // The error parked on `session.error` for a failed open, shaped so its
 // `.message` is always presentable copy an app can render verbatim. An HTTP
 // failure is returned as-is: its `.message` is the server's (non-disclosing,
@@ -66,6 +78,9 @@ export function createDocumentSession(deps) {
     // changes, so a per-commit `doc.subscribe` that doesn't move a command's
     // enabled state stays quiet.
     let lastSignature = null;
+    // Counts the documents bound, so a new copy of the same id (a reopen for
+    // editing, a reload) changes the signature and reaches subscribers.
+    let bindCount = 0;
     // Outstanding `whenReady()` promises, settled in `emit()`: resolve once a
     // document binds, reject if the user signs out before one ever does.
     const whenReadyPending = [];
@@ -95,17 +110,53 @@ export function createDocumentSession(deps) {
     // delete retracts its id, so a later remote delete of the same doc is not
     // misread as local.
     const localDeletes = new Set();
+    // Set for the length of an open started without an account (see `status`).
+    let accountFreeOpen = false;
+    // Documents the session opened read-only by request, as opposed to ones a
+    // reader's access made read-only. A reopen of one (a move, a reload) keeps
+    // that mode.
+    const readOnlyOpens = new WeakSet();
+    // The read intent of one open: the caller's ask where it made one, else the
+    // mode the app set at init.
+    function inMode(options, asked) {
+        const readOnly = asked ?? (deps.openReadOnly?.() === true ? true : undefined);
+        return readOnly === undefined ? options : { ...options, readOnly };
+    }
+    // Opens that asked to read, keyed by the open's own promise, so `activate`
+    // records the document it binds from one in `readOnlyOpens`.
+    const readOnlyAsks = new WeakSet();
+    function remember(opened, options) {
+        if (options.readOnly ?? options.documentOptions?.readOnly === true) {
+            readOnlyAsks.add(opened);
+        }
+        return opened;
+    }
+    function openById(docId, options, consent) {
+        const opened = consent === undefined
+            ? deps.openDocumentById(docId, options)
+            : deps.openDocumentById(docId, options, consent);
+        return remember(opened, options);
+    }
+    function openByLink(openGuest, token, options) {
+        return remember(openGuest(token, options), options);
+    }
     function status() {
         // 'unknown' before auth settles; the onUserChange handler re-fires
         // (start() / emit()) and flips this to its resolved value.
         if (deps.authStatus() === 'unknown')
             return 'unknown';
+        if (deps.initFailure?.())
+            return 'error';
         // A guest (opened via `?brass_link=`) is not signed in but still has a
         // read-only document to load, so it never reports 'signed-out' (which
         // would render the app's sign-in surface instead of the document).
         const isGuest = deps.guestLinkToken?.() != null;
-        if (!deps.isSignedIn() && !isGuest)
+        // An open started without an account loads before there is a link to be
+        // a guest on (a pick sends its file first), and the visitor is watching
+        // that load, not the sign-in surface.
+        if (!deps.isSignedIn() && !isGuest && !(loading && accountFreeOpen)) {
             return 'signed-out';
+        }
         if (loading)
             return 'loading';
         if (document)
@@ -129,15 +180,25 @@ export function createDocumentSession(deps) {
         const load = loading ? `${loadingMessage ?? ''}:${loadingProgress ?? ''}` : '';
         // `openError` message joins the signature so a switch from one failed open
         // to a different one (same 'error' status, no bound doc) still re-fires.
-        const err = openError ? `${openError.status ?? ''}:${openError.message}` : '';
+        const shown = openError ?? deps.initFailure?.() ?? null;
+        const err = shown ? `${shown.status ?? ''}:${shown.message}` : '';
         // The previewed version and the browsing flag are their own terms because
         // nothing else in this signature follows them: a preview -> preview step
         // holds the id, the name, the status and every command's enabled state
         // (edit affordances are already disabled by the first checkout), so
         // without these the step is a silent emit and the chrome rendering the
         // preview keeps showing the version the reader stepped away from.
-        const ver = `${document?.version ?? ''}:${document?.versionBrowsing ? 1 : 0}`;
-        return `${status()}|${document?.id ?? ''}|${documentName ?? ''}|${load}|${err}|${ver}|${cmds}`;
+        const ver = `${document?.previewVersion ?? ''}:${document?.versionBrowsing ? 1 : 0}`;
+        // The expiry moves once, to null, when the document is claimed; the
+        // chrome naming it has to hear that.
+        const expiry = document?.expiresAt?.getTime() ?? '';
+        return `${status()}|${bindCount}|${document?.id ?? ''}|${documentName ?? ''}|${load}|${err}|${ver}|${expiry}|${cmds}`;
+    }
+    // A listener that throws usually leaves the app showing nothing, so the
+    // app's `onError` hears about it as well as the console.
+    function reportListenerThrow(err) {
+        console.error('[Brass] session listener threw:', err);
+        deps.reportError(appCallbackError(err));
     }
     function emit() {
         const sig = signature();
@@ -157,7 +218,7 @@ export function createDocumentSession(deps) {
             }
             catch (err) {
                 // A throwing listener must not strand the others.
-                console.error('[Brass] session listener threw:', err);
+                reportListenerThrow(err);
             }
         }
     }
@@ -177,12 +238,14 @@ export function createDocumentSession(deps) {
             for (const { reject } of pending)
                 reject(error);
         }
-        else if (current === 'error' && openError) {
-            // A user-initiated open failed terminally; reject rather than hang the
-            // awaiter forever. Same error object the session surfaces on `.error`.
+        else if (current === 'error' && session.error) {
+            // A user-initiated open failed terminally, or init could not start;
+            // reject rather than hang the awaiter forever. Same error object the
+            // session surfaces on `.error`.
+            const failure = session.error;
             const pending = whenReadyPending.splice(0, whenReadyPending.length);
             for (const { reject } of pending)
-                reject(openError);
+                reject(failure);
         }
         // No branch for 'empty': it is both the idle pre-open state (an awaiter
         // legitimately waits for a future open) and the post-close state. A close
@@ -211,10 +274,70 @@ export function createDocumentSession(deps) {
             notify: emit,
         });
     }
-    const cmdNew = buildOrphanCommand('new', SESSION_LABELS.new, 'session', 'menu', deps.isSignedIn, async () => {
+    // New and Open start a document without an account where the app can mint
+    // one, so a visitor's own buttons and the menu run the same commands.
+    // A failed init leaves the page signed out with nothing either command
+    // could reach, so neither is offered.
+    const withoutAccount = () => {
+        if (deps.initFailure?.())
+            return false;
+        const status = deps.authStatus();
+        return status === 'signed-out' || status === 'guest';
+    };
+    // The server refuses every account-free route for an app that does not
+    // offer signed-out use, so New and Open are withdrawn once it says so
+    // rather than offered only to show that refusal. Read lazily, from the
+    // first check made while signed out, and settled for the page.
+    let signedOutRefusal = null;
+    let signedOutProbe = null;
+    const refusedWithoutAccount = () => {
+        if (signedOutProbe === null && deps.signedOutUseRefusal) {
+            const read = deps.signedOutUseRefusal;
+            signedOutProbe = (async () => {
+                try {
+                    signedOutRefusal = await read();
+                }
+                catch {
+                    signedOutRefusal = null;
+                }
+                if (signedOutRefusal !== null)
+                    emit();
+            })();
+        }
+        return signedOutRefusal !== null;
+    };
+    const canStartWithoutAccount = () => withoutAccount() &&
+        !refusedWithoutAccount() &&
+        deps.mintAnonymousDocument !== undefined &&
+        deps.enterGuestMode !== undefined &&
+        deps.openDocumentByLink !== undefined;
+    const canPickWithoutAccount = () => canStartWithoutAccount() &&
+        deps.chooseAnonymousFile !== undefined &&
+        deps.mintAnonymousDocumentFromFile !== undefined;
+    // An app that creates no documents offers no New. Read lazily, from the
+    // first check, and settled for the page; until it answers, New is offered.
+    let offersNew = true;
+    let offersNewProbe = null;
+    const appOffersNew = () => {
+        if (offersNewProbe === null && deps.appOffersNew) {
+            const read = deps.appOffersNew;
+            offersNewProbe = (async () => {
+                try {
+                    offersNew = await read();
+                }
+                catch {
+                    offersNew = true;
+                }
+                if (!offersNew)
+                    emit();
+            })();
+        }
+        return offersNew;
+    };
+    const cmdNew = buildOrphanCommand('new', SESSION_LABELS.new, 'session', 'menu', () => appOffersNew() && (deps.isSignedIn() || canStartWithoutAccount()), async () => {
         await create();
     });
-    const cmdOpen = buildOrphanCommand('open', SESSION_LABELS.open, 'session', 'menu', deps.isSignedIn, async () => {
+    const cmdOpen = buildOrphanCommand('open', () => (withoutAccount() ? SESSION_LABELS.upload : SESSION_LABELS.open), 'session', 'menu', () => deps.isSignedIn() || canPickWithoutAccount(), async () => {
         await pick();
     });
     const orphanCommands = [cmdNew, cmdOpen];
@@ -249,6 +372,8 @@ export function createDocumentSession(deps) {
             sessionCanvasUnregister = null;
         }
         const previous = document;
+        if (next !== previous)
+            bindCount += 1;
         document = next;
         documentName = name;
         if (next === null) {
@@ -262,6 +387,17 @@ export function createDocumentSession(deps) {
                 // A close failure (already-closed, freed WASM) is non-fatal.
             }
         }
+        if (next && next !== previous) {
+            // `reopen` on the bound copy goes through the session, so the new copy
+            // binds in its place. A copy the session no longer holds reopens the
+            // way the layer that opened it would.
+            const outside = next._reopenerFn;
+            next._setReopener((mode) => document === next
+                ? reopenBound(next, mode)
+                : outside !== null
+                    ? outside(mode)
+                    : Promise.reject(new BrassError('This document cannot be reopened', { status: 0 })));
+        }
         if (next) {
             // `subscribe` fires on every change including local mutations (the
             // session's listeners drive UI that re-renders on local edits). The
@@ -274,6 +410,8 @@ export function createDocumentSession(deps) {
                 // the pinned branch settles once the default is known.
                 if (event.kind === 'branches')
                     syncUrlForActive('replace');
+                if (event.kind === 'change' && event.source !== 'remote')
+                    noteTrialEdit(next);
                 // Take the doc's name whenever it moves. A rename reaches the doc
                 // from the server's `doc_meta` frame, which sets it directly, and
                 // `documentName` is what the emit signature reads: without this the
@@ -312,15 +450,34 @@ export function createDocumentSession(deps) {
                     // keeps its topic subscription and its LoroDoc until it is closed, so
                     // every move would otherwise leave one resident for the life of the
                     // page, taking a copy of every op the reopened document receives.
+                    //
+                    // A guest holds no access by id, so it re-opens through its link,
+                    // as its first open did.
+                    //
+                    // A copy that is already read-only (a reload onto converted or
+                    // sealed content, or one discarding a refused change) stays bound
+                    // until the re-opened one replaces it, so the reader keeps seeing
+                    // the document instead of a loading surface between two copies of
+                    // it. Nothing can be written to it in the meantime. An editable one
+                    // is detached as any other open detaches its predecessor.
                     const branch = urlBranch(next);
                     const evicted = next;
-                    document = null;
-                    documentName = null;
-                    void activate((onSnapshotProgress) => deps.openDocumentById(id, {
-                        ...withDefaults(),
-                        ...(branch ? { branch } : {}),
-                        onSnapshotProgress,
-                    }, 'skip'), null, 'skip', branch)
+                    const keepBound = next.readOnly;
+                    const mode = readOnlyOpens.has(next) ? { readOnly: true } : {};
+                    const guestToken = deps.guestLinkToken?.();
+                    const openGuest = deps.openDocumentByLink;
+                    if (!keepBound) {
+                        document = null;
+                        documentName = null;
+                    }
+                    void activate((onSnapshotProgress) => guestToken && openGuest
+                        ? openByLink(openGuest, guestToken, { ...mode, onSnapshotProgress })
+                        : openById(id, {
+                            ...withDefaults(),
+                            ...(branch ? { branch } : {}),
+                            ...mode,
+                            onSnapshotProgress,
+                        }, 'skip'), null, 'skip', branch, true, keepBound)
                         .catch(() => markGoneRemote())
                         .finally(() => closeQuietly(evicted));
                     return;
@@ -426,9 +583,16 @@ export function createDocumentSession(deps) {
     // boot last-selected fallback, whose failure is a stale-persistence
     // self-heal that should settle silently on empty (the user asked for
     // nothing specific).
-    surfaceOpenError = true) {
+    surfaceOpenError = true, 
+    // Re-opening the document already bound: it stays bound, and the session
+    // stays 'ready', until the new copy replaces it. A failure detaches it as
+    // though it had been detached at the start.
+    keepBound = false, 
+    // With `keepBound`: a failure leaves the bound document in place and only
+    // rejects the caller.
+    keepOnFailure = false) {
         const generation = ++openGeneration;
-        loading = true;
+        loading = !keepBound;
         loadingMessage = null;
         loadingProgress = null;
         // A new open attempt supersedes any prior failure's error state.
@@ -439,11 +603,13 @@ export function createDocumentSession(deps) {
         // 'loading' until the new doc binds; a failed open restores the previous
         // binding. The doc-event/gone subscriptions stay attached (`setDocument`
         // re-points them, and the restore path watches the same doc).
-        const previousDocument = document;
-        const previousName = documentName;
+        let previousDocument = keepBound ? null : document;
+        const previousName = keepBound ? null : documentName;
         const previousSpecifiedBranch = activeSpecifiedBranch;
-        document = null;
-        documentName = null;
+        if (!keepBound) {
+            document = null;
+            documentName = null;
+        }
         // What the join's spilled ops have cost so far, and what the whole
         // download was declared to be. Carried across the two phases so the pair
         // reads as one figure. Per open, because a second open of the same
@@ -453,9 +619,19 @@ export function createDocumentSession(deps) {
         emit();
         // Surface snapshot-download progress. Ignored once a newer open supersedes
         // this generation, so a slow stale download can't repaint the new open.
-        const onSnapshotProgress = (loaded, total, phase) => {
+        const onSnapshotProgress = (loaded, total, phase, message) => {
             if (generation !== openGeneration)
-                return;
+                return false;
+            // The platform is making the document editable, or replacing a
+            // reader's content, and the open waits for it with nothing bound
+            // meanwhile. A replacement is described in the platform's own words.
+            if (phase === 'preparing' || phase === 'importing') {
+                loadingProgress = null;
+                loadingMessage =
+                    phase === 'preparing' ? PREPARING_MESSAGE : message !== undefined && message !== '' ? message : 'Loading...';
+                emit();
+                return true;
+            }
             // One download, reported once. A document whose ops spilled to storage
             // fetches them from the join before the snapshot, so a load has two
             // stretches of bytes arriving over the network with a reader watching.
@@ -504,6 +680,7 @@ export function createDocumentSession(deps) {
                 loadingMessage = `Downloading... ${(loaded / 1_000_000).toFixed(1)} MB`;
             }
             emit();
+            return true;
         };
         // Give up on this open. A warm swap (previous doc present) rebinds it and
         // only rejects the caller, so the working surface is never clobbered; with
@@ -512,6 +689,13 @@ export function createDocumentSession(deps) {
         // and read as the app's document-less home. `display` is what the app
         // renders; it defaults to the platform's own open-failure copy.
         function abandonOpen(err, display) {
+            if (keepOnFailure && generation === openGeneration) {
+                loading = false;
+                loadingMessage = null;
+                loadingProgress = null;
+                emit();
+                throw err;
+            }
             if (generation === openGeneration) {
                 loading = false;
                 loadingMessage = null;
@@ -519,7 +703,11 @@ export function createDocumentSession(deps) {
                 // 'replace' restores the URL without planting an entry for an open
                 // that never happened.
                 activeSpecifiedBranch = previousSpecifiedBranch;
-                if (surfaceOpenError && previousDocument === null) {
+                if (err instanceof SignInToFollowLink) {
+                    // The URL names the document the sign-in returns to.
+                    setDocument(previousDocument, previousName, 'skip');
+                }
+                else if (surfaceOpenError && previousDocument === null) {
                     openError = display ?? toDisplayError(err);
                     // Leave the URL pointing at the doc that failed ('skip', not the
                     // 'replace' below that clears it for a null document): the error
@@ -538,13 +726,36 @@ export function createDocumentSession(deps) {
             }
             throw err;
         }
+        // A file the open sends before there is a document to read.
+        const onUploadProgress = (loaded, total) => {
+            if (generation !== openGeneration)
+                return;
+            loadingProgress = total > 0 ? Math.min(1, loaded / total) : null;
+            loadingMessage =
+                loadingProgress === null
+                    ? 'Uploading...'
+                    : `Uploading... ${Math.floor(loadingProgress * 100)}%`;
+            emit();
+        };
+        // A load that moves the page onto another document's link takes the
+        // outgoing document's credential with it, so that document closes then
+        // rather than after the bind, and a failed open has nothing to rebind.
+        const releasePrevious = () => {
+            closeQuietly(previousDocument);
+            previousDocument = null;
+        };
         let doc;
+        let askedToRead = false;
         try {
-            doc = await load(onSnapshotProgress);
+            const opening = load(onSnapshotProgress, onUploadProgress, releasePrevious);
+            askedToRead = readOnlyAsks.has(opening);
+            doc = await opening;
         }
         catch (err) {
             abandonOpen(err);
         }
+        if (askedToRead)
+            readOnlyOpens.add(doc);
         if (generation !== openGeneration) {
             // A newer open / close superseded this one. Discard the orphan (so its
             // WS subscription doesn't leak) plus the doc this generation detached.
@@ -552,13 +763,14 @@ export function createDocumentSession(deps) {
             closeQuietly(previousDocument);
             return doc;
         }
-        // A doc opened mid-preparation (drive-stub hydration, upload extraction)
-        // arrives empty + read-only with a pending blocking status; the SDK
-        // imports the content and emits the terminal status when the work
-        // finishes. Hold the session in 'loading' (surfacing the server message)
-        // and bind only on that terminal status, so the editor's first paint sees
-        // the content. A pending push is non-blocking and binds immediately.
-        const work = doc.status;
+        // An open by id resolves with the document's content or rejects, waiting
+        // out any import first. A trial document opened through its link can
+        // arrive empty while the visitor's file is imported, with a pending
+        // blocking status; hold the session in 'loading' (surfacing the server
+        // message) and bind only on the terminal status, so the editor's first
+        // paint sees the content. A pending push is non-blocking and binds
+        // immediately.
+        const work = doc._workStatusNow;
         if (work !== null && work.pending && work.blocking !== false) {
             loadingMessage = work.message;
             loadingProgress = work.progress ?? null;
@@ -600,7 +812,7 @@ export function createDocumentSession(deps) {
         // platform's own message is what the app renders.
         if (doc._contentLoadFailed) {
             closeQuietly(doc);
-            const failure = new BrassError(doc.status?.message ?? OPEN_FAILED_MESSAGE, { status: 0 });
+            const failure = new BrassError(doc._workStatusNow?.message ?? OPEN_FAILED_MESSAGE, { status: 0 });
             abandonOpen(failure, failure);
         }
         loading = false;
@@ -637,14 +849,24 @@ export function createDocumentSession(deps) {
                 return document;
             const openGuest = deps.openDocumentByLink;
             try {
-                return await activate((onSnapshotProgress) => openGuest(guestToken, { onSnapshotProgress }), null, 'skip', null);
+                return await activate((onSnapshotProgress) => openByLink(openGuest, guestToken, inMode({ onSnapshotProgress }, undefined)).catch(async (err) => {
+                    const claimed = await claimedDocumentOf(guestToken, err);
+                    if (claimed === null)
+                        throw err;
+                    if (claimed === 'sign-in')
+                        throw new SignInToFollowLink();
+                    return openById(claimed.docId, inMode({ onSnapshotProgress }, undefined), 'skip');
+                }), null, 'skip', null);
             }
-            catch {
+            catch (err) {
+                forgetUnsavedWorkIfGone(guestToken, err);
                 return null;
             }
         }
-        if (!deps.isSignedIn() || document)
+        if (document)
             return document;
+        if (!deps.isSignedIn())
+            return restoreUnsavedWork();
         // A pick handed back by the hosted picker's redirect fallback opens
         // before the ordinary URL / last-selection restore, and independently of
         // `syncDocToUrl`. `takePickSelection` strips the one-shot params as it
@@ -655,10 +877,10 @@ export function createDocumentSession(deps) {
             try {
                 // 'replace': a boot restore pins the URL selection in place, not a
                 // navigation, so it must not plant a history entry.
-                return await activate((onSnapshotProgress) => deps.openDocumentById(sel.docId, {
+                return await activate((onSnapshotProgress) => openById(sel.docId, inMode({
                     ...(sel.branchId ? { branch: sel.branchId } : {}),
                     onSnapshotProgress,
-                }, 'skip'), null, 'replace', sel.branchId);
+                }, undefined), 'skip'), null, 'replace', sel.branchId);
             }
             catch {
                 // The user navigated to a specific `?doc=` and it could not be
@@ -673,7 +895,7 @@ export function createDocumentSession(deps) {
         const last = deps.lastSelectedDocument();
         if (last) {
             try {
-                return await activate((onSnapshotProgress) => deps.openDocumentById(last.doc_id, { onSnapshotProgress }, 'skip'), last.name, 'replace', null, 
+                return await activate((onSnapshotProgress) => openById(last.doc_id, inMode({ onSnapshotProgress }, undefined), 'skip'), last.name, 'replace', null, 
                 // A stale last-selection is a persistence self-heal, not a request
                 // the user made; settle silently on empty rather than parking an
                 // error.
@@ -685,6 +907,64 @@ export function createDocumentSession(deps) {
         }
         return null;
     }
+    // Whether a failed link open says the link itself is gone. The view route
+    // answers `404` for a token it does not know, `410` for one that expired
+    // or was revoked and `403` for one its organization's policy now refuses;
+    // anything else (no response, a shed request) says nothing about the link.
+    function linkGone(err) {
+        return (err instanceof BrassError &&
+            (err.status === 403 || err.status === 404 || err.status === 410));
+    }
+    // The document a revoked link leads this person to, when their own claim
+    // revoked it. Asked only on a 410, the one refusal a claim produces.
+    async function claimedDocumentOf(token, err) {
+        if (!(err instanceof BrassError) || err.status !== 410 || !deps.followClaimedLink) {
+            return null;
+        }
+        try {
+            return await deps.followClaimedLink(token);
+        }
+        catch {
+            return null;
+        }
+    }
+    // A stashed token the platform no longer answers names nothing to
+    // continue, so it is forgotten where the refusal is heard, whether the
+    // open was the boot of its URL or the restore below.
+    function forgetUnsavedWorkIfGone(token, err) {
+        if (!linkGone(err))
+            return;
+        if (deps.unsavedWork?.()?.token === token)
+            deps.clearUnsavedWork?.();
+    }
+    // A signed-out boot on a URL that names no document reopens the last
+    // document this browser made without an account on this app, the way a
+    // signed-in boot reopens the last document picked.
+    async function restoreUnsavedWork() {
+        if (deps.readUrlSelection())
+            return null;
+        const entry = deps.unsavedWork?.();
+        if (!entry || !deps.enterGuestMode || !deps.openDocumentByLink)
+            return null;
+        const openGuest = deps.openDocumentByLink;
+        const { token } = entry;
+        // The same path a reload of the document's URL takes: the token becomes
+        // the page's credential and the URL carries it, then the link opens.
+        deps.enterGuestMode(token);
+        try {
+            return await activate((onSnapshotProgress) => openByLink(openGuest, token, inMode({ ...withDefaults({}), onSnapshotProgress }, undefined)), null, 'skip');
+        }
+        catch (err) {
+            // The token did not open, so it is not this page's credential after
+            // all: the page is signed out again, and the stash is kept unless the
+            // link is gone for good, so the next boot tries it again.
+            deps.leaveGuestMode?.();
+            openError = null;
+            forgetUnsavedWorkIfGone(token, err);
+            emit();
+            return null;
+        }
+    }
     function start() {
         if (startPromise)
             return startPromise;
@@ -699,12 +979,111 @@ export function createDocumentSession(deps) {
         return startPromise;
     }
     function open(docId, options) {
-        return activate((onSnapshotProgress) => deps.openDocumentById(docId, {
-            ...withDefaults(options),
-            onSnapshotProgress,
-        }), null, 'push', options?.branch ?? null);
+        if (options?.frozen === true) {
+            return Promise.reject(new BrassError(FROZEN_IN_SESSION, { status: 0 }));
+        }
+        const asked = options?.readOnly ?? options?.documentOptions?.readOnly;
+        return activate((onSnapshotProgress) => openById(docId, inMode({ ...withDefaults(options), onSnapshotProgress }, asked)), null, 'push', options?.branch ?? null);
+    }
+    // A switch the hosted history or branch surfaces make from the bound
+    // document (another branch, a version, a fork) opens in the mode that
+    // document was opened in, so a copy opened to read stays one and a copy
+    // reopened to edit stays one.
+    function openSibling(docId, options) {
+        const current = document;
+        const readOnly = current === null || current.id !== docId
+            ? undefined
+            : readOnlyOpens.has(current)
+                ? true
+                : current._openMode === 'edit'
+                    ? false
+                    : undefined;
+        return open(docId, { ...options, ...(readOnly !== undefined ? { readOnly } : {}) });
+    }
+    // `reopen` on the bound document: the new copy replaces it the way a move's
+    // reopen does, kept on screen until it binds and kept bound if the reopen
+    // fails. The session holds a live copy, so a frozen one is the caller's to
+    // open beside it.
+    async function reopenBound(current, mode) {
+        if (mode === 'frozen') {
+            throw new BrassError(FROZEN_IN_SESSION, { status: 0 });
+        }
+        const id = current.id;
+        if (id === null)
+            throw new BrassError('No document is open', { status: 0 });
+        const branch = urlBranch(current);
+        const guestToken = deps.guestLinkToken?.();
+        const openGuest = deps.openDocumentByLink;
+        const readOnly = mode === 'read';
+        const next = await activate((onSnapshotProgress) => guestToken && openGuest
+            ? openByLink(openGuest, guestToken, {
+                ...withDefaults(),
+                readOnly,
+                onSnapshotProgress,
+            })
+            : openById(id, {
+                ...withDefaults(),
+                ...(branch ? { branch } : {}),
+                readOnly,
+                onSnapshotProgress,
+            }), documentName, 'skip', activeSpecifiedBranch, true, true, true);
+        // A newer open, reopen or close took the session while this one joined,
+        // and closed the copy it produced.
+        if (document !== next) {
+            throw new BrassError('The reopen was replaced by a later open of the session', {
+                status: 0,
+            });
+        }
+        return next;
+    }
+    // A create fails in two regimes, and only the later one reaches the
+    // session. Once `activate` has the open, `abandonOpen` parks the failure on
+    // `session.error` for a status-gated app to render. Everything before that
+    // (minting the account-less document, resolving the destination) throws with
+    // the returned promise as its only report, and the documented way to call
+    // this from a button floats that promise, so the click reads as ignored.
+    // Parking here under `abandonOpen`'s own condition gives both regimes one
+    // surface. The generation check is what keeps a failure from clobbering a
+    // newer open that started while this one was still resolving a destination.
+    // The trial token this page last recorded an edit for, so a burst of
+    // edits writes the marker once.
+    let trialEditNoted = null;
+    function noteTrialEdit(doc) {
+        const token = deps.guestLinkToken?.();
+        if (!token || doc.expiresAt === null || trialEditNoted === token)
+            return;
+        trialEditNoted = token;
+        deps.markTrialEdited?.(token, doc.expiresAt);
+    }
+    // Whether New or Upload may replace the document on screen. A document
+    // made without an account that this browser edited is kept only at its
+    // link, so the visitor is asked first, and signing in is what keeps it.
+    async function mayLeaveTrial() {
+        const token = deps.guestLinkToken?.();
+        const doc = document;
+        if (!token || !doc || doc.expiresAt === null)
+            return true;
+        if (!deps.confirmReplaceTrial || !deps.trialEdited?.(token))
+            return true;
+        const answer = await deps.confirmReplaceTrial(doc.expiresAt);
+        if (answer === 'sign-in')
+            deps.signIn?.();
+        return answer === 'leave';
     }
     async function create(options) {
+        const generation = openGeneration;
+        try {
+            return await createUnguarded(options);
+        }
+        catch (err) {
+            if (generation === openGeneration && document === null && openError === null) {
+                openError = toDisplayError(err);
+                emit();
+            }
+            throw err;
+        }
+    }
+    async function createUnguarded(options) {
         // Placement is expressed by context, never an org this layer names.
         // Create-in-place: a New doc anchors on the active one via `sibling_of`,
         // resolved server-side (its project, or loose in its org). With no active
@@ -723,29 +1102,45 @@ export function createDocumentSession(deps) {
         // one. The server owns the single-vs-multi decision: a `needs-*` outcome
         // is where we open the corresponding hosted surface and retry with the
         // opaque destination it returns, relayed verbatim.
+        // No account: the document is minted without one and opened through
+        // its link token, which the URL then carries so a reload and a sign-in
+        // both find it again.
+        if (withoutAccount() &&
+            deps.mintAnonymousDocument &&
+            deps.enterGuestMode &&
+            deps.openDocumentByLink) {
+            if (!(await mayLeaveTrial()))
+                return null;
+            const minted = await deps.mintAnonymousDocument(options?.name !== undefined ? { name: options.name } : {});
+            const enterGuestMode = deps.enterGuestMode;
+            const openGuest = deps.openDocumentByLink;
+            accountFreeOpen = true;
+            try {
+                return await activate((onSnapshotProgress, _onUploadProgress, releasePrevious) => {
+                    releasePrevious();
+                    enterGuestMode(minted.linkToken);
+                    return openGuest(minted.linkToken, {
+                        ...withDefaults(options?.documentOptions
+                            ? { documentOptions: options.documentOptions }
+                            : undefined),
+                        onSnapshotProgress,
+                    });
+                }, options?.name ?? null, 'skip');
+            }
+            finally {
+                accountFreeOpen = false;
+            }
+        }
         let args = base;
         let knownName = options?.name ?? null;
-        let result;
-        for (;;) {
-            result = await deps.createDocumentId(args);
-            if (result.kind === 'created')
-                break;
-            if (result.kind === 'needs-organization') {
-                const acquired = await deps.acquireOrganization();
-                if (!acquired)
-                    return null;
-                args = { ...args, destination: { organization_id: acquired.organization_id } };
-                continue;
-            }
-            // needs-destination
-            const destination = await deps.selectCreateDestination(options?.name !== undefined ? { name: options.name } : undefined);
-            if (destination === null)
-                return null;
+        const result = await placeThroughHostedSurfaces(deps, (destination) => deps.createDocumentId(destination === undefined ? args : { ...args, destination }), options?.name, (chosen) => {
             // The dialog's final name wins on both the wire and the display: the
             // user saw and could edit it.
-            args = { ...args, destination, name: destination.name };
-            knownName = destination.name ?? knownName;
-        }
+            args = { ...args, name: chosen.name };
+            knownName = chosen.name;
+        });
+        if (result === null)
+            return null;
         const docId = result.docId;
         const openOptions = options?.documentOptions
             ? { documentOptions: options.documentOptions }
@@ -754,20 +1149,66 @@ export function createDocumentSession(deps) {
         // with no name the server owns it (resolving the next free "Untitled N"),
         // and a null `knownName` is what lets `resolveActiveDocRecord` adopt the
         // stored name once the record binds.
-        return activate((onSnapshotProgress) => deps.openDocumentById(docId, {
+        return activate((onSnapshotProgress) => openById(docId, {
             ...withDefaults(openOptions),
             onSnapshotProgress,
         }), knownName);
     }
+    // The upload runs inside the open, so the app renders its loading surface
+    // with the upload's progress rather than an unchanged screen. A failure
+    // lands on `session.error` the way a failed create's does.
+    async function pickAnonymousFile(choose, mint, enterGuestMode, openGuest) {
+        const generation = openGeneration;
+        let file;
+        try {
+            file = await choose();
+        }
+        catch (err) {
+            // Before `activate` there is no open to abandon, so the refusal is
+            // parked here under `create`'s condition.
+            if (generation === openGeneration && document === null && openError === null) {
+                openError = toDisplayError(err);
+                emit();
+            }
+            throw err;
+        }
+        if (file === null)
+            return null;
+        accountFreeOpen = true;
+        try {
+            return await activate(async (onSnapshotProgress, onUploadProgress, releasePrevious) => {
+                const minted = await mint({ file, onUploadProgress });
+                releasePrevious();
+                enterGuestMode(minted.linkToken);
+                return openGuest(minted.linkToken, {
+                    ...withDefaults(),
+                    onSnapshotProgress,
+                });
+            }, null, 'skip');
+        }
+        finally {
+            accountFreeOpen = false;
+            emit();
+        }
+    }
     async function pick() {
+        if (withoutAccount() &&
+            deps.chooseAnonymousFile &&
+            deps.mintAnonymousDocumentFromFile &&
+            deps.enterGuestMode &&
+            deps.openDocumentByLink) {
+            if (!(await mayLeaveTrial()))
+                return null;
+            return pickAnonymousFile(deps.chooseAnonymousFile, deps.mintAnonymousDocumentFromFile, deps.enterGuestMode, deps.openDocumentByLink);
+        }
         const result = await deps.selectDocument();
         if (!result)
             return null;
-        const opts = {
+        const opts = inMode({
             ...withDefaults(),
             ...(result.branch_id ? { branch: result.branch_id } : {}),
-        };
-        return activate((onSnapshotProgress) => deps.openDocumentById(result.doc_id, { ...opts, onSnapshotProgress }), result.name, 'push', result.branch_id ?? null);
+        }, undefined);
+        return activate((onSnapshotProgress) => openById(result.doc_id, { ...opts, onSnapshotProgress }), result.name, 'push', result.branch_id ?? null);
     }
     // Merge `defaultDocumentOptions` into the caller's options: caller values
     // win per-field, the default fills gaps, and nested `undo` is shallow-merged
@@ -849,11 +1290,11 @@ export function createDocumentSession(deps) {
             urlBranch(current) === sel.branchId) {
             return; // already showing this selection
         }
-        void activate((onSnapshotProgress) => deps.openDocumentById(sel.docId, {
+        void activate((onSnapshotProgress) => openById(sel.docId, inMode({
             ...withDefaults(),
             ...(sel.branchId ? { branch: sel.branchId } : {}),
             onSnapshotProgress,
-        }, 'skip'), null, 'skip', sel.branchId).catch(() => {
+        }, undefined), 'skip'), null, 'skip', sel.branchId).catch(() => {
             // Back / Forward to a doc that can't be opened parks the 'error' state
             // (or, warm, keeps the current doc); the URL the user navigated to is
             // left as-is, so the caught rejection needs no cleanup here.
@@ -877,7 +1318,14 @@ export function createDocumentSession(deps) {
     // (opened via `?brass_link=`) is never signed in, so the initial
     // resolution arrives here with `signedIn === false`; it must boot the
     // read-only link document rather than tear down to the sign-in surface.
+    //
+    // The first resolution to signed-out is the boot of a signed-out page, which
+    // restores the unsaved work this browser made (`restoreUnsavedWork`); a
+    // later sign-out lands on the sign-in surface.
+    let authResolved = false;
     deps.onUserChange((signedIn) => {
+        const boot = !authResolved;
+        authResolved = true;
         if (signedIn || deps.guestLinkToken?.() != null) {
             if (!document)
                 void start();
@@ -886,6 +1334,10 @@ export function createDocumentSession(deps) {
         }
         else {
             teardownForSignOut();
+            // Deferred: a session made after `init` settled hears this resolution
+            // while it is still being built.
+            if (boot)
+                queueMicrotask(() => void start());
         }
     });
     const session = {
@@ -899,7 +1351,17 @@ export function createDocumentSession(deps) {
             return status();
         },
         get error() {
-            return status() === 'error' ? openError : null;
+            // Not gated on `status() === 'error'`. A signed-out visitor's failed
+            // create is the case that gating loses: 'signed-out' outranks the error
+            // in `status()` (the app must keep rendering its sign-in surface, which
+            // is where the retry lives), so gating here left the try-before-signing-in
+            // failure with no channel at all.
+            // What makes ungating safe is that a parked error never coexists with a
+            // bound document: `activate` clears it on entry and is the only path that
+            // binds a non-null one, and `abandonOpen` parks only when there was no
+            // document to fall back to. So this can never show a stale failure beside
+            // a working document. A new write to `openError` has to hold that.
+            return openError ?? deps.initFailure?.() ?? null;
         },
         get loadingMessage() {
             return loading ? loadingMessage : null;
@@ -919,19 +1381,38 @@ export function createDocumentSession(deps) {
                 listener(session);
             }
             catch (err) {
-                console.error('[Brass] session listener threw:', err);
+                reportListenerThrow(err);
             }
             return () => {
                 listeners.delete(listener);
             };
         },
         start,
-        open,
+        open: ((docId, options) => docId === undefined ? pick() : open(docId, options)),
         create,
         pick,
         close,
         async run(commandId) {
             const command = allCommands().find((c) => c.id === commandId);
+            // An app's own signed-out button may still run a withdrawn New or Open,
+            // and the reader is owed the reason rather than a press that does
+            // nothing.
+            if (command &&
+                command.group === 'session' &&
+                !command.enabled &&
+                withoutAccount() &&
+                signedOutRefusal !== null) {
+                // A parked error never sits beside a bound document, so a guest
+                // reading one hears the refusal through `onError` instead.
+                if (document === null) {
+                    openError = signedOutRefusal;
+                    emit();
+                }
+                else {
+                    deps.reportError(signedOutRefusal);
+                }
+                return;
+            }
             if (command)
                 await command.run();
         },
@@ -970,8 +1451,9 @@ export function createDocumentSession(deps) {
             }
             // Already-terminal open failure: reject now rather than wait for a bind
             // that isn't coming.
-            if (status() === 'error' && openError) {
-                return Promise.reject(openError);
+            const failure = session.error;
+            if (status() === 'error' && failure) {
+                return Promise.reject(failure);
             }
             return new Promise((resolve, reject) => {
                 whenReadyPending.push({ resolve, reject });
@@ -989,6 +1471,7 @@ export function createDocumentSession(deps) {
         _clearLocalDelete(docId) {
             localDeletes.delete(docId);
         },
+        _openSibling: openSibling,
     };
     return session;
 }