> Documentation index for agents: https://docs.rocketride.ai/llms.txt

# Shell API

A complete guide for developers building micro-frontend applications for the RocketRide Cloud platform.

---

## Table of Contents

1. [Architecture Overview](#architecture-overview)
2. [Getting Started](#getting-started)
3. [The App Manifest](#the-app-manifest)
4. [The App Descriptor](#the-app-descriptor)
5. [Shell Props: What Your App Receives](#shell-props-what-your-app-receives)
6. [Screen Zones](#screen-zones)
7. [Shell Hooks & APIs](#shell-hooks--apis)
8. [The Connection Manager (connectionManager)](#the-connection-manager-connectionmanager)
9. [The Documents System](#the-documents-system)
10. [The Virtual File System (IVirtualFileSystem)](#the-virtual-file-system-ivirtualfilesystem)
11. [DocExplorer: File Tree Component](#docexplorer-file-tree-component)
12. [DocTabs: Tab Bar Component](#doctabs-tab-bar-component)
13. [DesktopView: The Shared Desktop Page](#desktopview-the-shared-desktop-page)
14. [Cross-App Component Loading](#cross-app-component-loading)
15. [Theming](#theming)
16. [Build Configuration](#build-configuration)

---

## Architecture Overview

Shell-UI is a thin shell framework that hosts micro-frontend applications via [Module Federation](https://module-federation.io/). The shell owns:

- **Four screen zones**: Sidebar, Client Area, Debug Panel (ALT+D), Status Bar
- **Authentication**: OAuth2 PKCE via Zitadel
- **Subscription gating**: Checks server-side subscription state before loading paid apps
- **WebSocket connection**: RocketRide client singleton
- **Workspace persistence**: Per-app state in `.workspace/` JSON files
- **Theme management**: CSS custom properties (`--rr-*`)
- **Event bus**: Typed message bus for cross-component communication

Apps are independent packages that export an `AppDescriptor` via Module Federation. The shell loads them lazily when the user activates the app.

```text
┌──────────┬─────────────────────────┬────────────┐
│          │                         │            │
│ Sidebar  │      Client Area        │   Debug    │
│          │                         │  (ALT+D)   │
│          │                         │            │
├──────────┴─────────────────────────┴────────────┤
│ ● Connected    Ready                            │
└─────────────────────────────────────────────────┘
```

The shell mounts one component from your app:
- `app` → Client Area (required). Your app composes its own layout inside (columns, sidebar, status bar) with `<AppLayout>`.

---

## Getting Started

You build a shell app in your own repository: `npm install rocketride`, export
an `AppDescriptor` through Module Federation, and deploy the source to a
RocketRide server, which builds and serves it.

> **Shortcut:** the VS Code extension's [App Builder](/clients/vscode/app-builder)
> scaffolds this whole shape from a template and adds a live preview, publish,
> and deploy loop — the steps below explain what it generates.

### 1. Create a new project

```bash
mkdir my-app && cd my-app
npm init -y
npm install rocketride react react-dom
npm install -D @rsbuild/core @rsbuild/plugin-react @module-federation/rsbuild-plugin typescript
```

### 2. Project structure

```text
my-app/
├── package.json
├── rsbuild.config.ts
├── tsconfig.json
└── src/
    ├── index.ts           # MF async boundary
    ├── AppDescriptor.ts   # What the shell loads
    └── MyApp.tsx           # Client area component
```

### 3. Define the manifest in `package.json`

```json
{
  "name": "my-app",
  "version": "1.0.0",
  "appManifest": {
    "id": "mycompany.myApp",
    "publisher": "My Company",
    "name": "My App",
    "description": "A short description for the app store",
    "categories": ["tools"]
  },
  "dependencies": {
    "rocketride": "^1.0.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}
```

### 4. Create the AppDescriptor (`src/AppDescriptor.ts`)

Import types from `rocketride/app-sdk`:

```typescript
import type { AppDescriptor } from 'rocketride/app-sdk';
import MyApp from './MyApp';

const MY_APP: AppDescriptor = {
  id: 'mycompany.myApp',
  name: 'My App',
  branding: { appName: 'My App' },
  app: MyApp,
};

export default MY_APP;
```

### 5. Create the App component (`src/MyApp.tsx`)

```typescript
import React from 'react';
import type { ShellAppProps } from 'rocketride/app-sdk';

const MyApp: React.FC<ShellAppProps> = ({ isConnected, identity }) => {
  return (
    <div style={{ padding: 40, fontFamily: 'var(--rr-font-family)' }}>
      <h1>Hello from My App!</h1>
      <p>Connected: {isConnected ? 'Yes' : 'No'}</p>
      <p>User: {identity?.displayName ?? 'Not logged in'}</p>
    </div>
  );
};

export default MyApp;
```

### 6. Async boundary (`src/index.ts`)

```typescript
import('./AppDescriptor');
```

### 7. rsbuild.config.ts

```typescript
import fs from 'node:fs';
import path from 'node:path';
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';

const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, 'package.json'), 'utf-8'));
const moduleId = (pkg.appManifest?.id ?? 'unknown').replace(/[^a-zA-Z0-9_$]/g, '_');

export default defineConfig(() => ({
  plugins: [
    pluginReact(),
    pluginModuleFederation({
      name: moduleId,
      filename: 'remoteEntry.js',
      exposes: { './AppDescriptor': './src/AppDescriptor.ts' },
      dts: false,
      shared: {
        react:              { singleton: true, eager: true, requiredVersion: '^18.2.0' },
        'react-dom':        { singleton: true, eager: true, requiredVersion: '^18.2.0' },
        'rocketride/app-sdk': { singleton: true, requiredVersion: false },
      },
    }),
  ],
  source: { entry: { index: './src/index.ts' } },
  output: {
    distPath: { root: './dist' },
    assetPrefix: 'auto',
  },
}));
```

### 8. Build and deploy

```bash
npx rsbuild build
```

A local build only checks that the app compiles. Nothing serves `./dist/`, and hosting it yourself does not make the app load: the shell only loads a version that the server built. To ship the app, deploy it from the Deploy tab of the [App Builder](/clients/vscode/app-builder), or with `rocketride app deploy`. That uploads your source, the server builds it into the next version, and publishing that version makes it available to its audience.

---

## The App Manifest

Declared in `package.json` under the `appManifest` key. This metadata is available at boot without loading the app bundle, used for the app store, authentication gating, and settings.

```typescript
interface AppManifest {
  /** Stable unique identifier (e.g. 'rocketride.myApp'). */
  id: string;
  /** Publisher name shown in the app store (e.g. 'My Company'). */
  publisher?: string;
  /** Display name shown in the app switcher. */
  name: string;
  /** Short description for the app store. */
  description?: string;
  /** Path to icon file (e.g. './src/icon.svg'). */
  icon?: string;
  /** Markdown readme for the app detail page. */
  readme?: string;
  /** Categories for filtering (e.g. ['tools', 'ai']). */
  categories?: string[];
  /** Shell editions the app serves ('saas' | 'oss' | 'vscode'). Absent: every shell. */
  shells?: string[];
  /** When false, the app runs without authentication. Default: true. */
  authenticated?: boolean;
  /** When false, the shell header (app name/icon in the sidebar) is hidden. Default: true. */
  showHeader?: boolean;
  /** When false, the status bar is hidden for this app. Default: true. */
  showStatusBar?: boolean;
  /** Settings contribution (VSCode `contributes.configuration` shape). Shown in the shell's Settings overlay. */
  contributes?: { configuration?: AppConfiguration };
  /** Internal: MF module identifier (derived from id). */
  moduleId?: string;
  /** App lifecycle status (e.g. 'auth', 'free', 'unsubscribed', 'subscribed', 'trialing', 'past_due', 'canceled'). */
  appStatus?: string;
  /** Whether the app is available on the desktop (non-cloud) platform. */
  onDesktop?: boolean;
  /** Platform apps only: public pages on the app origin (see Public pages). */
  publicPages?: PublicPage[];
  /** Platform apps only, honored from the app owning '/': the site's title, blurb, docs link, redirects, image, feeds and organization. */
  site?: {
    title?: string;
    blurb?: string;
    docsUrl?: string;
    /** The snapshot, in the build output, served with a 404 on paths nothing serves: 'pages/404.html'. */
    notFound?: string;
    /** Old URLs answered with a 301 to one of your pages, query string kept. */
    redirects?: { from: string; to: string }[];
    /** The link-preview image of pages that declare none (same forms as a page's image). */
    image?: string;
    /** Atom feeds of the dated pages under a prefix: { path: '/blog/feed.xml', prefix: '/blog/', title: 'Blog' }. */
    feeds?: { path: string; prefix: string; title: string }[];
    /** The organization the site belongs to: its Organization JSON-LD, with the @id `${url}#organization`. */
    organization?: { name: string; url: string; logo?: string; description?: string; sameAs?: string[] };
  };
}
```

### Public pages (platform apps)

The server builds the app origin's public page map from the `publicPages`
and `site` sections of published platform apps' manifests. A build can ship
both sections in `app-manifest.json` at the root of its output, next to the
page snapshots; the server reads that file in preference to the registered
manifest. Both sections are optional and append-only: fields are never
repurposed or removed, and the server ignores keys it does not know, so an
older server accepts a newer manifest.

```typescript
interface PublicPage {
  /** One exact path: '/pricing'. */
  path: string;
  /** The page title (at most 300 characters). */
  title: string;
  /** The page description (at most 1000 characters). */
  description?: string;
  /** Default true. false marks the page unlisted: not meant to be advertised or indexed. */
  listed?: boolean;
  /** The document crawlers get, inside the app's build output, e.g. 'pages/pricing.html'. */
  snapshot?: string;
  /** Server data the page names: 'plans' (this app's plans), 'plans:<appId>' or 'app:<appId>'. */
  data?: string[];
  /** The link-preview image: an https URL, a root path, or a path in the build output ('og/pricing.png'). */
  image?: string;
  /** When the page was first published, 'YYYY-MM-DD' or an RFC 3339 date-time: makes it an article. */
  published?: string;
  /** When the page last changed, in the same forms; never earlier than published. */
  modified?: string;
  /** At most 5 authors, each a name (at most 300 characters) and an optional https URL. */
  authors?: { name: string; url?: string }[];
}
```

Rules, enforced when a version is published to the public store rung (the
publish fails with a message naming the field):

- Only platform apps (ids in the `rocketride` developer namespace; on OSS
  that is every app, since every OSS app id is `rocketride.<name>`) may
  declare `publicPages`, and only a root app (`RR_PUBLIC_ROOT_APPS`, default
  `rocketride.home`) may declare pages. `site` goes with the `/` page: a
  platform app that declares `site` without declaring `/` is refused, and a
  third-party app's `site` is ignored, since it can never take effect.
- `path` is absolute and lowercase, with no query, fragment, trailing slash,
  empty or dot segment. Each segment uses only `a-z`, `0-9`, `-`, `.`, `_` and
  `~`, so `/café` and `/caf%C3%A9` are refused. Wildcard pages are not
  supported.
- Paths under a root route the engine serves itself (`/api`, `/apps`, `/auth`,
  `/mcp`, `/shell`, `/status`, `/task`, `/.well-known` and the rest of the
  engine's routes) or the three crawler files (`/sitemap.xml`, `/robots.txt`,
  `/llms.txt`) are rejected, as is a path a server route already serves, or one
  another published platform app already claims (first claim wins; unpublishing
  releases it).
- Each `data` entry is `plans`, `plans:<appId>` or `app:<appId>`, and a page
  names each source (`plans`, `app`) at most once.
- `snapshot` and `site.notFound` must be a relative `.html` path that exists
  in the built version, at most 2 MiB.
- `image` and `site.image` are an `https://` URL, a root path (`/apps/...`,
  never `//`) or a relative path inside the build output, with no empty or dot
  segment, at most 2048 characters.
- `published` and `modified` are a real date (`2026-11-09`) or an RFC 3339
  date-time with an offset (`2026-11-09T10:00:00Z`, at most `±23:59`) that
  stays within years 1 to 9999 in UTC. A date alone means midnight UTC, and
  `modified` may not be earlier than `published`.
- `authors` holds at most 5 entries, each with a non-empty `name` and, if
  given, an `https://` `url`.
- No text or URL field may hold a lone surrogate (U+D800 to U+DFFF, half of a
  UTF-16 pair, as a string cut through an emoji leaves), which UTF-8 cannot
  carry.
- `site.docsUrl` must be an `https://` URL, with `<`, `>`, `"`, `'` and
  `` ` `` percent-encoded.
- `site.redirects` (at most 100): each `from` is one exact path in the `path`
  grammar, except that a trailing slash is allowed (`/master-saas-agreement/`);
  it may not be reserved, and neither it nor its slash twin (`/x` and `/x/`)
  may be a server route or a page any published app serves; it appears once.
  List both forms of an old URL to redirect both. Each `to` is the exact path
  of one of the manifest's own pages.
- `site.feeds` (at most 5): each `path` is one exact path in the `path` grammar
  ending in `.xml`; it may not be reserved, and neither it nor its slash twin
  may be a page any published app serves, a redirect's `from` or a server
  route; it appears once. `prefix` is a page path ending in `/` (`/blog/`, or
  `/` for every page), and `title` a non-empty string of at most 300
  characters.
- `site.organization` needs a non-empty `name` (at most 300 characters) and an
  `https://` `url`; `logo` is an `https://` URL, `description` at most 1000
  characters, and `sameAs` a list of at most 20 `https://` URLs.

Until a published platform app contributes a valid page, the page map holds
the server's built-in page list instead. A published app whose storage cannot
be read keeps the pages of its last readable build while the server runs;
after a restart it has none until its storage can be read again. Kept pages
still compete with other apps' claims under the same first-claim rule.

A server without `RR_APP_URL` is not the public site: its `/robots.txt`
disallows all crawling and `/sitemap.xml` and `/llms.txt` answer `404`, so
search engines do not index its pages. Set `RR_APP_URL` to the public origin
to make published pages indexable; a server that serves published pages
without it logs a warning once.

The server answers `GET` and `HEAD` on each page with the shell's document
(the route's prerendered capture when the shell build carries one, else
`index.html`), its head carrying the page's `title`, `description`, a
canonical URL on `RR_APP_URL`, and `noindex` for an unlisted page.
Crawlers (search, AI and link-preview bots, by user agent) get the page's
`snapshot` instead, read from the production version's build output, with the
same head. A page without a snapshot, or whose snapshot cannot be read or
rendered, serves crawlers the shell's document; so does a stored snapshot over
2 MiB, which the server never reads.

Every page's head, for people and crawlers alike (link-preview fetchers do
not always say they are bots), also carries `og:site_name` (`site.title`),
`og:type` and a Twitter card. A page with `published` is an `article`, with
`article:published_time` and `article:modified_time` (`modified`, else
`published`); any other page is a `website`. `og:image` is the page's `image`,
else `site.image`, and asks for the large card (`summary_large_image`, else
`summary`). A snapshot's own hand-written `og:type`, `og:site_name`,
`og:image`, `twitter:card`, `article:published_time` and
`article:modified_time` tags are removed (as are its title, description,
canonical, robots, `og:title`, `og:description` and `og:url`), so the page's
`image` and `site.image` are the only source of `og:image`. A snapshot's own
`twitter:image` and `twitter:image:alt` are removed too, so X/Twitter falls back
to that `og:image`. An `https://` image is used as declared; a root path is made
absolute with `RR_APP_URL`; a relative path is a file of the declaring app's
build output, served from its production version
(`<RR_APP_URL>/apps/<appId>/v<N>/<path>`). Without `RR_APP_URL` only an
`https://` image is used.

Crawlers also get a `BlogPosting` (JSON-LD) for each page with `published`:
its `headline` (the title without a trailing ` | <site.title>`),
`description`, `datePublished`, `dateModified`, `image`, `mainEntityOfPage`
(the canonical URL), each author as a `Person`, and the site's organization
as `publisher`, also the `author` of a page without authors. That
organization is a reference to the `site.organization` node by its `@id`
when one is declared, else an organization named after `site.title`, on the
`RR_APP_URL` origin. Crawlers get the `site.organization` node (an
`Organization` with the declared fields and the `@id`
`<url>#organization`) on `/` and on every page with `published`, so the
reference resolves on the page itself; `/` also carries a `WebSite` node for
the `RR_APP_URL` origin, published by that organization.

A snapshot is a template with exactly three kinds of tag, each on one line:
`{{name}}` and `{{a.b}}` insert a value, HTML-escaped; `{{#name}}...{{/name}}`
repeats its content for each item of a list, enters an object, and renders
nothing for an absent, empty or false value. Sections nest at most 16 deep.
There is no `{{.}}`: a list item that is not an object adds no names, so a tag
inside its section reads the enclosing values (`{{b}}` inside `{{#a}}` over
`["x"]` renders the outer `b`).
Any `{{...}}` or `{{{...}}}` on one line, with at most 128 characters and no
other brace between the braces, is a tag, including inside `<script>` and
`<style>`; only a `{{` without such a closing `}}` stays as text. A tag of any
other kind renders nothing, as does a tag naming a value the server does not
provide. Escaping makes a value safe in HTML text and in quoted attributes that
are not URLs; it does not make a value safe in a URL attribute (`href`, `src`),
an event handler, `style`, `<script>` or an unquoted attribute, so only
server-derived URLs such as `{{assets}}` belong there. `{{assets}}` is the URL
of the version's build output, `/apps/<appId>/v<N>`, so a snapshot references
its images as `{{assets}}/seo-assets/logo.svg`, served from the same version it
was read from. The shell's own document is never treated as a template.

A page's `data` entries add server data to its snapshot, each under its source
name whatever its argument:

- `plans` and `plans:<appId>`: `{{#plans}}...{{/plans}}` iterates the plans of
  the declaring app or of the named app, each
  `{id, name, price, currency, period, features[]}`, with `price` a decimal
  string such as `29` or `29.50` (the server accepts a string, an integer or a
  decimal, never a float) and `currency` an upper-case code such as `USD`.
- `app:<appId>`: `{{#app}}...{{/app}}` holds `{name, description, url}`. `url` is
  the app's subdomain URL; it is empty until subdomain routing ships, so put a
  link to it inside `{{#url}}...{{/url}}`, which renders only when it is set.
  Name and description are store text, safe only where escaping makes them
  safe.

A named app contributes only while anonymous store visitors can see it: its
public listing is live, it requires no permissions, and its manifest does not
say `public: false`. Otherwise `plans` is empty and `app` is absent. Crawlers
also get JSON-LD built from the same data: a `SoftwareApplication` for `app`,
and a `Product` with an `Offer` for each plan whose price is a plain decimal
number (ASCII digits) and whose currency is a three-letter ISO 4217 code. A
price change (`invalidate('plans')` from the billing layer) or a deployment
change of an app a page names takes effect on the next crawl; other servers
pick it up within five minutes. A crawler response that carries this data is
sent `public` with a `max-age` of what remains of those five minutes, so no
cache keeps it longer; one rendered while that data changed is sent
`private, no-cache`. Other rendered snapshots are `public, max-age=3600`, and
every page response carries `Vary: User-Agent`. When the data cannot be read,
crawlers get the page without it.

`/sitemap.xml` and `/llms.txt` list the listed pages, and `/llms.txt` takes
its heading, blurb and docs link from `site`; redirects never appear in
either. Each sitemap entry's `<lastmod>` is the date of the page's `modified`,
else `published`; a page with neither has no `<lastmod>`, since a deploy is
not a content change. In
`/llms.txt`, a page whose parent path (`/blog` for `/blog/x`) is a listed page
is listed in that parent's section, headed by the parent's title without a
trailing ` | <site.title>`, with dated pages newest first and the rest by
path; every other page is under `## Pages`, by path.

A server with `RR_INDEXNOW_KEY` (8 to 128 letters, digits and `-`) and an
`https://` `RR_APP_URL` serves the key at `/<key>.txt` and, whenever the page
map changes, submits to IndexNow, which shares them with Bing and the other
participating search engines, the listed pages that are new or whose content
changed (a field of the page, or its snapshot's bytes; a new version alone
is no change) and the pages that were listed and are now gone or unlisted.
Without both settings it serves no key file and submits nothing. The pages
of an app missing from the page map altogether (unpublished, made
non-public, or skipped for a moment because its storage could not be read)
are not submitted as removed: a transient storage error must not look like
a removal.

Each feed in `site.feeds` answers `GET` and `HEAD` on its `path` with an Atom
1.0 document (`application/atom+xml`): the listed pages strictly under its
`prefix` that declare `published`, newest first, at most 50. An entry carries
the page's canonical URL, its title without a trailing ` | <site.title>`,
`published`, `updated` (`modified`, else `published`; a date alone is
midnight UTC), its description as the summary and its authors; the feed's
own author is `site.title`. Like the sitemap, a feed answers `404` without
`RR_APP_URL`. The prefix page and every page under it link to the feed from
their head (`<link rel="alternate" type="application/atom+xml">`).

`GET` and `HEAD` on a redirect's `from` answer `301` with
`Location: <to>?<query>`, and on `/x/` answer `301` to `/x` when `/x` is a
page (query kept). Any path that is neither a page, a redirect nor a server
route answers `404`. A browser or crawler (a `GET` or `HEAD` that accepts
HTML) gets the server's not-found page with it, which links home and to
sign-in; paths under `/api`, `/task`, `/mcp` and `/.well-known`, and API
clients, get the plain `404`. With `site.notFound` declared, a `GET` or `HEAD`
on such a path (outside those prefixes) answers `404` with a page titled
`Page not found | <site.title>`, `noindex`, no canonical URL and
`Cache-Control: private, no-cache`: crawlers get the `site.notFound` snapshot,
rendered like a page's (`{{assets}}` included), and people get the shell's
`index.html`, so your app renders its own not-found view. Without
`site.notFound`, the server's own not-found page serves instead.

### Settings

Apps can declare runtime settings (API keys, config values) that the shell manages. The declaration lives under `appManifest.contributes.configuration` — the exact `contributes.configuration` shape from the VSCode extension manifest specification, with setting keys dotted and prefixed with the app id:

```json
{
  "appManifest": {
    "contributes": {
      "configuration": {
        "title": "My App",
        "properties": {
          "mycompany.myApp.apiKey": {
            "type": "string",
            "description": "Your API key for the external service",
            "required": true
          }
        }
      }
    }
  }
}
```

Each property is a `SettingSchema` (`type`, `default`, `description`, `enum`, `required`, ...). Display labels derive from the setting key, VSCode-style — there is no label field (`apiKey` renders as "Api Key").

Settings are:
- Rendered in the shell's Settings overlay (grouped by app)
- Persisted to `.workspace/settings.json`
- Available to your app via `useWorkspace().settings`, access as `settings['mycompany.myApp.apiKey']` (effective values: declared defaults overlaid with the user's overrides)

The shell contributes its own **General** section (keys under `rocketride.general.*`), which always appears first in the Settings overlay. Its keys are reserved — an app redeclaring one is ignored. `rocketride.general.sidebar` (`default` | `vscode` | `cursor` | `rocketride`, default `default`) picks the sidebar layout for every app: `default` defers to each app's declared `sidebarMode`, any other choice overrides it. `vscode`/`cursor` take effect only on apps that declare `sidebarViews`; apps with a classic `sidebar` node keep the classic column.

---

## The App Descriptor

The runtime descriptor your app exports. Loaded lazily when the user first activates your app.

```typescript
interface AppDescriptor {
  id: string;                              // Must match manifest id
  name: string;                            // Display name
  icon?: React.ReactNode;                  // Icon in app switcher
  branding: ShellBrandingConfig;           // Sidebar header branding

  /** The app's ONE mount point — rendered raw in the client area. Required. */
  app: React.ComponentType<ShellAppProps>;

  /** How the app would like the shell sidebar to open when it activates. */
  sidebar?: 'expanded' | 'collapsed';

  /** Optional cross-app component catalog. Never mounted by the shell. */
  components?: {
    [key: string]: React.ComponentType<any>;
  };

  /** Dev-tool mounts — see "Dev Tools" below. Optional; hosted workbenches
      mount these directly instead of booting the full `app`. */
  devToolFrame?: React.ComponentType<DevToolProps>;
  devToolSidebar?: React.ComponentType<DevToolProps>;

  /** First-party apps only: the `app` value stamped on telemetry instead of
      `id`. See "Telemetry" below. */
  telemetryId?: string;
}
```

- **`app`** is the single component the shell mounts in the client area; the app composes its own layout inside (columns, sidebar, status bar) with `<AppLayout>`. It is **required** even for apps that are primarily dev tools — a tool with no meaningful full-screen form still declares a minimal mount
- **`sidebar`** lets an app ask for the shell sidebar collapsed on activation; absent means no opinion
- **`components`** entries (e.g. `Canvas`, `Toolbar`, `DataGrid`) are never mounted by the shell but are loadable by other apps via `useAppComponent()`
- **`devToolFrame`** / **`devToolSidebar`** are the dev-tool mount points (see [Dev Tools](#dev-tools))

### ShellBrandingConfig

```typescript
interface ShellBrandingConfig {
  appName: string;                 // Sidebar header text
  logo?: React.ReactNode;          // Expanded sidebar logo
  logoCollapsed?: React.ReactNode; // Collapsed sidebar logo
  iconDark?: React.ReactNode;      // Icon for dark palette (light-colored)
  iconLight?: React.ReactNode;     // Icon for light palette (dark-colored)
  icon?: React.ReactNode;          // Generic fallback icon
  welcomeLogo?: React.ReactNode;   // Welcome/loading screen logo
  welcomeTitle?: string;           // Welcome screen title
  welcomeSubtitle?: string;        // Welcome screen subtitle
}
```

**Icon resolution order**: the shell picks the best icon for the sidebar header:
1. `iconDark` / `iconLight` (matched to the active palette mode)
2. `icon` (generic branding icon)
3. Manifest `icon` URL (from `package.json`)
4. 2-letter monogram fallback

Pre-built theme-aware SVGs are available in `shared/assets/rocketride/`:
- `rocketride-dark.svg`: light body (`#E0DDF0`) for dark backgrounds
- `rocketride-light.svg`: dark body (`#1E1A34`) for light backgrounds
- `rocketride.svg`: `currentColor` body, CSS-controlled

---

## Shell Props: What Your App Receives

### ShellAppProps (your App component)

```typescript
interface ShellAppProps {
  /** Whether the RocketRide WebSocket is currently connected. */
  isConnected: boolean;
  /** Authenticated user identity, or null when not logged in. */
  identity: ConnectResult | null;
}
```

---

## Screen Zones

| Zone | Owner | Content |
|------|-------|---------|
| **Sidebar** | Your `app` component's layout (`AppLayout`) | Classic column for a `sidebar` node; activity rail + panel when the app declares `sidebarViews` (app icon and name in the panel header, your content in the panel, account footer on the rail) |
| **Client Area** | Your `app` component | Whatever your app renders |
| **Debug Panel** | Shell (ALT+D toggle) | Live event log, postMessage traffic |
| **Status Bar** | Shell | Connection status, app name, ready state |
| **Overlays** | Shell | Account, Billing, Settings (triggered from sidebar footer) |

If your app's layout renders no sidebar, the client area gets the full window width.

**Sidebar chrome.** The chrome follows the declaration. A plain
`sidebar={content}` node renders the classic single column (which iconifies
when collapsed). Declaring `sidebarViews` (one entry per rail icon; see
`SidebarViewContainer`) unlocks the VS Code-style frame instead: a fixed
activity rail beside a resizable panel holding your content. There,
collapsing closes the panel; the rail and account footer never disappear,
and your content is never asked to render an iconified form of itself. An
existing menu can be projected onto the rail with `viewsFromMenu(menu)` —
an explicit opt-in, never applied automatically. `sidebarMode: 'rocketride'`
opts a view-declaring app back into the classic column; compact (mobile)
widths always render a drawer. The user's **General > Sidebar** setting
(`rocketride.general.sidebar`) overrides `sidebarMode` whenever it is set to
anything other than `default`; on `default` the app's declaration applies.
The `vscode`/`cursor` choices apply only to apps that declare `sidebarViews`
— a classic sidebar is never shoehorned onto the rail.

---

## Shell Hooks & APIs

`rocketride/app-sdk` is a subpath export of the `rocketride` package: at build
time it gives your app types and IntelliSense, and at runtime Module
Federation's shared singleton mechanism replaces its stubs with the real
implementations from the shell host itself, published as the `shell`
package, which is why in-workspace code generated by the app scaffold
imports the same hooks directly from `'shell'`.

Import everything from `'rocketride/app-sdk'`:

```typescript
import { useShellConnection, useShellApiConfig, useWorkspace, connectionManager } from 'rocketride/app-sdk';
```

### Telemetry

The shell owns the one product-telemetry transport (keys, consent, delivery).
The platform serves these to it at runtime; your app never carries any of them.
Your app receives a bound reporter and simply calls it:

```typescript
import { useReport } from 'shell';

const report = useReport();
report('chat:message_sent', { length: 42 });
```

The shell binds the reporter to your app. Every event is stamped with an `app`
property, last, so your props cannot overwrite it. There is nothing to
initialise or configure. The stamped value is your descriptor's `telemetryId`
when the app is first-party (id `rocketride` or starting `rocketride.`) and the
alias is valid. Otherwise it is your app's `id`. A valid alias matches
`^[A-Za-z0-9._-]{1,128}$`, is not `shell` (reserved for the shell's own events)
and is not another registered app's id. An alias that fails these checks falls
back to the id with no warning. The alias is chosen once on the descriptor,
never per event. Events the analytics SDK generates on its own (`$pageleave`,
`$web_vitals`, `$autocapture`, `$exception` and the like) carry no `app`.
`$host` and `$pathname` do not identify the app either, because the URL does
not change on an app switch.

Events sent through `getConsentedCapture(...).report` are tagged internally as
attributed. A tagged event is dropped at send time unless consent is still
accepted and no browser privacy signal (DNT or GPC) is on. Without consent (the
cookieless instance) it is always dropped. Ordinary events are never dropped
because of their property names, and an app cannot set the tag itself. Event
names are your app's own taxonomy (`object:action` by convention); document
them beside your call sites. `useConsent()` exposes the visitor's
analytics-consent state read-only (plus `openSettings()` to the Privacy
section) for apps that gate their own captures on it. With no telemetry
configured on the server (self-hosted), every call is a silent no-op.

### Connection

| Hook/Function | Returns | Purpose |
|---------------|---------|---------|
| `useShellConnection()` | `{ client, isConnected, statusMessage }` | Access the RocketRide WebSocket client |
| `useShellApiConfig()` | `ShellApiConfig` | Read runtime config (API URLs, keys, user settings) |
| `getClient()` | `RocketRideClient \| null` | Non-React access to the client singleton |

### Auth

| Hook | Returns | Purpose |
|------|---------|---------|
| `useAuthUser()` | `ConnectResult \| null` | Current authenticated user identity |
| `useLogout()` | `() => void` | Trigger logout |
| `useSubscriptions()` | `{ desktopApps, isOnDesktop(appId), getStatus(appId) }` | User's desktop apps and subscription state |

### Workspace

| Hook | Returns | Purpose |
|------|---------|---------|
| `useWorkspace()` | `IWorkspaceContext` | Access workspace state and dispatch |

The workspace context provides:
- `seeded`: True once pre-auth default state has been populated (before connection)
- `loaded`: True once persisted workspace state has been read from disk (after connection)
- `prefs`: Current app preferences (theme, active view, etc.)
- `appState`: Opaque per-app state (used by Documents)
- `settings`: User-configured settings
- `activeAppId`: Current app ID
- `appManifest`: All registered apps
- `appLoading`: Whether the active app is currently loading
- `loadedApps`: Map of already-loaded app descriptors (for cross-app component loading)
- `loadApp(appId)`: Trigger lazy loading of an app's descriptor
- `updateAppState(updater)`: Update per-app state — pass a function receiving the previous state and returning the next
- `updateSetting(key, value)`: Update a single setting
- `updatePrefs(patch)`: Update workspace preferences
- `themeOptions`: Available theme choices
- `setTheme(themeId)`: Switch the active theme
- `dispatch(action)`: Update prefs or switch apps
- `emit(event, payload)` / `on(event, handler)`: Event bus (delegates to connectionManager)

### Workspace Lifecycle: `seeded` vs `loaded`

The workspace has a two-phase startup:

1. **Seeded** (`seeded = true`, `loaded = false`): The workspace has been populated with hardcoded defaults (default prefs, empty appState, empty settings). This happens immediately, before authentication or WebSocket connection. The Shell renders at this point so unauthenticated apps (e.g. home/landing page) can display.

2. **Loaded** (`seeded = true`, `loaded = true`): The WebSocket is connected and persisted state has been read from disk (`.workspace/global.json`, per-app workspace files, `settings.json`). Persisted prefs, appState, and settings overwrite the seeded defaults. Debounced persistence (auto-save) only activates after this point.

**What this means for your app:**

- The **Shell** renders as soon as `seeded` is true. It is then up to each app to decide whether it needs to wait for `loaded`.
- **Unauthenticated apps** (`authenticated: false`) can render immediately on seeded state, they receive `isConnected=false` and `identity=null` and should be designed to work with those values.
- **Authenticated apps** that depend on persisted settings (API keys, saved state) should gate on `loaded` before rendering data-dependent UI:

```typescript
const { loaded, settings } = useWorkspace();

if (!loaded) return <div>Loading workspace…</div>;

// Safe to read persisted settings here
const apiKey = settings.MY_API_KEY;
```

- **Persistence is safe**: debounced saves to disk only fire when `loaded` is true, so seeded defaults are never accidentally written over persisted data.

---

## The Connection Manager (connectionManager)

A typed, module-level event bus singleton. Works from React components, hooks, plain functions, anywhere.

### Basic usage

```typescript
import { connectionManager } from 'rocketride/app-sdk';

// Emit an event
connectionManager.emit('shell:loginRequest', { appId: 'rocketride.myApp' });

// Subscribe to an event (returns unsubscribe function)
const unsub = connectionManager.on('shell:connected', () => {
  console.log('Connected!');
});

// Later: unsubscribe
unsub();
```

### In a React component

```typescript
useEffect(() => {
  const unsub = connectionManager.on('shell:event', ({ event }) => {
    console.log('Server event:', event);
  });
  return unsub; // cleanup on unmount
}, []);
```

### Defined events

| Event | Payload | Direction | Description |
|-------|---------|-----------|-------------|
| `shell:connected` | `{}` | Shell → Apps | WebSocket connection established |
| `shell:disconnected` | `{ reason: string; hasError: boolean }` | Shell → Apps | WebSocket connection lost |
| `shell:login` | `{ user: ConnectResult }` | Shell → Apps | User authenticated |
| `shell:logout` | `{}` | Shell → Apps | User logged out |
| `shell:loginRequest` | `{ appId?: string; register?: boolean; auto?: boolean; signupProperties?: SignupProperties }` | Apps → Shell | Request OAuth login (optionally targeting an app); `register` marks a sign-up intent; `auto` is set only by the shell's own auth gate, apps leave it unset |
| `shell:logoutRequest` | `{}` | Apps → Shell | Request logout |
| `shell:switchApp` | `{ appId: string }` | Apps → Shell | Switch the active app |
| `shell:subscribe` | `{ app: AppManifestEntry, plan?: CheckoutPlan }` | Apps → Shell | Open subscription checkout for an app; optional `plan` preselects a tier and skips the picker (straight to payment) |
| `shell:myApps` | `{}` | Apps → Shell | Navigate to My Apps |
| `shell:accountUpdate` | `ConnectResult` | Server → Shell | Server-pushed account/subscription change |
| `shell:sidebarCollapsing` | `{}` | Shell → Apps | Sidebar is collapsing (for layout adjustments) |
| `shell:themeChange` | `{ tokens: Record<string, string> }` | Shell → Apps | Theme CSS tokens changed |
| `shell:statusChange` | `{ message: string \| null }` | Shell → Apps | Transient status bar text changed |
| `shell:event` | `{ event: unknown }` | Server → Apps | Raw server event forwarded from WebSocket |
| `shell:telemetry` | `TelemetryFact` (`{ event: string; props: Record<string, unknown>; ts: number; id: string }`) | Shell → Apps | DEPRECATED, never emitted (the shell owns the telemetry transport). Typed only for frozen-floor compatibility; see [Telemetry facts](#telemetry-facts) |
| `shell:appsUpdated` | `{ apps: ShellAppEntry[] }` | Shell-internal | App list updated |
| `shell:manifestRefresh` | `{ source: string }` | Shell-internal | App manifest re-fetched |
| `shell:openOverlay` | `{ id: 'account' \| 'settings' \| 'environment' }` | Shell-internal | Open a shell overlay |
| `shell:unsubscribe` | `{ appId: string }` | Shell-internal | Cancel an app subscription |
| `shell:viewActivated` | `{ viewId: string }` | Shell-internal | A shell view became active |

The events marked **Shell-internal** exist only in the shell package's internal event map — they are not part of the `ShellEventMap` exported from `rocketride/app-sdk`, so external apps cannot emit or subscribe to them type-safely.

### Telemetry facts

The shell reports its own product facts on its own reporter, stamped with app `shell`. No app forwards them. They are `auth:start`, when it starts the OAuth redirect, and `auth:complete`, when the callback resolves an identity, with the account's new-user flag `is_new`, its waitlist state `waitlisted`, and `duration_ms`, the OAuth round trip in milliseconds from the redirect to the callback (null when it is not known). `auth:start` always carries `is_authed: false` and `auth:complete` always carries `is_authed: true`, whatever the state of the page load that sends them. The consent banner's `consent:shown`, `consent:decision` and `consent:handoff` events are the shell's too. A fact raised before the analytics SDK has started waits in the shell's queue, which is mirrored to the tab's sessionStorage, so it is replayed with its original time on the next page load (the OAuth callback, for `auth:start`) if this one ends first.

`connectionManager.drainTelemetry()` and the `shell:telemetry` event are deprecated. Nothing feeds them any more: `drainTelemetry()` always returns an empty list and `shell:telemetry` is never emitted. They stay typed only for compatibility with the frozen v8/v9 floor. Do not subscribe to them or forward from them; your own events go through `useReport()` as described in [Telemetry](#telemetry).

### Extending the event map

Add custom events via TypeScript module augmentation:

```typescript
declare module 'rocketride/app-sdk' {
  interface ShellEventMap {
    'myapp:dataUpdated': { recordId: string; timestamp: number };
    'myapp:exportComplete': { fileUrl: string };
  }
}

// Now type-safe:
connectionManager.emit('myapp:dataUpdated', { recordId: '123', timestamp: Date.now() });
```

### Debug logging

All events are automatically captured in a circular buffer (500 entries) visible in the Debug Panel (ALT+D).

```typescript
import { getDebugLog, clearDebugLog, onAny } from 'rocketride/app-sdk';

// Get all captured events
const log = getDebugLog(); // DebugLogEntry[]

// Listen to ALL events (for custom logging)
const unsub = onAny((event, payload) => {
  console.log(`[${event}]`, payload);
});
```

---

## The Documents System

A VS Code-style document model for apps that manage files/documents. **Completely opt-in**, simple apps don't need it.

`Documents` is an **instantiable class**: your app creates it, owns it, passes it where needed. The shell never sees it.

### Core concepts

| Concept | Description |
|---------|-------------|
| **Document** | One per URI. Holds content in memory. Tracks dirty state and version. |
| **Editor** | A view onto a Document. Independent viewport state (scroll, cursor). Multiple editors can view the same document. |
| **EditorGroup** | A pane container. Holds an ordered list of editors. Supports horizontal/vertical splits. |

### Creating an instance

Create a `Documents` instance in your App component, passing an `IVirtualFileSystem`:

```typescript
// src/docs.ts — shared instance for your app
import { Documents } from 'rocketride/app-sdk';
import type { IVirtualFileSystem } from 'rocketride/app-sdk';

let _docs: Documents | null = null;

export function getDocs(): Documents {
  if (!_docs) throw new Error('Documents not initialised');
  return _docs;
}

export function createDocs(vfs: IVirtualFileSystem): Documents {
  _docs = new Documents(vfs);
  return _docs;
}

export function destroyDocs(): void {
  _docs?.destroy();
  _docs = null;
}
```

```typescript
// src/MyApp.tsx
import { createDocs, destroyDocs } from './docs';

const MyApp: React.FC<ShellAppProps> = () => {
  const { client } = useShellConnection();

  useEffect(() => {
    const vfs: IVirtualFileSystem = {
      list:   (dir) => client.fsListDir(dir),
      read:   (path) => client.fsReadJson(path),
      write:  (path, content) => client.fsWriteJson(path, content),
      rename: (old, new_) => client.fsRename(old, new_),
      delete: (path) => client.fsDelete(path),
      mkdir:  (path) => client.fsMkdir(path),
    };
    createDocs(vfs);
    return () => destroyDocs();
  }, [client]);

  return <MyAppInner />;
};
```

### Using the instance (call methods from anywhere)

```typescript
import { getDocs } from './docs';

// Open a file
await getDocs().openDocument('path/to/file.txt');

// Create a new document with initial content
const uri = getDocs().createDocument(undefined, { key: 'value' });

// Update content (any serializable value — stored as-is)
getDocs().updateContent(uri, { key: 'updated' });

// Save to disk
await getDocs().saveDocument(uri);
```

All operations are methods on the `Documents` instance:

| Method | Description |
|--------|-------------|
| `openDocument(uri, groupId?)` | Open a file (reads from VFS if not already open) |
| `createDocument(groupId?, content?)` | Create a new untitled document |
| `closeEditor(editorId)` | Close an editor (disposes doc if last clean ref) |
| `updateContent(uri, content)` | Update in-memory content (marks dirty) |
| `saveDocument(uri)` | Write to disk via VFS (marks clean) |
| `revertDocument(uri)` | Re-read from disk (replaces content) |
| `splitGroup(groupId, orientation)` | Split an editor group |
| `moveEditor(editorId, targetGroupId)` | Move editor between groups |
| `closeGroup(groupId)` | Close all editors in a group |
| `setActiveEditor(groupId, index)` | Activate an editor within a group |
| `setActiveGroup(groupId)` | Focus a group |
| `openStaticDocument(uri, label, content?, groupId?)`\* | Open a read-only static document with a display label |
| `splitGroupWithDocument(groupId, orientation)`\* | Split a group, moving the active document to the new pane |
| `updateSplitSizes(splitNodeId, sizes)`\* | Update the sizes of a split layout node |
| `updateEditorViewport(editorId, patch)` | Merge an editor's scroll position and cursor coordinates |
| `updateEditorViewState(editorId, viewState)`\* | Persist an editor's opaque view state (the app owns its shape) |
| `getState()` | Read state without subscribing |
| `getDocument(uri)` | Get a single document by URI |
| `destroy()` | Clean up the instance |

\* Available on the `shell` package's `Documents` implementation but not yet declared on the `rocketride/app-sdk` `Documents` typing — external TypeScript builds referencing them will fail to type-check.

### React subscription

```typescript
import { getDocs } from './docs';

const MyComponent: React.FC = () => {
  const state = getDocs().useStore(); // re-renders on any state change

  const activeGroup = state.groups[state.activeGroupId];
  const activeEditorId = activeGroup?.editorIds[activeGroup.activeEditorIndex];
  const activeEditor = activeEditorId ? state.editors[activeEditorId] : undefined;
  const activeDoc = activeEditor ? state.documents[activeEditor.documentUri] : undefined;

  return <div>{activeDoc?.uri ?? 'No document open'}</div>;
};
```

### Sharing across your app's tree

Components in different parts of your app's layout (e.g. your editor area and your sidebar) can share the same `Documents` instance via the module-level `getDocs()` function:

```text
MyApp (creates instance)     MySidebar (uses same instance)
     ↓                            ↓
  createDocs(vfs)              getDocs()
     ↓                            ↓
  getDocs().useStore()         getDocs().openDocument(path)
```

### Content type

`Document.content` is `unknown`, the exact object you store is the exact object you get back. No serialization happens inside the Documents class. The VFS handles serialization at the disk boundary.

- Pipeline editor: stores a `PipelineConfig` object
- Text editor: stores a `string`
- Image editor: stores a base64 string or metadata object

---

## The Virtual File System (IVirtualFileSystem)

The single abstraction for all file I/O. Created by the app, passed to both `new Documents(vfs)` and `DocExplorer`.

```typescript
interface IVirtualFileSystem {
  list(dir: string): Promise<{ name: string; type: 'file' | 'dir' }[]>;
  read(path: string): Promise<unknown>;
  write(path: string, content: unknown): Promise<void>;
  rename(oldPath: string, newPath: string): Promise<void>;
  delete(path: string): Promise<void>;
  mkdir(path: string): Promise<void>;
}
```

### Example: RocketRide client VFS

```typescript
const vfs: IVirtualFileSystem = {
  list: async (dir) => {
    const result = await client.fsListDir(`projects/${dir}`);
    return result.entries.map(e => ({ name: e.name, type: e.type }));
  },
  read:   (path) => client.fsReadJson(`projects/${path}`),
  write:  (path, content) => client.fsWriteJson(`projects/${path}`, content),
  rename: (old, new_) => client.fsRename(`projects/${old}`, `projects/${new_}`),
  delete: (path) => client.fsDelete(`projects/${path}`),
  mkdir:  (path) => client.fsMkdir(`projects/${path}`),
};
```

### Example: REST API VFS

```typescript
const vfs: IVirtualFileSystem = {
  list: async (dir) => {
    const res = await fetch(`/api/files?dir=${dir}`);
    return res.json();
  },
  read: async (path) => {
    const res = await fetch(`/api/files/${path}`);
    return res.json();
  },
  write: async (path, content) => {
    await fetch(`/api/files/${path}`, { method: 'PUT', body: JSON.stringify(content) });
  },
  rename: async (old, new_) => {
    await fetch(`/api/files/${old}/rename`, { method: 'POST', body: JSON.stringify({ to: new_ }) });
  },
  delete: async (path) => {
    await fetch(`/api/files/${path}`, { method: 'DELETE' });
  },
  mkdir: async (path) => {
    await fetch(`/api/files/${path}`, { method: 'POST', body: JSON.stringify({ type: 'dir' }) });
  },
};
```

---

## DocExplorer: File Tree Component

A generic file tree panel (like VS Code's EXPLORER). Renders a hierarchical file tree with:

- Directory expand/collapse
- Tree/flat view toggle
- File selection and active highlight
- Inline rename and create
- Context menus (rename/delete)
- Status dots (running/error/warning)
- Optional child items under files (with action buttons)
- Keyboard navigation

```typescript
import { DocExplorer } from 'shell';
import type { DocExplorerConfig, DocEntry } from 'shell';
import type { IVirtualFileSystem } from 'rocketride/app-sdk';

const config: DocExplorerConfig = {
  title: 'My Files',
  extensions: ['.txt', '.md'],
  displayName: (name) => name.replace(/\.(txt|md)$/, ''),
  emptyMessage: 'No files yet',
  createPlaceholder: 'file name',
};

<DocExplorer
  vfs={myVfs}
  config={config}
  entries={entries}
  statuses={statusMap}
  isConnected={isConnected}
  activeFilePath={activeUri}
  onOpenFile={(path) => getDocs().openDocument(path)}
  onFileManage={(action, path, newName) => { /* rename/delete/create */ }}
  onRefresh={() => refreshFileList()}
/>
```

### DocExplorerConfig

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `title` | `string` | (required) | Section header (e.g. "Pipelines", "Photos") |
| `extensions` | `string[] \| null` | `null` | File extensions to filter. Null = show all. |
| `displayName` | `(filename: string) => string` | Strips known extensions | Custom display name formatter |
| `createPlaceholder` | `string` | `'file name'` | Placeholder for inline create input |
| `emptyMessage` | `string` | `'No files'` | Empty state message |

---

## DocTabs: Tab Bar Component

A tab bar UI for a single editor group. Takes a `Documents` instance as a prop.

```typescript
import { DocTabs } from 'shell';
import { getDocs } from './docs';

<DocTabs
  docs={getDocs()}
  groupId={groupId}
  onDirtyClose={(editorId, uri) => {
    // Show "save changes?" dialog
  }}
/>
```

Features:
- Tab per editor in the group
- Dirty indicator (dot)
- Close button (on hover)
- Active tab highlight
- Calls `docs.setActiveEditor()` / `docs.closeEditor()` on the provided instance

---

## DesktopView: The Shared Desktop Page

`DesktopView` renders the RocketRide desktop content — a time-aware greeting, a rotating quote, and the responsive app-card grid (launch, version switcher, remove/unsubscribe, subscription badges). It is the one desktop implementation shared by the OSS and SaaS home apps; a launcher app renders it and supplies only the app list and chrome (nav, footer, padding).

```tsx
import { DesktopView } from 'shell';     // or getShellApi().DesktopView

<DesktopView
	apps={apps}                            // AppManifestEntry[], pre-filtered/sorted
	style={{ padding: '60px 40px 80px' }}  // host-owned spacing
/>
```

Server interactions (version rails, session overrides, desktop remove, unsubscribe, subscription status) are built in — the component talks to the shell's connection itself. Optional props adjust behavior:

| Prop | Purpose |
|---|---|
| `onLaunch` | Replace the default launch (`shell:switchApp`) |
| `greetingName` / `greetingOverride` | Personalize or pin the greeting |
| `showQuote` | Hide the rotating quote column (default shown) |
| `allowRemove` | Disable the hover X + remove/unsubscribe popover |
| `resolveIcon` | Theme-adaptive icon override per app |
| `adapter` | Override the server operations (`DesktopAdapter`) |
| `popoverBoundarySelector` | Host sticky-header selector for drop-list placement |
| `emptyMessage` | Zero-apps text |

Types: `DesktopViewProps`, `DesktopAdapter`, `DesktopQuote`, `DesktopVersionRow`, `DesktopVersionOverride`. Animations (card cascade, greeting reveal, icon fade) honor `prefers-reduced-motion`. Theming uses the standard `--rr-*` CSS variables.

### Dev Tools

An app can declare itself a **dev tool**: a UI that host workbenches (the VS Code extension, rocket-ui) mount directly as a component — no shell boot, no iframe. Declare the manifest category and the descriptor mount points:

```jsonc
// package.json → appManifest
"categories": ["devTool"]
```

```ts
// AppDescriptor
const MY_TOOL: AppDescriptor = {
	// ...existing fields
	devToolFrame: MyToolSurface,      // the tool's main surface
	devToolSidebar: MyToolSidebar,    // optional panel shown in the host's sidebar
};
```

Both components receive `DevToolProps`:

| Prop | Purpose |
|---|---|
| `channel` | The tool's ONE transport surface to its other mount (frame ↔ sidebar; the mounts may live in isolated documents — VS Code webviews). Three lanes: retained state topics, fire-and-forget events, correlated ops |
| `documents` | On multi-document hosts: `open(docKey, title)` / `close(docKey)` |
| `docKey` / `activeDocKey` | The document key a frame serves / the fronted document a sidebar follows |

There is NO client prop — and none is needed. The realm model in three lines:

1. Every surface runs in a **realm** (the shell page, each VS Code webview, each framework page) attached to the shell bus.
2. Every realm's `useShellConnection().client` is a **real `RocketRideClient`**: the root realm's client owns the socket; every other realm holds a *realm client* whose requests ride the bus to that same socket. There is ONE socket per host process.
3. A tool's sidebar mount (its **controller**) therefore owns *authority*, not transport: it coordinates the tool's genuinely shared state — refcounted resources, single-writer stores, one shared poller — through tool ops, while every mount makes its own engine calls on its own client.

A tool's ops live in a `src/ops/` directory with a fixed three-file layout (see sql-ui and monitor-ui for the reference shape), re-exported by an `ops/index.ts` barrel:

```ts
// ops/types.ts — the tool's COORDINATION protocol, declared ONCE as maps
// extending the shell's base maps (per tool; `host:*` keys are reserved).
// Only shared state belongs here — plain engine calls go through the realm
// client.
import type { ToolOpMap, ToolOpSpec, ToolStateMap, ToolEventMap } from 'shell';

export interface MyOps extends ToolOpMap {
	'myTool.acquire': ToolOpSpec<{ id: string }, MyHandle>; // refcounted — ONE owner realm
}
export interface MyStateMap extends ToolStateMap { records: MyRecord[] }
export interface MyEventMap extends ToolEventMap { save: MyRecord }

// ops/server.ts — the implementations, served by the sidebar CONTROLLER mount.
export function serveMyOps(channel: ToolChannel): () => void {
	const ops = createToolOpServer<MyOps>(channel);
	ops.serve('myTool.acquire', async ({ id }) => acquire(id));
	return () => ops.dispose();
}

// ops/client.ts — the typed calls, used by FRAME mounts.
export function createMyOpsClient(channel: ToolChannel) {
	const call = createToolOpClient<MyOps>(channel);
	return { acquire: (id: string) => call('myTool.acquire', { id }) };
}

// In the frame: engine work on the realm's own client; shared state via ops.
const { client, isConnected } = useShellConnection();
const rows = client ? await client.listTasks({}) : [];
const handle = await createMyOpsClient(channel).acquire(id);
```

**Why two readiness hooks exist.** `useShellConnection().isConnected` is *this realm's* connection truth — the mirrored state of the one socket the realm client rides; gate engine calls on it. `useConnectionReady(channel)` reads the `host:connection` system topic — the **controller realm's** reachability, published by the host (never by a tool) and retained on the channel. Today both describe the same single socket; they stay distinct because hosts are growing *multiple connections* (the VS Code dev/deploy slots — see `host.envSlots`), where "my realm's client can reach the engine" and "the controller's connection is up" stop being the same question. Gate frame↔controller coordination on `useConnectionReady`, engine calls on your own realm's state. `useConnectionReady` is tri-state: `undefined` means no `host:connection` snapshot has arrived yet (unknown — render a waiting state, never a "disconnected" claim), `false` means the host said disconnected, `true` means ready; a plain `if (!ready)` guard treats the initial `undefined` like `false`, which is safe for gating but wrong for *displaying* a disconnect.

There is no theme prop: dev-tool components are themed by the ambient `--rr-*` CSS custom properties of the document they mount into (the active shell theme in a browser; the editor-variable mapping in VS Code) — style exclusively with `var(--rr-*)` tokens. The tab icon hosts show comes from the manifest `icon`; the descriptor is loaded only when the tool is opened.

---

## Cross-App Component Loading

Apps can expose components for other apps to use, and load components from other apps at runtime via Module Federation.

### Exposing components

Add them to your `components` object in the AppDescriptor. They're bundled automatically because they're imported, no extra `exposes` in rsbuild needed.

```typescript
const MY_APP: AppDescriptor = {
  id: 'rocketride.myApp',
  name: 'My App',
  branding: { appName: 'My App' },
  app: MyApp,
  components: {
    // Shell never mounts these, but other apps can access them
    SpecialChart: MySpecialChartComponent,
    DataGrid: MyDataGridComponent,
  },
};
```

Your `rsbuild.config.ts` still only needs one expose:

```typescript
exposes: {
  './AppDescriptor': './src/AppDescriptor.ts',
}
```

When the shell loads your AppDescriptor, all components referenced in `components` are included in the bundle automatically.

### Loading components from another app

Use `useAppComponent()`, it lazy-loads the target app's descriptor if needed and returns the component once available:

```typescript
import { useAppComponent } from 'rocketride/app-sdk';

const MyComponent: React.FC = () => {
  const Chart = useAppComponent('rocketride.otherApp', 'SpecialChart');

  if (!Chart) return <div>Loading...</div>;
  return <Chart data={myData} />;
};
```

The hook:
- Returns `null` while the target app's descriptor is loading
- Triggers a lazy load automatically if the app hasn't been visited yet
- Returns the component once available, no manual loading needed

---

## Theming

The shell manages themes via CSS custom properties. Your app should use `--rr-*` variables for all colors, fonts, and borders.

### Available CSS variables

| Variable | Purpose |
|----------|---------|
| `--rr-bg-default` | Main background |
| `--rr-bg-paper` | Card/panel background |
| `--rr-bg-surface-alt` | Hover/alternate background |
| `--rr-bg-input` | Input field background |
| `--rr-text-primary` | Primary text |
| `--rr-text-secondary` | Secondary/muted text |
| `--rr-text-disabled` | Disabled text |
| `--rr-brand` | Brand/accent color |
| `--rr-border` | Border color |
| `--rr-font-family` | Primary font |
| `--rr-font-family-mono` | Monospace font |
| `--rr-color-success` | Success green |
| `--rr-color-warning` | Warning orange |
| `--rr-color-error` | Error red |

### Responding to theme changes

```typescript
useEffect(() => {
  return connectionManager.on('shell:themeChange', ({ tokens }) => {
    // tokens is a Record<string, string> of all --rr-* values
    console.log('New theme:', tokens['--rr-brand']);
  });
}, []);
```

---

## Build Configuration

See the [Getting Started](#getting-started) section for the complete `rsbuild.config.ts` template.

Key points:
- The MF container `name` is derived automatically from `appManifest.id` in `package.json`
- Always expose `./AppDescriptor` as the single MF entry point
- `rocketride/app-sdk` must be a shared singleton so your app and the shell agree on one instance
- React and react-dom must be shared singletons to avoid duplicate instances

---

For the App Builder loop, see [App Builder](/guides/apps/app-builder).

### Optional signup attribution

`ConnectionManager.startOAuth(register, context)` and `shell:loginRequest` accept optional
`signupProperties` analytics metadata. The shell validates it, carries it across the identity
provider redirect in one of two ways below, consumes it once on the OAuth callback, and passes it in
the PKCE credential through a resolver that rechecks consent, privacy signals and expiry immediately
before the SDK sends authentication. The encoded `cd_` credential uses the wire key
`signup_properties`. Native `auth:start` and `auth:complete` telemetry facts contain no signup
attribution. Missing, expired or invalid context does not stop sign-in. Embedded developer previews
do not touch the host tab's storage.

A consented context is held in tab storage under active analytics consent and never appears in the
identity provider URL. A cookieless context (`consent_state: 'undecided'`) is only for a visitor who
has not chosen yet. Nothing is written to site storage for it: the shell sends it as the OAuth
`state`, base64 JSON `{ v: 1, signup }`, and reads it back on the callback. That state is readable
and unsigned, and like the rest of the authorize URL it stays in the browser's history and reaches
the identity provider's request logs. PKCE prevents forged callbacks, so a forged state can only
change attribution. A consented context is never accepted from the URL.

Version 1 carries `experiment`, `experiment_revision`, `variant_id`, `assignment_id`, `exposure_id`,
`landing_message_revision`, `exposed_at`, `expires_at`, `consent_version: 1`, and `schema_version: 1`,
plus `consent_state` on a cookieless context. Consumers must check `consent_state` before treating a
context as consented. Times are milliseconds since epoch; expiry is fixed at 30 minutes after
exposure. The account service validates its experiment/catalog separately. This context is
untrusted analytics input and must never authorize access or establish account identity.

The consent record is written by the shell's consent banner (`packages/shell/src/telemetry`),
under `localStorage['rr_consent_v1']`. Its shared schema is
`{ v: 1, choice: 'accepted' | 'rejected', at: number }`, where `at` is milliseconds since epoch.
A record is valid up to 365 days old, with at most 60 seconds of future clock skew. A consented
context needs a valid `accepted` record. A cookieless context needs no valid record at all (missing,
malformed or expired reads as undecided), so accepting or rejecting on the banner drops it. DNT or GPC,
or storage that cannot be read, omits either kind. Coordinate any change to this key or schema with
both repositories.
`CloudAuthProvider.signIn()` owns pending signup storage; `startOAuth()` passes validated context
to it.
