@mostra/runtime 0.9.0 → 0.11.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 +6628 -9
- package/dist/bin.js.map +1 -1
- package/dist/builder/child/main.js +2 -2
- package/dist/{child-Chiavhdx.js → child-BmNZ4a70.js} +2 -2
- package/dist/{child-Chiavhdx.js.map → child-BmNZ4a70.js.map} +1 -1
- package/dist/deps/child/install.js +1 -1
- package/dist/{directories-mJ1qlVht.js → directories-BLJjeSPD.js} +5 -5
- package/dist/directories-BLJjeSPD.js.map +1 -0
- package/dist/{files-FygSJIzK.js → files-DGeWuE4I.js} +2 -2
- package/dist/{files-FygSJIzK.js.map → files-DGeWuE4I.js.map} +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -2
- package/dist/{instance-EnaZPs14.js → instance-DCiUHvgZ.js} +3835 -255
- package/dist/instance-DCiUHvgZ.js.map +1 -0
- package/dist/reference/cli.md +1322 -0
- package/dist/reference/diagnostics.json +1552 -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_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 +122 -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 +217 -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/verify.md +71 -0
- package/package.json +12 -5
- package/src/actions/index.ts +163 -10
- package/src/bin.ts +78 -1
- package/src/gateway/actions.ts +40 -4
- package/src/gateway/browser.ts +162 -95
- package/src/gateway/capabilities.ts +23 -6
- package/src/gateway/http.ts +12 -1
- package/src/gateway/index.ts +282 -20
- package/src/gateway/listener.ts +31 -6
- package/src/gateway/routes.ts +23 -7
- package/src/gc/index.ts +19 -0
- package/src/instance/index.ts +60 -2
- package/src/interaction/ephemeral.ts +32 -23
- package/src/interaction/events.ts +21 -1
- package/src/interaction/imports.ts +317 -0
- package/src/interaction/index.ts +228 -15
- package/src/interaction/outbox.ts +9 -0
- package/src/interaction/pause.ts +106 -0
- package/src/interaction/results.ts +8 -1
- package/src/interaction/runs.ts +52 -2
- package/src/interaction/submissions.ts +59 -2
- package/src/interaction/tally.ts +129 -0
- package/src/interaction/viewers.ts +34 -1
- package/src/ledger/index.ts +124 -10
- package/src/ledger/migrations.ts +234 -0
- package/src/ledger/types.ts +8 -0
- package/src/link/author.ts +215 -0
- package/src/link/binding.ts +289 -0
- package/src/link/hosted.ts +101 -0
- package/src/link/http.ts +141 -0
- package/src/link/index.ts +10 -0
- package/src/link/manager.ts +1489 -0
- package/src/link/relay.ts +512 -0
- package/src/live/index.ts +112 -2
- package/src/platform/filesystems.ts +78 -0
- package/src/platform/index.ts +1 -0
- package/src/protocol-server/client.ts +53 -0
- package/src/protocol-server/index.ts +19 -2
- package/src/protocol-server/server.ts +38 -7
- package/src/protocol-server/websocket.ts +161 -0
- package/src/publish/bundle.ts +398 -0
- package/src/publish/manifest.ts +9 -0
- package/src/publish/methods.ts +12 -1
- package/src/publish/publisher.ts +127 -0
- package/src/registry/index.ts +35 -14
- package/src/server/api.ts +881 -0
- package/src/server/auth.ts +1139 -0
- package/src/server/authorize.ts +816 -0
- package/src/server/clients.ts +235 -0
- package/src/server/config.ts +228 -0
- package/src/server/data.ts +427 -0
- package/src/server/directory.ts +210 -0
- package/src/server/feed.ts +191 -0
- package/src/server/handle.ts +172 -0
- package/src/server/hosted-pages.ts +532 -0
- package/src/server/hosted.ts +1323 -0
- package/src/server/index.ts +650 -0
- 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 +498 -0
- package/src/server/providers.ts +284 -0
- package/src/server/relay.ts +1163 -0
- package/src/server/remove.ts +148 -0
- package/src/server/routing.ts +275 -0
- package/src/share/index.ts +110 -6
- package/src/verify/runner.ts +23 -2
- package/dist/directories-mJ1qlVht.js.map +0 -1
- package/dist/instance-EnaZPs14.js.map +0 -1
|
@@ -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.11.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.11.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.
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
# The artifact: files, manifest, pages and packages
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
- Files
|
|
6
|
+
- The manifest
|
|
7
|
+
- Pages
|
|
8
|
+
- Packages
|
|
9
|
+
- Styles and assets
|
|
10
|
+
- MDX
|
|
11
|
+
- Who and where: `useViewer`, `useArtifact`
|
|
12
|
+
- Sending the person elsewhere: `openLink`
|
|
13
|
+
- Pages written for Claude: `window.storage`
|
|
14
|
+
|
|
15
|
+
## Files
|
|
16
|
+
|
|
17
|
+
An artifact is a directory (or a single `.tsx`, `.jsx` or `.mdx` file). No `package.json`, `tsconfig.json` or build configuration is needed; Mostra brings its own.
|
|
18
|
+
|
|
19
|
+
```text
|
|
20
|
+
my-artifact/
|
|
21
|
+
index.tsx the entry: `export const artifact = defineArtifact({...})` and the page as the default export
|
|
22
|
+
AGENTS.md what `mostra new` wrote for agents editing this artifact
|
|
23
|
+
pages/ optional routes, see Pages
|
|
24
|
+
actions.ts any module whose first statement is "use server" (the name is free), see server.md
|
|
25
|
+
live.ts live data sources (this exact name), see long-lived.md
|
|
26
|
+
components/ anything else you import
|
|
27
|
+
public/ files served as they are, at /<name>
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
A directory has exactly one entry: `index.tsx`, `index.jsx` or `index.mdx`. `node_modules`, `.git`, `.mostra`, editor backups and paths listed in a `.mostraignore` file stay out of the published source.
|
|
31
|
+
|
|
32
|
+
## The manifest
|
|
33
|
+
|
|
34
|
+
```tsx
|
|
35
|
+
import { defineArtifact } from "@mostra/react";
|
|
36
|
+
|
|
37
|
+
export const artifact = defineArtifact({
|
|
38
|
+
id: "art_01M66HS31X56AW7VKS2JV1C9N7", // written by `mostra new`; keep it
|
|
39
|
+
title: "Q4 hiring plan", // required when a manifest is present
|
|
40
|
+
description: "Approve or change the plan for next quarter.",
|
|
41
|
+
family: "proposal", // questionnaire, proposal, prototype, review, dashboard, deck, demo, inbox, tasks, or your own word
|
|
42
|
+
submission: { policy: "once" }, // see answers.md; the host running Mostra may override it
|
|
43
|
+
links: [{ rel: "round-of", artifact: "art_…" }],
|
|
44
|
+
limits: { heapMb: 1024, watchdogMs: 10000, idleMinutes: 10 },
|
|
45
|
+
});
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
- Every value is a literal (`as const` and `satisfies` are fine). Mostra reads the manifest without running your code; a computed value is `MOSTRA_MANIFEST_NOT_LITERAL`.
|
|
49
|
+
- `artifact.title` and the other fields are usable in the page (`<h1>{artifact.title}</h1>`).
|
|
50
|
+
- An artifact without an `id` is bound to its directory at its first publish. Copying a directory that carries an `id` makes two sources claim one artifact (`MOSTRA_PUBLISH_ID_CONFLICT`): give the copy a new one with `mostra new`.
|
|
51
|
+
- An entry without any manifest publishes with defaults, titled after its directory.
|
|
52
|
+
|
|
53
|
+
## Pages
|
|
54
|
+
|
|
55
|
+
With a `pages/` directory every `.tsx`, `.jsx` or `.mdx` file in it is a route:
|
|
56
|
+
|
|
57
|
+
| File | Route |
|
|
58
|
+
|---|---|
|
|
59
|
+
| `pages/index.tsx` | `/` |
|
|
60
|
+
| `pages/settings.tsx` | `/settings` |
|
|
61
|
+
| `pages/reports/index.tsx` | `/reports` |
|
|
62
|
+
| `pages/reports/[id].tsx` | `/reports/:id` |
|
|
63
|
+
| `pages/docs/[...rest].tsx` | `/docs/*` |
|
|
64
|
+
|
|
65
|
+
The entry's default export then becomes the layout every page renders inside, receiving the page as `children`. Link between pages with React Router's `Link` (`import { Link, useParams } from "react-router"`). Fields work the same on every page: they belong to the artifact, not to a route.
|
|
66
|
+
|
|
67
|
+
## Packages
|
|
68
|
+
|
|
69
|
+
- Import any npm package by name. Packages in the warm set ([libraries.md](libraries.md)) resolve instantly; any other is installed on demand at the newest release at least a day old, pinned exactly, and frozen into the version at publish.
|
|
70
|
+
- `mostra add <package>[@version] --artifact <dir>` pins a version yourself, before you import it.
|
|
71
|
+
- Imports must stay inside the artifact: `../shared/x` is refused (`MOSTRA_BUILD_UNRESOLVED`). Use `@/components/x` for a path from the artifact's root.
|
|
72
|
+
- A package without types is a warning (`MOSTRA_TYPE_UNTYPED_PACKAGE`); declare a module or ignore it.
|
|
73
|
+
- Offline, only packages already in Mostra's store resolve (`MOSTRA_DEP_OFFLINE` names the missing one).
|
|
74
|
+
|
|
75
|
+
## Styles and assets
|
|
76
|
+
|
|
77
|
+
- Tailwind CSS 4 is always on: write utility classes, with no configuration file. Theme values live in CSS (`@theme`), as in [design.md](design.md).
|
|
78
|
+
- Import your own CSS from the page (`import "./styles.css"`). A stylesheet that defines `@theme` or `@layer base` starts with `@import "tailwindcss";`.
|
|
79
|
+
- Files in `public/` are served at the root: `public/logo.svg` is `/logo.svg`. Use root-relative paths.
|
|
80
|
+
- Fonts and images load from the artifact; a page makes no third-party request unless you write one.
|
|
81
|
+
|
|
82
|
+
## MDX
|
|
83
|
+
|
|
84
|
+
`index.mdx` (or any page in `pages/`) is Markdown with JSX. The manifest is YAML frontmatter with the same fields:
|
|
85
|
+
|
|
86
|
+
```mdx
|
|
87
|
+
---
|
|
88
|
+
title: Release notes for 2.4
|
|
89
|
+
family: proposal
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
import { Approve } from "./approve";
|
|
93
|
+
|
|
94
|
+
# What changed
|
|
95
|
+
|
|
96
|
+
<Approve />
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
GitHub-flavoured Markdown (tables, task lists) works. MDX isn't type-checked.
|
|
100
|
+
|
|
101
|
+
## Who and where
|
|
102
|
+
|
|
103
|
+
```tsx
|
|
104
|
+
import { useArtifact, useViewer } from "@mostra/react";
|
|
105
|
+
|
|
106
|
+
function Greeting() {
|
|
107
|
+
const viewer = useViewer(); // { id, name?, source: "local" | "tailnet" | "token" | "host" }
|
|
108
|
+
const page = useArtifact(); // { id, versionId, version, viewId, mode: "live" | "static" | "mcp-app" | "verify" }
|
|
109
|
+
return <p>{viewer.name ? `Hello, ${viewer.name}.` : "Hello."} This is version {page.version}.</p>;
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`useViewer().name` is the person's name when the link or tailnet knows it. `mode` is `verify` while verify renders the page and `live` when a person opens it.
|
|
114
|
+
|
|
115
|
+
## Sending the person elsewhere
|
|
116
|
+
|
|
117
|
+
The page runs in a frame that can't navigate the person's tab, so it can never replace Mostra's trusted controls. Use `openLink`, which opens `http:`, `https:`, `mailto:` and `tel:` URLs in a new tab:
|
|
118
|
+
|
|
119
|
+
```tsx
|
|
120
|
+
import { openLink } from "@mostra/react";
|
|
121
|
+
|
|
122
|
+
function PullRequestLink() {
|
|
123
|
+
return <button onClick={() => void openLink("https://github.com/acme/app/pull/42")}>Open the pull request</button>;
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Plain `<a href target="_blank">` links work too.
|
|
128
|
+
|
|
129
|
+
## Pages written for Claude
|
|
130
|
+
|
|
131
|
+
A page that uses Claude artifacts' `window.storage` works unchanged: `get`, `set`, `delete` and `list`, each with `shared`. Personal keys are the person's saved fields (`storage.<key>`), shared keys are the artifact's shared state. A value is at most 1 MiB. For new code, prefer `useField`, which verify understands and results label.
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# Server code: actions, secrets and side effects
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
- Server functions
|
|
6
|
+
- Actions: `useAction`
|
|
7
|
+
- Side effects that happen once
|
|
8
|
+
- Secrets
|
|
9
|
+
- What server code can use: `@mostra/server`
|
|
10
|
+
- Verify and `dryRun()`
|
|
11
|
+
- Limits and crashes
|
|
12
|
+
|
|
13
|
+
## Server functions
|
|
14
|
+
|
|
15
|
+
Any module whose first statement is `"use server"` runs on this machine, in a worker process of its own, with full Node.js: files, processes, the network, any npm package. It exports only async functions (async generators too). The page imports them like ordinary functions; Mostra sends the call to the worker.
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
// actions.ts
|
|
19
|
+
"use server";
|
|
20
|
+
import { readFile } from "node:fs/promises";
|
|
21
|
+
|
|
22
|
+
export async function loadReport(name: string) {
|
|
23
|
+
return JSON.parse(await readFile(`data/${name}.json`, "utf8")); // relative to the artifact's directory
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
```tsx
|
|
28
|
+
// index.tsx
|
|
29
|
+
import { useState } from "react";
|
|
30
|
+
import { loadReport } from "./actions";
|
|
31
|
+
|
|
32
|
+
function Report() {
|
|
33
|
+
const [report, setReport] = useState<unknown>();
|
|
34
|
+
return <button onClick={async () => setReport(await loadReport("q3"))}>Load the Q3 report</button>;
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
- Arguments and results are what React's Server Functions accept: JSON values, `Date`, `Map`, `Set`, `BigInt`, typed arrays, `FormData`, `File`, promises, plus async iterables as results. Functions and class instances don't cross (`MOSTRA_ACTION_UNSERIALIZABLE`).
|
|
39
|
+
- A thrown error reaches the page as a `MostraError` with `code: "MOSTRA_ACTION_THREW"` and the error's message; its stack goes to the run's log.
|
|
40
|
+
- Calling a function directly is a plain call: nothing is recorded, and a reload forgets it. Use it to read things. For anything that changes the world, use an action.
|
|
41
|
+
|
|
42
|
+
## Actions: `useAction`
|
|
43
|
+
|
|
44
|
+
`useAction` makes every call a recorded **run** with progress, a log, a final state, and cancellation:
|
|
45
|
+
|
|
46
|
+
```tsx
|
|
47
|
+
import { useAction } from "@mostra/react";
|
|
48
|
+
import { sendReply } from "./actions";
|
|
49
|
+
|
|
50
|
+
function Reply({ email, body }: { email: { id: string }; body: string }) {
|
|
51
|
+
const send = useAction(sendReply, { key: `reply-${email.id}` });
|
|
52
|
+
return (
|
|
53
|
+
<button disabled={send.isPending || send.status === "succeeded"} onClick={() => void send.run(email.id, body)}>
|
|
54
|
+
{send.status === "succeeded" ? "Sent" : send.isPending ? send.progress?.message ?? "Sending…" : "Send"}
|
|
55
|
+
</button>
|
|
56
|
+
);
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
- **Without a `key`**, a second call while the first runs joins it, so a double click runs once.
|
|
61
|
+
- **With a `key`**, the run happens at most once, ever: every click, tab, reload and viewer with that key joins the same run and sees its progress and result. A run that failed stays failed; a new attempt needs a new key (`reply-${email.id}-retry-1`).
|
|
62
|
+
- The handle has `status` (`idle`, `queued`, `running`, `succeeded`, `failed`, `cancelled`), `isPending`, `data`, `error` (`{ code, message }`), `progress` (`{ fraction?, message? }`), `log`, `partial` (the items an async-iterable result yielded so far), `runId` and `cancel()`.
|
|
63
|
+
- `run()` resolves with the result or rejects with a `MostraError` whose `code` says why (`MOSTRA_ACTION_THREW`, `MOSTRA_ACTION_CANCELLED`, `MOSTRA_ACTION_INTERRUPTED`, `MOSTRA_RUNTIME_WORKER_PARKED`).
|
|
64
|
+
- A run keeps going when the tab closes. A page that loads later finds a keyed run again by its key.
|
|
65
|
+
- Results list the runs started in the submitting view, so you can see what the person did.
|
|
66
|
+
|
|
67
|
+
## Side effects that happen once
|
|
68
|
+
|
|
69
|
+
A run cut off by a crash or a restart ends `failed` with `MOSTRA_ACTION_INTERRUPTED`, and Mostra never retries it: the email may or may not have gone. So for any external side effect, pass an idempotency key the provider understands, derived from the run's key, so the provider drops a repeat:
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
"use server";
|
|
73
|
+
import { abortSignal, progress, secret } from "@mostra/server";
|
|
74
|
+
|
|
75
|
+
export async function sendReply(emailId: string, body: string) {
|
|
76
|
+
progress({ message: "Sending…" });
|
|
77
|
+
const response = await fetch("https://api.mail.example/v1/send", {
|
|
78
|
+
method: "POST",
|
|
79
|
+
headers: {
|
|
80
|
+
authorization: `Bearer ${secret("MAIL_TOKEN")}`,
|
|
81
|
+
"idempotency-key": `reply-${emailId}`, // the same key the page gave useAction
|
|
82
|
+
"content-type": "application/json",
|
|
83
|
+
},
|
|
84
|
+
body: JSON.stringify({ inReplyTo: emailId, body }),
|
|
85
|
+
signal: abortSignal, // cancel() aborts the request
|
|
86
|
+
});
|
|
87
|
+
if (!response.ok) throw new Error(`The mail service answered ${response.status}`);
|
|
88
|
+
return { sent: true };
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Secrets
|
|
93
|
+
|
|
94
|
+
Keep keys and tokens out of the source. Mostra stores each one in its home, read from stdin:
|
|
95
|
+
|
|
96
|
+
```sh
|
|
97
|
+
mostra secret set MAIL_TOKEN --artifact ./inbox < mail-token.txt # this artifact only
|
|
98
|
+
mostra secret set CALENDAR_KEY < calendar-key.txt # every artifact in this home
|
|
99
|
+
mostra secret list --artifact ./inbox # names only, never values
|
|
100
|
+
mostra secret rm MAIL_TOKEN --artifact ./inbox # remove it
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Server code reads it with `secret("MAIL_TOKEN")`, synchronously; a missing one throws `MOSTRA_SECRET_MISSING`. Mostra redacts every value it hands out from logs, run logs, errors, events, results and live values, so returning or logging one shows `[redacted]`. A secret is the person's to store: ask them to run `mostra secret set` themselves, and never ask for the value in the conversation or in a page field.
|
|
104
|
+
|
|
105
|
+
## What server code can use
|
|
106
|
+
|
|
107
|
+
Import these from `@mostra/server` inside a `"use server"` function or a live source:
|
|
108
|
+
|
|
109
|
+
| Function | Does |
|
|
110
|
+
|---|---|
|
|
111
|
+
| `progress({ fraction?, message? })` | Shows progress on the page's run |
|
|
112
|
+
| `log(line)` | Adds a line to the run's log (`console.log` goes there too) |
|
|
113
|
+
| `abortSignal` | Aborts when the run is cancelled; pass it to `fetch` and child processes |
|
|
114
|
+
| `secret(name)` | Reads a secret |
|
|
115
|
+
| `viewer()` | The person who called: `{ id, name? }` |
|
|
116
|
+
| `signal(name, payload?)` | Raises a signal you can `mostra wait <dir> --until signal:<name>` for |
|
|
117
|
+
| `emit("host.<name>", payload?)` | An event for the program hosting Mostra; pages never see it |
|
|
118
|
+
| `state.get(id)`, `state.set(id, value)`, `state.patch(ops)` | Reads and writes the artifact's shared fields ([long-lived.md](long-lived.md)) |
|
|
119
|
+
| `dryRun()` | True only while verify exercises the page |
|
|
120
|
+
| `defineLive` | Defines a live source in `live.ts` ([long-lived.md](long-lived.md)) |
|
|
121
|
+
|
|
122
|
+
Errors these throw are `MostraServerError`s with a `code`.
|
|
123
|
+
|
|
124
|
+
## Verify and `dryRun()`
|
|
125
|
+
|
|
126
|
+
Verify clicks through the page but never runs a server function unless that function opts in by checking `dryRun()`:
|
|
127
|
+
|
|
128
|
+
```ts
|
|
129
|
+
"use server";
|
|
130
|
+
import { dryRun } from "@mostra/server";
|
|
131
|
+
|
|
132
|
+
export async function archiveEmail(emailId: string) {
|
|
133
|
+
if (dryRun()) return { archived: emailId }; // verify: nothing archived, a realistic answer
|
|
134
|
+
// …archive it for real, then:
|
|
135
|
+
return { archived: emailId };
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
A function that doesn't opt in is refused in verify, its click gets `MOSTRA_VERIFY_ACTION_SKIPPED` (a hint), and the verdict lists it under skipped actions. Opt in when the page's behavior after the action matters to what verify should see; keep real side effects behind the check.
|
|
140
|
+
|
|
141
|
+
## Limits and crashes
|
|
142
|
+
|
|
143
|
+
- Arguments and results up to 16 MiB each, a run's log 1 MB, signals 64 KiB.
|
|
144
|
+
- A worker has a 1 GiB heap and is stopped when its event loop is blocked for 10 s; change them in the manifest's `limits` (`heapMb`, `watchdogMs`).
|
|
145
|
+
- A crashed worker restarts with backoff. After more than five crashes in ten minutes it stops (`MOSTRA_RUNTIME_WORKER_PARKED`, and the page says the server code keeps crashing); publish a fix to clear it.
|
|
146
|
+
- Workers stop after 10 idle minutes and start again on the next call. Keep nothing in module variables that must survive; use shared state or files.
|