blockworx/

doc.rs

//! The editor's document handle: the two places a document can live, as one
//! enum.
//!
//! [`Doc::Scratch`] is an in-process [`Repo`] — a session that dies with the
//! process. It is what an opened document file and the whole web build
//! hold. [`Doc::Attached`] is a `.bwx` container: the same repo, with
//! every accepted commit in `revs/` and `manifest.jsonl` before the call
//! returns.
//!
//! Reads go through [`Doc::repo`]/[`Doc::document`]; writes through
//! [`Doc::submit`] and its two history neighbours, which route to the
//! container's write door when there is one. Nothing hands out a `&mut Repo`
//! for an attached document, so "folded but not logged" is unrepresentable
//! rather than merely avoided.

use blockworx_doc::{
    commit::Commit,
    document::Document,
    repo::Repo,
    rev::Rev,
    trail::{Direction, Trail},
};
use serde::{Deserialize, Serialize};

use crate::store::Refusal;
use crate::store::history::Journal;
use crate::store::projection::Stamp;
use crate::store::record::{Attribution, Digest};
use crate::store::revs;
use crate::store::tags::Tags;

#[cfg(not(target_arch = "wasm32"))]
use crate::store::{container::ReadOnlyReason, handle::Store};

/// Whether this session may write its document. Not a bool: the read-only
/// arm always has a reason, and the reason is something the user is told.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Writability {
    Writable,
    ReadOnly,
}

/// Whether the affordances that *add* something are offered: the faint
/// "Add name"/"Add type" prompts, the free-slot pin dots, the route-start
/// targets, a wire's waypoint handles and text anchors — and, with them,
/// the gestures those affordances begin.
///
/// One value for two questions that have always had the same answer. A
/// locked block already withheld its prompts because its interface is
/// frozen; a read-only session freezes everything, so it withholds them on
/// the same terms. Folding both here is what keeps the paint layer and the
/// gesture layer from disagreeing about whether a thing is editable.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Authoring {
    Offered,
    Withheld,
}

impl Authoring {
    /// What a session of this [`Writability`] offers on a shape under this
    /// `InterfaceLock` — the whole rule, in one place.
    pub fn of(writability: Writability, lock: crate::edit::naming::InterfaceLock) -> Self {
        match (writability, lock.is_locked()) {
            (Writability::Writable, false) => Authoring::Offered,
            _ => Authoring::Withheld,
        }
    }

    pub fn is_withheld(self) -> bool {
        self == Authoring::Withheld
    }
}

impl From<Writability> for Authoring {
    fn from(writability: Writability) -> Self {
        Authoring::of(writability, crate::edit::naming::InterfaceLock::Unlocked)
    }
}

/// Which document the canvas is showing: the log's head, or a rev out of
/// the past — the time machine
/// (`docs/single-author-playbook.md`, Phase 4).
///
/// Only the *state*: the fold a past rev is viewed through lives in the
/// editor beside it, so this stays `Copy` and can be handed to the command
/// registry and the chrome. Viewing the past is the second consumer of the
/// one read-only presentation, which is why it answers the same
/// [`Writability`] question a container does.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Viewing {
    Head,
    Past(Rev),
}

impl Viewing {
    /// Looking at the past is looking, never editing: every writing
    /// command is withheld, and undo/redo with them — they act on the head
    /// nobody is looking at.
    pub fn writability(self) -> Writability {
        match self {
            Viewing::Head => Writability::Writable,
            Viewing::Past(_) => Writability::ReadOnly,
        }
    }

    /// How much color the canvas draws with — spec §3.2's third read-only
    /// signal, beside band 3b and the dimmed tool band.
    pub fn saturation(self) -> crate::canvas::Saturation {
        match self {
            Viewing::Head => crate::canvas::Saturation::Full,
            Viewing::Past(_) => crate::canvas::Saturation::Drained,
        }
    }

    /// One step through a log whose newest rev is `head`. `None` where the
    /// step has nowhere to go.
    ///
    /// The policy in one place, because two surfaces read it: the cluster
    /// draws its buttons enabled or not by it, and the dispatch acts on it.
    /// Log positions are contiguous — a refused commit consumes none — so
    /// stepping is arithmetic rather than a search. Stepping forward off
    /// the end is how the past gives way to the writable present.
    pub fn stepped(self, head: Rev, step: TimeStep) -> Option<At> {
        let Viewing::Past(at) = self else {
            return None;
        };
        match step {
            TimeStep::Back => at.prev().filter(|before| *before > Rev::ZERO).map(At::Rev),
            TimeStep::Forward if at >= head => Some(At::Current),
            TimeStep::Forward => Some(At::Rev(at.next())),
        }
    }
}

/// Where a time-machine step lands: on a rev, or back in the writable
/// present.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum At {
    Rev(Rev),
    Current,
}

/// Which way a time-machine step goes.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum TimeStep {
    Back,
    Forward,
}

/// Whether "Save" has anything to write. Saving refreshes the projection
/// beside a log (D11), so it needs a writable container — a scratch session
/// has no file to keep in step with, and a read-only one may not touch the
/// file it has.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Saving {
    Offered,
    Withheld,
}

/// Whether the document can be renamed. Renaming moves the container the
/// document lives in (D20), so it asks exactly what [`Saving`] asks — is
/// there a container, and may this session write it — and is derived from
/// it rather than forming a second opinion.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Renaming {
    Offered,
    Withheld,
}

impl From<Saving> for Renaming {
    fn from(saving: Saving) -> Self {
        match saving {
            Saving::Offered => Renaming::Offered,
            Saving::Withheld => Renaming::Withheld,
        }
    }
}

/// Which opened document this is, for the life of the handle holding it —
/// minted when a document is created or opened, never written to a log, a
/// projection, or anything else durable.
///
/// Its whole job is to make two documents opened in one process compare
/// unequal, and one document opened in two processes compare unequal too:
/// 64 drawn bits, so a payload that travels through the OS clipboard can
/// say which document it was cut out of and be believed (D22).
#[derive(Clone, Copy, PartialEq, Eq, Debug, Serialize, Deserialize)]
pub struct DocumentNonce(u64);

impl DocumentNonce {
    /// A document of its own. Every [`Doc`] mints one, which is what makes
    /// "this handle's document" a thing the clipboard can name without any
    /// call site remembering to.
    ///
    /// Drawn through `RandomState` rather than `naming::entropy`, which is
    /// desktop-only: the browser build has documents and a clipboard too.
    /// The counter is what keeps two documents *in one process* apart
    /// whatever the draw does.
    pub fn mint() -> Self {
        use std::hash::{BuildHasher as _, Hasher as _, RandomState};
        use std::sync::atomic::{AtomicU64, Ordering};
        static OPENED: AtomicU64 = AtomicU64::new(0);
        let mut hasher = RandomState::new().build_hasher();
        hasher.write_u64(OPENED.fetch_add(1, Ordering::Relaxed));
        Self(hasher.finish())
    }
}

/// Which record a step moves, which way, and what that record is called —
/// the three things a step's own commit is written from.
#[derive(Clone, Copy)]
pub(crate) struct Stepping<'a> {
    pub edit: Rev,
    pub direction: Direction,
    pub label: &'a str,
}

/// One history step: adopt the document the trail's top entry restores,
/// and record it as a commit of its own so the step stays *in* the
/// history (F7).
///
/// S6's whole policy, in one place, over the one thing the two session
/// arms disagree about — where the document at a rev comes from. Both
/// read a rev copy; only the shelf it sits on differs.
///
/// # Errors
/// [`Refusal::Step`] when the trail will not take the step, and whatever
/// `at` says when the document it names cannot be had.
pub(crate) fn stepped(
    repo: &mut Repo,
    trail: &mut Trail,
    step: Stepping<'_>,
    at: impl FnOnce(Rev) -> Result<Document, Refusal>,
) -> Result<Rev, Refusal> {
    let Stepping {
        edit,
        direction,
        label,
    } = step;
    let entry = trail.stepping(edit, direction)?;
    let target = at(entry.restores)?;
    Ok(repo.restore(
        trail,
        blockworx_doc::repo::Restoring {
            entry,
            direction,
            target,
            label,
        },
    ))
}

/// A session with no files, keeping the document at every rev exactly as
/// a container does — the same encoding over a map instead of a directory
/// (`docs/log-vs-snapshot.md` S6, resolution 6).
///
/// The payloads come off the revs and go into a store of their own for
/// the same reason they do on disk: a rev the session steps back through
/// is one copy of the document, not one copy of every icon in it.
#[derive(Default)]
pub struct Shelf {
    revs: revs::Memory,
    payloads: crate::store::assets::Held,
    /// What each rev's act named and the scope it was made in — a
    /// manifest row's two advisory fields (§10.1), for a session that
    /// writes no rows. A step keeps the framing of the act it moves, so
    /// it frames what it moved.
    worked: std::collections::BTreeMap<Rev, crate::spotlight::Worked>,
}

impl Shelf {
    /// Keep the document this session has just reached as rev `at`.
    ///
    /// A write that fails is a fault in a map, so it is reported and
    /// dropped: the document is still in hand, and what a lost rev costs
    /// is a step this session can no longer take back — which the trail
    /// then refuses out loud.
    fn keep(&mut self, at: Rev, document: &Document, worked: crate::spotlight::Worked) {
        if let Err(why) = revs::write(&mut self.revs, at, document, &mut self.payloads) {
            tracing::error!("rev {} was not kept: {why}", at.get());
        }
        self.worked.insert(at, worked);
    }

    fn worked_at(&self, at: Rev) -> Option<crate::spotlight::Worked> {
        self.worked.get(&at).cloned()
    }

    /// The document at `at`, payloads and all.
    ///
    /// # Errors
    /// [`Refusal::Unreachable`] for a rev this session did not keep.
    fn at(&self, at: Rev) -> Result<Document, Refusal> {
        let unreachable = |why: &dyn std::fmt::Display| Refusal::Unreachable {
            at,
            why: why.to_string(),
        };
        let document = revs::read(&self.revs, at).map_err(|why| unreachable(&why))?;
        revs::attached(document, &self.payloads).map_err(|why| unreachable(&why))
    }

    /// The digest of the bytes rev `at` was written as, or the empty
    /// document's for one this session did not keep.
    fn stamp(&self, at: Rev) -> Digest {
        revs::stamp(&self.revs, at).unwrap_or_else(|_| Digest::of(&[]))
    }
}

/// What the commit at `at` is called — `log[i]` holds rev `i + 1` for a
/// session whose commits are all its own.
fn label_of(repo: &Repo, at: Rev) -> Option<String> {
    let ndx = usize::try_from(at.get().checked_sub(1)?).ok()?;
    repo.log().get(ndx).map(|commit| commit.label().to_owned())
}

/// Both arms are boxed, so swapping the document — which is all the editor
/// ever does with one — moves two words rather than a whole folded document
/// either way.
pub enum Doc {
    /// No file behind it: the history lives and dies with the process.
    /// The browser has only this arm. Its tags die with it too — there
    /// are no rows for them to be rebuilt from.
    Scratch {
        repo: Box<Repo>,
        /// Where this session's history stands. Beside the repo rather
        /// than in it: a step adopts a document the repo cannot reach on
        /// its own (`docs/log-vs-snapshot.md` S6).
        trail: Trail,
        tags: Tags,
        /// The document at every rev, in the container's own encoding
        /// over a map rather than a directory — so this arm steps exactly
        /// as an attached one does.
        revs: Box<Shelf>,
        session: DocumentNonce,
    },
    /// A `.bwx` container, open and (unless it says otherwise) writable.
    #[cfg(not(target_arch = "wasm32"))]
    Attached {
        store: Box<Store>,
        session: DocumentNonce,
    },
}

impl Default for Doc {
    fn default() -> Self {
        Doc::scratch(Repo::default())
    }
}

impl Doc {
    pub fn scratch(repo: Repo) -> Self {
        let mut trail = Trail::default();
        // A repo handed in has already folded its own past, and nobody may
        // take back a step they did not make.
        trail.seeded(repo.rev());
        // The past a handed-in repo arrives with is folded once here, so
        // the time machine and a step both read a copy rather than
        // re-folding a prefix per pick.
        let mut revs = Shelf::default();
        let mut folding = Repo::default();
        for commit in repo.log() {
            let worked = crate::spotlight::Worked::of(folding.document(), commit);
            match folding.fold_one(commit.clone()) {
                Ok(document) => revs.keep(document.rev(), document, worked),
                Err(why) => tracing::error!("a session's own past will not fold: {why}"),
            }
        }
        revs.keep(
            repo.rev(),
            repo.document(),
            crate::spotlight::Worked::nothing(),
        );
        Doc::Scratch {
            repo: Box::new(repo),
            trail,
            tags: Tags::default(),
            revs: Box::new(revs),
            session: DocumentNonce::mint(),
        }
    }

    #[cfg(not(target_arch = "wasm32"))]
    pub fn attached(store: Store) -> Self {
        Doc::Attached {
            store: Box::new(store),
            session: DocumentNonce::mint(),
        }
    }

    /// Which document this handle is holding. Stable while it is open and
    /// unequal to every other, which is what a cut payload compares itself
    /// against when a paste asks whether it has come home.
    pub fn session(&self) -> DocumentNonce {
        match self {
            Doc::Scratch { session, .. } => *session,
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { session, .. } => *session,
        }
    }

    pub fn repo(&self) -> &Repo {
        match self {
            Doc::Scratch { repo, .. } => repo,
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { store, .. } => store.repo(),
        }
    }

    /// Where this session's history stands (S6): which rev's document the
    /// head holds, and what one press either way would move.
    pub fn trail(&self) -> &Trail {
        match self {
            Doc::Scratch { trail, .. } => trail,
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { store, .. } => store.trail(),
        }
    }

    /// What this document's revs are called (D18).
    pub fn tags(&self) -> &Tags {
        match self {
            Doc::Scratch { tags, .. } => tags,
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { store, .. } => store.tags(),
        }
    }

    /// Where the rows a reader is shown come from: this container's
    /// manifest, or a session's own commits.
    pub fn journal(&self) -> Journal<'_> {
        match self {
            Doc::Scratch { repo, .. } => Journal::Session(repo.log()),
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { store, .. } => Journal::Recorded(store.rows()),
        }
    }

    /// What the record at `at` says it worked on: the scope its author was
    /// standing in and the entities they named (§10.1). `None` for a rev
    /// this history does not hold.
    ///
    /// A container reads the row; a session with no rows reads the commit
    /// it still holds, which is what S2 keeps ops in memory for.
    pub fn worked_at(&self, at: Rev) -> Option<crate::spotlight::Worked> {
        match self {
            Doc::Scratch { revs, .. } => revs.worked_at(at),
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { store, .. } => {
                store.framing(at).map(crate::spotlight::Worked::recorded)
            }
        }
    }

    /// Where the author of the record at `at` was looking when they wrote
    /// it (§10.1). `None` for a session that keeps no rows: there is
    /// nothing recorded to stand at, so the pick frames the change
    /// instead.
    // The browser has only the scratch arm, which records no camera.
    #[cfg_attr(target_arch = "wasm32", expect(unused_variables))]
    pub fn camera_at(&self, at: Rev) -> Option<crate::store::record::Camera> {
        match self {
            Doc::Scratch { .. } => None,
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { store, .. } => store.framing(at).map(|row| row.camera),
        }
    }

    /// What the record at `at` is called — how the undo and redo buttons
    /// name the step they stand over.
    pub fn label_at(&self, at: Rev) -> Option<&str> {
        match self {
            Doc::Scratch { repo, .. } => {
                let ndx = usize::try_from(at.get().checked_sub(1)?).ok()?;
                repo.log().get(ndx).map(Commit::label)
            }
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { store, .. } => store.row(at).map(|row| row.label.as_str()),
        }
    }

    /// The document this session holds at `at`, payloads and all — the rev
    /// copy, never a fold.
    ///
    /// # Errors
    /// [`Refusal::Unreachable`] for a rev whose copy cannot be shown.
    pub fn document_at(&self, at: Rev) -> Result<Document, Refusal> {
        match self {
            Doc::Scratch { revs, .. } => revs.at(at),
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { store, .. } => store.document_at(at),
        }
    }

    /// The rev this session heads at, and the digest of the bytes it was
    /// written as — what an export stamps itself with (D19).
    pub fn stamp_at(&self, at: Rev) -> Stamp {
        Stamp::at(at, self.state_at(at))
    }

    fn state_at(&self, at: Rev) -> Digest {
        match self {
            Doc::Scratch { revs, .. } => revs.stamp(at),
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { store, .. } => store
                .row(at)
                .map_or_else(|| Digest::of(&[]), |row| row.hash),
        }
    }

    pub fn document(&self) -> &Document {
        self.repo().document()
    }

    /// # Errors
    /// [`Refusal::Fold`] when the fold refuses the commit, and — for an
    /// attached document — [`Refusal::ReadOnly`] or [`Refusal::Append`].
    // The web build has only the scratch arm, which attributes nothing.
    // The browser has only the scratch arm, which attributes nothing: there,
    // the attribution really is unused and really is not consumed.
    #[cfg_attr(
        target_arch = "wasm32",
        allow(unused_variables, clippy::needless_pass_by_value)
    )]
    pub fn submit<'a>(
        &mut self,
        commit: Commit,
        by: impl Into<Attribution<'a>>,
    ) -> Result<Rev, Refusal> {
        match self {
            Doc::Scratch {
                repo, trail, revs, ..
            } => {
                // Read before the fold: what a commit worked on is
                // measured against the document it was written against.
                let worked = crate::spotlight::Worked::of(repo.document(), &commit);
                let rev = repo.submit(commit, trail)?;
                revs.keep(rev, repo.document(), worked);
                Ok(rev)
            }
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { store, .. } => store.submit_edit(commit, by),
        }
    }

    /// Name `rev` — or, with an empty `name`, stop naming it (D18). Never
    /// an edit: no rev is spent and the trail does not move.
    ///
    /// # Errors
    /// As [`Store::tag`]; a scratch session's tags are in memory and
    /// refuse only a rev the log does not hold.
    // The browser has only the scratch arm, which attributes nothing: there,
    // the attribution really is unused and really is not consumed.
    #[cfg_attr(
        target_arch = "wasm32",
        allow(unused_variables, clippy::needless_pass_by_value)
    )]
    pub fn tag<'a>(
        &mut self,
        rev: Rev,
        name: &str,
        how: crate::store::tags::Tagging,
        by: impl Into<Attribution<'a>>,
    ) -> Result<(), Refusal> {
        match self {
            Doc::Scratch { repo, tags, .. } => {
                if rev == Rev::ZERO || rev > repo.rev() {
                    return Err(Refusal::NoSuchRev(rev));
                }
                tags.apply(rev, name, how);
                Ok(())
            }
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { store, .. } => store.tag(rev, name, how, by),
        }
    }

    /// # Errors
    /// [`Refusal::Step`] when the trail will not take the step, and as
    /// [`Self::submit`] otherwise.
    // The browser has only the scratch arm, which attributes nothing: there,
    // the attribution really is unused and really is not consumed.
    #[cfg_attr(
        target_arch = "wasm32",
        allow(unused_variables, clippy::needless_pass_by_value)
    )]
    pub fn undo<'a>(&mut self, edit: Rev, by: impl Into<Attribution<'a>>) -> Result<Rev, Refusal> {
        self.step(edit, Direction::Undo, by)
    }

    /// # Errors
    /// As [`Self::undo`].
    // The browser has only the scratch arm, which attributes nothing: there,
    // the attribution really is unused and really is not consumed.
    #[cfg_attr(
        target_arch = "wasm32",
        allow(unused_variables, clippy::needless_pass_by_value)
    )]
    pub fn redo<'a>(&mut self, edit: Rev, by: impl Into<Attribution<'a>>) -> Result<Rev, Refusal> {
        self.step(edit, Direction::Redo, by)
    }

    /// One history step, whichever way and whichever arm holds the revs.
    ///
    /// # Errors
    /// As [`Self::undo`].
    #[cfg_attr(
        target_arch = "wasm32",
        allow(unused_variables, clippy::needless_pass_by_value)
    )]
    fn step<'a>(
        &mut self,
        edit: Rev,
        direction: Direction,
        by: impl Into<Attribution<'a>>,
    ) -> Result<Rev, Refusal> {
        match self {
            Doc::Scratch {
                repo, trail, revs, ..
            } => {
                // As the store: the trail's own refusal comes first.
                let entry = trail.stepping(edit, direction)?;
                let label = label_of(repo, entry.rev).ok_or(Refusal::NoSuchRev(edit))?;
                let moved = revs
                    .worked_at(entry.rev)
                    .unwrap_or_else(crate::spotlight::Worked::nothing);
                let at = stepped(
                    repo,
                    trail,
                    Stepping {
                        edit,
                        direction,
                        label: &label,
                    },
                    |restores| revs.at(restores),
                )?;
                revs.keep(at, repo.document(), moved);
                Ok(at)
            }
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { store, .. } => match direction {
                Direction::Undo => store.undo(edit, by),
                Direction::Redo => store.redo(edit, by),
            },
        }
    }

    /// A scratch session is always writable: there is nothing for a lock to
    /// be held on and no history to be broken.
    pub fn writability(&self) -> Writability {
        match self {
            Doc::Scratch { .. } => Writability::Writable,
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { store, .. } => match store.read_only_reason() {
                Some(_) => Writability::ReadOnly,
                None => Writability::Writable,
            },
        }
    }

    /// Why this document cannot be written, when it cannot be.
    #[cfg(not(target_arch = "wasm32"))]
    pub fn read_only_reason(&self) -> Option<&ReadOnlyReason> {
        match self {
            Doc::Scratch { .. } => None,
            Doc::Attached { store, .. } => store.read_only_reason(),
        }
    }

    /// Whether this session can be asked to refresh its projection.
    pub fn saving(&self) -> Saving {
        match self {
            Doc::Scratch { .. } => Saving::Withheld,
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { store, .. } => match store.read_only_reason() {
                Some(_) => Saving::Withheld,
                None => Saving::Offered,
            },
        }
    }

    /// Whether this session can be asked to rename its document.
    pub fn renaming(&self) -> Renaming {
        self.saving().into()
    }

    /// Rename this document's container — the directory's name *is* the
    /// document's name (D20).
    ///
    /// # Errors
    /// [`Refusal::Detached`] for a session with no container to rename, and
    /// as [`Store::rename`].
    #[cfg(not(target_arch = "wasm32"))]
    pub fn rename(&mut self, to: &std::path::Path) -> Result<(), Refusal> {
        match self {
            Doc::Scratch { .. } => Err(Refusal::Detached),
            Doc::Attached { store, .. } => store.rename(to),
        }
    }

    /// How `document.json` stands against the log's head — `None` where
    /// there is no file to be stale (a scratch session, and the whole web
    /// build).
    pub fn projection(&self) -> Option<crate::store::projection::Freshness> {
        match self {
            Doc::Scratch { .. } => None,
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { store, .. } => Some(store.projection()),
        }
    }

    /// Rewrite the attached container's `document.json` from the head fold.
    ///
    /// # Errors
    /// [`Refusal::Detached`] for a scratch session — which the registry
    /// withholds Save from, so this is the belt-and-braces arm rather than a
    /// path a user can take — and as
    /// [`Store::save_projection`](crate::store::handle::Store::save_projection)
    /// otherwise.
    pub fn save_projection(&mut self) -> Result<crate::store::projection::Stamp, Refusal> {
        match self {
            Doc::Scratch { .. } => Err(Refusal::Detached),
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { store, .. } => store.save_projection(),
        }
    }

    /// The container this document is attached to, for the chrome that names
    /// it.
    #[cfg(not(target_arch = "wasm32"))]
    pub fn container_root(&self) -> Option<&std::path::Path> {
        match self {
            Doc::Scratch { .. } => None,
            Doc::Attached { store, .. } => Some(store.root()),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::store::record::Identity;
    use blockworx_doc::fixtures::rev;

    fn author() -> Identity {
        Identity::new("ada")
    }

    /// The lens drains the canvas's color and the present restores it
    /// (spec §3.2).
    #[test]
    fn the_past_is_drawn_drained_of_color_and_the_present_is_not() {
        use crate::canvas::Saturation;
        assert_eq!(Viewing::Head.saturation(), Saturation::Full);
        assert_eq!(Viewing::Past(rev(23)).saturation(), Saturation::Drained);
    }

    /// The stepping policy the cluster's two buttons and the dispatch both
    /// read: bounded at the oldest rev, and off the newest into the present.
    #[test]
    fn stepping_walks_the_log_and_falls_off_its_end_into_the_present() {
        let head = rev(3);
        let step = |at: Viewing, dir| at.stepped(head, dir);

        assert_eq!(step(Viewing::Head, TimeStep::Back), None);
        assert_eq!(step(Viewing::Head, TimeStep::Forward), None);
        assert_eq!(step(Viewing::Past(rev(1)), TimeStep::Back), None);
        assert_eq!(
            step(Viewing::Past(rev(2)), TimeStep::Back),
            Some(At::Rev(rev(1))),
        );
        assert_eq!(
            step(Viewing::Past(rev(2)), TimeStep::Forward),
            Some(At::Rev(rev(3))),
        );
        assert_eq!(
            step(Viewing::Past(rev(3)), TimeStep::Forward),
            Some(At::Current),
        );
        assert_eq!(
            step(Viewing::Past(rev(3)), TimeStep::Back),
            Some(At::Rev(rev(2))),
            "the newest rev still steps back",
        );
    }

    /// A tag is not an edit: no rev is spent and nothing becomes undoable.
    #[test]
    fn tagging_a_scratch_rev_moves_neither_the_log_nor_the_trail() {
        let mut doc = Doc::default();
        let at = doc.submit(one_block(), &author()).expect("the edit lands");
        let depth = doc.trail().undo_depth();

        doc.tag(
            at,
            "Initial Draft",
            crate::store::tags::Tagging::Added,
            &author(),
        )
        .expect("it tags");
        assert_eq!(doc.tags().of(at), ["Initial Draft"]);
        assert_eq!(doc.repo().rev(), at, "tagging spent a rev");
        assert_eq!(doc.trail().undo_depth(), depth, "tagging moved the trail");

        doc.tag(
            at,
            "Initial Draft",
            crate::store::tags::Tagging::Removed,
            &author(),
        )
        .expect("and untags");
        assert!(doc.tags().is_empty());
        assert!(matches!(
            doc.tag(
                rev(9),
                "Nowhere",
                crate::store::tags::Tagging::Added,
                &author()
            ),
            Err(Refusal::NoSuchRev(_)),
        ));
    }

    fn one_block() -> Commit {
        Commit::new(
            "Added a block".to_owned(),
            vec![crate::store::tests::fixture::block_create(1, "Adder")],
        )
    }

    /// A scratch document takes the same three calls an attached one does,
    /// so the editor's write path has no second shape for the no-file case.
    #[test]
    fn a_scratch_document_submits_undoes_and_redoes() {
        let mut doc = Doc::default();
        assert_eq!(doc.writability(), Writability::Writable);

        let edit = doc.submit(one_block(), &author()).expect("the edit lands");
        let undone = doc.undo(edit, &author()).expect("and undoes");
        doc.redo(undone, &author()).expect("and redoes");
        assert_eq!(doc.repo().log().len(), 3, "an undo is a forward commit");
    }

    /// The scratch arm's answer to "where did I stand": the log prefix,
    /// folded. It has no rev copies, so this is the one place the two
    /// session arms differ — and they must reach the same documents.
    #[test]
    fn a_scratch_session_steps_through_its_own_prefix_folds() {
        use blockworx_doc::repo::Repo;

        let mut doc = Doc::default();
        let mut revs = Vec::new();
        for n in 1..=3 {
            revs.push(
                doc.submit(
                    Commit::new(
                        format!("Added block {n}"),
                        vec![crate::store::tests::fixture::block_create(
                            n,
                            &format!("b{n}"),
                        )],
                    ),
                    &author(),
                )
                .expect("the edit lands"),
            );
        }
        let folded = |at: Rev| {
            Repo::folding(&doc.repo().log()[..at.get() as usize])
                .expect("the prefix folds")
                .document()
                .clone()
        };
        let at_three = folded(revs[2]);
        let at_two = folded(revs[1]);
        assert_ne!(at_two, at_three, "precondition: the last edit moved it");

        let undone = doc.undo(revs[2], &author()).expect("the undo lands");
        assert_eq!(doc.document(), &at_two, "the undo did not reach rev 2");
        assert_eq!(doc.trail().standing(), revs[1]);

        doc.undo(revs[1], &author()).expect("the second undo lands");
        assert_eq!(doc.trail().standing(), revs[0]);

        doc.redo(
            doc.trail().next_redo().expect("a step to put back"),
            &author(),
        )
        .expect("the redo lands");
        doc.redo(undone, &author()).expect("and the second redo");
        assert_eq!(
            doc.document(),
            &at_three,
            "the walk back up did not return the document it started from",
        );
        assert_eq!(doc.trail().standing(), revs[2]);
    }

    /// A scratch session has no projection to keep in step with, and says so
    /// rather than reporting a read-only container it does not have.
    #[test]
    fn a_scratch_session_refuses_to_save_a_projection_it_has_none_of() {
        let mut doc = Doc::default();
        assert_eq!(doc.saving(), Saving::Withheld);
        assert!(doc.projection().is_none());
        assert!(matches!(doc.save_projection(), Err(Refusal::Detached)));
    }

    /// The refusal the editor's history walk reads to decide whether a step
    /// is spent or the repo is broken, in the spelling both arms report.
    #[test]
    fn a_step_the_trail_does_not_hold_is_refused_as_a_step() {
        let mut doc = Doc::default();
        assert!(matches!(
            doc.undo(blockworx_doc::fixtures::rev(1), &author()),
            Err(Refusal::Step(blockworx_doc::trail::UndoRefusal::Spent)),
        ));
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn an_attached_document_writes_through_the_container() {
        use crate::store::handle::Clock;

        let dir = crate::store::tests::fixture::dir("doc-attached");
        let root = dir.join("doc.bwx");
        let mut doc = Doc::attached(Store::create(&root, Clock::System).expect("the container"));
        assert_eq!(doc.writability(), Writability::Writable);

        doc.submit(one_block(), &author()).expect("the edit lands");
        assert_eq!(
            std::fs::read_to_string(root.join(crate::store::container::MANIFEST))
                .expect("the log")
                .lines()
                .count(),
            1,
            "an edit through the document handle did not reach the log",
        );
    }

    /// A container someone else holds opens read-only, and the handle says so
    /// in the one spelling the command registry and the chrome both read.
    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn a_locked_container_is_read_only_and_refuses_writes() {
        use crate::store::handle::Clock;

        let dir = crate::store::tests::fixture::dir("doc-locked");
        let root = dir.join("doc.bwx");
        let _held = Store::create(&root, Clock::System).expect("the first session");

        let mut doc = Doc::attached(Store::open(&root, Clock::System).expect("the second"));
        assert_eq!(doc.writability(), Writability::ReadOnly);
        assert!(matches!(
            doc.submit(one_block(), &author()),
            Err(Refusal::ReadOnly),
        ));
        // Renaming is a write on someone else's open document, not a read.
        assert_eq!(doc.renaming(), Renaming::Withheld);
        assert!(matches!(
            doc.rename(&dir.join("renamed.bwx")),
            Err(Refusal::ReadOnly),
        ));
        assert!(root.exists(), "the refused rename moved it anyway");
    }

    /// A session with no container has no name to change, and says so
    /// rather than inventing a file.
    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn a_scratch_session_has_no_container_to_rename() {
        let mut doc = Doc::default();
        assert_eq!(doc.renaming(), Renaming::Withheld);
        assert!(matches!(
            doc.rename(std::path::Path::new("/tmp/nowhere.bwx")),
            Err(Refusal::Detached),
        ));
    }
}