room

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 1, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package room shares workbooks between the people 012 serve hosts: a room is one workbook, opened by every session that opens the same file (or joins the same named room), and each participant has a seat in it. The server holds the workbook, so there is no merging: every participant acts on it in turn, under the room's lock, and the steps they make are ordered by the workbook's one mutation path (Batch and its undo steps), each attributed to its author, as a stream of operations (sheet.Op) the room hands every participant. A participant is anything with a name that can be told the room changed (Participant): a served session's model, a local session sharing its workbook with the agent, or the agent itself, an MCP client attached in live mode (internal/cowork, the Agent interface). See docs/contributing/architecture.md.

Index

Constants

View Source
const Colors = 6

Colors is how many colors participants are told apart by.

Variables

This section is empty.

Functions

This section is empty.

Types

type Agent added in v0.6.0

type Agent interface {
	Participant
	Agent()
}

Agent is a participant that is one of the agents (live mode, an MCP client attached): the others see it marked as one, and it keeps nothing the room runs.

type Mark

type Mark struct {
	Seq    uint64
	Author int
	Name   string
	Color  int
	Kind   sheet.OpKind
	Label  string
	Sheet  *sheet.Sheet
	Rect   sheet.Rect
	At     time.Time
}

Mark is an operation's place in the workbook: who changed which cells, for showing whose change a cell holds.

type Mode

type Mode int

Mode is who may change a room's workbook.

const (
	// Edit lets every participant edit.
	Edit Mode = iota
	// View lets one participant, the writer, edit; the others follow.
	// The writer hands the role over explicitly (Seat.HandTo).
	View
)

type Participant

type Participant interface {
	// Name is who they are to the others: the SSH user of a session.
	Name() string
	// Notify tells them the room changed: someone else's operations,
	// where the others are, who writes, a save, a message posted for
	// them. It's called with the room locked, so it must neither block
	// nor call back into the room: they look at what changed on their
	// next turn (Seat.Do).
	Notify()
}

Participant is one who takes part in a room. The room asks only this of it; everything else a participant does, it does through its Seat.

type Peer

type Peer struct {
	ID       int
	Name     string
	Color    int
	Presence Presence
	Writing  bool
	Joined   time.Time
	Agent    bool
}

Peer is what a participant sees of another: who, in what color, where, and whether they write.

type Presence

type Presence struct {
	Sheet     *sheet.Sheet
	Cursor    sheet.Addr
	Selection sheet.Rect
	Editing   bool // typing into the cell at Cursor
}

Presence is where a participant is.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry is the rooms a server holds, by key: a file's path, or @name for a named room.

func NewRegistry

func NewRegistry(mode Mode) *Registry

NewRegistry holds rooms whose participants edit as mode says.

func (*Registry) Has

func (g *Registry) Has(key string) bool

Has reports whether a room with key is open.

func (*Registry) Join

func (g *Registry) Join(key string, p Participant, book func() *sheet.Workbook) (*Seat, bool)

Join seats p in the room with key, opening it on the workbook book makes when there's none (book is called with no lock held but the registry's, and may be nil when the room is known to be open). It reports whether it opened the room. A room's history is shared: undo takes back each participant's own steps.

func (*Registry) JoinOpen added in v0.6.0

func (g *Registry) JoinOpen(key string, p Participant) (*Seat, bool)

JoinOpen seats p in the room with key if it's open, reporting false when it isn't: the agent joins only a workbook someone has open.

func (*Registry) Rooms

func (g *Registry) Rooms() int

Rooms is how many rooms are open.

type Room

type Room struct {
	// contains filtered or unexported fields
}

Room is one shared workbook and the seats of those in it.

type Saved

type Saved struct {
	State   int    // the workbook's StateID then
	Outputs int    // its OutputsChanged then
	Name    string // the file's name, as typed, "" for none
	Key     string // the file's room key, its path: the room is its room too
	Stamp   any    // the file on disk then, the UI's to compare
}

Saved is the room's file as last saved or opened: what every session in it counts unsaved changes from.

type Seat

type Seat struct {
	// contains filtered or unexported fields
}

Seat is a participant's place in a room.

func (*Seat) Agent added in v0.6.0

func (s *Seat) Agent() bool

Agent reports whether the participant is one of the agents.

func (*Seat) Book

func (s *Seat) Book() *sheet.Workbook

Book is the room's workbook. Only use it in a turn (Do).

func (*Seat) Closed added in v0.6.0

func (s *Seat) Closed() bool

Closed reports whether the room closed: its last person left. Call it in a turn.

func (*Seat) Color

func (s *Seat) Color() int

Color is the participant's color, from 0 to Colors-1.

func (*Seat) Do

func (s *Seat) Do(fn func(w *sheet.Workbook))

Do runs fn as the participant's turn: with the room locked, the workbook's steps made in the participant's name. When the turn ends, the others are told of what changed.

func (*Seat) HandTo

func (s *Seat) HandTo(id int) bool

HandTo hands the writer's role to the participant with id, reporting false when this one doesn't write or there's no such participant. Call it in a turn.

func (*Seat) ID

func (s *Seat) ID() int

ID identifies the seat in the room: the author of its steps.

func (*Seat) Keeper

func (s *Seat) Keeper() bool

Keeper reports whether the participant keeps what the room runs on its own (linked files followed, notebook cells running): the person who has been there longest, as agents run nothing of the room's. Call it in a turn.

func (*Seat) Key

func (s *Seat) Key() string

Key is the room's key: the file's path, or @name for a named room.

func (*Seat) Last

func (s *Seat) Last() uint64

Last is the latest operation's number. Call it in a turn.

func (*Seat) Leave

func (s *Seat) Leave() (last bool)

Leave gives up the seat, reporting whether it was the last person there: the room closes then, and its workbook is the participant's alone. Agents still there are told, and find the room closed (Closed).

func (*Seat) Marks

func (s *Seat) Marks(since uint64) []Mark

Marks are the operations since seq, oldest first, whoever made them. Call it in a turn.

func (*Seat) Mode

func (s *Seat) Mode() Mode

Mode is who may edit the room's workbook.

func (*Seat) Move

func (s *Seat) Move(p Presence)

Move sets where the participant is, for the others to see once the turn ends. Call it in a turn.

func (*Seat) Name

func (s *Seat) Name() string

Name is the participant's name.

func (*Seat) Others

func (s *Seat) Others() int

Others is how many others are in the room. Call it in a turn.

func (*Seat) Peer added in v0.6.0

func (s *Seat) Peer(id int) (Peer, bool)

Peer is the participant with id, and whether they're here. Call it in a turn.

func (*Seat) Peers

func (s *Seat) Peers() []Peer

Peers are the others in the room, in the order they joined. Call it in a turn.

func (*Seat) People added in v0.6.0

func (s *Seat) People() int

People is how many other people are in the room, agents left out: those who keep the workbook open when this one leaves. Call it in a turn.

func (*Seat) Post

func (s *Seat) Post(msg any)

Post leaves msg for the keeper, whoever it is when it takes it: what the room runs reports back this way rather than to the participant that started it, who may have left. It may be called from any goroutine, outside a turn.

func (*Seat) Saved

func (s *Seat) Saved() Saved

Saved is the room's file as last saved or opened. Call it in a turn.

func (*Seat) SetSaved

func (s *Seat) SetSaved(v Saved)

SetSaved records a save, or the file the room was opened from, for every session. Call it in a turn.

func (*Seat) Take

func (s *Seat) Take() []any

Take is what was posted for the keeper, if this is the keeper. Call it in a turn.

func (*Seat) Touch added in v0.6.0

func (s *Seat) Touch()

Touch tells the others, once the turn ends, that something they share changed without the workbook changing: a value of the room's (Value), such as the agent's suggestions. Call it in a turn.

func (*Seat) Value

func (s *Seat) Value(key string, make func() any) any

Value is the room's value for key, made by make the first time: state every participant shares, such as the notebook cells running. Call it in a turn.

func (*Seat) Writer

func (s *Seat) Writer() string

Writer is the writer's name in a View room, "" in an Edit room.

func (*Seat) Writing

func (s *Seat) Writing() bool

Writing reports whether the participant may edit: in an Edit room everyone, in a View room the writer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL