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 workawait workspaces.saveCurrent('Mine'); // the current arrangement as a new workspaceawait workspaces.saveBaseline(); // the current arrangement becomes the baselineworkspaces.rename(id, 'Reviews');const reset = await workspaces.reset(); // active workspace; asks about unsaved workawait workspaces.reset('review'); // a workspace you are not in; asks about unsaved work parked under itconst all = await workspaces.resetAll(); // asks once for all of themconst 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 workspaceRead it
workspaces.workspaces(); // Signal<readonly Workspace[]>: the saved workspacesworkspaces.activeId(); // Signal<string>workspaces.hasChanges(); // the active workspace differs from its baselineworkspaces.changedIds(); // every workspace that differs from its baselineworkspaces.claimsOfWorkspace(id); // readonly WorkspaceClaim[]: the address prefixes it claimsworkspaces.destinationFor(path); // the workspace a path would settle in, by those claimsworkspaces() 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
- Developer-defined workspaces:
provideWorkspacesand what it declares. - Resetting the application: every workspace and the frame in one guarded call.