Activity-Oriented Application Standard

The activity architecture is the preferred reference for Wavenumber applications built from composable, stack-oriented workflows. Its core is platform-neutral. The executable browser reference uses TypeScript and Lit, while native desktop, embedded UI, terminal, and other hosts may implement the same contract through different adapters.

When To Use It

Use activities when a product has independent workflows that open nested work, return typed results, retain caller state, and compose into larger flows. A static site, simple form, or small component collection does not need activities merely to conform.

Mental Model

An activity is an independently registered unit of behavior with typed input, typed completion, owned transient state, and frame-scoped resources. The conceptual contract is Activity<Input, Output> plus a managed lifecycle.

The model is loosely inspired by Android activities, intents, results, and the back stack. It does not copy Android manifests, implicit intents, operating-system component ownership, process restoration, or its large lifecycle API.

Navigation Semantics

push

Retains the caller frame, opens a registered child with typed input, and returns a completion that contains a typed result or cancellation.

pop

Successfully completes a non-root frame with typed output and resumes its caller. Popping the root is invalid.

cancel

Completes a non-root frame without a successful result. Cancellation is distinct from an unexpected failure and from a domain-level result.

switch

Replaces a root activity when no caller is waiting for a result. It is invalid on a frame with a waiting caller; that frame must return control explicitly.

Registration And Dependencies

• Activities publish definitions containing identity and typed boundaries.
• Activities never self-register.
• A composition root maps definitions to factories and injects capabilities.
• A feature may import another activity's public definition.
• A feature must not import a sibling activity implementation, store, view, or private state.
• The activity system is not a global service locator.

Lifecycle

Creation, initialization, activation, leave evaluation, deactivation, and disposal are serialized and non-reentrant. Each created frame is disposed exactly once, including when initialization or activation fails.

Activity contexts are frame-bound capabilities. Navigation from an inactive or disposed frame cannot mutate a different active frame. Stale navigation rejects; stale change notifications are ignored.

A frame owns an abort signal or equivalent cancellation scope. Disposal terminates requests, streams, timers, observers, subscriptions, and other frame-owned work before references are released.

Unexpected failures reach a host error boundary after cleanup. Expected validation and domain failures remain typed feature state or typed output; they are not smuggled through unexpected exceptions.

Cleanup is best-effort and failure-aggregating: shutdown and failed transitions continue through remaining disposal and recovery hooks before an error is reported.

Leave Policy

Activities expose one of four reviewable leave states:

• clean: leaving may proceed immediately;
• dirty: the host must ask for discard confirmation;
• validating or committing: leaving requires cancellation or completion policy;
• blocked: leaving is denied with a user-visible reason.

Browser back/forward, shell navigation, application shutdown, and native window close use the same activity leave decision rather than inventing separate feature-specific rules.

State Ownership

State is promoted only when ownership genuinely broadens. A single global store is not the default transport between activities.

Centralized Backend Boundary

Raw HTTP, URL, authentication-header, EventSource, and WebSocket mechanics do not belong in activities, stores, or components. Generated contracts own wire shapes; shared transports own protocol mechanics; feature clients own semantic operations; stores own feature state; activities compose workflows; components render state and report intent.

• Use HTTP for finite commands and queries.
• Use SSE for server-to-client progress and event streams.
• Use WebSockets for genuinely bidirectional or low-latency protocols.
• Use polling for simple, infrequent, latency-tolerant updates.
• Pair reconnectable streams with an authoritative snapshot path.

Client policy must cover normalized errors, deadlines, cancellation, retry and idempotency ownership, reconnect and backoff, heartbeat and backpressure, protocol versions, and local-loopback origin, authentication, and CSRF posture.

Lit Web Reference

Lit is preferred, not required, when a new TypeScript browser application needs stateful custom elements, lifecycle, templates, and reusable component contracts. Native semantic HTML remains the first choice for ordinary controls. Each project documents its Shadow DOM or light DOM policy.

The activity kernel must not import Lit, DOM, browser history, HTTP, application composition, or feature modules. Lit hosting, browser history, and lifecycle integration are adapters around the kernel.

Shell And Theme Boundary

Activities select named shell profiles. They do not manipulate headers, navigation, side panels, overlays, or backgrounds directly. The canonical profiles are workspace, focused, background-only, and bare.

A reference-only profile preview must retain a recovery affordance when an override hides its own selector or navigation. Production chrome-free profiles do not gain hidden global navigation; their activities must expose an intentional completion or cancellation path.

The reference design language uses a dark industrial palette, gold accent, compact density, square controls, zero-radius styling, panels, and rotating backgrounds. All design-bearing values flow through theme primitives and semantic tokens so another theme can replace them without editing feature components.

CSS policy must parse and enforce a curated set of design-bearing properties rather than rejecting every numeric literal. Token definitions, zero, percentages, unitless values, runtime geometry, data visualization, currentColor, transparent, inheritance, and reviewed exceptions remain valid.

Public Assets And Typography

The approved Wavenumber background snapshots may be copied from install/assets/branding/backgrounds. The public template must record source, Wavenumber ownership and redistribution authorization, checksums, release inclusion, and update policy. The copied files are versioned template snapshots; Install remains the live editable branding authority. A product-use stock license alone is not sufficient for raw redistribution in a reusable public template; those assets must be omitted unless explicit public-template redistribution rights are recorded.

Berkeley Mono is licensed for private Wavenumber use and must not be redistributed from this public repository. The public reference uses JetBrains Mono under its open font license with a system-monospace fallback. Private products may substitute Berkeley Mono through the typography theme token without changing component styles.

Template Distribution

The Lit activity reference is a private, copy-owned project template rather than a shared runtime framework. Version-matched template resources are obtainable from the installed governance package through dev-std template copy and browsable at the matching source release tag.

Executable Evidence

docs/templates/web/lit-activity/ is the canonical runnable evidence. Its rendering-independent src/activity/ kernel, composition root, isolated feature activities, browser adapters, and host lifecycle tests demonstrate the required dependency direction. Use the live Vite and signoff commands in Build Documentation when reviewing changes.