Marina Applet

Work with Marina applets

Read the Publishing an applet section of infra/marina/README.md before changing an applet or publishing one. Use infra/marina/examples/problem-set-applet/ as the minimal working package and backend reference. Treat those files and marina --help as authoritative when this skill disagrees with the checkout.

Choose the applet shape

Ensure the built package contains:

my-applet/
  applet.toml
  dist/index.html

Add browser assets below dist/. Use only relative asset, API, and query URLs so both /a/<uuid>/ and /a/<uuid>/v/<revision>/ work.

The source directory may omit dist/index.html only when applet.toml has a build_command that creates it before packaging.

Use plain HTML and JavaScript for a small single-view applet. Use Vue with Vite when the applet needs multiple views, reusable components, or substantial client state. For Vue applets:

• Set Vite's base to "./" so built asset URLs remain relative.
• Use createWebHashHistory() when the app has client-side routes. This avoids hard-coding an applet UUID or revision into the router base.
• Use relative backend calls such as fetch("api/results") and fetch("query", ...); do not start applet-owned URLs with /.
• Bundle dependencies into dist/. Marina's content security policy does not allow scripts loaded from a third-party CDN.

Keep the source index.html, package.json, the Vite configuration, and src/ beside applet.toml. They are local build inputs and are not uploaded. A typical manifest uses build_command = "npm ci && npm run build". Marina runs that command before every publish by default. Use --no-build only when the existing dist/ has already been built and validated.

Use the applet's implicit Postgres schema for mutable or queryable data. Do not create or attach a separate database. Load simple scalar tables with the CLI, or add server/ when the applet needs parameterized business logic, custom responses, or server-side integration.

An optional backend has this shape:

my-applet/
  server/__init__.py
  server/app.py

Declare it in applet.toml:

title = "Problem sets"
description = "Browse generated math problem sets."
python_entrypoint = "server.app:create_api"

Export create_api(services) -> ASGIApp. Use services.engine() for an engine configured with the applet role and schema. Optionally export migrate(connection) -> None; it runs inside the publish transaction before the new revision becomes current. Keep schema changes compatible with retained revisions.

Use get_verified_identity() from rigging.server_auth when a backend needs the authenticated caller. Import only packages already declared in infra/marina/pyproject.toml. Shared Marin helpers must come from installed packages under lib/*; do not import checked-in apps under infra/marina/apps.

Treat Python applets as trusted plugins. They run inside Marina with its filesystem, network, credentials, and process identity. Do not publish code from an untrusted source or depend on lifespan events, background workers, or local filesystem persistence.

Build and validate

Inspect existing Marina and repository helpers before introducing a framework or dependency. Build frontend output locally; Marina does not install applet dependencies. marina publish runs a declared build_command before packaging by default, and the command may create dist/index.html. Pass --no-build to reuse an existing validated dist/.

Validate the package and import a declared backend from the current Marina environment without changing server state:

uv run marina validate my-applet

The report names its completed checks and omissions. It does not execute the backend factory, run its migration, connect to Postgres, or start a browser. Use package-only validation when only the upload archive matters:

uv run marina publish my-applet --dry-run

Dry-run reports backend imports as unchecked. Both commands reject executable inline scripts under Marina's script-src 'self' policy. Load JavaScript from relative packaged files.

Respect the current package limits: 25 MiB total, 8 MiB per file, and 2,000 regular files. Keep large data out of the package until Marina gains an object store path.

Run the complete local stack with:

uv run marina publish my-applet --local

This starts disposable Postgres in Docker, installs Marina's privileged applet provisioning, migrates the registry, starts Marina on a free loopback port, publishes the applet with its migration, and prints its immutable revision URL. It requires a running Docker daemon, binds only to loopback, and does not enable IAP authentication. It stays in the foreground. After validation, send Ctrl-C and verify that both Marina and the container stop. If uv cannot write its cache in a restricted checkout, use the current checkout's .venv/bin/marina executable instead of installing or synchronizing dependencies.

To preserve the disposable Postgres stack across edits, leave the first publish --local --json process running. From a second terminal, publish the edit with this command, using each returned revision as the next base version:

uv run marina publish my-applet --url <printed-origin> \
  --update <printed-id> --base-version <current-version>

Open the printed immutable revision URL. Exercise the frontend, every backend route, caller identity when used, and at least one schema read/write path. For Marina code changes, run the focused tests and then:

cd infra/marina && uv run pytest