@deepdeck-apps/strudel-vis-builder

Readme

# Strudel Studio for DeepDeck

A source-backed DeepDeck App that brings the official [Strudel](https://strudel.cc/) browser REPL into a Strudel.cc-style workspace and adds a revision-safe AI Assistant through DeepDeck App Conversations.

## Screenshot

The standalone Strudel Studio workspace combines the official live-coding editor and transport with DeepDeck-native examples, sound browsing, reference, export, console, settings and AI-assisted composition. The screenshot uses the bundled starter pattern and contains no account or personal data.

![Strudel Studio live-coding workspace in DeepDeck](docs/images/deepdeck-strudel-studio.png)

## Install with DeepDeck (recommended)

Install [DeepDeck](https://github.com/jo32/DeepDeck) first, then:

1. Open **Settings → Apps** in DeepDeck.
2. Paste `https://github.com/jo32/dsh-strudel-studio.git` into **Install an App plugin**.
3. Choose **Inspect source**, review the detected package and build command, then choose **Confirm install**.
4. Restart DeepDeck when prompted.
5. Open **Apps → Strudel Studio** from the sidebar.

For local development, build the checkout and install the resulting local bundle into the active DeepDeck web profile:

```bash
git clone https://github.com/jo32/dsh-strudel-studio.git
cd dsh-strudel-studio
bun install
bun test
bun run build
dsh plugin --profile web add "$PWD"
```

The last command mounts the Cordis App bundle. Run it in a DeepDeck-managed profile so the required Apps and App Conversations runtimes are available.

## What changed

The former visual step-sequencer builder and its simulated audio engine have been removed. The App now uses the published upstream runtime directly:

- `@strudel/repl@1.3.0` for CodeMirror, Strudel evaluation, scheduling, highlighting, samples and Web Audio
- `@strudel/core@1.2.6` for compatible Strudel source sharing
- a shell modeled on the upstream Strudel REPL: 40px transport header, full-height editor, right-side menu tabs, examples, sounds, reference, export, console and settings
- a new **AI Assistant** tab connected to the canonical DeepDeck main-Agent Session

The package identity remains `@deepdeck-apps/strudel-vis-builder` and the App ID remains `strudel-vis-builder`.

## AI Assistant contract

The standalone App sends a bounded instruction, the complete current Strudel source, a non-negative revision, and up to four optional pasted images through a fixed `message` action. The bottom-pinned composer supports paste, picker, drag-and-drop, previews, and removal. Users can also select an exact CodeMirror range and right-click to attach it to the composer or trigger a focused Agent rewrite. Questions receive normal Agent replies. Explicit change requests may call one App-owned tool:

- tool: `strudel_apply_source`
- effect: `source.replace`
- result: a complete Strudel source draft, a base revision and a short summary

Pasted images are validated on both runtime and Host boundaries (PNG/JPEG/WebP/GIF, at most four, 5 MiB each and 12 MiB total), stored through the Harness attachment service, and exposed to the Agent only through expiring opaque tokens and `strudel_view_image`. Returned drafts are rejected when stale, oversized, malformed or when they contain browser, DOM, network, storage, navigation, import, cross-window messaging or dynamic-evaluation APIs. A successful draft replaces CodeMirror content but **never starts playback automatically**. The user reviews the code and explicitly presses play/update.

## Runtime isolation

Strudel’s official evaluator intentionally uses dynamic JavaScript evaluation. To keep that capability away from the trusted DeepDeck bridge:

1. The App window is a same-origin bridge page with a CSP that does not permit `unsafe-eval`.
2. The Strudel UI runs inside an iframe with `sandbox="allow-scripts allow-downloads allow-popups"` and no `allow-same-origin`.
3. The child frame therefore has an opaque origin and cannot read the bridge page, DeepDeck local storage or same-origin Host APIs.
4. A private `MessageChannel` carries bounded source and Agent state between the two surfaces.
5. Only the sandboxed runtime CSP allows `unsafe-eval`, remote sample reads and blob workers.

User-authored Strudel still executes as JavaScript inside that sandbox after an explicit play/update action. The default upstream sample manifests are loaded from `raw.githubusercontent.com`, so first playback may require network access.

## Development

```bash
bun install
bun test
bun run build
```

When editing this registered DeepDeck App Workspace, use the Creator apply lifecycle instead of invoking the build separately. Generated `lib/` output is build-only.

## Architecture

| Area | Source |
| --- | --- |
| Cordis Host registration, CSP routes and action tool | `src/index.js` |
| DeepDeck launcher and main-Agent action | `src/client.js` |
| Trusted App-window bridge and revision owner | `src/app.js` |
| Opaque-origin official Strudel runtime and UI | `src/runtime.js` |
| Source, AI validation and starter pattern | `src/studio-model.js` |
| Agent prompt contract | `src/agent-actions.js` |
| Agent Session continuation routing | `src/agent-continuation.js` |
| Standalone UI styling | `src/app.css` |

## Upstream and license

This App is based on [uzu/strudel](https://codeberg.org/uzu/strudel) and includes the unmodified published Strudel REPL package. Strudel and this combined App are licensed under **GNU AGPL-3.0-or-later**. See [LICENSE](LICENSE).

- Upstream source: <https://codeberg.org/uzu/strudel>
- Upstream integration guide: <https://strudel.cc/technical-manual/project-start/>
- Strudel documentation: <https://strudel.cc/learn/>
- App source: <https://github.com/jo32/dsh-strudel-studio>

The Strudel name and upstream project remain independent. This integration is modified for DeepDeck and comes with no warranty.