Skip to content

Workspaces

This is a guide, not the contract. What the platform guarantees is specified under openspec/specs/. For this page: workspaces · host-services. Where this page and a specification disagree, the specification is right, and that is a defect in this page: change the behaviour there, then explain it here.

Everything the workspace dialog and the rail do, from your own code, under the ids you declared or the facts hand you.

Do it

const workspaces = inject(WorkspaceService);
await workspaces.switchTo('review'); // never asks, never loses work
await workspaces.saveCurrent('Mine'); // the current arrangement as a new workspace
await workspaces.saveBaseline(); // the current arrangement becomes the baseline
workspaces.rename(id, 'Reviews');
const reset = await workspaces.reset(); // active workspace; asks about unsaved work
await workspaces.reset('review'); // a workspace you are not in; asks about unsaved work parked under it
const all = await workspaces.resetAll(); // asks once for all of them
const removed = await workspaces.remove(id); // asks for the work parked under it and, if it was active, the work it shows; the user then lands in the default workspace

Read it

workspaces.workspaces(); // Signal<readonly Workspace[]>: the saved workspaces
workspaces.activeId(); // Signal<string>
workspaces.hasChanges(); // the active workspace differs from its baseline
workspaces.changedIds(); // every workspace that differs from its baseline
workspaces.claimsOfWorkspace(id); // readonly WorkspaceClaim[]: the address prefixes it claims
workspaces.destinationFor(path); // the workspace a path would settle in, by those claims

workspaces() is the list the user saved; the declared ones come from provideWorkspaces. The default workspace is the one declared initial, or the built-in default where none is. activeId() is the active one, hasChanges() whether it differs from its baseline, changedIds() every workspace that does.

What asks about unsaved work

Resetting the active workspace, resetAll() and remove() ask the question the built-in commands ask, inside the service, and answer whether they ran. Resetting a workspace you are not in asks about the unsaved work parked under it, and asks nothing where there is none. Removing the workspace the user is in asks once, for the work parked under it and the work every one of its surfaces shows. switchTo never asks and never loses work: it parks the work, as the capability requires. The “really reset?” confirmation the dialog shows is your control’s decision, not the service’s.

Switched off

workspaces.enabled removes the manage and reset commands and the rail entries for the user; the service keeps working for you. A declared workspace that nothing offers is then not reported, because there is no dialog it could be reached through.

In depth

Answers. Every asking action answers whether it ran, so a chain of them can stop when the user declined. Which actions ask is listed under What asks about unsaved work.

A remembered workspace that is gone. The workspace the user was last in may be neither declared nor saved any more. The workbench then gives way to the default workspace for the session, once the saved workspaces have answered, and the opening does not wait for them. Before it does, it asks about the unsaved work in everything that workspace shows or parked, except the tab at the address it keeps, and a refusal leaves the user there for the session. Giving way writes nothing: the remembered choice stays, and so does what is stored for that workspace. A remembered choice of a workspace that is really gone therefore gives way again at each opening until the user chooses a workspace. Saved workspaces whose first read was rejected, or that are not wholly a list of workspaces, move nobody. A store that reports a failed read as nothing stored is taken at its word, and so is a read at sign-in that fails: either is an empty list, and an answer.

Where the story is told