Edge / User Admin

Appearance

Local apps ​

The app launcher is Edge's most-used surface. It lists installed webapps with click-through links to launch them.

Two views ​

Overview ​

The default landing (#overview) shows the launcher inline as part of the dashboard. Source: main.ts:389-419.

Each row carries icon, display name, description / package, route, runtime label, and an Open link. An expandable "Route plan" panel below each row shows the full route plan.

Catalog ​

The catalog (#catalog) shows tile cards for apps declaring shells: ["edge"] (or omitting shells, which means all). Source: main.ts:421-475.

Per-tile: icon, display name, description, route, package, shell tags, Open link.

How URLs are computed ​

Source: edge-model.ts:176-181 (appUrl).

ts
appUrl(entry, routeKey) =>
  routeKey ? productAppPath(entry.appName, routeKey) : entry.url || `/apps/${entry.appName}/`
  • If a routeKey is present (Device is paired), the URL is /<routeKey>/<appName>/ — the public Space-path route.
  • Otherwise, the URL is the entry's declared url or the default /apps/<appName>/ current-host route.

The choice between linked-Space URL and current-host URL is the route provenance decision. Per P1.22e, this must be visible — Edge surfaces it via the route plan.

Default app set ​

A standard install ships the following webapps (per STANDARD_APP_ROUTES in edge-model.ts:111-116):

  • Director
  • Chat
  • FlowPad
  • Smithers

Plus the implicit Edge itself, the platform web, and inference-settings. Edge filters out appName === 'web' from the launcher (the platform shell does not appear in the local launcher).

The "primary action" ​

Source: main.ts:357-387 (renderPrimaryActions).

The action panel shows two buttons:

  • Open <first-app> — picks the first app in the launcher (sorted by navOrder then by standard-app order).
  • Connect to HiveCast or Manage devices — depending on link state.

This is the recommended next click on a fresh install: open Director (or whichever app comes first) and start using Matrix.

Route plan diagnostics ​

Per P1.22d (DONE), each app row's route-plan panel shows:

  • URL.
  • appName.
  • Route prefix (e.g., /apps/director/).
  • Gateway (always system.gateway.http).
  • Scope (/<routeKey>/ linked, local otherwise).
  • Route kind (e.g., gateway-resolved-app).
  • Runtime id.
  • Package.
  • Asset source (e.g., system.runtimes.<runtime-id>.http).

If asset source is missing, a warning shows: "/api/apps did not report an assetMount or origin for this route."

Filtering by shell ​

The catalog page filters to entries that declare shells: ["edge"] or have no shell restriction. From main.ts:477-479:

ts
appShells(entry) =>
  Array.isArray(entry.shells) && entry.shells.length > 0 ? entry.shells : ['platform', 'edge']

A package declaring only shells: ["platform"] is filtered OUT of the Edge catalog. This is how matrix-web (the platform shell) does not show up in Edge.

What an "app" is, technically ​

An "app" in Edge's launcher is anything declaring webapp metadata in its matrix.json and currently registered as a runtime with webapp data in system.runtimes. The chain:

  1. Package's matrix.json declares webapp.{appName, routePrefix, displayName, shells}.
  2. Package is loaded as a runtime with --serve.
  3. Runtime registers with system.runtimes carrying its webapp metadata.
  4. Gateway aggregates webapp metadata from all runtimes, exposes as /api/apps.
  5. Edge fetches /api/apps.
  6. Edge renders.

A package that has matrix.json webapp but no running runtime (or wasn't loaded with --serve) is invisible to the launcher.

Empty launcher ​

If /api/apps returns successfully but with an empty apps[] array, Edge renders:

No installed web apps reported /api/apps returned successfully, but the app list was empty.

If /api/apps returns 404 or 5xx:

App inventory unavailableHTTP <status> in <ms>ms. The launcher will not invent shortcuts when /api/apps is missing.

Edge does not invent placeholder rows. Per P1.22b/P1.22e (no silent substitution), the launcher only shows what the gateway reports.

Linked-Space URLs ​

When the Device is paired, app URLs are linked-Space form:

https://hivecast.ai/alt.stories.ghost-stories.funny/director/
https://hivecast.ai/alt.stories.ghost-stories.funny/chat/

These work over the cloud's gateway. The user sees their own apps via the public route, served by the runtime on their own Device through the federated bus.

Target state ​

  • Per-app live health pill — request/reply against the runtime's control mount.
  • In-launcher quick action — restart, reload, view logs.
  • Custom app order — user-configurable.

See also ​

Source: projects/matrix-3/packages/matrix-edge/src/main.ts:389-535. edge-model.ts:160-190 for installedApps.