# Surfaces

Dynamic surface lifecycle. Core surfaces are registered at startup.
Extension surfaces are uploaded by admins and served from the
`surface_registry` table.

## User Endpoints

### List Enabled Surfaces

```
GET /surfaces
```

Returns surfaces the user can access (enabled in registry).

```json
{
  "surfaces": [
    { "id": "chat", "title": "Chat", "source": "core", "enabled": true },
    { "id": "editor", "title": "Editor", "source": "core", "enabled": true },
    { "id": "hello-dashboard", "title": "Hello Dashboard", "source": "extension", "enabled": true }
  ]
}
```

**Auth:** Authenticated.

## Admin Endpoints

### List All Surfaces

```
GET /admin/surfaces
```

Returns all surfaces including disabled ones.

**Auth:** Platform admin.

### Get Surface

```
GET /admin/surfaces/:id
```

Returns full surface details including manifest.

### Install Surface

```
POST /admin/surfaces/install
Content-Type: multipart/form-data
```

Field: `archive` — a `.surface` archive (tar.gz containing `manifest.json`
+ static assets). The manifest declares `id`, `title`, `route`, required
data loaders, scripts, and CSS.

**Auth:** Platform admin.

### Enable / Disable

```
PUT /admin/surfaces/:id/enable
PUT /admin/surfaces/:id/disable
```

Disabled surfaces redirect to `/` and hide from navigation.

**Auth:** Platform admin.

### Delete Surface

```
DELETE /admin/surfaces/:id
```

Removes the surface and its static assets. Core surfaces cannot be deleted.

**Auth:** Platform admin.

## Surface Registry Object

```json
{
  "id": "hello-dashboard",
  "title": "Hello Dashboard",
  "manifest": { "route": "/s/hello-dashboard", "scripts": [...], "css": [...] },
  "enabled": true,
  "source": "core|extension",
  "installed_at": "...",
  "updated_at": "..."
}
```

## Page Routes

Extension surfaces are served at `/s/:slug` via `RenderExtensionSurface()`.
The page engine does a runtime DB lookup — no server restart needed after install.

Static assets are served from `/surfaces/:id/` (nginx location block in
both unified and split deployment).

## Surface Archive Format

A `.surface` file is a tar.gz containing:

```
manifest.json     — required
script.js         — optional
style.css         — optional
assets/           — optional (icons, images, etc.)
```

See [EXTENSION-SURFACES.md](../EXTENSION-SURFACES.md) for the full
authoring guide including manifest schema, platform API, and CSS
custom properties.