The package does not construct daemon clients, access desktop preload APIs, resolve host paths, spawn processes, or register workbench or dock contributions.

Runtime Failure Semantics

Runtime status remains a lifecycle status, so all terminal failures use failed. Hosts should attach WorkspaceAppRuntimeError.failurePhase to retain where the failure occurred: downloading, installing, starting, or runtime. Host adapters may carry the same phase on WorkspaceAppCenterApp before projecting the runtime state. The shared card uses that optional phase for accurate failure copy and falls back to a neutral runtime failure for older hosts.

Do not add compound statuses such as install_failed or start_failed. Keeping outcome and failure phase orthogonal lets hosts preserve their existing install and runtime event hooks while sharing one compatible status machine.

Runtime Refresh Policy

createWorkspaceAppCenterController defaults to refreshPolicy: "poll" for backward compatibility. In this mode, the controller schedules bounded refreshes while installs and transient runtime states are active.

Event-driven hosts can pass refreshPolicy: "event". This disables the controller's per-app install refreshes and transient-runtime refresh timer. The host must then subscribe to its daemon/runtime event stream and forward each app change through controller.applyAppUpdate(...) with an operationCursor:

controller.applyAppUpdate({
  app,
  operationCursor: {
    desiredGeneration,
    operationId,
    sequence
  },
  workspaceId
});

Within an operation, sequence must increase. A replacement operation must use a greater desiredGeneration and a new operationId; stale, duplicate, or ambiguous updates are discarded. Event updates are accepted only while that workspace's polling lifecycle is active. endWorkspacePolling is a full workspace teardown and rejects late events from the disposed stream.

Event mode deliberately does not provide an app-state polling fallback. The host owns reconnect handling. For a reconnect of the same active workspace, first pause and guard delivery from the old stream, call resetWorkspaceEventCursors(workspaceId), fetch and apply a full WorkspaceAppCenterSnapshot, and then resume ordered applyAppUpdate events from the replacement stream. The reset keeps pending install/report state, while the fresh snapshot establishes the new event-ordering baseline. Do not call endWorkspacePolling for a reconnect; reserve it for leaving or disposing the workspace. The catalog-loading refresh remains workspace-scoped and is independent of app runtime event delivery.

View State

WorkspaceAppCenterViewState preserves the selected app tab and may include an openAppId. Hosts can use that id to replace the app list with the running app in the same presentation region, then clear it to return to the preserved list. The package only owns this host-neutral state contract; rendering and webview lifecycle remain host responsibilities.

Developer Sources

Developer/source presentation is host-controlled. AppCenterPanel and AppCard accept showDeveloperSources, default it to false, and render the developer/source row from app metadata only when enabled. The shared package does not own the preference or persistence policy.

Desktop owns the showAppDeveloperSources preference, persists it through the desktop-preferences service, and passes the resulting value into the App Center pane. Keep preference UI, daemon storage, and host-specific source links out of this package.

Visible App Tabs

AppCenterPanel shows the recommended, community, and my-apps tabs by default. Hosts can restrict or reorder them with visibleAppTabs. For example, a host that only exposes the official catalog can render:

<AppCenterPanel visibleAppTabs={["recommended"]} {...props} />

If the controlled active tab is not visible, the panel renders the first visible tab. An empty configuration falls back to the recommended tab.

Recommended App Categories

Recommended category filtering uses the stable ids product-design, content-creation, office, and tools. The package classifies the supported official app ids and aliases in its core view-model layer, while the shared i18n resources own the labels shown to users. Hosts may provide one of the stable ids through WorkspaceAppRecord.categoryId for apps outside the built-in map. The legacy free-form category field remains supported for host compatibility, but new integrations should keep localized presentation labels out of category data.