marimo-export 0.0.2__tar.gz → 0.0.4__tar.gz

marimo_export-0.0.4/.agent-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "marimo-export",
+  "description": "Turn selected marimo notebook states into verified exports and static applications.",
+  "author": {
+    "name": "marimo team"
+  },
+  "repository": "https://github.com/marimo-team/marimo-export",
+  "keywords": ["marimo", "notebooks", "static-apps", "agent-skills"]
+}

marimo_export-0.0.4/.agent-plugin/skills/notebook-to-static-app/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: notebook-to-static-app
+description: Turn an existing marimo Python notebook into a polished static HTML, CSS, and TypeScript application by designing an ExportSpec, creating and capturing finite notebook states with marimo-export, loading outputs through @marimo-team/marimo-export, and validating the deployed browser experience. Use when a user points to a marimo .py notebook and wants a CDN-deployable interactive app that runs with no Python server or Python WebAssembly runtime.
+---
+
+# Notebook to Static App
+
+Create a user-facing web application from completed marimo executions. Keep the
+notebook unchanged. Precompute the choices the audience needs, then make the
+browser experience feel authored for their task.
+
+## Read first
+
+Read:
+
+- [references/workflow.md](references/workflow.md) for workspace setup and the
+  exact build or capture commands
+- [references/contracts.md](references/contracts.md) for ExportSpec, exporter,
+  loader, and state-transition contracts
+
+Inspect the current marimo-export docs and source when a command or type differs
+from the references. The checkout is authoritative.
+
+## Invariants
+
+- Leave the source notebook byte-for-byte unchanged.
+- Use notebook definition names in state-row keys and output selectors.
+- Run every selected output through normal marimo execution.
+- Treat browser choices as a finite product surface, not a free-form Python
+  prompt.
+- Choose CLI `build` for a saved file and CLI `capture` for an existing live
+  session. Both write a deployment directory. Python `capture()` returns a
+  leased prepared export.
+- The deployed app must run from static files with no Python process.
+- Freeze every notebook data dependency into the export. Mounted charts must
+  not fetch their source dataset at runtime.
+- Use exported values as the data source. Do not replace failed notebook data
+  with fixtures or invented values.
+- Keep implementation terminology out of the visible app. Users should not see
+  export, state, codec, loader, cache, notebook, or Python unless the product
+  itself teaches those concepts.
+
+## Workflow
+
+### 1. Understand the notebook
+
+Read the complete notebook before choosing outputs. Identify:
+
+- the audience and decision the notebook can support
+- authored variables and UI controls that change meaningful results
+- expensive or environment-dependent calculations
+- definitions that contain data, metrics, charts, images, or widgets
+- browser interactions that can continue without another Python execution
+
+Write one internal product sentence:
+
+> `<audience>` uses this app to `<decision or task>` using `<notebook result>`.
+
+Reject an app concept that merely displays notebook outputs or demonstrates
+marimo-export features.
+
+### 2. Choose the finite interaction model
+
+Design three to seven named states unless the notebook supports a genuinely
+different meaningful range. Each state should represent a recognizable scenario,
+policy, cohort, threshold, or comparison.
+
+Use sparse overrides. Let omitted inputs come from the captured baseline.
+Prefer a small set of high-value choices over a Cartesian product of every
+possible control.
+
+Choose outputs that let the browser answer the product question. A strong app
+usually combines:
+
+- one or two scalar summaries
+- one primary visual or interactive value
+- one inspectable table, array, or detail view
+
+Export only values the application loads.
+
+### 3. Create the app workspace
+
+Resolve `scripts/scaffold_app.py` through `marimo_export.agent.agent_skill()` and
+create the local Python and Vite workspace from the notebook's PEP 723
+dependencies. Select only the browser loader families the app will import.
+
+Treat the generated `src/main.ts` as a loading shell. Replace it with the real
+application after the ExportSpec is known.
+
+### 4. Inspect the notebook boundary
+
+For `build`, run:
+
+```bash
+uv run --project "$STATIC_APP_DIR" marimo-export inspect "$NOTEBOOK_PATH" --json
+```
+
+For `capture`, set `NOTEBOOK_PORT` and `SESSION_ID`, then run:
+
+```bash
+uv run --project "$STATIC_APP_DIR" marimo-export inspect \
+  "http://127.0.0.1:$NOTEBOOK_PORT" \
+  --session "$SESSION_ID" \
+  --json
+```
+
+Both commands return definition and cell records before state preparation.
+
+Do not infer a definition from displayed prose or a local variable whose name
+starts with `_`. Use the inspection result.
+
+### 5. Author and preflight the ExportSpec
+
+Create `<name>.export.yaml` beside the app. Use domain names for states and
+published output names.
+
+Run planning after authoring the spec. Correct missing input or output names
+before preparation:
+
+```bash
+uv run --project "$STATIC_APP_DIR" marimo-export plan "$NOTEBOOK_PATH" \
+  --spec "$STATIC_APP_DIR/app.export.yaml" \
+  --json
+```
+
+The plan reports inferred inputs, normalized states, the default, observations,
+reusable fingerprints, and missing fingerprints.
+
+Choose the narrowest representation that preserves the browser experience:
+
+- keep supported scalars, NumPy arrays, Arrow tables, and `BlobAsset` values
+  native
+- use Parquet for browser-readable table rows
+- use Vega-Lite for interactive Altair charts
+- use PNG when the audience needs a fixed chart image
+- use AnyWidget bundles when the widget's saved browser model supports the
+  audience's local interaction
+- add a focused custom exporter and paired loader when no built-in
+  representation fits
+
+Inspect exported Vega-Lite data references. When a notebook chart points to a
+remote dataset, use an export-time representation that embeds the data or
+pair the chart with an exported table and rebuild the chart in the browser.
+
+### 6. Create and verify the export
+
+Use `build` when the workflow owns notebook startup, execution, cleanup, and the
+deployment directory. Write to `public/export`, then run `marimo-export verify`
+before the browser build.
+
+Use CLI `capture --output public/export` when a running kernel already owns the
+configured environment or completed computation. Use the Python `capture()`
+context when the app needs to inspect, serve, or retain the prepared generation
+before writing.
+
+Run one producer mode for an app workflow. Do not hand-edit `index.json` or its
+assets.
+
+### 7. Build the browser application
+
+Open `./export/`, resolve named states, and load outputs explicitly. For a
+changing prepared publication, use `@marimo-team/marimo-export/prepared` with one
+`PreparedStateController` and an application-owned `PreparedStatePort`.
+
+Keep one transition owner that:
+
+1. aborts stale loads
+2. disposes mounted charts or widgets
+3. loads all outputs for the selected state
+4. commits the new view only if the transition is still current
+5. renders a recoverable error when loading fails
+
+Make state controls shareable through a URL hash or query parameter.
+
+Follow the marimo design system:
+
+- use compact controls, slate borders, white or near-black work surfaces, and
+  restrained blue interaction
+- use PT Sans for UI text and Lora for editorial headings
+- use borders before shadows
+- keep charts and tables full-width and overflow-safe
+- avoid gradients, oversized marketing heroes, nested cards, decorative
+  animation, and one-off palettes
+
+Use one clear visual direction for the domain. Keep the app inspectable and
+small. Prefer vanilla DOM code until a real composition problem justifies a
+framework.
+
+### 8. Validate the user boundary
+
+Run:
+
+- Python export verification for the selected producer mode
+- TypeScript type checking and production build
+- a static preview with the final export
+- browser checks at desktop and mobile widths
+
+Use a dedicated `agent-browser --session` name. Exercise every state control and
+at least one interaction inside each mounted chart or widget. Confirm:
+
+- visible results change with the selected domain scenario
+- rapid changes do not leave stale content
+- no console or page errors occur
+- no page-level horizontal overflow occurs
+- the final app makes no request to a Python server
+- notebook result data loads from the static app origin
+- the UI contains no implementation commentary
+
+Close the browser session and notebook server after validation.
+
+## Failure discipline
+
+Treat failures as product evidence.
+
+- Missing definition: inspect the live session and correct the spec.
+- Missing Python package: add the notebook's declared dependency to the app
+  environment.
+- Unsupported output: choose a data definition or write a focused exporter and
+  loader pair.
+- Custom exporter import failure: keep its module in the app and run the
+  notebook, build, and capture with the app directory on `PYTHONPATH`.
+- Capture package mismatch: run the notebook from the app environment with the
+  same marimo-export version and implementation.
+- Loader resolution failure: consume the packed browser package, then install
+  the peer dependency for the imported loader.
+- Blank or duplicated mount: make disposal and abort ownership explicit.
+- Unhelpful state matrix: return to the audience decision and redesign the
+  states rather than adding more.
+
+Record the failed command, error, cause, and correction while working. Keep
+that diagnostic record out of the visible app.

marimo_export-0.0.4/.agent-plugin/skills/notebook-to-static-app/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Notebook to Static App"
+  short_description: "Turn marimo notebooks into static web apps"
+  default_prompt: "Use $notebook-to-static-app to turn this marimo notebook into a polished static web app."

marimo_export-0.0.4/.agent-plugin/skills/notebook-to-static-app/assets/app/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+node_modules/
+dist/
+.exports/
+public/export/

marimo_export-0.0.4/.agent-plugin/skills/notebook-to-static-app/assets/app/index.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="light dark" />
+    <link
+      rel="icon"
+      href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='6' fill='%230880ea'/%3E%3Cpath d='M8 22V10h3l5 7 5-7h3v12h-3v-7l-5 7-5-7v7Z' fill='white'/%3E%3C/svg%3E"
+    />
+    <title>__APP_TITLE__</title>
+  </head>
+  <body>
+    <main id="app" aria-live="polite">
+      <p class="loading">Loading…</p>
+    </main>
+    <script type="module" src="./src/main.ts"></script>
+  </body>
+</html>

marimo_export-0.0.4/.agent-plugin/skills/notebook-to-static-app/assets/app/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - "."

marimo_export-0.0.4/.agent-plugin/skills/notebook-to-static-app/assets/app/src/main.ts

@@ -0,0 +1,4 @@
+import "./style.css";
+
+const root = document.querySelector<HTMLElement>("#app");
+if (root === null) throw new Error("Application root is missing.");

marimo_export-0.0.4/.agent-plugin/skills/notebook-to-static-app/assets/app/src/style.css

@@ -0,0 +1,89 @@
+:root {
+  color: #0f172a;
+  background: #ffffff;
+  font-family: "PT Sans", sans-serif;
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-width: 320px;
+  min-height: 100vh;
+}
+
+button,
+input,
+select,
+textarea {
+  font: inherit;
+}
+
+button,
+select,
+input {
+  min-height: 2.25rem;
+  border: 1px solid #e2e8f0;
+  border-radius: 6px;
+}
+
+button {
+  padding: 0.375rem 0.75rem;
+  color: #0f172a;
+  background: #f1f5f9;
+  cursor: pointer;
+}
+
+button[aria-pressed="true"],
+button[data-active="true"] {
+  color: #f8fafc;
+  background: #0880ea;
+  border-color: #0880ea;
+}
+
+button:focus-visible,
+select:focus-visible,
+input:focus-visible,
+a:focus-visible {
+  outline: 2px solid #94a3b8;
+  outline-offset: 2px;
+}
+
+#app {
+  width: min(100% - 2rem, 1110px);
+  margin-inline: auto;
+  padding-block: 2rem;
+}
+
+h1,
+h2,
+h3 {
+  font-family: Lora, serif;
+}
+
+.loading {
+  color: #64748b;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    color: #eceeed;
+    background: #181c1a;
+  }
+
+  button,
+  select,
+  input {
+    color: #eceeed;
+    background: #252927;
+    border-color: #3b403e;
+  }
+
+  .loading {
+    color: #aab2af;
+  }
+}

marimo_export-0.0.4/.agent-plugin/skills/notebook-to-static-app/assets/app/src/vite-env.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="vite/client" />
+
+declare module "*.css";

marimo_export-0.0.4/.agent-plugin/skills/notebook-to-static-app/assets/app/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "allowImportingTsExtensions": true,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "noEmit": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "noUncheckedIndexedAccess": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES2022",
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src/**/*.ts", "vite.config.ts"]
+}

marimo_export-0.0.4/.agent-plugin/skills/notebook-to-static-app/assets/app/vite.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vite-plus";
+
+export default defineConfig({
+  base: "./",
+  build: {
+    target: "es2022",
+  },
+});

marimo_export-0.0.4/.agent-plugin/skills/notebook-to-static-app/references/contracts.md

@@ -0,0 +1,161 @@
+# marimo-export contracts
+
+## ExportSpec
+
+Declare one default, sparse states, and published outputs:
+
+```yaml
+schema: marimo-export.spec.v2
+default_state: national
+states:
+  national: {}
+  northeast:
+    region: Northeast
+  strict:
+    threshold_slider: 0.8
+outputs:
+  headline:
+    source: { kind: json, selector: summary }
+  chart:
+    source: { kind: export, selector: comparison_chart }
+    exporter: altair.vegalite
+  rows:
+    source: { kind: export, selector: filtered_table }
+    exporter: parquet.table
+```
+
+Planning infers inputs from output dependencies and state-row keys. Sparse rows
+inherit omitted inputs from one baseline. Equivalent rows retain their aliases
+and share one fingerprint.
+
+Run `marimo-export inspect NOTEBOOK --json` to discover definitions and cells.
+Run `marimo-export plan NOTEBOOK --spec FILE --json` to inspect normalized and
+reusable work.
+
+## Preparation
+
+```python
+from marimo_export import ExportSpec, prepare
+
+spec = ExportSpec.from_file("app.export.yaml")
+with prepare("notebook.py", spec=spec) as prepared:
+    prepared.write("public/export", replace=True)
+```
+
+`prepare()` opens a notebook only when repository work is missing. `capture()`
+returns the same leased `PreparedExport` from a named live session.
+
+`PreparedExport` can:
+
+- open the immutable `NotebookExport`
+- lease one file through `asset(relative)`
+- create `marimo-export.prepared.v1` browser metadata through `manifest()`
+- copy and verify a deployment directory through `write()`
+- report prepared and reused state fingerprints
+
+Keep the handle open while serving its files. Close independently leased assets
+after their responses finish.
+
+## Representations
+
+| Notebook result | Exporter or source             | Browser loader         |
+| --------------- | ------------------------------ | ---------------------- |
+| JSON value      | `OutputSpec.json()`            | `jsonLoader()`         |
+| Native scalar   | `OutputSpec.native()`          | `scalarLoader()`       |
+| NumPy array     | `OutputSpec.native()`          | `numpyLoader()`        |
+| Arrow table     | `OutputSpec.native()`          | `arrowTableLoader()`   |
+| Marimo output   | `OutputSpec.output()`          | `marimoOutputLoader()` |
+| Marimo cell     | `OutputSpec.cell()`            | `marimoCellLoader()`   |
+| DataFrame       | `parquet.table`                | `parquetRowsLoader()`  |
+| Altair chart    | `altair.vegalite`              | `vegaLiteLoader()`     |
+| PNG             | `altair.png`                   | `imageLoader()`        |
+| AnyWidget       | `anywidget.bundle`             | `anyWidgetLoader()`    |
+| Custom value    | callable returning `BlobAsset` | custom loader          |
+
+Each descriptor exposes codec, media type, originating Python type, and an inline
+value or content-addressed asset.
+
+## Immutable browser entry
+
+```ts
+import { openExport } from "@marimo-team/marimo-export";
+import { jsonLoader } from "@marimo-team/marimo-export/loader/json";
+
+const notebookExport = await openExport("./export/");
+const state = notebookExport.defaultState;
+const headline = await state.output("headline").load(jsonLoader());
+```
+
+Use `state(alias)`, `resolve(completeInputs)`, or `state.resolve(patch)` to select
+another exported vector.
+
+## Prepared browser entry
+
+```ts
+import { jsonLoader } from "@marimo-team/marimo-export/loader/json";
+import {
+  PreparedPublicationRefresh,
+  PreparedStateController,
+  type PreparedStatePort,
+} from "@marimo-team/marimo-export/prepared";
+
+const port: PreparedStatePort = {
+  async apply({ next }, signal) {
+    const headline = await next.state.output("headline").load(jsonLoader(), { signal });
+    signal.throwIfAborted();
+    document.querySelector("#headline")!.textContent = String(headline);
+  },
+};
+
+const controller = new PreparedStateController(port);
+const manifestUrl = new URL("/runtime/prepared.json", location.href);
+const refresh = new PreparedPublicationRefresh(manifestUrl, controller);
+
+await refresh.start();
+await controller.updateInputs({ region: "Northeast" });
+```
+
+The port loads and commits the complete application state. Stage multi-output
+views before changing visible hosts. `restore()` can reinstate the last committed
+publication after a failure.
+
+## Custom BlobAsset pair
+
+Python:
+
+```python
+import json
+
+from marimo_export.outputs import BlobAsset
+
+
+def encode(value: object) -> BlobAsset:
+    return BlobAsset(
+        data=json.dumps(value).encode(),
+        media_type="application/vnd.example.summary.v1+json",
+        filename="summary.json",
+    )
+```
+
+TypeScript:
+
+```ts
+import { defineBlobAssetLoader } from "@marimo-team/marimo-export";
+
+const summaryLoader = defineBlobAssetLoader({
+  mediaTypes: "application/vnd.example.summary.v1+json",
+  load({ payload, signal }) {
+    signal?.throwIfAborted();
+    return JSON.parse(new TextDecoder().decode(payload.data));
+  },
+});
+```
+
+## Trust boundary
+
+`build`, `prepare`, `capture`, planning that requires inspection, and notebook
+inspection execute notebook or exporter code with the environment's file,
+credential, network, and package access.
+
+Opening and verifying parse inert records. Mounting AnyWidget, Vega-Lite, or a
+custom interactive value grants its module browser page authority.