Experience and presentation#

One keeps presentation meaning separate from any renderer. A place, an intent, a complete page snapshot, renderer-local state, and the canonical operation states are owned values that several languages and targets can share. Which framework or target actually paints, dispatches, or hydrates them remains a removable physical choice.

Experience is currently active only as a bounded cross-language slice. This page describes that slice and the hold around it; it does not describe a general UI framework or an Experience authoring grammar, and neither exists today.

Renderer-neutral identities and one complete snapshot#

The shared values are:

• PlaceId and IntentId — non-zero u128 identities for a conceptual place and a user goal;
• Page<T> — one complete snapshot of a place together with its canonical operation state, never a partial patch a renderer must reconcile;
• Local<T> — explicitly renderer-local presentation state that is not part of the page snapshot and carries no domain meaning;
• View — the completion boundary that exposes the concrete document type without selecting HTML, a host, an operation binding, or authority; and
• the canonical operation-state vocabulary below.

Identity is nominal. Two structurally similar pages under different owners do not become one page, and a renderer cannot mint a place or intent from a route, a component name, or rendered HTML.

Canonical operation states#

Every realization consumes the same three state families.

ResourceState: Empty, Loading, Ready, Refreshing, Stale, Offline, Failed.

CommandState: Idle, Validating, Pending, Succeeded, Rejected, OutcomeUnknown, Reconciling, Cancelled, Defect, Failed.

SubscriptionState: Connecting, Current, Reconnecting, GapDetected, Resnapshotting, Exhausted, Revoked, Failed.

The mappings are fixed, not renderer discretion:

Only an Idle command may begin dispatch. An OutcomeUnknown retains its effect reference and cannot be redispatched implicitly; the only forward path is explicit reconciliation. A stream gap is never smoothed over as continuity. A renderer may present target-specific detail but cannot reinterpret these states as a generic error without a declared semantic loss.

Two transparent language bindings#

Rust exposes one::experience; TypeScript exposes @one/experience. Both carry the same owned meaning rather than defining a second Experience model.

The TypeScript binding enforces the same unknown-outcome no-redispatch rule through finite pure state helpers: non-zero place and intent identities, complete snapshots, renderer-local values, an idle-only dispatch guard, and retention of an unknown outcome's effect reference. It owns no async runtime, operation transport, framework store, retry policy, or authority.

Physical facades#

Web delivery is a separate physical facade:

• Rust's opt-in one::web::server composes the deterministic escaped server-HTML adapter with one fixed host. Its routes are exactly GET /, POST /submit, GET /style.css, and GET /health. It sends no JavaScript or browser runtime, performs no hydration, and carries no authority. A finite server-HTML projection of the headless viewer frame is also available as one::web::server::viewer_document.
• TypeScript's @one/web maps one selected page and command state to finite inert DOM attribute records and decodes bounded, duplicate-free, text-only browser FormData. React/Next remains application-selected and keeps its own routes, components, state, layout, and interaction behavior.

Neither facade selects an operation implementation, provider, transport, or authority. Ordinary applications that make no Experience claim should use their framework directly, as described in applications.

Desktop over a real data plane#

Rust's opt-in one::desktop composes place, intent, page, local, view, and canonical command-state identities with the removable desktop renderer adapter's headless frame: top bar, tile viewport, blueprint tree, selection panel, time panel, command-palette index, and welcome/toast state, together with spatial 2D/3D, time-series, bar, dataframe, graph, map, tensor, text-document, text-log, and state-timeline views.

Ownership is split so no adapter becomes the meaning owner:

• Data owns entity paths, timeline and time coordinates, and the ported columnar chunk and query model;
• Experience owns geometry, cameras, ruler axes, selections, blueprints, playback, views, and design semantics; and
• the adapter owns only its finite headless panel and view mapping plus its explicit losses.

The facade owns only the fixed present and dispatch composition. The executable consumers are the adapter's one-desktop binary, the facade-only dummy viewer fixture, and products/rerun. The removable one-provider-desktop-egui-host realizes the same frames in a native window and is selected per root; a first-party renderer or UI may replace it behind the same owned contracts.

This desktop frame reads the data plane described in the ported data plane.

The Experience hold#

Outside the bounded cross-language and ported-desktop slice above, the Experience hold applies. It prohibits, until the hold is lifted:

• new Experience declaration grammar;
• automatic Experience-to-document lowering;
• a shared client runtime or hydration;
• unrelated framework abstraction or adapters;
• additional renderers beyond the named desktop provider; and
• generalized cross-target conformance machinery.

The hold ends only through an owner-approved update to the root AGENTS.md and systems/experience/AGENTS.md after an executable consumer demonstrates a repeated renderer-independent need that existing operations, schemas, SDKs, components, and ordinary framework code cannot satisfy. Merely declaring that a target could be realized does not place its framework or capabilities in another root's closure.

One Cloud, the public website, documentation, and dashboards MUST NOT depend on Experience contracts merely to dogfood One. They use ordinary application frameworks and integrate through the narrow public One contracts they actually consume.

Demonstrated example#

The snippet below is drawn from the demonstrated Rust facade and its physical server host; Page::new and one::web::server::view! are exercised by the standalone Order Review Web product. It is a fixed composition, not an authoring grammar.

use one::experience::{CommandStateKind, IntentId, Page, PlaceId};
use one::web::server::{Document, view};

fn order_page(state: CommandStateKind) -> Document {
    let page = Page::new(PlaceId::new(1).unwrap(), state);
    view! {
        page: &page,
        title: "Order Review";
        <h1>{"Order Review"}</h1>
        <button intent={IntentId::new(1).unwrap()}>{"Review order"}</button>
    }
}

Follow One Web for the fixed routes and Build a Rust One Web application for the complete standalone product.

There is no Experience authoring kind today#

There is no experience, place, or intent declaration kind to author in .one today. The active slice consumes existing owned identities through the Rust and TypeScript bindings; it does not add declaration grammar. A future grammar would require the owner-approved update described in the hold.

Next: read the ported data plane or root and composition.

Normative owner & evidence#

The normative owner is systems/experience/AGENTS.md, under the repository composition law in AGENTS.md.

Demonstrated today: the one::experience and @one/experience bindings and their canonical states and dispatch guard; the one::web::server fixed-route host; the @one/web inert DOM and FormData mapping; the one::desktop headless frame over the removable adapter; and the named one-desktop, dummy viewer, and products/rerun consumers, each with owning tests.

Illustrative or deferred: any experience, place, or intent .one declaration kind, automatic Experience-to-document lowering, a shared client runtime or hydration, additional renderers, and generalized cross-target conformance. The AGENTS.md prose that describes broader lowering, modules, and renderer providers defines the owned boundary and validation shape, not a claim that those integrations can be selected today.