CremaUIStudio/arcadia-admin
1
0
Fork 0
Code Issues Pull Requests 4 Actions Packages Projects Releases Wiki Activity

init: arcadia-admin — admin webapp for arcadia-core, cloned from vibespace

Browse Source 
Initial commit. Spun up via the docs/STARTER.md recipe: cp from vibespace,
reset git, rename package, set brand to "Arcadia Admin" with Shield icon
in app/lib/identity.ts.

Inherits the full Crema sibling-lib wiring including @crema/arcadia-client
(typed HTTP + Phoenix Channels realtime against arcadia-core) and
@crema/arcadia-auth-ui (login/signup/password-reset/2FA forms). The /login
route already renders <LoginForm>; <ArcadiaProvider> in app/root.tsx reads
VITE_ARCADIA_URL (default localhost:4000) and VITE_ARCADIA_TENANT (default
"default").

CLAUDE.md and README rewritten to frame this as the admin app for
arcadia-core. docs/STARTER.md removed — arcadia-admin is a leaf consumer,
not a downstream starter.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
jules
2026-04-29 21:28:39 +10:00
commit f8cbf142b5
108 changed files with 23740 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

366
docs/AI_FIRST.md Normal file
View File

@@ -0,0 +1,366 @@
# AI-first system tour
The "anything can drive the UI" architecture — the contract every interactive
element opts into, the command bus that dispatches actions, the DSL that
makes scripts and LLM output ergonomic, and the LLM integration that wires
the whole thing into a chat surface.
It's one system, designed end-to-end. Reading top-to-bottom is the fastest
way to understand it.
## Overview
```
┌─ producers ─────────────────────┐ ┌─ executor ──────────────────┐
│ ⌨ console (window.commandBus) │ │ command-bus.ts │
│ 📜 scripts (.script DSL) │ ─▶ │ • dispatch(cmd) │
│ 🤖 LLM (```action blocks) │ │ • handlers map │
│ 🔌 WebSocket (optional) │ │ • vars + history │
└─────────────────────────────────┘ │ • listActions / readState │
└─────────┬───────────────────┘
│
┌───────────────────┴───────────────────┐
│ │
▼ ▼
┌──────────────┐ ┌──────────────────┐
│ DOM actions │ │ replay layer │
│ (click/fill/ │ │ • virtual cursor │
│ navigate/…) │ │ • ripple on click│
└──────────────┘ └──────────────────┘
```
Every interactive element opts in by adding `data-action="<id>"`. That's the
entire contract. From there, the bus can find it, scripts can target it, and
the LLM can drive it.
## The `[data-action]` convention
Every interactive UI element gets a stable id:
```tsx
<button data-action="sidebar-toggle">…</button>
<input data-action="appbar-search" />
<NavLink data-action="nav-resources" to="/resources">Resources</NavLink>
```
**Naming:** lowercase, kebab-case, prefixed by the surface it lives in:
| Prefix | Surface |
|---|---|
| `nav-*` | Sidebar nav links (`nav-overview`, `nav-resources`, …) |
| `nav-mobile-*` | Mobile sheet versions of nav |
| `appbar-*` | Top bar controls (`appbar-search`, `appbar-notifications`) |
| `avatar-*` | Avatar dropdown items |
| `<route>-*` | Route-specific (`assistant-clear`, `settings-save`) |
| `home-tile-*`, `run-script-*`, etc. | Domain-grouped |
**Why this works:** the bus introspects the DOM at dispatch time —
`commandBus.listActions()` returns every visible `[data-action]` in the page
right now. New components are automatically scriptable as long as they tag
their interactive slots. No central registry to maintain.
**One gotcha:** elements rendered in portals (closed dropdowns, sheets,
dialogs) appear in the DOM but aren't visible. The `listActions()` filter
uses `Element.checkVisibility()` + `offsetParent` + bbox checks to exclude
those — so the LLM doesn't see actions it can't actually click.
## The command bus
`app/lib/command-bus.ts`. Single dispatch point. Built-in handlers:
| Command | Args | Purpose |
|---|---|---|
| `navigate` | `path` | React Router navigation |
| `click` | `target` | Find `[data-action=target]`, scroll into view, click |
| `fill` | `target`, `value` | Set input value, fire input + change events |
| `submit` | `target` | Submit the form containing target |
| `select` | `target`, `value` | Set `<select>` value |
| `wait` | `ms` | Sleep |
| `wait_for` | `target`, `timeout?` | Poll for element existence (default 5s timeout) |
| `scroll` | `target?` | scrollIntoView, or page bottom if no target |
| `read` | `target?` | Return innerText (truncated to 4000 chars) |
| `expect` | `target`, `op`, `value?` | Assert: `to_contain`, `to_be_visible`, `to_have_value` |
| `set` | `name`, `value` | Set a variable for later interpolation |
### Variables
Every command can declare `as: "name"` — its return value gets stored under
that name. Other commands reference it via `$name` interpolation.
```js
commandBus.dispatch({ type: "read", target: "row-1", as: "id" })
commandBus.dispatch({ type: "click", target: "$id" }) // resolves at dispatch
```
In DSL form:
```
$id = read row-1
click $id
```
### Custom handlers
Register your own anywhere:
```ts
import { commandBus } from "~/lib/command-bus"
commandBus.register("ring", async (cmd) => {
const el = document.querySelector(`[data-action="${cmd.target}"]`)
el?.classList.add("animate-ring")
setTimeout(() => el?.classList.remove("animate-ring"), 1200)
})
// dispatch as: { type: "ring", target: "save-button" }
```
Returns an `unregister` fn for cleanup.
### Console API
The provider exposes `window.commandBus`, `window.runScript`, and
`window.runScriptText`. Open devtools and try:
```js
commandBus.listActions().filter(a => a.id.startsWith("nav-"))
commandBus.readState() // visible page text
commandBus.history // every dispatch + result/error
runScript("demo-tour") // load + run /scripts/demo-tour.script
runScriptText('click sidebar-toggle\nwait 500\nclick nav-assistant')
```
## The DSL
Plain text, one command per line. Parses to canonical JSON. Both layers
share the same vocabulary; the DSL is just sugar.
```
# Comfy Cloud — short tour through the rail
# speed: 0.9
click sidebar-toggle
wait 500
click nav-resources
wait_for nav-resources
wait 500
click nav-assistant
wait 700
# Variables
$id = read row-1
click $id
# Assertions
fill appbar-search "acme"
expect resources-table to_contain "Acme"
```
**Syntax:**
- One command per line.
- Whitespace-tolerant. Quote values with spaces (`"hello world"`). Backslash-escape inside quotes.
- `#` starts a comment. The `# speed: <n>` directive at the top sets cursor animation speed (default 1).
- `$name = <command>` assigns the command's return value to a variable.
- `$name` in args is interpolated at dispatch.
- `run other-script` includes another script (resolved as `/scripts/other-script.script`).
**API:**
```ts
import { parseScript, parseLine, stringifyScript } from "~/lib/command-parser"
import { runScript, runScriptText } from "~/lib/command-script"
const { options, commands } = parseScript(text) // → JSON commands
const dsl = stringifyScript(commands, options) // → text (round-trips)
await runScriptText(dsl)
await runScript("demo-tour")
```
## Scripts
Live in `public/scripts/*.script`. Two ways to invoke at runtime:
1. **Dialog** — appbar Play icon, or **⌘⇧P** keyboard shortcut. Lists known
scripts + a paste-DSL textarea. See `app/components/scripts-dialog.tsx`.
2. **Console** — `runScript("demo-tour")` or `runScriptText("…")`.
Sub-scripts compose:
```
# in a parent script
run setup-fixtures
run actual-test
```
## Virtual cursor
`app/lib/virtual-cursor.ts`. A floating SVG cursor + ripple element appended
to `document.body`. The bus's `beforeCommand` hook moves the cursor to the
target element before each command and rips a ripple on `click`. Speed is
controlled by the script's `# speed:` header (default 1; lower = slower
animation).
`aria-hidden`/`role="presentation"` so screen readers ignore it. To run
silently (e.g. tests), pass `{ silent: true }` to `dispatch()` or `run()`.
## LLM integration
`app/lib/llm-tools.ts`. Two responsibilities:
### 1. Build the system prompt
`buildSystemPrompt({ path, includeActions })` returns a string with:
- A short preface ("You are the assistant in Comfy Cloud…")
- A compact DSL reference (~120 tokens — kept tight for small context windows)
- The current route
- A live snapshot of every visible `[data-action]` on screen, formatted as
`- <id>: <label>` (skipping invisible/portal items)
The Assistant route rebuilds this on every send when **UI Control** is on,
so the model always sees the current page's actions.
### 2. Extract action blocks from streamed replies
The system prompt teaches the model to emit a fenced ` ```action ` block
when the user asks it to do something. After each assistant turn ends, the
Assistant route runs `runActionBlocks(message.content)` which:
1. Regex-extracts every ` ```action ... ``` ` block.
2. Feeds each through `runScriptText` → DSL parser → command bus.
3. Returns `{ ran, errors }` for the route to surface as a status pill
("Ran 2 actions").
The action-block fence renders as a small pill in the chat bubble (not raw
text) — see `app/components/assistant/message-body.tsx`.
### Format the model emits
```
I'll take you to resources.
​```action
navigate /resources
wait_for nav-resources
​```
Done — anything else?
```
The "rules" the system prompt teaches the model:
- Only emit a block when asked to *do* something. Questions and chitchat
reply normally.
- Use only ids from the "Available actions" list.
- A short sentence + the block. Optional follow-up after.
- Never invent target ids.
Smaller models (≤7B) sometimes drift — the system prompt is explicit about
each rule, but you'll see occasional invented ids or extra prose. Bigger
models or Claude follow it near-perfectly.
### Token budget
`useChat` with these `reqExtras`:
- `system` — fresh per send via `buildSystemPrompt(...)`
- `messages` — pre-trimmed via `trimMessages(...)` to fit `contextTokens − sysTokens − responseBudget`
- `maxTokens: responseBudget` — caps the reply length
`contextTokens`, `responseBudget`, and `baseURL` come from `/settings`.
Default 9000 / 512. The header bar shows a live `<used> / <total>` badge
that turns amber when getting close.
## Producer 4: WebSocket (optional, unwired)
`app/lib/command-ws.ts`. A reconnecting `WebSocket` listener that accepts
three message shapes:
```json
{ "id": "abc", "command": { "type": "click", "target": "save-button" } }
{ "id": "abc", "script": [ {"type":"navigate","path":"/x"}, … ] }
{ "id": "abc", "dsl": "navigate /x\nclick save-button" }
```
Replies with `{ id, ok: true }` or `{ id, ok: false, error: "…" }`.
Not wired up by default. To enable for a session:
```ts
import { connectCommandSocket } from "~/lib/command-ws"
const sock = connectCommandSocket("ws://localhost:9229/ui")
// ... later ...
sock.close()
```
The intended use is screen-share / observer / CI scenarios where an external
process drives the UI. **Origin checks and an opt-in toggle in /settings are
sketched but not built** — don't auto-connect in production.
## Safety (sketch, not built)
When the UI gains destructive surfaces, mark them with
`data-action-danger`:
```tsx
<Button data-action="delete-account" data-action-danger>Delete</Button>
```
The bus's `beforeCommand` hook can refuse danger-marked targets unless the
caller passes a confirmation token. This is **not implemented yet** — flag
and design when you have a real destructive action to gate.
## Files at a glance
| File | Role |
|---|---|
| `app/lib/command-bus.ts` | JSON layer, dispatch, handlers, vars, history, `listActions`, `readState` |
| `app/lib/command-parser.ts` | DSL ↔ JSON |
| `app/lib/command-script.ts` | Script runner — load `/scripts/*.script`, run with cursor speed |
| `app/lib/virtual-cursor.ts` | Visible cursor + ripple |
| `app/lib/command-provider.tsx` | React glue: registers `navigate`, mounts cursor, exposes `window.*` |
| `app/lib/command-ws.ts` | Optional WebSocket producer |
| `app/lib/llm-tools.ts` | `buildSystemPrompt`, `extractActionBlocks`, `runActionBlocks`, token utils |
| `app/lib/llm-settings.ts` | Persisted base URL / context / response cap |
| `app/components/scripts-dialog.tsx` | ⌘⇧P script runner UI |
| `app/components/assistant/message-body.tsx` | Markdown bubble + action-block pill |
| `public/scripts/demo-*.script` | Examples |
## Quick recipes
**Make a new component scriptable** — add `data-action="<id>"`. Done.
**Test a flow** — write a `.script` file with `expect` assertions:
```
navigate /settings
fill settings-base-url "http://localhost:1234/v1"
click settings-test
wait 1500
expect settings-test to_contain "models available"
```
Run it via the dialog or `runScript("…")`.
**Drive a custom widget** — register a handler:
```ts
commandBus.register("highlight", async (cmd) => {
/* ...your logic... */
})
```
Then dispatch `{ type: "highlight", target: "…" }` from anywhere.
**Send the LLM a different system prompt** — `buildSystemPrompt` accepts a
`preface` override:
```ts
buildSystemPrompt({
preface: "You are the support agent for Comfy Cloud's billing team.",
path: window.location.pathname,
})
```

99
docs/LIBS.md Normal file
View File

@@ -0,0 +1,99 @@
# Available Crema libs
> Generated by `scripts/sync-libs.mjs` from crema-manifest@3.1.0.
> Run `npm run sync-libs` to refresh.
Every `@crema/*-ui` lib is its own git repo at
`https://git.sky-ai.com/CremaUIStudio/lib-<name>-ui`. To add one, clone it
as a sibling of this project, then add the tsconfig path entry and the
`@source` line to `app/app.css` (the marker comments make this easy).
## Wired in this project (5)
These are importable from your code right now (`import { … } from "@crema/<name>"`):
| Lib | Alias | Purpose |
|---|---|---|
| `action-bus` | `@crema/action-bus` | Anything-can-drive-the-UI command bus. Single dispatch point for LLM tool calls, scripts, and (optional) WebSocket remote control. JSON c… |
| `aifirst-ui` | `@crema/aifirst-ui` | AI-first card primitives: AICard with left-border accent + canonical anatomy (title, metadata, AI rationale, verb-prefixed action buttons… |
| `chat-ui` | `@crema/chat-ui` | Chat threads, message bubbles, composer, channel list |
| `llm-ui` | `@crema/llm-ui` | LLM client + React bindings. Two adapters out of the box: OpenAICompatibleAdapter (LM Studio, Ollama, DeepSeek, OpenAI, Together, Groq, O… |
| `notification-ui` | `@crema/notification-ui` | Toasts, badges, bell, banners, inbox, notification center |
## Active theme
| Theme | Dark mode | Purpose |
|---|---|---|
| `mightypix` | supported | Warm AI-first companion to pristine. Cream paper surfaces, deep ink-blue accent, soft flat elevation, asymmetric typography (Inter for UI chrome, Source Seri… |
## Available to add (50)
From the manifest. To wire one in: `crema add <name>` (CLI), or
manually clone the repo + edit `tsconfig.json` paths + `app/app.css`
`@source`.
| Lib | Alias | Purpose |
|---|---|---|
| `a11y-ui` | `@crema/a11y-ui` | Skip links, focus trap/ring, shortcut overlay, contrast checker |
| `agent-ui` | `@crema/agent-ui` | Agentic UI atoms: action proposals + queue, diff proposals, tool-call audit cards, multi-step run panel with step trail and milestone rai… |
| `artifact-ui` | `@crema/artifact-ui` | AI-generated artifacts as cards: code, file, email, sql, draft, chart, image, dataset. Type-specific previews, draft/reviewing/applied li… |
| `auth-ui` | `@crema/auth-ui` | Sign-in, sign-up, MFA, password reset, OAuth buttons |
| `billing-ui` | `@crema/billing-ui` | Pricing tables, plan comparison, usage meters, invoices, payment methods |
| `calendar-ui` | `@crema/calendar-ui` | Calendar grid, week/day views, event cards, scheduling |
| `callcentre-ui` | `@crema/callcentre-ui` | Agent desktop: softphone, active call card, queue, history, customer lookup, scripts, knowledge search, transcript, notes, disposition, w… |
| `card-ui` | `@crema/card-ui` | Theme-agnostic card primitives: three-zone template (media / body / actions) with portrait, landscape, compact, wide-banner orientations;… |
| `chart-ui` | `@crema/chart-ui` | Themed charting primitives: sparkline, line, bar, donut, heatmap. Pure SVG, currentColor-driven. |
| `code-ui` | `@crema/code-ui` | Code blocks, diff viewer, syntax highlighting, file tree |
| `codereview-ui` | `@crema/codereview-ui` | Code review primitives in two registers, sharing PullRequest/DiffHunk/ReviewComment/Reviewer types. Plain: PullRequestCard (queue row), D… |
| `color-ui` | `@crema/color-ui` | Color picker, swatches, palettes, contrast tooling |
| `command-ui` | `@crema/command-ui` | Command palette (⌘K) with self-registering commands, fuzzy match, keyboard navigation. |
| `comments-ui` | `@crema/comments-ui` | Threaded comments, mentions, reactions, presence |
| `commerce-ui` | `@crema/commerce-ui` | Product cards, cart, checkout, order summary |
| `content-editor-ui` | `@crema/content-editor-ui` | Rich-text editor (Tiptap), blog composer, slash menu, image embeds |
| `content-media-ui` | `@crema/content-media-ui` | Media library, image gallery, video/audio players, lightbox |
| `content-ui` | `@crema/content-ui` | Article display, prose styles, table of contents, callouts |
| `crm-ui` | `@crema/crm-ui` | CRM-domain primitives in two registers sharing the same Deal/Contact/Company/Activity types (Deal includes probability for forecasting; C… |
| `dashboard-ui` | `@crema/dashboard-ui` | Stat cards, KPI tiles, gauges, sparklines, heatmap calendar |
| `data-ui` | `@crema/data-ui` | Lists, key-value, definition rows, descriptive blocks |
| `diagram-ui` | `@crema/diagram-ui` | Node graphs, flow diagrams, swimlanes, sequence diagrams |
| `ehr-ui` | `@crema/ehr-ui` | EHR primitives in two registers, sharing Patient/Vital/Medication/Allergy/LabResult/Order/ProblemListItem/Encounter types. Plain: Patient… |
| `eval-ui` | `@crema/eval-ui` | Eval result UI: score cards, A/B comparison rows, run grids, score distributions. |
| `feedback-ui` | `@crema/feedback-ui` | Alerts, banners, empty states, error boundaries |
| `file-ui` | `@crema/file-ui` | Dropzone, file grid/list, previewers, upload progress, browser |
| `fleetops-ui` | `@crema/fleetops-ui` | Air traffic / fleet ops: radar map, flight strips, status badges, schedule gantt, weather, runway load, aircraft health, crew |
| `flow-ui` | `@crema/flow-ui` | Workflow / state-machine canvas: drag nodes, draw edges, execute with branching decisions. |
| `form-ui` | `@crema/form-ui` | Forms, fields, validation, multi-step wizards |
| `futurecafe-ui` | `@crema/futurecafe-ui` | Near-future café barista dashboard: AI↔AI handshake summary, customer card with mood/vibe, pedestrian approach map, arrival countdown, or… |
| `inflight-aurora-ui` | `@crema/inflight-aurora-ui` | Near-future supersonic cabin UI (second theme): glassmorphism aurora aesthetic — flight arc globe, trip timeline, ETA, altitude strip, ov… |
| `inflight-ui` | `@crema/inflight-ui` | Near-future luxury inflight passenger UI: flight map arc, trip timeline, ETA, altitude strip, gourmet menu, order tray, cabin mood, windo… |
| `kanban-ui` | `@crema/kanban-ui` | Kanban board, draggable cards, columns, swimlanes |
| `layout-ui` | `@crema/layout-ui` | Grids, stacks, dividers, sidebars, scroll areas |
| `log-ui` | `@crema/log-ui` | Streamed log viewer: level filter, structured-field expansion, follow-mode auto-scroll, pause/resume/clear. |
| `map-ui` | `@crema/map-ui` | SVG maps (world, US states), choropleth, spatial primitives, game grid |
| `morph-ui` | `@crema/morph-ui` | Shared-element container primitive: tiles with icon/card/workspace states, FLIP transitions, body-portaled workspace with grid-centered l… |
| `motorsport-ui` | `@crema/motorsport-ui` | F1 / motorsport: animated track map, telemetry cluster, tyre + sector badges, lap timing tower, race control, stint chart, pit stop seque… |
| `onboarding-ui` | `@crema/onboarding-ui` | Welcome cards, checklists, wizards, coachmarks, product tours |
| `presence-ui` | `@crema/presence-ui` | Human + agent presence layer: avatars, ambient strips, rails, workspace panel, proposals with voting, interrupt dock, inline threads, cro… |
| `print-ui` | `@crema/print-ui` | Print provider, page sizes, invoice/receipt/label/badge templates |
| `prompt-ui` | `@crema/prompt-ui` | Prompt + template authoring: variable highlighting, token estimation, version diff. |
| `property-man-ui` | `@crema/property-man-ui` | Real estate listings, property cards, gallery, filter facets, mortgage calculator, agent cards |
| `rag-ui` | `@crema/rag-ui` | Retrieval result UI: ranked chunks with highlighted spans, source attribution, retriever comparison. |
| `search-ui` | `@crema/search-ui` | Search input, command palette, facets, query tokens |
| `settings-ui` | `@crema/settings-ui` | Settings shell, preferences, profile, API keys, danger zone |
| `status-ui` | `@crema/status-ui` | System status board: components with uptime grids, incident timeline, maintenance windows. Renders subgrid-aligned bars across rows. |
| `table-ui` | `@crema/table-ui` | Sortable tables, row selection, pagination, sticky headers |
| `tool-ui` | `@crema/tool-ui` | Agentic tool catalog, schema editor, and mock-execution preview. Pairs with agent-ui (single-call display) as the management surface for … |
| `typography-ui` | `@crema/typography-ui` | Type scale, font specimens, prose blocks |
## Other themes (5)
Swap by changing the `@import "../../lib-theme-<name>/theme.css"` line at the top of `app/app.css`.
| Theme | Dark mode | Purpose |
|---|---|---|
| `arcade` | dark-only | Gaming-shell theme: dark-first cobalt canvas, electric-cyan CTA, neon burst accents, sharper radii, snappier motion. For app surfaces around a game (lobby, s… |
| `caffe-florian` | supported | Editorial theme for content-first apps — cream parchment surfaces, Venetian red accent, Libre Baskerville display + DM Sans body. Generous line-heights, soft… |
| `otium` | supported | Pristine UI's Apple-inspired glass aesthetic with generous, spacious typography. Sharp clean translucent surfaces, hairline borders, vibrancy stack. More rel… |
| `pristine` | supported | Apple-inspired glass design system with translucent surfaces, spring motion, and SF/Inter typography. |
| `swish` | supported | Touchscreen Apple-feel theme for shared surfaces (inflight seatback, automotive passenger, kiosks). Saturated-and-serene sky canvas with opaque matte chiclet… |