@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,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.
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Sharing: links, people and devices
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
- The link
|
|
6
|
+
- One person, one link
|
|
7
|
+
- The four setups: local, tailnet share, public share, hosted
|
|
8
|
+
- Hosted on a server
|
|
9
|
+
- Behind a public quick tunnel
|
|
10
|
+
- Managing links and shares
|
|
11
|
+
- Moving a version to another machine
|
|
12
|
+
- Asking people well
|
|
13
|
+
|
|
14
|
+
## The link
|
|
15
|
+
|
|
16
|
+
`mostra publish` prints the artifact's **default link**; `mostra open <dir>` prints it again; `--browser` also opens it in this machine's browser (without it, only a terminal opens one), and stderr says when no browser opened. The link is a capability URL: whoever holds it can view, answer, submit and run the page's actions. The secret is after the `#`, so it never reaches a server log, but treat the whole link like a password.
|
|
17
|
+
|
|
18
|
+
The default link doesn't expire and stays the same across versions. It opens on this machine only (`http://127.0.0.1:…`).
|
|
19
|
+
|
|
20
|
+
## One person, one link
|
|
21
|
+
|
|
22
|
+
A link without a named person acts as one person: everyone who holds the default link shares one draft and one `once` submission. When several people should answer, mint one link per person:
|
|
23
|
+
|
|
24
|
+
```sh
|
|
25
|
+
mostra open ./retro --new --viewer ada@example.com --viewer-name "Ada Lovelace" --no-browser
|
|
26
|
+
mostra open ./retro --new --viewer grace@example.com --viewer-name "Grace Hopper" --no-browser
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
`--viewer` is your own stable key for the person (an email, a user ID); the same key always means the same person, and results name them. Use `{ policy: "once", scope: "per-viewer" }` so each of them submits once.
|
|
30
|
+
|
|
31
|
+
Other options of `mostra open <dir> --new`: `--ttl 24h` (the link expires), `--scope view` (look but not answer; also `draft`, `submit`, `review`, `signal`, `action:*`), `--version 3` (only that version).
|
|
32
|
+
|
|
33
|
+
## The four setups
|
|
34
|
+
|
|
35
|
+
| Setup | Who can open it | Command |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| **Local** | Only this machine's browser | `mostra open <dir> --browser` |
|
|
38
|
+
| **Tailnet share** | People and devices in your Tailscale network, such as your phone | `mostra share <dir> --tailnet` |
|
|
39
|
+
| **Public share** | Anyone with the link, on any device | `mostra share <dir> --public` |
|
|
40
|
+
| **Hosted** | Anyone with the link, even while this machine sleeps | `mostra share <dir> --cloud` |
|
|
41
|
+
|
|
42
|
+
- **Tailnet share** uses Tailscale Serve. Each person is their tailnet identity, so results name them without `--viewer`. The link doesn't expire unless you give `--ttl`. The output names the two ports the tailnet's access policy must allow, and the viewer's device must run Tailscale.
|
|
43
|
+
- **Public share** uses a Cloudflare quick tunnel by default (no account needed), or Tailscale Funnel with `--via funnel` (the URL shows your device's tailnet name). The link lasts 1 hour unless `--ttl` says otherwise, 7 days at most. Each public link is a visitor of its own: their answers never mix with yours or anyone else's, and results show them as "Shared link" unless you pass `--viewer`.
|
|
44
|
+
- Both drive tools installed on this machine (`tailscale`, `cloudflared`); when one is missing or signed out, the command says how to install or enable it (`MOSTRA_SHARE_TOOL_MISSING`, `MOSTRA_SHARE_TOOL_NOT_READY`, `MOSTRA_SHARE_NOT_ENABLED`).
|
|
45
|
+
- A share keeps Mostra running while it lasts. A quick tunnel can't keep its address across a restart, so a public Cloudflare share ends when Mostra restarts; tailnet and Funnel shares come back.
|
|
46
|
+
|
|
47
|
+
## Hosted on a server
|
|
48
|
+
|
|
49
|
+
`mostra share <dir> --cloud` puts the latest version on a remote server this machine signed in to, and prints a link there. The page keeps taking answers while this machine is off: they wait on the server and reach `mostra wait` and `mostra results` here when Mostra runs again, the same as local answers. Every later `mostra publish` of the artifact goes to the server too.
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
mostra login https://api.example.com # once per machine: open the address it prints and approve the code
|
|
53
|
+
mostra share ./x --cloud # host it there; prints the hosted link
|
|
54
|
+
mostra status # the servers this machine is linked to, and whether they're connected
|
|
55
|
+
mostra logout # sign out; hosted pages keep working, answers wait for the next login
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
- The person answering sees "Your answer was sent." once the server has it, and nothing about this machine. You see the delivery states.
|
|
59
|
+
- Only the source, its versions and its secrets stay on this machine; the server holds the built page and what people enter.
|
|
60
|
+
- Several machines can sign in to one account. The one that shared a page receives its answers. `mostra login <server> --default` makes this machine the one pages created from a chat app go to.
|
|
61
|
+
- `mostra share stop` and `mostra share list` include hosted shares.
|
|
62
|
+
- `mostra pause ./x --reason "Closed until Monday"` stops a page taking answers and running actions, here and on every server it's hosted on; it stays viewable, its links keep working, and the draft people typed is kept. `mostra resume ./x` opens it again. A pause the server's operator made can only be lifted by the operator.
|
|
63
|
+
|
|
64
|
+
### Actions on a hosted page
|
|
65
|
+
|
|
66
|
+
A hosted page's actions run on this machine, with its secrets, while it is connected. The manifest's `hosted` key says how they behave on the server:
|
|
67
|
+
|
|
68
|
+
```tsx
|
|
69
|
+
export const artifact = defineArtifact({
|
|
70
|
+
title: "Proposal",
|
|
71
|
+
hosted: {
|
|
72
|
+
actions: "link", // who may press them: "signed-in" (default) or anyone with the link
|
|
73
|
+
offline: { actions: "queue", limit: "24h" }, // while this machine is off: wait ("queue", default) or fail at once ("fail")
|
|
74
|
+
},
|
|
75
|
+
});
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
- By default only people the link names (`--viewer`) or who signed in may run actions; `actions: "link"` lets anyone with the link run them.
|
|
79
|
+
- While this machine is off, a pressed action waits: `useAction`'s `status` is `"waiting"`, and it runs once, in order, when Mostra runs here again. Past `limit` (at most `7d`) a run that never started fails. Under `"fail"` it fails at once.
|
|
80
|
+
- If the connection drops while an action runs and this machine never reports how it ended within the limit, its `status` becomes `"unknown"`: it may have happened, so show that rather than "failed". `run()` rejects with `MOSTRA_REMOTE_OWNER_OFFLINE`; the real end replaces `unknown` if it arrives later.
|
|
81
|
+
- A plain server function (called directly, not through `useAction`) answers `MOSTRA_REMOTE_OWNER_OFFLINE` while this machine is off.
|
|
82
|
+
- Live values show the last value, with `ownerOffline` set, while this machine is off.
|
|
83
|
+
|
|
84
|
+
## Behind a public quick tunnel
|
|
85
|
+
|
|
86
|
+
Over a Cloudflare quick tunnel the page runs in a slightly different mode, and nothing in your code needs to change for it:
|
|
87
|
+
|
|
88
|
+
- updates arrive by polling rather than streaming, so other people's edits and live values show up a second or two later;
|
|
89
|
+
- a streamed result (an async iterable) arrives in one piece at the end;
|
|
90
|
+
- the page can't register a service worker of its own (`MOSTRA_HYGIENE_FRAME_SESSION`).
|
|
91
|
+
|
|
92
|
+
## Managing links and shares
|
|
93
|
+
|
|
94
|
+
```sh
|
|
95
|
+
mostra share list # active shares, with their links
|
|
96
|
+
mostra share list --all # ended ones too, and why
|
|
97
|
+
mostra share stop <shareId> # or the artifact, for all of its shares; the link stops working
|
|
98
|
+
mostra open ./x --rotate <tokenId> # replace a link that leaked; the old one stops working
|
|
99
|
+
mostra open ./x --revoke <tokenId> # stop a link
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
`--json` output carries each link's `tokenId`.
|
|
103
|
+
|
|
104
|
+
## Moving a version to another machine
|
|
105
|
+
|
|
106
|
+
A published version can move whole to another Mostra home, where it is the same version with the same IDs, and its actions run there:
|
|
107
|
+
|
|
108
|
+
```sh
|
|
109
|
+
mostra export ./x --out ./x.tar.zst # the latest version; --version 2 for another
|
|
110
|
+
mostra run ./x.tar.zst # on the other machine: imports it and prints its link
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The bundle holds the version's builds, manifest, lockfile and source, never secrets: set the secrets its actions read on the other machine with `mostra secret set`. Answers stay in the home where people gave them.
|
|
114
|
+
|
|
115
|
+
## Asking people well
|
|
116
|
+
|
|
117
|
+
The link arrives as a message from you, so write it like one:
|
|
118
|
+
|
|
119
|
+
- Say who is asking and why ("I'm the coding agent working on the checkout redesign; I need your call between two layouts").
|
|
120
|
+
- Say what the page asks of them and how long it takes.
|
|
121
|
+
- Give a real deadline only if there is one.
|
|
122
|
+
- Ask for no passwords, keys or codes on a page; collect secrets through `mostra secret set` instead.
|
|
123
|
+
- Post a link somewhere public only if the page is meant for anyone.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Teams: several people on one page
|
|
2
|
+
|
|
3
|
+
Read this when more than one person answers the page, when you need to know who has answered, or when people work on it together.
|
|
4
|
+
|
|
5
|
+
## Send one page to a team
|
|
6
|
+
|
|
7
|
+
1. **Take one submission per person.** In the manifest, `submission: { policy: "once", scope: "per-viewer" }` (one answer each), or `{ policy: "epochs" }` (each can answer again; a round ends when everyone has). *Done when* the manifest names one of the two.
|
|
8
|
+
2. **Name the people you expect.** After `mostra publish <dir>`:
|
|
9
|
+
|
|
10
|
+
```sh
|
|
11
|
+
mostra roster add <dir> ada@example.com grace@example.com alan@example.com
|
|
12
|
+
mostra roster add <dir> ada@example.com --name "Ada Lovelace" # a display name for one person
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
The ref is your own stable key for each person (an email, an account ID). Each gets a **personal link** that acts as them: their own draft, their own submission, their name on what they change. Adding someone again keeps their link and updates their name. On a remote server, `mostra share <dir> --cloud --respondent ada@example.com,grace@example.com` hosts the page and names them at once. *Done when* every expected person has a link.
|
|
16
|
+
3. **Give each person their own link.** One link is one person: a link sent to two people makes them one respondent. *Done when* each link has gone to its person.
|
|
17
|
+
4. **Wait for everyone.** `mostra wait <dir> --until submitted:all --timeout 1h` returns once every expected respondent has submitted; under `epochs` it returns at the end of each round. `--until submitted:5` waits for five submissions from anyone. Exit 5 means still waiting: nothing is lost. *Done when* it exits 0.
|
|
18
|
+
5. **Read every answer.** `mostra results <dir> --all` prints every submission, oldest first. *Done when* you've used each person's answers.
|
|
19
|
+
|
|
20
|
+
`mostra roster get <dir>` shows who is expected and where each stands: `not-opened`, `drafting` or `submitted`. `mostra roster remove <dir> <ref>` stops expecting someone; their link and answers stay.
|
|
21
|
+
|
|
22
|
+
## Show the team on the page
|
|
23
|
+
|
|
24
|
+
The shell draws nothing about other people: the page shows them in its own design.
|
|
25
|
+
|
|
26
|
+
```tsx
|
|
27
|
+
import { useField, usePresence, useRespondents } from "@mostra/react";
|
|
28
|
+
|
|
29
|
+
function Progress() {
|
|
30
|
+
const { counts } = useRespondents();
|
|
31
|
+
if (!counts) return null; // visibility "private": only the owner sees counts
|
|
32
|
+
return <p>{counts.submitted} of {counts.total} answered</p>;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
function Cursors() {
|
|
36
|
+
const { others } = usePresence({ cursor: true }); // shares this viewer's pointer while mounted
|
|
37
|
+
return (
|
|
38
|
+
<>
|
|
39
|
+
{others.map((peer) =>
|
|
40
|
+
peer.cursor ? (
|
|
41
|
+
<span key={peer.key} className="pointer-events-none absolute text-xs"
|
|
42
|
+
style={{ left: peer.cursor.x, top: peer.cursor.y }}>
|
|
43
|
+
▲ {peer.name}
|
|
44
|
+
</span>
|
|
45
|
+
) : null,
|
|
46
|
+
)}
|
|
47
|
+
</>
|
|
48
|
+
);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
function SharedNotes() {
|
|
52
|
+
const [text, setText, meta] = useField("team.notes", "", { scope: "artifact", label: "Notes" });
|
|
53
|
+
const who = meta.updatedBy; // { name, at, self, key } of the last change
|
|
54
|
+
return (
|
|
55
|
+
<label>
|
|
56
|
+
Notes
|
|
57
|
+
<textarea value={text} onChange={(e) => setText(e.target.value)} />
|
|
58
|
+
{who && <small>{who.self ? "You" : who.name} changed this</small>}
|
|
59
|
+
</label>
|
|
60
|
+
);
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
- `useRespondents()` gives `self` (this viewer's own entry, when they are expected), `counts`, `complete` and `respondents`, each with `key`, `name` and `status`, as far as the visibility allows.
|
|
65
|
+
- `usePresence({ cursor, selection })` gives `others`, the people here now, each with `key`, `name` and what they share. `cursor` is the pointer in document coordinates; `selection` names the focused element by its `data-presence-id`, `id` or `name`. Nothing is shared without the hook, and nothing is ever stored.
|
|
66
|
+
- A person's `key` is the same in `useRespondents`, `usePresence` and a shared field's `meta.updatedBy`, so the page can match them.
|
|
67
|
+
|
|
68
|
+
## What people see of each other
|
|
69
|
+
|
|
70
|
+
The manifest's `team: { visibility }` decides what a viewer sees of the others:
|
|
71
|
+
|
|
72
|
+
| `visibility` | A respondent sees |
|
|
73
|
+
|---|---|
|
|
74
|
+
| `"private"` (the default) | Their own entry only |
|
|
75
|
+
| `"counts"` | Also how many are expected, drafting and submitted, and how many are here now |
|
|
76
|
+
| `"names"` | Also each person by name, their status, and who is here with their cursor |
|
|
77
|
+
|
|
78
|
+
The page's owner sees everyone in every case, and you see everything through `mostra roster get`. Attribution of shared fields (`meta.updatedBy`) is always shown.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Verify: the verdict, screenshots and the dev preview
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
- What verify does
|
|
6
|
+
- Reading the verdict
|
|
7
|
+
- Errors, warnings and hints
|
|
8
|
+
- Screenshots and the ARIA snapshot
|
|
9
|
+
- Regressions between versions
|
|
10
|
+
- Publish and verify
|
|
11
|
+
- The dev preview: `mostra dev`
|
|
12
|
+
|
|
13
|
+
## What verify does
|
|
14
|
+
|
|
15
|
+
`mostra verify <dir>` checks the artifact's current source without publishing it, in a sandbox that touches no one's answers and calls no host:
|
|
16
|
+
|
|
17
|
+
1. **prepare** and **compile**: reads the manifest, resolves and installs packages, type-checks (TypeScript in strict mode, or with the artifact's own `tsconfig.json` settings), builds.
|
|
18
|
+
2. **boot** and **render**: opens the page in a headless Chromium at 1280 × 800 and 390 × 844, with a fixed clock and reduced motion, waits until it's still (and until the calls, runs and live values it loads at mount have arrived), records page errors, console errors and failed requests, runs axe, takes an ARIA snapshot and a screenshot per size.
|
|
19
|
+
3. **smoke**: clicks and types through the page's controls (up to 200 interactions or 60 s), checking that each does something and that nothing breaks. Server functions run only when they opt in through `dryRun()` ([server.md](server.md)); live sources run for real, and secrets resolve as they would.
|
|
20
|
+
4. **regression**: compares with the last published version that passed ([below](#regressions-between-versions)).
|
|
21
|
+
|
|
22
|
+
It takes 10 to 30 s.
|
|
23
|
+
|
|
24
|
+
## Reading the verdict
|
|
25
|
+
|
|
26
|
+
The human output prints `verify: pass` or `verify: fail`, each diagnostic with its hint, and the screenshots worth looking at. Exit code 0 is pass, 1 is fail. With `--json`, the result is:
|
|
27
|
+
|
|
28
|
+
```json
|
|
29
|
+
{
|
|
30
|
+
"status": "pass",
|
|
31
|
+
"artifact": { "id": "art_…", "path": "…", "sourceDigest": "…", "envDigest": "…", "versionId": "ver_…" },
|
|
32
|
+
"diagnostics": [{ "code": "MOSTRA_…", "severity": "error", "message": "…", "hint": "…", "location": { "file": "index.tsx", "line": 12, "column": 7 }, "docs": "…" }],
|
|
33
|
+
"screenshots": [{ "viewport": "desktop", "path": "…/desktop.png", "width": 1280, "height": 800, "tokensEstimate": { "claude": 1334, "gpt": 1200, "gemini": 1120 }, "returned": false }],
|
|
34
|
+
"aria": [{ "viewport": "desktop", "path": "…/desktop.aria.yml", "summary": "3 headings, 1 button, 1 textbox, landmarks: main" }],
|
|
35
|
+
"smoke": { "interactions": 3, "skippedActions": [], "stateChanges": 3 },
|
|
36
|
+
"regressions": {},
|
|
37
|
+
"timingsMs": { "build": 36, "typecheck": 538, "render": 9548, "smoke": 2492, "total": 13898 }
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`status` is `fail` exactly when there is an error. Diagnostics come errors first; identical ones fold into one with a `count`. `mostra docs <CODE>` prints any code's page with an example fix.
|
|
42
|
+
|
|
43
|
+
## Errors, warnings and hints
|
|
44
|
+
|
|
45
|
+
| Severity | Means | Examples |
|
|
46
|
+
|---|---|---|
|
|
47
|
+
| error | Something is definitely broken; publish refuses it | type and build errors, uncaught page errors, console errors, failed requests to the page's own origin, a blank page, a page that never gets ready, duplicate or unstable field IDs, a manifest that can't be read |
|
|
48
|
+
| warning | Worth checking; publish allows it | axe's serious findings, failed requests to other sites, a failing live source, a package without types, a secret the page needed that isn't set, every regression, a control with no visible effect |
|
|
49
|
+
| hint | Information | an input not bound to a field (`MOSTRA_FIELD_UNBOUND`, fine for a search box or a draft you don't want saved), an action skipped in verify, axe's minor findings, the smoke test's budget, no baseline yet |
|
|
50
|
+
|
|
51
|
+
Warnings that begin with **"Observed only"** (`MOSTRA_SMOKE_NO_EFFECT`, `MOSTRA_REGRESSION_*`) report what verify saw, such as a button whose click changed nothing visible or a page that changed since the last version. Look at the screenshot and decide; when the behavior is what you intended, change nothing.
|
|
52
|
+
|
|
53
|
+
Fix errors at their location, run verify again, and repeat until it passes. Fix the first error first: later ones are often its consequences.
|
|
54
|
+
|
|
55
|
+
## Screenshots and the ARIA snapshot
|
|
56
|
+
|
|
57
|
+
Screenshots are always taken. `--screenshots on-failure` (the default) marks them `returned` only when verify fails; `always` marks them every time; `never` never does. The human output lists the returned ones. **Look at them before you publish**, on every round: verify can't tell you that the page looks wrong, only that it works. The design checks in [design.md](design.md#reading-your-screenshots) say what to look for.
|
|
58
|
+
|
|
59
|
+
The ARIA snapshot (`.aria.yml`) is the page as a screen reader sees it: headings, buttons, inputs and their names. Read it when you can't look at images: it shows what text and controls the page actually rendered.
|
|
60
|
+
|
|
61
|
+
## Regressions between versions
|
|
62
|
+
|
|
63
|
+
From the second version on, verify renders the last published version that passed, in the same run, and compares: the ARIA snapshot, the pixels at each size, and the contract (fields, actions, live sources and pages that disappeared). A field you removed leaves people's answers behind, so `MOSTRA_REGRESSION_FIELD_REMOVED` is worth a second look; a layout change you made on purpose is expected.
|
|
64
|
+
|
|
65
|
+
## Publish and verify
|
|
66
|
+
|
|
67
|
+
`mostra publish` reuses the verdict of the same source, or runs verify itself. It refuses a source whose verdict has errors (`MOSTRA_PUBLISH_VERIFY_FAILED`). `--force` publishes anyway and records the failing codes on the version; it never publishes a source that didn't build. Use it only when you know why the error doesn't matter. When the headless browser isn't available (`MOSTRA_ENV_BROWSER_MISSING`), verify still type-checks and builds, and the code's page says how to install the browser.
|
|
68
|
+
|
|
69
|
+
## The dev preview: `mostra dev`
|
|
70
|
+
|
|
71
|
+
`mostra dev <dir>` serves the unpublished source with hot reload on this machine until Ctrl-C, and prints a link. Edits appear in the browser as you save; changed server code restarts its worker. Answers and submissions there go to a scratch store that's thrown away, and actions run for real with the real secrets. Nobody but you sees it: use it while building, then verify and publish.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mostra/runtime",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.12.0",
|
|
4
4
|
"description": "The Mostra runtime: the supervisor that owns a home, its ledger, its child processes and the host protocol server (mostra-runtime host|daemon).",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "The Mostra Authors",
|
|
@@ -36,12 +36,14 @@
|
|
|
36
36
|
"dependencies": {
|
|
37
37
|
"@hono/node-server": "2.1.5",
|
|
38
38
|
"@mdx-js/mdx": "3.1.1",
|
|
39
|
-
"@mostra/
|
|
39
|
+
"@mostra/mcp": "0.12.0",
|
|
40
|
+
"@mostra/protocol": "0.12.0",
|
|
40
41
|
"@tailwindcss/vite": "4.3.3",
|
|
41
42
|
"@vitejs/plugin-react": "6.1.2",
|
|
42
43
|
"better-sqlite3": "13.0.3",
|
|
43
44
|
"hono": "4.13.13",
|
|
44
45
|
"ignore": "7.0.13",
|
|
46
|
+
"openid-client": "6.8.8",
|
|
45
47
|
"oxc-parser": "0.155.0",
|
|
46
48
|
"pnpm": "10.34.7",
|
|
47
49
|
"remark-frontmatter": "5.0.0",
|
|
@@ -55,11 +57,14 @@
|
|
|
55
57
|
"zod": "4.6.7"
|
|
56
58
|
},
|
|
57
59
|
"devDependencies": {
|
|
58
|
-
"@
|
|
60
|
+
"@modelcontextprotocol/client": "2.4.0",
|
|
61
|
+
"@modelcontextprotocol/conformance": "0.1.16",
|
|
62
|
+
"@modelcontextprotocol/conformance-next": "npm:@modelcontextprotocol/conformance@0.2.0-alpha.12",
|
|
63
|
+
"@mostra/shell": "0.12.0",
|
|
59
64
|
"@mostra/tools": "0.0.0",
|
|
60
|
-
"@mostra/verify": "0.
|
|
65
|
+
"@mostra/verify": "0.12.0",
|
|
61
66
|
"@mostra/warm": "0.0.0",
|
|
62
|
-
"@mostra/worker": "0.
|
|
67
|
+
"@mostra/worker": "0.12.0",
|
|
63
68
|
"@types/better-sqlite3": "9.6.0",
|
|
64
69
|
"@types/node": "24.19.2",
|
|
65
70
|
"@types/semver": "7.8.0",
|
package/src/gateway/actions.ts
CHANGED
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
import {
|
|
11
11
|
CallRequest,
|
|
12
12
|
type CapabilityScope,
|
|
13
|
+
createDiagnostic,
|
|
13
14
|
type Diagnostic,
|
|
14
15
|
LiveRequest,
|
|
15
16
|
RpcError,
|
|
@@ -152,6 +153,21 @@ export function actionRoutes(options: ActionRoutesOptions): ActionRoutes {
|
|
|
152
153
|
const may = (page: PageIdentity, fnId: string): boolean =>
|
|
153
154
|
scopeAllows(page.scopes ?? [], `action:${fnId}` as CapabilityScope);
|
|
154
155
|
|
|
156
|
+
/**
|
|
157
|
+
* A paused artifact runs no actions (D165 item 14): a call or a new run is refused before
|
|
158
|
+
* anything is recorded, started or relayed to the owner.
|
|
159
|
+
*/
|
|
160
|
+
const paused = (page: PageIdentity): Response | undefined => {
|
|
161
|
+
const pause = interaction.pauseOf(page.artifactId);
|
|
162
|
+
if (!pause) return undefined;
|
|
163
|
+
return answer(
|
|
164
|
+
createDiagnostic("MOSTRA_ACTION_PAUSED", {
|
|
165
|
+
message: `This page is paused${pause.by === "operator" ? " by its server's operator" : ""}: its actions don't run until it is resumed.`,
|
|
166
|
+
}),
|
|
167
|
+
423,
|
|
168
|
+
);
|
|
169
|
+
};
|
|
170
|
+
|
|
155
171
|
return {
|
|
156
172
|
async call(context) {
|
|
157
173
|
const refused = served(context);
|
|
@@ -162,6 +178,8 @@ export function actionRoutes(options: ActionRoutesOptions): ActionRoutes {
|
|
|
162
178
|
const page = pageOf(context);
|
|
163
179
|
// The route checked `action:<fnId>` already (D97 item 4); this keeps the rule in one place.
|
|
164
180
|
if (!may(page, fnId)) return denied(fnId);
|
|
181
|
+
const pausedNow = paused(page);
|
|
182
|
+
if (pausedNow) return pausedNow;
|
|
165
183
|
let lines: AsyncIterable<unknown>;
|
|
166
184
|
const abort = new AbortController();
|
|
167
185
|
context.request.signal.addEventListener("abort", () => abort.abort(), { once: true });
|
|
@@ -215,6 +233,8 @@ export function actionRoutes(options: ActionRoutesOptions): ActionRoutes {
|
|
|
215
233
|
if (request instanceof Response) return request;
|
|
216
234
|
const page = pageOf(context);
|
|
217
235
|
if (!may(page, request.fnId)) return denied(request.fnId);
|
|
236
|
+
const pausedNow = paused(page);
|
|
237
|
+
if (pausedNow) return pausedNow;
|
|
218
238
|
try {
|
|
219
239
|
return jsonResponse(
|
|
220
240
|
actions.startRun(page, {
|