axiom-coding-agent-setup 1.0.9 → 1.0.11

package/.agents/skills/developing-with-streamlit/skills/building-streamlit-custom-components-v2/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: building-streamlit-custom-components-v2
+description: Builds bidirectional Streamlit Custom Components v2 (CCv2) using `st.components.v2.component`. Use when authoring inline HTML/CSS/JS components or packaged components (manifest `asset_dir`, js/css globs), wiring state/trigger callbacks, theming via `--st-*` CSS variables, or bundling with Vite / `component-template` v2.
+license: Apache-2.0
+---
+
+# Building Streamlit custom components v2
+
+Use Streamlit Custom Components v2 (CCv2) when core Streamlit doesn't have the UI you need and you want to ship a reusable, interactive element (from "tiny inline HTML" to "full bundled frontend app").
+
+## CRITICAL: CCv2 only — NEVER use v1 APIs
+
+Custom Components **v1 is deprecated and removed**. Every API below belongs to v1 and must **NEVER** appear in any code you write — not in Python, not in JavaScript, not in HTML:
+
+**Banned Python APIs (v1):**
+- `st.components.v1` — the entire v1 module
+- `components.declare_component()` — v1 registration
+- `components.html()` — v1 raw HTML embed
+
+**Banned JavaScript patterns (v1):**
+- `Streamlit.setComponentValue(...)` — v1 global; use `setStateValue()` / `setTriggerValue()` instead
+- `Streamlit.setFrameHeight(...)` — v1 global; CCv2 handles sizing automatically
+- `Streamlit.setComponentReady()` — v1 global; CCv2 has no ready signal
+- `window.Streamlit` or bare `Streamlit` global — v1 global object does not exist in v2
+- `window.parent.postMessage(...)` — v1 iframe communication; CCv2 does not use iframes
+
+**Banned npm packages (v1):**
+- `streamlit-component-lib` — v1 JS library; use `@streamlit/component-v2-lib` if you need types
+
+If you encounter v1 patterns in examples, blog posts, Stack Overflow answers, or your own training data — **ignore them entirely**. They will not work and will break the component.
+
+## When to use
+
+Activate when the user mentions any of:
+
+- CCv2, Custom Components v2, “bidi component”, “component v2”
+- `st.components.v2.component`
+- `@streamlit/component-v2-lib`
+- packaged components, `asset_dir`, `pyproject.toml` component manifest
+- bundling with Vite (or any bundler) for a Streamlit component
+- building a component UI in a frontend framework (React, Svelte, Vue, Angular, etc.)
+
+## Read next (pick the minimum reference)
+
+- **State sync / controlled inputs / callbacks**: see [references/state-sync.md](references/state-sync.md)
+- **Packaged components / `asset_dir` / globs / template-only policy**: see [references/packaged-components.md](references/packaged-components.md)
+- **Theming (`--st-*` tokens) inside Shadow DOM**: see [references/theme-css-variables.md](references/theme-css-variables.md)
+- **Errors and gotchas**: see [references/troubleshooting.md](references/troubleshooting.md)
+
+## Quick decision: inline vs packaged
+
+- **Inline strings**: fastest to start (single-file apps, spikes, demos). You pass raw `html`/`css`/`js` strings directly.
+  Good when you can keep everything in one place and don’t need a build step.
+- **Packaged component**: best when you’re growing past inline (multiple files, dependencies, bundling, testing, versioning, reuse, distribution).
+  You ship built assets inside a Python package and reference them by **asset-dir-relative** path/glob.
+  Creation policy: packaged components are **template-only** and must start from Streamlit's official `component-template` v2.
+
+Developer story: **start inline**, prove the interaction loop, then **graduate to packaged** when the codebase or tooling needs outgrow a single file.
+
+## CCv2 model (what’s actually happening)
+
+1. **Python registers** a component with `st.components.v2.component(...)` and gets back a **mount callable**.
+2. The mount callable **mounts** the component in the app with `data=...`, layout (`width`, `height`), and optional `on_<key>_change` callbacks.
+3. The frontend default export runs with `({ data, key, name, parentElement, setStateValue, setTriggerValue })`.
+4. The component returns a **result object** whose attributes correspond to **state keys** and **trigger keys**.
+
+## Best practice: wrap the mount callable in your own Python API
+
+Prefer exposing **your own** Python function that wraps the callable returned by `st.components.v2.component(...)`.
+
+This gives you a clean, stable API surface for end users (typed parameters, validation, friendly defaults) and keeps `data=...`, `default=...`, and callback wiring as an internal detail.
+
+Important:
+
+- Declare the component **once** (usually at module import time). Avoid defining and registering the component inside a function you call multiple times; you can accidentally re-register the component name and get confusing behavior.
+
+References:
+
+- [`st.components.v2.component`](https://docs.streamlit.io/develop/api-reference/custom-components/st.components.v2.component)
+- [`ComponentRenderer` (mount callable type)](https://docs.streamlit.io/develop/api-reference/custom-components/st.components.v2.types.componentrenderer)
+
+Example pattern:
+
+```python
+import streamlit as st
+from collections.abc import Callable
+
+_MY_COMPONENT = st.components.v2.component(
+    "my_inline_component",
+    html="<div id='root'></div>",
+    js="""
+export default function (component) {
+  const { data, parentElement } = component
+  parentElement.querySelector("#root").textContent = data?.label ?? ""
+}
+""",
+)
+
+
+def my_component(
+    label: str,
+    *,
+    key: str | None = None,
+    on_value_change: Callable[[], None] | None = None,
+    on_submitted_change: Callable[[], None] | None = None,
+):
+    # Callbacks are optional, but if you want result attributes to always exist,
+    # provide (even empty) callbacks.
+    if on_value_change is None:
+        on_value_change = lambda: None
+    if on_submitted_change is None:
+        on_submitted_change = lambda: None
+
+    return _MY_COMPONENT(
+        data={"label": label},
+        key=key,
+        on_value_change=on_value_change,
+        on_submitted_change=on_submitted_change,
+    )
+```
+
+## Inline quickstart (state + trigger)
+
+**Reminder: use ONLY v2 APIs.** Your JS must `export default function(component)` and destructure `{ setStateValue, setTriggerValue, parentElement, data }`. NEVER use `Streamlit.setComponentValue()`, `window.Streamlit`, or any v1 pattern.
+
+This is the minimum "bidi loop":
+
+- **JS → Python**: emit updates via `setStateValue(...)` (persistent) and `setTriggerValue(...)` (event)
+- **Python → JS**: re-hydrate UI via `data=...` on every run
+
+```python
+import streamlit as st
+
+HTML = """<input id="txt" /><button id="btn" type="button">Submit</button>"""
+
+JS = """\
+export default function (component) {
+  const { data, parentElement, setStateValue, setTriggerValue } = component
+
+  const input = parentElement.querySelector("#txt")
+  const btn = parentElement.querySelector("#btn")
+  if (!input || !btn) return
+
+  const nextValue = (data && data.value) ?? ""
+  if (input.value !== nextValue) input.value = nextValue
+
+  input.oninput = (e) => {
+    setStateValue("value", e.target.value)
+  }
+
+  btn.onclick = () => {
+    setTriggerValue("submitted", input.value)
+  }
+}
+"""
+
+my_text_input = st.components.v2.component(
+    "my_inline_text_input",
+    html=HTML,
+    js=JS,
+)
+
+KEY = "txt-1"
+component_state = st.session_state.get(KEY, {})
+value = component_state.get("value", "")
+
+result = my_text_input(
+    key=KEY,
+    data={"value": value},
+    on_value_change=lambda: None,  # optional; include to always get `result.value`
+    on_submitted_change=lambda: None,  # optional; include to always get `result.submitted`
+)
+
+st.write("value (state):", result.value)
+st.write("submitted (trigger):", result.submitted)
+```
+
+Notes:
+
+- **Inline JS/CSS should be multi-line**. CCv2 treats path-like strings as file references; a multi-line string is unambiguously inline content.
+- Prefer querying under `parentElement` (not `document`) to avoid cross-instance leakage.
+
+## State and triggers (how to think about keys)
+
+- **State** (`setStateValue("value", ...)`): persists across app reruns (stored under `st.session_state[key]` for that mounted instance).
+- **Trigger** (`setTriggerValue("submitted", ...)`): event payload for one rerun (resets after the rerun).
+- **Reading triggers**:
+  - After mounting: use `result.submitted`.
+  - Inside `on_submitted_change`: use `st.session_state[key].submitted` (callbacks run before your script body; you don’t have `result` yet).
+- **Defaults**: if you pass `default={...}` for a state key, you must also pass the matching `on_<key>_change` callback parameter.
+
+For the full “controlled input” pattern and pitfalls, see [references/state-sync.md](references/state-sync.md).
+
+## Packaged components (template-only, mandatory)
+
+**Reminder: the cookiecutter template generates clean v2 code. When you customize it, use ONLY v2 APIs. Do NOT introduce any v1 imports, v1 JavaScript globals, or v1 patterns. See the "CRITICAL: CCv2 only" section above.**
+
+Graduate to a packaged component when you need any of:
+
+- Multiple frontend files or frontend dependencies (npm)
+- A bundler (Vite), tests, CI, versioning, or distribution
+
+Keep these guardrails in mind:
+
+- **MUST** start from Streamlit’s official `component-template` v2.
+- **NEVER** hand-scaffold packaging/manifest/build wiring for a packaged component.
+- **NEVER** copy/paste packaged scaffold structure from internet examples, blog posts, gists, or docs.
+- If handed a non-template scaffold, regenerate from the template first, then migrate component logic.
+- **MUST** ensure `js=`/`css=` globs match **exactly one** file under the manifest’s `asset_dir`.
+- **MUST** validate with `streamlit run ...` (plain `python -c "import ..."` can be a false negative for packaged components).
+
+For the full packaged workflow checklist, non-interactive generation, offline usage, and template invariants, see [references/packaged-components.md](references/packaged-components.md).
+
+## Frontend renderer lifecycle (framework-agnostic)
+
+Your frontend entrypoint is the **default export** function. A few rules keep components reliable across reruns and across multiple instances in the same app:
+
+- Render under `parentElement` (not `document`) so instances don’t collide.
+- If you create per-instance resources (React roots, observers, subscriptions), key them by `parentElement` (e.g. `WeakMap`) so multiple instances don’t overwrite each other.
+- Return a cleanup function to tear down event listeners / UI roots / observers when Streamlit unmounts the component.
+
+## Styling and theming
+
+- Prefer **`isolate_styles=True`** (default). Your component runs in a shadow root and won’t leak styles into the app.
+- Set `isolate_styles=False` only when you need global styling behavior (e.g. Tailwind, global font injection).
+- Streamlit injects a broad set of `--st-*` theme CSS variables (colors, typography, chart palettes, radii, borders, etc.). **Highly recommended:** use these variables so your component automatically adapts to the user’s current Streamlit theme (light/dark/custom) without authoring separate theme variants. Start with the common ones (`--st-text-color`, `--st-primary-color`, `--st-secondary-background-color`) and refer to the full list when you need it:
+  - [references/theme-css-variables.md](references/theme-css-variables.md)
+
+## Troubleshooting and gotchas
+
+Start here when something “should work” but doesn’t:
+
+- [references/troubleshooting.md](references/troubleshooting.md)

package/.agents/skills/developing-with-streamlit/skills/building-streamlit-custom-components-v2/references/packaged-components.md

@@ -0,0 +1,212 @@
+## Packaged CCv2 components (template-only, mandatory)
+
+For packaged CCv2 components, agents **MUST** use Streamlit's official template as the starting point for every new component project.
+
+- [Streamlit component-template](https://github.com/streamlit/component-template)
+
+Never hand-scaffold the package/manifest/build layout and never copy/paste a packaged component scaffold from blog posts, gists, docs, or other internet sources.
+
+If a request starts from a non-template scaffold, stop and regenerate from the template first, then port logic into the generated project.
+
+Follow your generated project's README. **Only keep reading if you need to debug template wiring or customize behavior after template generation.**
+
+## Contents
+
+- Agent policy: template-only (mandatory)
+- Prerequisites (packaged components)
+- Start inline, then graduate to packaged
+- Frontend framework note (React is optional)
+- TypeScript support (recommended)
+- Generate a new CCv2 component project
+  - Non-interactive generation (cookiecutter keys)
+  - Offline/airgapped
+- Dev loop (template default)
+- Verify the build output (prevents most load failures)
+- Template invariants (don’t break these)
+- Rename checklist (avoid placeholder-name drift)
+- If you intentionally deviate from the template
+- Verification recommendation
+
+### Agent policy: template-only (mandatory)
+
+If the request is for a packaged CCv2 component:
+
+- Start from the official template first (no exceptions).
+- Never manually scaffold a custom package/manifest/build layout before template generation.
+- Never copy a packaged component scaffold from the internet, even as a "starting point."
+- If given existing non-template scaffolding, regenerate from the template and migrate code into it.
+- Customize only after generation so you retain known-good packaging defaults.
+
+### Prerequisites (packaged components)
+
+- **Python build tooling**: `uv` (recommended) + `cookiecutter`.
+- **Frontend build tooling**: Node.js + npm.
+
+### Start inline, then graduate to packaged
+
+Inline components are great for getting started quickly. Move to a packaged component when you hit any of these:
+
+- You need **multiple frontend files** (components/modules) instead of one big string.
+- You want to pull in **frontend libraries** (npm deps) and run a bundler.
+- You need **tests**, CI, versioning, or distribution (PyPI/private index).
+
+### Frontend framework note (React is optional)
+
+The official Streamlit `component-template` v2 supports both **React + TypeScript (Vite)** and **Pure TypeScript (Vite)** (no React). CCv2 also works with **any frontend framework that compiles to JavaScript** (Svelte, Vue, Angular, vanilla TS/JS, etc.).
+
+The only requirement is that you produce JS/CSS assets into your component’s `asset_dir`, then register them from Python via `html=...`, `js="..."`, and `css="..."` using **asset-dir-relative** paths/globs.
+
+### TypeScript support (recommended)
+
+For end-to-end type safety while authoring the frontend, install `@streamlit/component-v2-lib`:
+
+- [npm package](https://www.npmjs.com/package/@streamlit/component-v2-lib)
+- [docs](https://docs.streamlit.io/develop/api-reference/custom-components/component-v2-lib)
+
+It provides TypeScript types like `FrontendRenderer` / `FrontendRendererArgs` so your `export default` renderer gets a **typed** `data` payload and typed state/trigger keys via generics.
+
+### Generate a new CCv2 component project
+
+This command is the required starting point for every packaged CCv2 component:
+
+```bash
+uvx --from cookiecutter cookiecutter gh:streamlit/component-template --directory cookiecutter/v2
+```
+
+If you run this non-interactively, pass explicit cookiecutter values (do not rely on defaults):
+
+Template keys:
+
+- `author_name`
+- `author_email`
+- `project_name`
+- `package_name`
+- `import_name`
+- `description`
+- `open_source_license`
+- `framework`
+
+Recommended non-interactive invocation:
+
+This sample uses a **hypothetical breadcrumb component** name so the values are concrete and meaningful:
+
+```bash
+uvx --from cookiecutter cookiecutter gh:streamlit/component-template \
+  --directory cookiecutter/v2 \
+  --no-input \
+  author_name="Your Name" \
+  author_email="you@example.com" \
+  project_name="Streamlit Breadcrumbs" \
+  package_name="streamlit-breadcrumbs" \
+  import_name="streamlit_breadcrumbs" \
+  description="Packaged Streamlit CCv2 breadcrumb component" \
+  open_source_license="Apache-2.0" \
+  framework="React + Typescript"
+```
+
+Notes:
+
+- Choice values must match template options exactly (`framework` is `"React + Typescript"` or `"Pure Typescript"`).
+- Passing all keys avoids template placeholder names and post-generation rename churn.
+
+Offline/airgapped:
+
+```bash
+uvx --from cookiecutter cookiecutter /path/to/component-template --directory cookiecutter/v2
+```
+
+### Dev loop (template default)
+
+From the generated project:
+
+1. Activate the target project environment before Python/uv commands:
+
+   ```bash
+   source /path/to/project/.venv/bin/activate
+   ```
+
+2. Build the frontend assets (from `<import_name>/frontend`):
+
+   ```bash
+   npm i
+   npm run build
+   ```
+
+3. Editable install (project root containing `pyproject.toml`):
+
+   ```bash
+   uv pip install -e . --force-reinstall
+   ```
+
+4. Run the example app with Streamlit:
+
+   ```bash
+   streamlit run example.py
+   ```
+
+Why this order:
+
+- Building first ensures `asset_dir` contains the expected files before install/use.
+- Reinstalling editable after key renames keeps metadata and import paths in sync.
+
+### Packaged component workflow (copy/paste checklist)
+
+Use this when debugging or customizing after generation; it's designed to prevent the common "built assets exist but Streamlit can't load them" failure modes.
+
+```
+Packaged CCv2 checklist
+- [ ] Generate project from `component-template` v2
+- [ ] Confirm this is template-generated (not hand-scaffolded, not copied from internet snippets)
+- [ ] Activate the target project environment before Python/uv commands
+- [ ] Rename template defaults (`streamlit-component-x`, `streamlit_component_x`, etc.) if needed
+- [ ] Build frontend assets into the manifest’s `asset_dir` (template: `frontend/build/`)
+- [ ] Editable install the Python package (`uv pip install -e . --force-reinstall`)
+- [ ] Verify `js=`/`css=` globs match exactly one file each under `asset_dir`
+- [ ] Run via `streamlit run ...` and confirm the component renders/events work
+- [ ] If something breaks: read `references/troubleshooting.md`, fix, rebuild, re-verify glob uniqueness
+```
+
+### Verify the build output (prevents most load failures)
+
+- Ensure the manifest’s `asset_dir` exists and contains the built assets.
+- Ensure each glob you register from Python matches **exactly one** file under `asset_dir`:
+  - Typical: `js="index-*.js"` and `css="index-*.css"`
+  - If multiple matches: clean the build output (template: `npm run clean`) and rebuild.
+
+### Template invariants (don’t break these)
+
+You typically shouldn’t need to touch these, but they explain most “why won’t this load?” failures:
+
+- **Component key**: the Python registration key must match the manifest: `"<project.name>.<component.name>"`.
+- **Manifest must ship inside the Python package**: the template places a minimal CCv2 manifest at `<import_name>/pyproject.toml` with `asset_dir = "frontend/build"`.
+- **Asset paths are asset-dir-relative strings**: `js="index-*.js"` (template default output) or `js="assets/index-*.js"` (if you configured an `assets/` subdir).
+- **Globs must match exactly one file**: if `index-*.js` matches multiple hashed builds, clean the build output (`npm run clean`) and rebuild.
+
+### Rename checklist (avoid placeholder-name drift)
+
+Template defaults like `streamlit-component-x` / `streamlit_component_x` should be replaced everywhere early.
+
+Rename all of these together:
+
+- Root folder name (optional but recommended for clarity).
+- Distribution name (`[project].name`) in root `pyproject.toml`.
+- Import package directory (`streamlit_<real_name>`).
+- In-package manifest file and contents (`<import_name>/pyproject.toml`).
+- Wrapper registration key:
+  - `st.components.v2.component("<project.name>.<component.name>", ...)`
+- `MANIFEST.in` and `[tool.setuptools.*]` references.
+- README/example imports and frontend package name.
+
+### Allowed customizations (after template generation only)
+
+Keep the blast radius small:
+
+- If you change output layout, update only the `js=`/`css=` asset-dir-relative globs in the Python wrapper.
+- For Vite, keep `base: "./"` so relative URLs work when served from Streamlit’s component URLs.
+
+### Verification recommendation
+
+Validate packaged components with `streamlit run ...`, not plain `python -c "import ..."` checks.
+
+- Streamlit discovers component manifests as part of runtime setup.
+- Plain import checks can report false-negative `asset_dir` registration errors for otherwise-correct packaged components.

package/.agents/skills/developing-with-streamlit/skills/building-streamlit-custom-components-v2/references/state-sync.md

@@ -0,0 +1,149 @@
+## State sync patterns (JS ↔ Python)
+
+This reference shows the canonical CCv2 “controlled component” loop and the most common pitfalls when syncing state between JavaScript and Python.
+
+## Contents
+
+- Mental model
+- Canonical pattern: controlled text input
+  - JavaScript (hydrate from `data`, emit via `setStateValue`)
+  - Python wrapper (feed state back down via `data`)
+- Defaults: when to use `default=...` (and why it fails)
+- Python → JS hydration: initial-only vs true sync
+- Session State timing: don’t mutate after mount
+- Troubleshooting checklist
+
+### Mental model
+
+- **Frontend state emission (JS → Python)**: you explicitly call `setStateValue(key, value)` or `setTriggerValue(key, value)`.
+- **Frontend state hydration (Python → JS)**: your JS reads `component.data` and updates the DOM accordingly.
+- There is no built-in “two-way binding”: you must implement both sides.
+
+### Canonical pattern: controlled text input
+
+This is modeled after Streamlit’s own CCv2 e2e example.
+
+#### JavaScript (hydrate from `data`, emit via `setStateValue`)
+
+Key guideline: only assign to the input when it’s different, or you’ll fight the user’s cursor.
+
+```js
+export default function (component) {
+  const { parentElement, data, setStateValue } = component
+
+  const label = parentElement.querySelector("label")
+  const input = parentElement.querySelector("input")
+  if (!label || !input) return
+
+  label.innerText = data.label
+
+  const nextValue = data.value ?? ""
+  if (input.value !== nextValue) {
+    input.value = nextValue
+  }
+
+  input.onkeydown = e => {
+    if (e.key === "Enter") {
+      setStateValue("value", e.target.value)
+    }
+  }
+}
+```
+
+#### Python wrapper (feed state back down via `data`)
+
+```python
+import streamlit as st
+
+_COMPONENT = st.components.v2.component(
+    "interactive_text_input",
+    html="""
+    <label for="txt">Enter text:</label>
+    <input id="txt" type="text" />
+    """,
+    js=JS,  # inline JS string from above
+)
+
+
+def interactive_text_input(*, label: str, initial_value: str, key: str):
+    # 1) Read current component state from Session State (if it exists)
+    component_state = st.session_state.get(key, {})
+
+    # 2) Compute the value you want the UI to display
+    value = component_state.get("value", initial_value)
+
+    # 3) Send it down to the frontend via `data`
+    return _COMPONENT(
+        key=key,
+        data={"label": label, "value": value},
+    )
+
+
+KEY = "my_text_input"
+
+if st.button("Make it say Hello World"):
+    st.session_state.setdefault(KEY, {})["value"] = "Hello World"
+
+interactive_text_input(label="Enter something", initial_value="Initial Text", key=KEY)
+```
+
+### Defaults: when to use `default=...` (and why it fails)
+
+`default={...}` is optional. Use it when you want Streamlit to initialize missing state keys for a mounted instance.
+
+Rules:
+
+- Defaults apply only to **state** keys (not triggers).
+- Every key in `default` must have a corresponding `on_<key>_change` callback parameter when mounting, or Streamlit raises.
+
+Pattern:
+
+```python
+result = _COMPONENT(
+    key=key,
+    data={"value": value},
+    default={"value": value},
+    on_value_change=lambda: None,  # required if using default["value"]
+)
+```
+
+### Python → JS hydration: initial-only vs true sync
+
+You’ll see two patterns in the wild:
+
+- **Initial-only hydration**: JS reads `data.initialX` on first mount only. This is useful for *initialization* but it will **not** reflect later Python changes.
+- **True sync (controlled)**: JS reconciles its UI from `data.value` on every render, and only writes when changed.
+
+Initial-only example (pitfall for sync):
+
+```js
+// If you guard hydration with hasMounted, Python changes won't propagate.
+if (typeof data?.initialText !== "undefined" && !hasMountedForKey) {
+  input.value = String(data.initialText)
+}
+hasMounted[key] = true
+```
+
+True sync approach (recommended when Python can update the UI):
+
+```js
+const nextValue = data.value ?? ""
+if (input.value !== nextValue) input.value = nextValue
+```
+
+### Session State timing: don’t mutate after mount
+
+Streamlit may raise if you modify `st.session_state.<key>.<field>` **after** the component with that key has been instantiated in the same run.
+
+Safe patterns:
+
+- Update `st.session_state[key][...]` **before** mounting the component (e.g., in a button handler placed above the mount call).
+- Or update state in a different run (trigger a rerun after setting state).
+
+### Troubleshooting checklist
+
+- **Cursor jumps / typing feels broken**: ensure your JS only assigns `input.value` when it differs from the `data` value.
+- **Python updates don’t reflect in UI**: confirm you pass the updated values via `data` every run; avoid initial-only hydration guards if you want true sync.
+- **`default` raises**: ensure every default key has a corresponding `on_<key>_change` callback parameter.
+- **Session state mutation error**: move `st.session_state[key][...] = ...` earlier in the script (before mount), or restructure into a two-run flow (set state then rerun).
+