Frontend State and Commands¶
Last changes: Documentation changelog
Frontend state is resource-oriented and dual-plane. Control-plane metadata, commands, and revisions exchange over typed OpenAPI v2 JSON endpoints synchronized via WebSocket invalidations, while dense spatial meshes, vector buffers, region masks, planar cuts, and table histories stream over versioned binary HTTP codecs. Components must never invent a parallel local simulation truth.
Key invariants:
drafts stay local and isolated until explicitly applied;
successful authoring writes return an updated backend
scene_revision;dependent mesh, preparation, and field caches are invalidated explicitly across resources;
command acceptance, command completion, and scientific qualification remain separate states;
currentandlatest-successfulmesh/runtime artifacts remain distinct;backend validation and transport errors appear verbatim or in bounded summaries.
Command Registry & Palette (Ctrl+Shift+P)¶
Modules declare typed actions (CommandContribution) with id, title, group, category,
scope, shortcut, isEnabled, disabledReason, isActive, and run. All global and session
commands are searchable from the Command Palette (CommandPaletteModule, opened with
Ctrl+Shift+P, Edit -> Command Palette, or the top-bar Command search button). Non-session
contexts restrict visible items using projectWorkspacePaletteCommands.
Isolated Drafts, Commit Fencing & Revision Reconciliation¶
All inspector editors register with InspectorEditSession under "staged", "liveViewport", or
"immediate" mode:
Because an external Python script or sibling tab may mutate the session concurrently, authoring
writes (runAuthoringMutationWithHistory) carry optimistic scene_revision preconditions. When a
409 revision conflict occurs (revision_conflict / scene_revision_conflict), reconciliation
helpers (reconcileObjectEditAck, reconcileObjectIdentityAck) preserve unconflicted local edits
or prompt the user to rebase before retrying. Stage re-execution (executeStageAfterApply) also
pins (scene_revision, solver_profile, domain) and aborts cleanly if any compute input changes
between Apply and Compute.
Live Python Client Presence & Session Sync¶
When an interactive Python script calls fm.connect(), LiveSession
(packages/fullmag-py/src/fullmag/live/_session.py) registers a unique python-<hex> client_id
and sends a presence heartbeat every 10 s to PUT /v2/sessions/current/clients/{client_id}
(SessionClientsResource, 30 s API TTL). Scene transactions committed from Python bump
scene_revision, emit WebSocket invalidation events, refresh Control Room resources cleanly, and
surface attached sessions directly inside Active simulations on /home.
Versioned Binary HTTP Codecs¶
To keep JSON payloads thin (docs specification: binary data plane), apps/control-room/src/kernel/api/codecs/
decodes zero-copy ArrayBuffer responses identified by 4-byte magic headers:
Magic |
Codec module |
Payload semantics |
|---|---|---|
|
|
3D/spatial scalar & vector fields ( |
|
|
FEM topology (positions, cell/facet connectivity, global ordinals, cell/facet/boundary markers) |
|
|
FDM grid cell-to-region membership ( |
|
|
Per-layer active cell masks for multilayer FDM models |
|
|
2D planar slice field and geometry cut payloads |
|
|
2D cross-section mesh quality profiles |
|
|
FEM element size, edge-length, and quality histograms |
|
|
Bloch-periodic master/slave boundary facet pairing data |
|
|
Decimated scalar/time-series table rows for charts and exports |
Screenshots illustrate the interface; they are not runtime or physics qualification evidence.
Control Room crosswalk¶
Status classification:
partial— command infrastructure, optimisticscene_revisiondrafts, WebSocket invalidation, and all nine binary decoders above areimplemented; live two-way Python script buffer diff/sync in the hidden RibbonAutomationtab remainsTODO: frontend support.Routes: Command Palette (
Ctrl+Shift+P), Inspector Apply (Ctrl+Shift+Enter) / Reset, Footer Logs (HTTP/WS/Command audit), and Start Screen Active simulations.
Python/API crosswalk¶
fullmag.live(fm.connect(),LiveSession) drives HTTP resource endpoints compatible with the same OpenAPI v2 schema consumed byControlRoomApi.Client binary decoders match backend serializers used by
fullmag.client(fmvp,fmtb, etc.).
Physics and bibliography scope¶
This page describes browser state synchronization, transport codecs, and concurrency safety; it introduces no independent physical equations.
Source-code index¶
Responsibility |
Repository path |
Stable symbol |
|---|---|---|
Command palette & command filtering |
|
|
Command palette shortcut registration |
|
|
Inspector edit session contract |
|
|
Revision-pinned stage execution |
|
|
Python live session & 10s heartbeat |
|
|
Binary vector/scalar field codec |
|
|
Binary FEM topology codec |
|
|
Binary FDM region mask codec |
|
|