Elonn Docs Platform Documentation

Runtime Object And Workspace System

Elonn is moving away from a surface-centered architecture toward a World-owned object/workspace model and canonical runtime dataset. The current implementation still uses surface vocabulary in contracts and code, but Surface is no longer the assumed architectural center.

For current implementation status, see Current State.

Target Hierarchy

Service
  └─ Domain object
       └─ World canonical model
            ├─ Runtime object
            ├─ Workspace item
            ├─ Context/control group
            ├─ Field object
            ├─ Finding
            └─ Action
                 └─ Canonical runtime dataset
                      └─ Runtime adapter presentation

Runtime

A complete executable presentation environment — web, Android, XR, desktop, room-scale spatial, or another future runtime. A runtime consumes the canonical runtime dataset. It is responsible for rendering, input handling, lifecycle, accessibility implementation, local performance, projection, and platform adaptation. It does not own social, message, map, calendar, workspace, or finding data.

Existing runtimes are not design references. Their behavior can identify migration cost or architectural failure, but future runtime questions should be resolved from services, World, contracts, and conformance fixtures.

Region

A persistent semantic zone within a runtime presentation. The two primary platform regions are:

  • carry — user-following interface space; anchored to the member; persists during movement
  • field — world-anchored environmental space; spatially fixed; tied to locations

Runtimes decide how those regions appear. A compact screen may use sheets or bottom navigation. A tablet may use multiple panes. A room-scale runtime may use anchors, volumes, and spatial placement.

Stack

A navigable ordered collection within a region. In the target model, this should be owned by World as workspace state and projected by runtimes. The current implementation still uses surface stacks.

Navigation is driven by runtime capability: gesture, keyboard, pointer, gaze, controller, voice, proximity, or programmatic transition. The contract should define the semantic result, not one fixed transition geometry.

Top dock, bottom dock, left rail, center stack, and right rail are not universal concepts. They are one possible runtime projection for conventional screens.

Surface

A self-contained contextual presentation container in the current implementation. The target architecture should treat this as a World-owned workspace item or runtime presentation, not as a separate service-owned primitive.

Examples: Nearby Restaurants, Friends Nearby, Messages, Today's Schedule, Transit, System Status.

A surface is not a web page, a screen, a tab, or a window. Existing Surface state, stack membership, focus, and placement are persisted by surface.elonn.local; the target architecture moves durable workspace state into World and retires surface.elonn as a service boundary.

Surface types: launcher_surface, findings_surface, feed_surface, map_surface, conversation_surface, dashboard_surface.

For the proof path where real Find provider results become individual movable Web surfaces, see Current State.

Panel

A panel is runtime UI displayed inside a rail stack or surface body. Panels are not durable primary workspace surfaces by default. They do not own service data, surface identity, placement, sharing, or saved layout unless explicitly promoted into durable surfaces.

Examples: Profile Panel, Visibility Panel, Calendar Filter Panel, Participants Panel, Map Layers Panel.

Use the distinction:

Time Service
  -> Calendar Surface
  -> Calendar Inspector Panel

If a UI element must move between stacked, docked, detached, shared, or field-anchored placement without changing identity, it is a durable surface. If it is contextual UI around the focused surface, it is a panel in a rail stack.

Dock

A possible presentation of launcher/locator semantics in a screen runtime. A dock is not a universal runtime requirement.

Rail

A possible presentation of context/control semantics in a screen runtime. Rails are not universal runtime requirements.

Block

A structured content region within a surface. Blocks organize objects, cards, controls, and findings into logical groups. Block type defines rendering semantics.

Block types: list_block, card_block, hero_block, action_block, map_block, media_block.

Object

A renderable entity within a block, originating from a service. Examples: place (maps), member (api), message (messages), calendar item (time). Objects may expose actions. Always prefer the domain noun over bare "object."

Card

A visual presentation wrapper for an object. A card is renderer-level, temporary, and replaceable. It previews, launches, expands, or links to an object — it never becomes the environment itself. Cards scale across web, mobile, XR, and desktop without changing semantics.

Card variants: compact, expanded, hero, stacked, floating, minimal.

Action

An executable interaction exposed by an object or surface — open, join, navigate, message, save, pin. Actions belong to objects and surfaces, not to blocks or cards.

Window

Window is reserved. It implies an OS-managed container with independent z-order, resizing, and overlap — the desktop metaphor. Elonn uses surfaces, not windows. Window becomes valid only if Elonn supports multiple simultaneous independently positioned surfaces. The correct evolution path is surface → detach → window, not window as a starting primitive.