119 lines
2.4 KiB
Markdown
119 lines
2.4 KiB
Markdown
# 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.
|