@mostra/runtime 0.10.0 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin.js +4178 -310
- package/dist/bin.js.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/{instance-FExcyENK.js → instance-CBUlOmzG.js} +1892 -85
- package/dist/instance-CBUlOmzG.js.map +1 -0
- package/dist/reference/cli.md +1432 -0
- package/dist/reference/diagnostics.json +1579 -0
- package/dist/reference/errors/MOSTRA_A11Y_MINOR.md +23 -0
- package/dist/reference/errors/MOSTRA_A11Y_SERIOUS.md +23 -0
- package/dist/reference/errors/MOSTRA_ACTION_CANCELLED.md +23 -0
- package/dist/reference/errors/MOSTRA_ACTION_EVENT_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_ACTION_EXPORT_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_ACTION_INTERRUPTED.md +23 -0
- package/dist/reference/errors/MOSTRA_ACTION_PAUSED.md +23 -0
- package/dist/reference/errors/MOSTRA_ACTION_RUN_NOT_FOUND.md +23 -0
- package/dist/reference/errors/MOSTRA_ACTION_THREW.md +23 -0
- package/dist/reference/errors/MOSTRA_ACTION_TOO_LARGE.md +23 -0
- package/dist/reference/errors/MOSTRA_ACTION_UNKNOWN_FUNCTION.md +23 -0
- package/dist/reference/errors/MOSTRA_ACTION_UNSERIALIZABLE.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_BUNDLE_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_DIR_NOT_EMPTY.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_ID_DROPPED.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_NOT_FOUND.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_NO_ENTRY.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_NO_PAGE.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_PATCH_REJECTED.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_PATH_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_SOURCE_MISSING.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_SOURCE_UNREADABLE.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_VERSION_COLLECTED.md +23 -0
- package/dist/reference/errors/MOSTRA_ARTIFACT_VERSION_NOT_FOUND.md +23 -0
- package/dist/reference/errors/MOSTRA_BUILD_CRASHED.md +23 -0
- package/dist/reference/errors/MOSTRA_BUILD_FAILED.md +23 -0
- package/dist/reference/errors/MOSTRA_BUILD_TIMEOUT.md +23 -0
- package/dist/reference/errors/MOSTRA_BUILD_UNRESOLVED.md +23 -0
- package/dist/reference/errors/MOSTRA_CLI_CONFIG_UNWRITABLE.md +23 -0
- package/dist/reference/errors/MOSTRA_CLI_UNKNOWN_COMMAND.md +23 -0
- package/dist/reference/errors/MOSTRA_CLI_USAGE.md +23 -0
- package/dist/reference/errors/MOSTRA_CONSOLE_ERROR.md +23 -0
- package/dist/reference/errors/MOSTRA_CONSOLE_WARNING.md +23 -0
- package/dist/reference/errors/MOSTRA_DEP_INSTALL_FAILED.md +23 -0
- package/dist/reference/errors/MOSTRA_DEP_MISSING.md +23 -0
- package/dist/reference/errors/MOSTRA_DEP_NOT_FOUND.md +23 -0
- package/dist/reference/errors/MOSTRA_DEP_OFFLINE.md +23 -0
- package/dist/reference/errors/MOSTRA_DEP_SPEC_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_DEP_TIMEOUT.md +23 -0
- package/dist/reference/errors/MOSTRA_DEP_WARM_CONFLICT.md +23 -0
- package/dist/reference/errors/MOSTRA_ENV_BIND_FAILED.md +23 -0
- package/dist/reference/errors/MOSTRA_ENV_BROWSER_MISSING.md +23 -0
- package/dist/reference/errors/MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED.md +23 -0
- package/dist/reference/errors/MOSTRA_ENV_BUNDLE_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_ENV_BUNDLE_UNAVAILABLE.md +23 -0
- package/dist/reference/errors/MOSTRA_ENV_HELPER_MISSING.md +23 -0
- package/dist/reference/errors/MOSTRA_ENV_NODE_UNSUPPORTED.md +23 -0
- package/dist/reference/errors/MOSTRA_ENV_PORT_TAKEN.md +23 -0
- package/dist/reference/errors/MOSTRA_ENV_RUNTIME_INSTALLING.md +23 -0
- package/dist/reference/errors/MOSTRA_ENV_RUNTIME_MISSING.md +23 -0
- package/dist/reference/errors/MOSTRA_ENV_SERVICE_FAILED.md +23 -0
- package/dist/reference/errors/MOSTRA_ENV_SHELL_MISSING.md +23 -0
- package/dist/reference/errors/MOSTRA_ENV_WARM_MISSING.md +23 -0
- package/dist/reference/errors/MOSTRA_FIELD_CONFLICT.md +23 -0
- package/dist/reference/errors/MOSTRA_FIELD_DUPLICATE_ID.md +23 -0
- package/dist/reference/errors/MOSTRA_FIELD_ID_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_FIELD_ID_UNSTABLE.md +23 -0
- package/dist/reference/errors/MOSTRA_FIELD_MUTATION_ID_REUSED.md +23 -0
- package/dist/reference/errors/MOSTRA_FIELD_SHARED.md +23 -0
- package/dist/reference/errors/MOSTRA_FIELD_TOO_LARGE.md +23 -0
- package/dist/reference/errors/MOSTRA_FIELD_UNBOUND.md +23 -0
- package/dist/reference/errors/MOSTRA_HOME_DISK_FULL.md +23 -0
- package/dist/reference/errors/MOSTRA_HOME_GC_INCOMPLETE.md +23 -0
- package/dist/reference/errors/MOSTRA_HOME_GONE.md +23 -0
- package/dist/reference/errors/MOSTRA_HOME_INTEGRITY.md +23 -0
- package/dist/reference/errors/MOSTRA_HOME_LEDGER_UNREADABLE.md +23 -0
- package/dist/reference/errors/MOSTRA_HOME_LOCKED.md +23 -0
- package/dist/reference/errors/MOSTRA_HOME_MISMATCH.md +23 -0
- package/dist/reference/errors/MOSTRA_HOME_NETWORK_FILESYSTEM.md +23 -0
- package/dist/reference/errors/MOSTRA_HOME_NOT_ALWAYS_ON.md +23 -0
- package/dist/reference/errors/MOSTRA_HOME_NOT_OWNED.md +23 -0
- package/dist/reference/errors/MOSTRA_HOME_SOCKET_TOO_LONG.md +23 -0
- package/dist/reference/errors/MOSTRA_HOME_TOO_NEW.md +23 -0
- package/dist/reference/errors/MOSTRA_HOST_CONNECTION_CLOSED.md +23 -0
- package/dist/reference/errors/MOSTRA_HOST_CURSOR_COMPACTED.md +23 -0
- package/dist/reference/errors/MOSTRA_HOST_IDENTITY_UNAVAILABLE.md +23 -0
- package/dist/reference/errors/MOSTRA_HOST_INITIALIZE_ORDER.md +23 -0
- package/dist/reference/errors/MOSTRA_HOST_INTERNAL_ERROR.md +23 -0
- package/dist/reference/errors/MOSTRA_HOST_INVALID_PARAMS.md +23 -0
- package/dist/reference/errors/MOSTRA_HOST_MALFORMED.md +23 -0
- package/dist/reference/errors/MOSTRA_HOST_MESSAGE_TOO_LARGE.md +23 -0
- package/dist/reference/errors/MOSTRA_HOST_METHOD_UNKNOWN.md +23 -0
- package/dist/reference/errors/MOSTRA_HOST_NOTIFICATION_UNSUPPORTED.md +23 -0
- package/dist/reference/errors/MOSTRA_HOST_PORT_UNSUPPORTED.md +23 -0
- package/dist/reference/errors/MOSTRA_HOST_REQUEST_ID_REUSED.md +23 -0
- package/dist/reference/errors/MOSTRA_HOST_REVISION_UNSUPPORTED.md +23 -0
- package/dist/reference/errors/MOSTRA_HOST_SHUTDOWN_REFUSED.md +23 -0
- package/dist/reference/errors/MOSTRA_HOST_SUBSCRIPTION_UNKNOWN.md +23 -0
- package/dist/reference/errors/MOSTRA_HOST_TIMEOUT.md +23 -0
- package/dist/reference/errors/MOSTRA_HYGIENE_CONTENT_TYPE.md +23 -0
- package/dist/reference/errors/MOSTRA_HYGIENE_CSRF_MISSING.md +23 -0
- package/dist/reference/errors/MOSTRA_HYGIENE_FRAME_SESSION.md +23 -0
- package/dist/reference/errors/MOSTRA_HYGIENE_HEADERS_TOO_LARGE.md +23 -0
- package/dist/reference/errors/MOSTRA_HYGIENE_HOST_REFUSED.md +23 -0
- package/dist/reference/errors/MOSTRA_HYGIENE_NOT_SERVED.md +23 -0
- package/dist/reference/errors/MOSTRA_HYGIENE_ORIGIN_REFUSED.md +23 -0
- package/dist/reference/errors/MOSTRA_HYGIENE_RATE_LIMITED.md +23 -0
- package/dist/reference/errors/MOSTRA_HYGIENE_REQUEST_MALFORMED.md +23 -0
- package/dist/reference/errors/MOSTRA_HYGIENE_SCOPE_DENIED.md +23 -0
- package/dist/reference/errors/MOSTRA_HYGIENE_SESSION_CONFLICT.md +23 -0
- package/dist/reference/errors/MOSTRA_HYGIENE_SESSION_MISSING.md +23 -0
- package/dist/reference/errors/MOSTRA_HYGIENE_TOKEN_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_HYGIENE_TOKEN_REVOKED.md +23 -0
- package/dist/reference/errors/MOSTRA_LIVE_SOURCE_FAILED.md +23 -0
- package/dist/reference/errors/MOSTRA_LIVE_TOO_LARGE.md +23 -0
- package/dist/reference/errors/MOSTRA_MANIFEST_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_MANIFEST_NOT_LITERAL.md +23 -0
- package/dist/reference/errors/MOSTRA_MANIFEST_UNKNOWN_KEY.md +23 -0
- package/dist/reference/errors/MOSTRA_NETWORK_EXTERNAL_FAILED.md +23 -0
- package/dist/reference/errors/MOSTRA_NETWORK_REQUEST_FAILED.md +23 -0
- package/dist/reference/errors/MOSTRA_PLATFORM_UNSUPPORTED.md +23 -0
- package/dist/reference/errors/MOSTRA_PUBLISH_ID_CONFLICT.md +23 -0
- package/dist/reference/errors/MOSTRA_PUBLISH_SOURCE_CHANGED.md +23 -0
- package/dist/reference/errors/MOSTRA_PUBLISH_VERIFY_FAILED.md +23 -0
- package/dist/reference/errors/MOSTRA_REGRESSION_ACTION_REMOVED.md +23 -0
- package/dist/reference/errors/MOSTRA_REGRESSION_ARIA.md +23 -0
- package/dist/reference/errors/MOSTRA_REGRESSION_FIELD_REMOVED.md +23 -0
- package/dist/reference/errors/MOSTRA_REGRESSION_LIVE_REMOVED.md +23 -0
- package/dist/reference/errors/MOSTRA_REGRESSION_PAGE_REMOVED.md +23 -0
- package/dist/reference/errors/MOSTRA_REGRESSION_PIXELS.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_CONFIG_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_HOME_MOVING.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_HOME_SUSPENDED.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_LIMIT_REACHED.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_LOGIN_FAILED.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_NOT_OWNER_INSTANCE.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_NO_INSTANCE.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_OPERATOR_UNAVAILABLE.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_OWNER_OFFLINE.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_PAUSED_BY_OPERATOR.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_QUEUE_FULL.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_RATE_LIMITED.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_SIGN_IN_REQUIRED.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_UNDER_REVIEW.md +23 -0
- package/dist/reference/errors/MOSTRA_REMOTE_UNREACHABLE.md +23 -0
- package/dist/reference/errors/MOSTRA_RUNTIME_BLANK.md +23 -0
- package/dist/reference/errors/MOSTRA_RUNTIME_NOT_READY.md +23 -0
- package/dist/reference/errors/MOSTRA_RUNTIME_PAGE_ERROR.md +23 -0
- package/dist/reference/errors/MOSTRA_RUNTIME_WORKER_CRASHED.md +23 -0
- package/dist/reference/errors/MOSTRA_RUNTIME_WORKER_PARKED.md +23 -0
- package/dist/reference/errors/MOSTRA_SECRET_MISSING.md +23 -0
- package/dist/reference/errors/MOSTRA_SHARE_NOT_ENABLED.md +23 -0
- package/dist/reference/errors/MOSTRA_SHARE_NOT_FOUND.md +23 -0
- package/dist/reference/errors/MOSTRA_SHARE_PORTS_EXHAUSTED.md +23 -0
- package/dist/reference/errors/MOSTRA_SHARE_TOOL_MISSING.md +23 -0
- package/dist/reference/errors/MOSTRA_SHARE_TOOL_NOT_READY.md +23 -0
- package/dist/reference/errors/MOSTRA_SHARE_TTL_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_SHARE_TUNNEL_FAILED.md +23 -0
- package/dist/reference/errors/MOSTRA_SMOKE_BUDGET.md +23 -0
- package/dist/reference/errors/MOSTRA_SMOKE_NO_EFFECT.md +23 -0
- package/dist/reference/errors/MOSTRA_SUBMIT_ALREADY.md +23 -0
- package/dist/reference/errors/MOSTRA_SUBMIT_BLOCKED.md +23 -0
- package/dist/reference/errors/MOSTRA_SUBMIT_CHANNEL_DENIED.md +23 -0
- package/dist/reference/errors/MOSTRA_SUBMIT_NOT_FOUND.md +23 -0
- package/dist/reference/errors/MOSTRA_SUBMIT_PAUSED.md +23 -0
- package/dist/reference/errors/MOSTRA_SUBMIT_POLICY_NONE.md +23 -0
- package/dist/reference/errors/MOSTRA_SUBMIT_REVISION_MOVED.md +23 -0
- package/dist/reference/errors/MOSTRA_SUBMIT_SIGNAL_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_SUBMIT_VIEW_INVALID.md +23 -0
- package/dist/reference/errors/MOSTRA_TARGET_UNAVAILABLE.md +23 -0
- package/dist/reference/errors/MOSTRA_TEAM_PRESENCE_RATE_LIMITED.md +23 -0
- package/dist/reference/errors/MOSTRA_TEAM_ROSTER_POLICY.md +23 -0
- package/dist/reference/errors/MOSTRA_TEAM_ROSTER_TOO_LARGE.md +23 -0
- package/dist/reference/errors/MOSTRA_TYPE_ERROR.md +23 -0
- package/dist/reference/errors/MOSTRA_TYPE_UNTYPED_PACKAGE.md +23 -0
- package/dist/reference/errors/MOSTRA_VERIFY_ACTION_SKIPPED.md +23 -0
- package/dist/reference/errors/MOSTRA_VERIFY_BASELINE_MISSING.md +23 -0
- package/dist/reference/errors/MOSTRA_VERIFY_CRASHED.md +23 -0
- package/dist/reference/errors/MOSTRA_VERIFY_LIVE_FAILED.md +23 -0
- package/dist/reference/errors/MOSTRA_VERIFY_NO_BASELINE.md +23 -0
- package/dist/reference/errors/MOSTRA_VERIFY_SECRET_MISSING.md +23 -0
- package/dist/reference/errors/MOSTRA_VERIFY_SKIP_CONSEQUENCE.md +23 -0
- package/dist/reference/errors/MOSTRA_VERIFY_TIMEOUT.md +23 -0
- package/dist/reference/self-hosting.md +130 -0
- package/dist/reference/telemetry.md +84 -0
- package/dist/skill/SKILL.md +124 -0
- package/dist/skill/assets/examples/dashboard/index.tsx +161 -0
- package/dist/skill/assets/examples/dashboard/live.ts +25 -0
- package/dist/skill/assets/examples/dashboard/styles.css +125 -0
- package/dist/skill/assets/examples/decision/index.tsx +95 -0
- package/dist/skill/assets/examples/decision/styles.css +125 -0
- package/dist/skill/assets/examples/inbox/actions.ts +23 -0
- package/dist/skill/assets/examples/inbox/index.tsx +109 -0
- package/dist/skill/assets/examples/inbox/styles.css +125 -0
- package/dist/skill/assets/studio.css +125 -0
- package/dist/skill/references/answers.md +219 -0
- package/dist/skill/references/design.md +154 -0
- package/dist/skill/references/libraries.md +167 -0
- package/dist/skill/references/long-lived.md +148 -0
- package/dist/skill/references/mcp.md +68 -0
- package/dist/skill/references/page.md +131 -0
- package/dist/skill/references/server.md +146 -0
- package/dist/skill/references/sharing.md +123 -0
- package/dist/skill/references/teams.md +78 -0
- package/dist/skill/references/verify.md +71 -0
- package/package.json +10 -5
- package/src/gateway/actions.ts +20 -0
- package/src/gateway/browser.ts +128 -1
- package/src/gateway/capabilities.ts +8 -0
- package/src/gateway/http.ts +12 -1
- package/src/gateway/index.ts +210 -6
- package/src/gateway/listener.ts +31 -6
- package/src/gateway/routes.ts +8 -0
- package/src/gateway/team.ts +181 -0
- package/src/gc/index.ts +5 -0
- package/src/instance/index.ts +22 -2
- package/src/interaction/ephemeral.ts +21 -0
- package/src/interaction/events.ts +17 -0
- package/src/interaction/index.ts +325 -20
- package/src/interaction/pause.ts +106 -0
- package/src/interaction/roster.ts +585 -0
- package/src/interaction/submissions.ts +42 -1
- package/src/interaction/team.ts +426 -0
- package/src/interaction/viewers.ts +34 -1
- package/src/interaction/wait.ts +150 -0
- package/src/ledger/index.ts +20 -1
- package/src/ledger/migrations.ts +86 -0
- package/src/link/author.ts +215 -0
- package/src/link/hosted.ts +51 -4
- package/src/link/http.ts +6 -1
- package/src/link/index.ts +3 -1
- package/src/link/manager.ts +169 -35
- package/src/protocol-server/client.ts +53 -0
- package/src/protocol-server/index.ts +1 -1
- package/src/server/api.ts +514 -72
- package/src/server/auth.ts +600 -74
- package/src/server/authorize.ts +816 -0
- package/src/server/clients.ts +235 -0
- package/src/server/config.ts +7 -0
- package/src/server/data.ts +59 -1
- package/src/server/directory.ts +91 -0
- package/src/server/feed.ts +277 -0
- package/src/server/handle.ts +172 -0
- package/src/server/hosted-pages.ts +532 -0
- package/src/server/hosted.ts +551 -18
- package/src/server/index.ts +353 -61
- package/src/server/mcp.ts +330 -0
- package/src/server/metering.ts +156 -0
- package/src/server/oauth-clients.ts +510 -0
- package/src/server/operator.ts +557 -0
- package/src/server/providers.ts +284 -0
- package/src/server/remove.ts +148 -0
- package/src/server/routing.ts +275 -0
- package/src/share/index.ts +50 -2
- package/src/verify/index.ts +7 -0
- package/src/verify/runner.ts +27 -2
- package/dist/instance-FExcyENK.js.map +0 -1
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
# Design: pages people answer and work in
|
|
2
|
+
|
|
3
|
+
An artifact is a working page: someone reads it, decides, answers, acts. It succeeds when they understand it in five seconds and finish without help. Design is your choice entirely; nothing here is enforced. These are the defaults that make a page look considered, and the checks to run on its screenshots.
|
|
4
|
+
|
|
5
|
+
## Contents
|
|
6
|
+
|
|
7
|
+
- Start from the person's job
|
|
8
|
+
- The baseline stylesheet
|
|
9
|
+
- Type
|
|
10
|
+
- Color
|
|
11
|
+
- Layout and spacing
|
|
12
|
+
- Components and states
|
|
13
|
+
- Forms and answers
|
|
14
|
+
- Numbers, tables and charts
|
|
15
|
+
- Motion
|
|
16
|
+
- Accessibility
|
|
17
|
+
- Words on the page
|
|
18
|
+
- Phones
|
|
19
|
+
- Reading your screenshots
|
|
20
|
+
|
|
21
|
+
## Start from the person's job
|
|
22
|
+
|
|
23
|
+
Before markup, write down:
|
|
24
|
+
|
|
25
|
+
1. **Who opens it and what they do.** "Ada picks one of two checkout layouts and says why."
|
|
26
|
+
2. **The one question the page answers**, and the block that answers it. That block is the largest and comes first.
|
|
27
|
+
3. **The real content.** Real names, numbers, units and dates from the task, with totals that add up. Placeholder names (Acme, John Doe), lorem ipsum and round invented figures make a page read as a mock-up.
|
|
28
|
+
4. **The look the subject asks for.** A finance review, a design critique and a team retro want different pages. Pick deliberately; the baseline below is quiet on purpose and a fine choice when nothing else is called for.
|
|
29
|
+
|
|
30
|
+
## The baseline stylesheet
|
|
31
|
+
|
|
32
|
+
Copy [`../assets/studio.css`](../assets/studio.css) into the artifact as `styles.css` and `import "./styles.css";` in the entry. It starts with `@import "tailwindcss";`, defines light and dark colors with shadcn's token names, and maps them to Tailwind utilities:
|
|
33
|
+
|
|
34
|
+
| Utility | Use |
|
|
35
|
+
|---|---|
|
|
36
|
+
| `bg-background`, `text-foreground` | The page |
|
|
37
|
+
| `bg-card`, `border` | Panels |
|
|
38
|
+
| `bg-muted`, `text-muted-foreground` | Secondary surfaces and text |
|
|
39
|
+
| `bg-primary`, `text-primary-foreground` | The one main action |
|
|
40
|
+
| `text-destructive`, `text-success`, `text-warning` | Status, in text |
|
|
41
|
+
| `bg-answer` | Marks what the person answered or chose (never text color) |
|
|
42
|
+
| `border-input`, `ring-ring` | Inputs and focus |
|
|
43
|
+
| `fill-chart-1` … `fill-chart-6`, `var(--chart-1)` | Chart series, in this order |
|
|
44
|
+
|
|
45
|
+
Three complete examples that pass verify use it, and are worth copying from: [`../assets/examples/decision/`](../assets/examples/decision/) (a choice with a reason), [`../assets/examples/inbox/`](../assets/examples/inbox/) (drafts with real Send actions) and [`../assets/examples/dashboard/`](../assets/examples/dashboard/) (live data and a shared list).
|
|
46
|
+
|
|
47
|
+
A stylesheet that defines `@theme` must start with `@import "tailwindcss";`, or its utilities silently don't exist and verify still passes; check the screenshot. Change any value, or replace the file with your own theme.
|
|
48
|
+
|
|
49
|
+
## Type
|
|
50
|
+
|
|
51
|
+
- One family is enough: the system sans the page already has, or one face you load from `public/` with `@font-face`. A second face only for code or figures (`font-mono`).
|
|
52
|
+
- Four to six sizes per page. For a working page: title `text-2xl` to `text-3xl` (24 to 30 px), section headings `text-base` to `text-lg` with `font-medium`, body `text-base` (16 px) or `text-sm` (14 px) for dense data, labels and meta `text-sm`. Titles on a working page stay modest; a 60 px headline makes it read as a landing page.
|
|
53
|
+
- Weights 400, 500 and 600; one heavier weight at most, for one thing.
|
|
54
|
+
- Body text at most about 70 characters per line (`max-w-prose`). Headings `text-balance`, paragraphs `text-pretty`.
|
|
55
|
+
- Secondary text is softer in color (`text-muted-foreground`), not smaller than 13 px and never lighter in weight.
|
|
56
|
+
- Sentence case for titles, labels and buttons. At most one small uppercase label per page.
|
|
57
|
+
- Use `…` for an ellipsis, curly quotes, and an en dash for ranges (9–5).
|
|
58
|
+
|
|
59
|
+
## Color
|
|
60
|
+
|
|
61
|
+
- Color goes on data, on status, on the selected answer and on one primary action. Everything else is neutral. On most good working pages only a few percent of the pixels are colored.
|
|
62
|
+
- One primary filled button per screen. Secondary actions are outlined or plain text.
|
|
63
|
+
- Status is said in words and shown in color: "Failed", in `text-destructive`, never a red dot alone.
|
|
64
|
+
- Every text color meets 4.5:1 contrast on its background (3:1 for large text), placeholders included. Disabled controls stay legible and say why they're disabled.
|
|
65
|
+
- Dark mode: the baseline follows the system's setting. Check both if the person may use either.
|
|
66
|
+
- Defaults that make a page look generated: a purple or indigo gradient, glowing buttons, glass panels, cream paper with a serif and a terracotta accent, neon on black, a colored icon in a tinted circle on every card. Use them only when the subject calls for exactly that.
|
|
67
|
+
|
|
68
|
+
## Layout and spacing
|
|
69
|
+
|
|
70
|
+
- Spacing on a 4 px grid (Tailwind's scale): tight inside a group (`gap-2`, `gap-3`), clear between groups (`gap-6`, `gap-8`), more space above a heading than below it.
|
|
71
|
+
- One left edge. Content in a centered column: `max-w-2xl` or `max-w-3xl` for a form or a decision, `max-w-5xl` to `max-w-6xl` for a dashboard, with `px-6` on the sides.
|
|
72
|
+
- Group with space and alignment first, a border second, a shadow rarely. A border or a shadow, never both. No cards inside cards.
|
|
73
|
+
- Cards in one row share their height. Pick the column count from the number of items: four figures in a row of four, not in a three-column grid with an orphan.
|
|
74
|
+
- One radius family (the baseline's `rounded-md` and `rounded-lg`); pills only for small buttons and tags.
|
|
75
|
+
- At 1280 × 800 the block that answers the question is visible without scrolling.
|
|
76
|
+
|
|
77
|
+
## Components and states
|
|
78
|
+
|
|
79
|
+
Build every state a person can meet, then look at each:
|
|
80
|
+
|
|
81
|
+
| State | Do |
|
|
82
|
+
|---|---|
|
|
83
|
+
| Loading | The final layout with gray blocks where values will be (`bg-muted`), no spinner over the page, no layout jump when data arrives |
|
|
84
|
+
| Empty | Keep the block and its heading; one sentence saying why it's empty and what to do ("No priorities yet. Add the first one below.") |
|
|
85
|
+
| Zero | Print it normally: `0`, `€0.00` |
|
|
86
|
+
| Missing | A dash `–` in muted text |
|
|
87
|
+
| Error | Inside the block that failed: what failed, when the data was last good, and a retry. Keep the person's input |
|
|
88
|
+
| Stale | "Updated 09:14" beside the data; a refresh button where it helps |
|
|
89
|
+
| Done | Say what happened ("Sent at 09:20"), and disable what can't happen twice |
|
|
90
|
+
|
|
91
|
+
Every control has hover, focus, active and disabled states. Buttons press slightly (`active:scale-[.97]`) and change color on hover; they don't lift or glow.
|
|
92
|
+
|
|
93
|
+
## Forms and answers
|
|
94
|
+
|
|
95
|
+
- The label sits above the field, always visible; a placeholder is an example, never the label. Inputs at least 40 px tall with `text-base` (16 px), which also keeps iOS from zooming.
|
|
96
|
+
- Group related fields under a `fieldset` with a `legend`. Choices among a few options are radio cards the person can see at once, not a dropdown.
|
|
97
|
+
- Say what's required and what format is expected before they type. Validate inline, next to the field, in plain words ("Enter a date after 1 November"), and tie the message with `aria-describedby`.
|
|
98
|
+
- Use `type="email"`, `inputMode="numeric"`, `autoComplete` and real `<label>`s, so phones and password managers help.
|
|
99
|
+
- Show the selected answer clearly (`has-checked:border-primary`, or `bg-answer` as a mark).
|
|
100
|
+
- One way to save: Mostra saves as they type, so add no Save button for answers. The trusted Submit is the only "done".
|
|
101
|
+
- A destructive action names its object and consequence ("Delete the 3 draft replies"), and asks to confirm, or offers undo.
|
|
102
|
+
|
|
103
|
+
## Numbers, tables and charts
|
|
104
|
+
|
|
105
|
+
- Numbers in tables, figures and anything that updates use `tabular-nums`, align right in columns, and keep a fixed number of decimals per measure. Format with `Intl.NumberFormat` and `Intl.DateTimeFormat`, in the person's locale.
|
|
106
|
+
- Every change names its baseline ("+12% vs last week"). Color says good or bad, not up or down.
|
|
107
|
+
- A figure is label above value: `text-sm text-muted-foreground` then `text-2xl font-semibold`. Several figures share one bordered strip with dividers rather than one card each.
|
|
108
|
+
- Tables: sentence-case headers in `text-sm text-muted-foreground`, thin row borders, no zebra stripes, the identifying column widest and never the one truncated. Truncate with an ellipsis and show the full text on hover or focus. Past about 50 rows, page or virtualize.
|
|
109
|
+
- Charts: one question per chart, one series in `var(--chart-1)` (more in the order of the chart colors, at most four), a few horizontal gridlines, labeled axes, a legend only for more than one series, no 3D, no gradients. Annotate the point the person should notice. A chart with three numbers is better as three numbers.
|
|
110
|
+
|
|
111
|
+
## Motion
|
|
112
|
+
|
|
113
|
+
- Motion is feedback: a press, a hover, a menu opening, a row arriving. A page people work in has no entrance animations.
|
|
114
|
+
- Durations: press 100 to 160 ms, hover and color 150 to 200 ms, menus and popovers 150 to 250 ms, dialogs and drawers 200 to 400 ms. Leaving takes a little less time than arriving.
|
|
115
|
+
- Ease out (`ease-out`, or `cubic-bezier(0.22, 1, 0.36, 1)`), no bounce. Animate `transform` and `opacity`, not size or position; list the properties (`transition-colors`, `transition-transform`), never `transition-all`.
|
|
116
|
+
- Popovers grow from their trigger, never from `scale(0)`. Things people do constantly (typing, keyboard shortcuts) don't animate at all.
|
|
117
|
+
- Respect `prefers-reduced-motion`: keep color and opacity changes, drop movement (`motion-safe:` and `motion-reduce:` in Tailwind, `useReducedMotion` in Motion).
|
|
118
|
+
- Hover effects behind `(hover: hover)` where a hover-only reveal would hide something on a phone.
|
|
119
|
+
|
|
120
|
+
## Accessibility
|
|
121
|
+
|
|
122
|
+
- Real elements: `<button>` for actions, `<a>` for navigation, `<label>` for every input, one `<h1>`, headings in order, `<main>`.
|
|
123
|
+
- Every icon-only button has `aria-label`; decorative icons have `aria-hidden`. Images have `alt`.
|
|
124
|
+
- Visible focus on everything focusable (`focus-visible:` ring; the baseline sets one). Everything works from the keyboard, in reading order.
|
|
125
|
+
- Live values and results that change announce politely (`aria-live="polite"`).
|
|
126
|
+
- Touch targets at least 44 × 44 px on phones.
|
|
127
|
+
- Verify runs axe on every render: critical and serious findings are warnings to fix.
|
|
128
|
+
|
|
129
|
+
## Words on the page
|
|
130
|
+
|
|
131
|
+
- The title says what the page is ("Checkout: which layout ships?"), not "Welcome". A one-line description under it says what you need and by when.
|
|
132
|
+
- Buttons say what they do, in a verb and an object: "Send my decision", "Approve the plan", "Add". Not "Submit", "OK" or "Click here".
|
|
133
|
+
- Use the task's own words for things, not "items" or "records". Say each thing once.
|
|
134
|
+
- No marketing words (seamless, effortless, unlock, supercharge) and no emoji as icons.
|
|
135
|
+
|
|
136
|
+
## Phones
|
|
137
|
+
|
|
138
|
+
- Check the 390 × 844 screenshot every time. One column; side padding `px-4` to `px-6`; nothing scrolls sideways.
|
|
139
|
+
- Rows of cards stack; tables become two-line rows (the identity and key number first, the rest smaller beneath) or scroll inside their own frame.
|
|
140
|
+
- The main action stays reachable without hunting.
|
|
141
|
+
|
|
142
|
+
## Reading your screenshots
|
|
143
|
+
|
|
144
|
+
Open both screenshots after every verify, and check:
|
|
145
|
+
|
|
146
|
+
1. Is the biggest, first thing the answer to the page's question?
|
|
147
|
+
2. Do the blocks share one left edge and one right edge? Any orphan card, ragged row or empty band?
|
|
148
|
+
3. Is color only on data, status, the chosen answer and one primary action?
|
|
149
|
+
4. Do numbers line up, add up, and name their baselines?
|
|
150
|
+
5. Does every empty, zero and loading value look like what it is?
|
|
151
|
+
6. Does each label, legend and caption match what it labels, with nothing colliding or cut off?
|
|
152
|
+
7. On the phone, does every block still work, with nothing sideways?
|
|
153
|
+
|
|
154
|
+
Fix the worst problems first, verify again, and look again. Two or three rounds are usually enough; stop when the screenshot shows what you meant.
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
# Libraries: what's preinstalled, and what changed in them
|
|
2
|
+
|
|
3
|
+
Every artifact can import these without any install; they share one React. Anything else on npm installs on demand ([page.md](page.md#packages)).
|
|
4
|
+
|
|
5
|
+
## Contents
|
|
6
|
+
|
|
7
|
+
- The preinstalled set
|
|
8
|
+
- Write this, not that
|
|
9
|
+
- UI primitives: Base UI
|
|
10
|
+
- Tables: TanStack Table 9
|
|
11
|
+
- Charts
|
|
12
|
+
- Motion
|
|
13
|
+
|
|
14
|
+
## The preinstalled set
|
|
15
|
+
|
|
16
|
+
| Need | Package (version line) | Import |
|
|
17
|
+
|---|---|---|
|
|
18
|
+
| React | `react`, `react-dom` 19 | `import { useState } from "react"` |
|
|
19
|
+
| Routing for `pages/` | `react-router` 8 | `import { Link, useParams } from "react-router"` |
|
|
20
|
+
| Styling | `tailwindcss` 4, `cn` | utility classes; `import { cn } from "cn"` to merge class names |
|
|
21
|
+
| UI primitives | `@base-ui/react` 1 (default), `radix-ui` 1 | `import { Dialog } from "@base-ui/react/dialog"` |
|
|
22
|
+
| Forms and validation | `react-hook-form` 7, `@hookform/resolvers` 5, `zod` 4 | through `@mostra/react/form` ([answers.md](answers.md#forms-with-react-hook-form)) |
|
|
23
|
+
| Icons | `lucide-react` 1 | `import { Check } from "lucide-react"` |
|
|
24
|
+
| Charts | `recharts` 3, `echarts` 6, `uplot` 1 | see [Charts](#charts) |
|
|
25
|
+
| Tables | `@tanstack/react-table` 9 | see [Tables](#tables-tanstack-table-9) |
|
|
26
|
+
| Motion | `motion` 14 | `import { motion, AnimatePresence } from "motion/react"` |
|
|
27
|
+
| Diagrams | `mermaid` 12, `@xyflow/react` 12 | |
|
|
28
|
+
| Code | `shiki` 4 (display), `codemirror` 6 and `@codemirror/*` (editing) | |
|
|
29
|
+
| Math | `katex` | |
|
|
30
|
+
| Terminal output | `@xterm/xterm` and its addons | |
|
|
31
|
+
| Smaller pieces | `sonner` (toasts), `vaul` (drawers), `cmdk` (command menu), `embla-carousel-react`, `react-day-picker`, `input-otp`, `react-resizable-panels` | |
|
|
32
|
+
|
|
33
|
+
Maps, 3D and whiteboards (MapLibre, deck.gl, react-three-fiber, Excalidraw) install on demand when imported.
|
|
34
|
+
|
|
35
|
+
## Write this, not that
|
|
36
|
+
|
|
37
|
+
Several of these had a major release recently, so older habits break the build or silently do nothing:
|
|
38
|
+
|
|
39
|
+
| Write this | Not that | Why |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| `@import "tailwindcss";` at the top of a stylesheet, theme in `@theme` | `tailwind.config.js`, `@tailwind base;` | Tailwind 4 is configured in CSS |
|
|
42
|
+
| `shadow-xs`, `rounded-xs`, `blur-xs` | `shadow-sm`, `rounded-sm`, `blur-sm` for the smallest size | Tailwind 4 renamed the scale: `-sm` is now one step larger |
|
|
43
|
+
| `outline-hidden` | `outline-none` to hide a focus outline | Tailwind 4 renamed it; `outline-none` now really removes it |
|
|
44
|
+
| `ring-3` | `ring` for a 3 px ring | `ring` is 1 px in Tailwind 4 |
|
|
45
|
+
| `bg-black/50`, `shrink-0`, `grow`, `text-ellipsis` | `bg-opacity-50`, `flex-shrink-0`, `flex-grow`, `overflow-ellipsis` | Removed in Tailwind 4 |
|
|
46
|
+
| `bg-linear-to-r` | `bg-gradient-to-r` | Renamed in Tailwind 4 |
|
|
47
|
+
| `bg-(--brand)` | `bg-[--brand]` | CSS variables in arbitrary values use parentheses |
|
|
48
|
+
| `border border-border` (or the baseline stylesheet) | a bare `border` expecting light gray | Tailwind 4 borders default to the text color |
|
|
49
|
+
| `flex! hover:bg-muted!` | `!flex` | The important mark goes at the end |
|
|
50
|
+
| `import { motion } from "motion/react"` | `import { motion } from "framer-motion"` | Framer Motion is now Motion |
|
|
51
|
+
| `import { Link } from "react-router"` | `"react-router-dom"` | One package since React Router 7 |
|
|
52
|
+
| `z.email()`, `z.url()`, `z.uuid()` | `z.string().email()` | Zod 4 top-level formats |
|
|
53
|
+
| `z.string().min(1, { error: "Required" })` or `.min(1, "Required")` | `{ message: "Required" }` | Zod 4 calls it `error`; `message` still works but is deprecated |
|
|
54
|
+
| `import * as z from "zod"` | `import { z } from "zod/v3"` | Zod 4 is the default |
|
|
55
|
+
| `<Dialog.Trigger render={<Button />}>` | `<Dialog.Trigger asChild>` | Base UI composes with `render`; `asChild` is Radix's |
|
|
56
|
+
| `function Input({ ref, ...props })` | `forwardRef(...)` | React 19 passes `ref` as a prop |
|
|
57
|
+
| `useTable({ features, columns, data })` | `useReactTable({ getCoreRowModel: getCoreRowModel(), … })` | TanStack Table 9 |
|
|
58
|
+
|
|
59
|
+
## UI primitives: Base UI
|
|
60
|
+
|
|
61
|
+
Base UI is unstyled and accessible; style it with utilities. Each component is a namespace of parts, imported from its own path:
|
|
62
|
+
|
|
63
|
+
```tsx
|
|
64
|
+
import { Dialog } from "@base-ui/react/dialog";
|
|
65
|
+
|
|
66
|
+
function PlanDialog() {
|
|
67
|
+
return (
|
|
68
|
+
<Dialog.Root>
|
|
69
|
+
<Dialog.Trigger render={<button type="button" className="rounded-full bg-primary px-4 py-2 text-sm text-primary-foreground" />}>
|
|
70
|
+
Review the plan
|
|
71
|
+
</Dialog.Trigger>
|
|
72
|
+
<Dialog.Portal>
|
|
73
|
+
<Dialog.Backdrop className="fixed inset-0 bg-black/40" />
|
|
74
|
+
<Dialog.Popup className="fixed top-1/2 left-1/2 w-96 -translate-1/2 rounded-lg bg-card p-6">
|
|
75
|
+
<Dialog.Title className="font-medium">The plan</Dialog.Title>
|
|
76
|
+
<Dialog.Description className="mt-2 text-sm text-muted-foreground">Three hires in Q4, two in engineering.</Dialog.Description>
|
|
77
|
+
<Dialog.Close className="mt-4 rounded-md border px-3 py-1.5 text-sm">Close</Dialog.Close>
|
|
78
|
+
</Dialog.Popup>
|
|
79
|
+
</Dialog.Portal>
|
|
80
|
+
</Dialog.Root>
|
|
81
|
+
);
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Others: `accordion`, `alert-dialog`, `checkbox`, `collapsible`, `combobox`, `menu`, `popover`, `radio-group`, `select`, `slider`, `switch`, `tabs`, `toggle`, `tooltip` and more, each at `@base-ui/react/<name>`. Radix works too (`import { Dialog } from "radix-ui"`); keep one of them per artifact.
|
|
86
|
+
|
|
87
|
+
## Tables: TanStack Table 9
|
|
88
|
+
|
|
89
|
+
Version 9 declares the features a table uses, then `useTable`:
|
|
90
|
+
|
|
91
|
+
```tsx
|
|
92
|
+
import { createColumnHelper, createSortedRowModel, FlexRender, rowSortingFeature, sortFns, tableFeatures, useTable } from "@tanstack/react-table";
|
|
93
|
+
|
|
94
|
+
interface Invoice { id: string; customer: string; amount: number }
|
|
95
|
+
|
|
96
|
+
const euros = new Intl.NumberFormat("en", { style: "currency", currency: "EUR" });
|
|
97
|
+
|
|
98
|
+
const features = tableFeatures({ rowSortingFeature, sortedRowModel: createSortedRowModel(), sortFns });
|
|
99
|
+
const column = createColumnHelper<typeof features, Invoice>();
|
|
100
|
+
const columns = column.columns([
|
|
101
|
+
column.accessor("id", { header: "Invoice" }),
|
|
102
|
+
column.accessor("customer", { header: "Customer" }),
|
|
103
|
+
column.accessor("amount", { header: "Amount", cell: (info) => euros.format(info.getValue()) }),
|
|
104
|
+
]);
|
|
105
|
+
|
|
106
|
+
function Invoices({ data }: { data: Invoice[] }) {
|
|
107
|
+
const table = useTable({ features, columns, data });
|
|
108
|
+
return (
|
|
109
|
+
<table className="w-full text-sm">
|
|
110
|
+
<thead>
|
|
111
|
+
{table.getHeaderGroups().map((group) => (
|
|
112
|
+
<tr key={group.id}>
|
|
113
|
+
{group.headers.map((header) => (
|
|
114
|
+
<th key={header.id} className="text-left font-normal text-muted-foreground">
|
|
115
|
+
<button type="button" onClick={header.column.getToggleSortingHandler()}><FlexRender header={header} /></button>
|
|
116
|
+
</th>
|
|
117
|
+
))}
|
|
118
|
+
</tr>
|
|
119
|
+
))}
|
|
120
|
+
</thead>
|
|
121
|
+
<tbody>
|
|
122
|
+
{table.getRowModel().rows.map((row) => (
|
|
123
|
+
<tr key={row.id} className="border-t">
|
|
124
|
+
{row.getAllCells().map((cell) => <td key={cell.id} className="py-2"><FlexRender cell={cell} /></td>)}
|
|
125
|
+
</tr>
|
|
126
|
+
))}
|
|
127
|
+
</tbody>
|
|
128
|
+
</table>
|
|
129
|
+
);
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Filtering, pagination and selection are features too (`columnFilteringFeature` with `createFilteredRowModel()`, and so on). Code written for version 8 runs through `useLegacyTable`, but new code uses `useTable`. A plain `<table>` over an array is often enough.
|
|
134
|
+
|
|
135
|
+
## Charts
|
|
136
|
+
|
|
137
|
+
- **Recharts** for most charts. Wrap in `<ResponsiveContainer width="100%" height="100%">` inside a parent with a fixed height (`h-56`), and color series with the theme's chart colors: `fill="var(--chart-1)"`, `stroke="var(--border)"` for gridlines.
|
|
138
|
+
- **uPlot** for thousands of points updating several times a second (a live latency trace from `useLive(key, { mode: "append" })`).
|
|
139
|
+
- **ECharts** for chart types Recharts lacks (heat maps, Sankey, treemaps, geographic maps).
|
|
140
|
+
|
|
141
|
+
A chart reaches the ARIA snapshot (and screen readers) as little more than its axis labels, so give it a heading and, where the numbers matter, the key values in text beside it.
|
|
142
|
+
|
|
143
|
+
## Motion
|
|
144
|
+
|
|
145
|
+
```tsx
|
|
146
|
+
import { useState } from "react";
|
|
147
|
+
import { AnimatePresence, motion, useReducedMotion } from "motion/react";
|
|
148
|
+
|
|
149
|
+
function Details() {
|
|
150
|
+
const [open, setOpen] = useState(false);
|
|
151
|
+
const reduce = useReducedMotion();
|
|
152
|
+
return (
|
|
153
|
+
<div>
|
|
154
|
+
<button type="button" aria-expanded={open} onClick={() => setOpen(!open)}>Details</button>
|
|
155
|
+
<AnimatePresence>
|
|
156
|
+
{open && (
|
|
157
|
+
<motion.p initial={{ opacity: 0, y: reduce ? 0 : 4 }} animate={{ opacity: 1, y: 0 }} exit={{ opacity: 0 }} transition={{ duration: 0.18, ease: "easeOut" }}>
|
|
158
|
+
Built from Friday's numbers.
|
|
159
|
+
</motion.p>
|
|
160
|
+
)}
|
|
161
|
+
</AnimatePresence>
|
|
162
|
+
</div>
|
|
163
|
+
);
|
|
164
|
+
}
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Motion animates CSS variables too (`animate={{ backgroundColor: "var(--muted)" }}`). Keep durations and easing to [design.md](design.md#motion).
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
# Long-lived pages: shared state, live data, always on
|
|
2
|
+
|
|
3
|
+
A dashboard open all week, a task list a team works through, a status page you keep updating: these pages don't end in one submission. They use the `none` policy (no Submit), shared fields, live sources, actions and signals.
|
|
4
|
+
|
|
5
|
+
## Contents
|
|
6
|
+
|
|
7
|
+
- Shared state
|
|
8
|
+
- Live data
|
|
9
|
+
- Talking without a Submit
|
|
10
|
+
- New versions of a page people keep open
|
|
11
|
+
- Always on
|
|
12
|
+
|
|
13
|
+
## Shared state
|
|
14
|
+
|
|
15
|
+
A field with `scope: "artifact"` is shared: every viewer sees and edits the same value, and so can you from the command line.
|
|
16
|
+
|
|
17
|
+
```tsx
|
|
18
|
+
import { useField } from "@mostra/react";
|
|
19
|
+
|
|
20
|
+
type Task = { id: string; title: string; done: boolean };
|
|
21
|
+
|
|
22
|
+
function Tasks() {
|
|
23
|
+
const [tasks, setTasks, meta] = useField("tasks", [] as Task[], { label: "Tasks", scope: "artifact" });
|
|
24
|
+
// meta.updatedBy: { kind: "viewer" | "agent" | "host", name? } of the last change
|
|
25
|
+
const toggle = (id: string) =>
|
|
26
|
+
setTasks((list) => list.map((task) => (task.id === id ? { ...task, done: !task.done } : task)));
|
|
27
|
+
return (
|
|
28
|
+
<ul>
|
|
29
|
+
{tasks.map((task) => (
|
|
30
|
+
<li key={task.id}>
|
|
31
|
+
<label>
|
|
32
|
+
<input type="checkbox" checked={task.done} onChange={() => toggle(task.id)} /> {task.title}
|
|
33
|
+
</label>
|
|
34
|
+
</li>
|
|
35
|
+
))}
|
|
36
|
+
{meta.updatedBy && <li className="text-sm text-muted-foreground">Last changed by {meta.updatedBy.name ?? meta.updatedBy.kind}</li>}
|
|
37
|
+
</ul>
|
|
38
|
+
);
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
```sh
|
|
43
|
+
mostra state get ./tasks # every shared field, with the revision
|
|
44
|
+
mostra state set ./tasks priorities '["Ship the CLI"]' # one field, as the agent
|
|
45
|
+
mostra state patch ./tasks --ops '[{"id":"tasks","value":[]},{"id":"old","delete":true}]'
|
|
46
|
+
mostra state set ./tasks priorities '["Ship the CLI","Fix #12"]' --base 41 # only if unchanged since revision 41, else exit 6
|
|
47
|
+
mostra wait ./tasks --until state:tasks --timeout 1h # when a person changes it
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
- Writes are compare-and-set per field. Two writers changing the same field get a conflict, never a silent overwrite: the page shows `meta.conflict`, and the CLI exits 6 when `--base` is stale. Read again, merge, write again.
|
|
51
|
+
- Server code writes the same fields with `state.set(id, value)` and `state.patch(ops)` from `@mostra/server`.
|
|
52
|
+
- A person's own fields (the default `scope: "viewer"`) stay private to their link; shared fields are the same for everyone.
|
|
53
|
+
|
|
54
|
+
## Live data
|
|
55
|
+
|
|
56
|
+
A live source is a value that updates without a new version: prices, build status, a feed. Define producers in `live.ts` (this exact name):
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
// live.ts
|
|
60
|
+
import { readFile } from "node:fs/promises";
|
|
61
|
+
import { defineLive, secret } from "@mostra/server";
|
|
62
|
+
|
|
63
|
+
export const builds = defineLive({
|
|
64
|
+
refresh: "30s", // load again every 30 s while someone looks
|
|
65
|
+
load: async () => {
|
|
66
|
+
const response = await fetch("https://ci.example/api/builds", {
|
|
67
|
+
headers: { authorization: `Bearer ${secret("CI_TOKEN")}` },
|
|
68
|
+
});
|
|
69
|
+
return (await response.json()) as { passing: number; failing: number };
|
|
70
|
+
},
|
|
71
|
+
});
|
|
72
|
+
|
|
73
|
+
export const latency = defineLive({
|
|
74
|
+
ring: 600, // keep the last 600 values for charts
|
|
75
|
+
stream: async function* (signal) {
|
|
76
|
+
while (!signal.aborted) {
|
|
77
|
+
const started = performance.now();
|
|
78
|
+
await fetch("https://api.example/health", { signal });
|
|
79
|
+
yield { at: Date.now(), ms: Math.round(performance.now() - started) };
|
|
80
|
+
await new Promise((resolve) => setTimeout(resolve, 1000));
|
|
81
|
+
}
|
|
82
|
+
},
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
export const config = defineLive({ // load again when a watched file changes
|
|
86
|
+
watch: "data/*.json",
|
|
87
|
+
load: async () => JSON.parse(await readFile("data/config.json", "utf8")) as Record<string, unknown>,
|
|
88
|
+
});
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
```tsx
|
|
92
|
+
import { useLive } from "@mostra/react";
|
|
93
|
+
|
|
94
|
+
function Builds() {
|
|
95
|
+
const builds = useLive("builds"); // { data, isLoading, error, refresh(), revision, at }
|
|
96
|
+
const latency = useLive("latency", { mode: "append", window: 300 }); // data: the last 300 values
|
|
97
|
+
if (builds.isLoading) return <p>Loading builds…</p>;
|
|
98
|
+
return (
|
|
99
|
+
<p>
|
|
100
|
+
{builds.data?.passing} passing, {builds.data?.failing} failing; {latency.data?.length ?? 0} latency samples
|
|
101
|
+
</p>
|
|
102
|
+
);
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
- A source needs `load`, `stream` or both. `refresh` is `1s` to `24h`. `always: true` keeps it running with nobody looking; otherwise producers run while a page shows the source and stop a minute after.
|
|
107
|
+
- The latest value is kept, so a page opening later shows it at once, with `at` saying when it was produced. A failing producer sets `error` and keeps the last good value; show both.
|
|
108
|
+
- `useLive` keys and value types come from `live.ts` automatically.
|
|
109
|
+
- You can feed a source from outside too, with no `live.ts` entry needed: `mostra push ./dash deploys --value '{"today":14}'`, or `--append` to add to its ring. Values are up to 4 MiB. Before its first push such a source isn't loading: `data` is `undefined` and `isLoading` is false, so show an empty state ("No deploys pushed yet").
|
|
110
|
+
- When the artifact also has a `live.ts`, `useLive` only takes the keys it defines, so declare a pushed key's type in a file of its own:
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
// pushed.d.ts
|
|
114
|
+
import "@mostra/react";
|
|
115
|
+
|
|
116
|
+
declare module "@mostra/react" {
|
|
117
|
+
interface LiveSources {
|
|
118
|
+
deploys: { today: number };
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
- Live updates aren't events: nothing wakes you when they change.
|
|
123
|
+
|
|
124
|
+
## Talking without a Submit
|
|
125
|
+
|
|
126
|
+
With `{ policy: "none" }` the page has no Submit. It talks to you through:
|
|
127
|
+
|
|
128
|
+
- shared fields you watch with `mostra wait <dir> --until state:<fieldId>`;
|
|
129
|
+
- signals the page sends (`useSignal`) or server code raises (`signal()`), watched with `mostra wait <dir> --until signal:<name>`, which prints each signal's payload;
|
|
130
|
+
- actions that do the work themselves ([server.md](server.md)).
|
|
131
|
+
|
|
132
|
+
`mostra wait <dir> --until submitted` is refused under `none` (`MOSTRA_SUBMIT_POLICY_NONE`), and `mostra results` has no submission to show: read what the page keeps with `mostra state get <dir>`.
|
|
133
|
+
|
|
134
|
+
## New versions of a page people keep open
|
|
135
|
+
|
|
136
|
+
Publishing again shows a banner on open pages: "Switch", "Always follow this artifact" and "Later". A person who chose to follow gets new versions by themselves, unless they have unsaved edits or answers that wouldn't carry over. Keep field IDs stable so nothing is left behind.
|
|
137
|
+
|
|
138
|
+
## Always on
|
|
139
|
+
|
|
140
|
+
Mostra's background process stops after 30 idle minutes, and links stop answering until a command starts it again. A page that must answer at any hour needs the login service:
|
|
141
|
+
|
|
142
|
+
```sh
|
|
143
|
+
mostra daemon install # launchd on macOS, systemd on Linux, Task Scheduler on Windows
|
|
144
|
+
mostra daemon status
|
|
145
|
+
mostra doctor # warns about `none` pages in a home without it
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`mostra daemon uninstall` removes it again.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Mostra's MCP server: the same loop through tools
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
- When to use the tools
|
|
6
|
+
- The loop, tool by tool
|
|
7
|
+
- Files and directories
|
|
8
|
+
- Waiting and results
|
|
9
|
+
- Links for people
|
|
10
|
+
- Through a Mostra server in a chat app
|
|
11
|
+
- Long-lived pages
|
|
12
|
+
- Adding the server to a client
|
|
13
|
+
|
|
14
|
+
## When to use the tools
|
|
15
|
+
|
|
16
|
+
Use Mostra's tools when they're in your tool list (`artifact_create`, `artifact_verify` and the rest): a client starts the server for you, so nothing needs installing, and you need no shell. Each step of the loop in [SKILL.md](../SKILL.md) has its tool, and everything the Skill says about pages, fields, design and verify holds unchanged. Read any part of this guide with `docs_search` and a `topic` (`guide`, `guide/answers`, a diagnostic code), or a `query` of a few words.
|
|
17
|
+
|
|
18
|
+
## The loop, tool by tool
|
|
19
|
+
|
|
20
|
+
| Step | Command | Tool |
|
|
21
|
+
|---|---|---|
|
|
22
|
+
| Create | `mostra new <dir>` | `artifact_create` with a `title` (and a `dir`, or one is made for you) |
|
|
23
|
+
| Write | your own file tools | `artifact_write` (whole files), `artifact_patch` (exact replacements or a unified diff) |
|
|
24
|
+
| Verify | `mostra verify <dir>` | `artifact_verify`; `screenshots: "always"` returns both screenshots as images |
|
|
25
|
+
| Publish | `mostra publish <dir>` | `artifact_publish`; its `url` is the default link |
|
|
26
|
+
| Hand out the link | `mostra open <dir> --browser` | `artifact_open` |
|
|
27
|
+
| Wait | `mostra wait <dir> --until submitted` | `artifact_wait` with `until: "submitted"` |
|
|
28
|
+
| Read the answers | `mostra results <dir>` | `artifact_results` (Markdown; `format: "json"` for the full structure) |
|
|
29
|
+
|
|
30
|
+
A tool that fails returns `isError` with `{ "error": <diagnostic> }`: its `code`, `hint` and `docs` mean what the same code means anywhere in this guide. Fix what the hint says and call again.
|
|
31
|
+
|
|
32
|
+
The first time the server runs on a computer, it installs Mostra's runtime in the background (a few minutes on a slow connection). A tool called meanwhile answers `MOSTRA_ENV_RUNTIME_INSTALLING` with how far it is: write the page in the meantime (`artifact_write` and `docs_search` already work), then call the tool again.
|
|
33
|
+
|
|
34
|
+
## Files and directories
|
|
35
|
+
|
|
36
|
+
`artifact_create` returns the artifact's `dir` and its `artifactId`; pass either to the other tools. A relative `dir` is inside the server's workspace folder, which its instructions name. Paths in `artifact_write` and `artifact_patch` are relative to the artifact's directory (`index.tsx`, `components/chart.tsx`), and a tool only ever changes files inside it. Names are ones every system can hold, so the artifact moves between macOS, Linux and Windows whole: no `<>:"|?*`, no device name such as `CON` or `NUL`, no dot or space at the end, and two names that differ only in case are one file.
|
|
37
|
+
|
|
38
|
+
When you also have your own file tools on the same computer, use whichever you like for the files: verify and publish read the directory as it is.
|
|
39
|
+
|
|
40
|
+
`artifact_write` and `artifact_patch` apply all or nothing. When an `old` text appears twice, or a diff's lines don't match the file, nothing is written and `rejected` names each edit or hunk and why; read the file again and send a patch that fits.
|
|
41
|
+
|
|
42
|
+
## Waiting and results
|
|
43
|
+
|
|
44
|
+
`artifact_wait` waits at most 50 seconds per call. When it returns `still_waiting`, nothing is lost: call it again with `after` set to the `cursor` it returned, or do other work and check later. Under `once`, a wait for `submitted` returns at once when the person already submitted. `artifact_results` returns the latest submission; `MOSTRA_SUBMIT_NOT_FOUND` means nobody has submitted yet. A page with the `none` policy never has one: read its shared state with `state_get`, and wait for its signals with `until: "signal:<name>"`, whose event carries the payload the page sent (`event.payload.payload`).
|
|
45
|
+
|
|
46
|
+
## Links for people
|
|
47
|
+
|
|
48
|
+
`artifact_open` returns the artifact's default link. A link made without `viewer` is shared by everyone who holds it: they edit one draft and have one `once` submission between them. For several people, call `artifact_open` once per person with `viewer: { ref, name }` and give each their own link (with `{ policy: "once", scope: "per-viewer" }` each submits once). `ttl`, `scopes` and `version` make a new link that expires, allows less, or opens one version, as in [sharing.md](sharing.md). `open: true` also opens the link in a browser on this computer, for the person sitting at it.
|
|
49
|
+
|
|
50
|
+
A local server's links open on this computer only: to reach someone elsewhere, share the page as [sharing.md](sharing.md) shows. Through a Mostra server (a chat app's connector), links open anywhere: `artifact_publish` and `artifact_open` return the hosted link, `https://` and a server's address ending in `/a/rte_…`.
|
|
51
|
+
|
|
52
|
+
## Through a Mostra server in a chat app
|
|
53
|
+
|
|
54
|
+
A chat app's connector reaches the person's own computer through their Mostra server. Creating, writing, verifying and publishing run there, in its workspace, so that computer must be on with Mostra running; otherwise those tools answer `MOSTRA_REMOTE_NO_INSTANCE`, while listing, waiting and reading results keep working. Answers people send wait on the server while that computer sleeps, and reach it when it's back.
|
|
55
|
+
|
|
56
|
+
## Long-lived pages
|
|
57
|
+
|
|
58
|
+
`state_get` and `state_patch` read and change the artifact's shared state (fields with `scope: "artifact"`), as `mostra state` does; `live_push` pushes a value to a live source, as `mostra push` does. See [long-lived.md](long-lived.md).
|
|
59
|
+
|
|
60
|
+
## Adding the server to a client
|
|
61
|
+
|
|
62
|
+
A client starts the server as `mostra mcp` over stdio, or `npx -y @mostra/cli@0.12.0 mcp` where `mostra` isn't installed. Its configuration names that command, for example:
|
|
63
|
+
|
|
64
|
+
```json
|
|
65
|
+
{ "mcpServers": { "mostra": { "command": "npx", "args": ["-y", "@mostra/cli@0.12.0", "mcp"] } } }
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
For a client that speaks only HTTP, `mostra mcp --http` serves Streamable HTTP on `127.0.0.1` and prints its URL and a token on stderr; every request sends `Authorization: Bearer <token>` (set `MOSTRA_MCP_TOKEN` to choose it). `--workspace <dir>` chooses where new artifacts go.
|