begin project-start doc

+ improve embed + repl package doc

packages/embed/README.md

@@ -2,32 +2,63 @@
 
 This package contains a embeddable web component for the Strudel REPL.
 
-## Usage
+## Usage via Script Tag
 
-Either install with `npm i @strudel/embed` or just use a cdn to import the script:
+Use this code in any HTML file:
 
 ```html
 <script src="https://unpkg.com/@strudel/embed@latest"></script>
 <strudel-repl>
   <!--
-note(`[[e5 [b4 c5] d5 [c5 b4]]
+setcps(1)
-[a4 [a4 c5] e5 [d5 c5]]
+n("<0 1 2 3 4>*8").scale('G4 minor')
-[b4 [~ c5] d5 e5]
+.s("gm_lead_6_voice")
-[c5 a4 a4 ~]
+.clip(sine.range(.2,.8).slow(8))
-[[~ d5] [~ f5] a5 [g5 f5]]
+.jux(rev)
-[e5 [~ c5] e5 [d5 c5]]
+.room(2)
-[b4 [b4 c5] d5 e5]
+.sometimes(add(note("12")))
-[c5 a4 a4 ~]],
+.lpf(perlin.range(200,20000).slow(4))
-[[e2 e3]*4]
+-->
-[[a2 a3]*4]
-[[g#2 g#3]*2 [e2 e3]*2]
-[a2 a3 a2 a3 a2 a3 b1 c2]
-[[d2 d3]*4]
-[[c2 c3]*4]
-[[b1 b2]*2 [e2 e3]*2]
-[[a1 a2]*4]`).slow(16)
-      -->
 </strudel-repl>
 ```
 
-Note that the Code is placed inside HTML comments to prevent the browser from treating it as HTML.
+This will load the strudel website in an iframe, using the code provided within the HTML comments `<!-- -->`.
+The HTML comments are needed to make sure the browser won't interpret it as HTML.
+
+Alternatively you can create a REPL from JavaScript like this:
+
+```html
+<script src="https://unpkg.com/@strudel/embed@1.0.2"></script>
+<div id="strudel"></div>
+<script>
+  let editor = document.createElement('strudel-repl');
+  editor.setAttribute(
+    'code',
+    `setcps(1)
+n("<0 1 2 3 4>*8").scale('G4 minor')
+.s("gm_lead_6_voice")
+.clip(sine.range(.2,.8).slow(8))
+.jux(rev)
+.room(2)
+.sometimes(add(note("12")))
+.lpf(perlin.range(200,20000).slow(4))`,
+  );
+  document.getElementById('strudel').append(editor);
+</script>
+```
+
+When you're using JSX, you could also use the `code` attribute in your markup:
+
+```html
+<script src="https://unpkg.com/@strudel/embed@1.0.2"></script>
+<strudel-repl code={`
+setcps(1)
+n("<0 1 2 3 4>*8").scale('G4 minor')
+.s("gm_lead_6_voice")
+.clip(sine.range(.2,.8).slow(8))
+.jux(rev)
+.room(2)
+.sometimes(add(note("12")))
+.lpf(perlin.range(200,20000).slow(4))
+`}></strudel-repl>
+```

packages/embed/embed.js

@@ -4,7 +4,7 @@ class Strudel extends HTMLElement {
   }
   connectedCallback() {
     setTimeout(() => {
-      const code = (this.innerHTML + '').replace('<!--', '').replace('-->', '').trim();
+      const code = this.getAttribute('code') || (this.innerHTML + '').replace('<!--', '').replace('-->', '').trim();
       const iframe = document.createElement('iframe');
       const src = `https://strudel.cc/#${encodeURIComponent(btoa(code))}`;
       // const src = `http://localhost:3000/#${encodeURIComponent(btoa(code))}`;

packages/repl/README.md

@@ -2,4 +2,93 @@
 
 The Strudel REPL as a web component.
 
-[Usage example](https://github.com/tidalcycles/strudel/blob/main/examples/buildless/web-component-no-iframe.html)
+## Add Script Tag
+
+First place this script tag once in your HTML:
+
+```html
+<script src="https://unpkg.com/@strudel/repl@latest"></script>
+```
+
+You can also pin the version like this:
+
+```html
+<script src="https://unpkg.com/@strudel/repl@1.0.2"></script>
+```
+
+This has the advantage that your code will always work, regardless of potential breaking changes in the strudel codebase.
+See [releases](https://github.com/tidalcycles/strudel/releases) for the latest versions.
+
+## Use Web Component
+
+When you've added the script tag, you can use the `strudel-editor` web component:
+
+```html
+<strudel-editor>
+  <!--
+setcps(1)
+n("<0 1 2 3 4>*8").scale('G4 minor')
+.s("gm_lead_6_voice")
+.clip(sine.range(.2,.8).slow(8))
+.jux(rev)
+.room(2)
+.sometimes(add(note("12")))
+.lpf(perlin.range(200,20000).slow(4))
+-->
+</strudel-editor>
+```
+
+This will load the Strudel REPL using the code provided within the HTML comments `<!-- -->`.
+The HTML comments are needed to make sure the browser won't interpret it as HTML.
+
+Alternatively you can create a REPL from JavaScript like this:
+
+```html
+<script src="https://unpkg.com/@strudel/repl@latest"></script>
+<div id="strudel"></div>
+<script>
+  const repl = document.createElement('strudel-editor');
+  repl.setAttribute(
+    'code',
+    `setcps(1)
+n("<0 1 2 3 4>*8").scale('G4 minor')
+.s("gm_lead_6_voice")
+.clip(sine.range(.2,.8).slow(8))
+.jux(rev)
+.room(2)
+.sometimes(add(note("12")))
+.lpf(perlin.range(200,20000).slow(4))`,
+  );
+  document.getElementById('strudel').append(repl);
+</script>
+```
+
+## Interacting with the REPL
+
+If you get a hold of the `strudel-editor` element, you can interact with the strudel REPL from Javascript:
+
+```html
+<script src="https://unpkg.com/@strudel/repl@latest"></script>
+<strudel-editor id="repl">
+  <!-- ... -->
+</strudel-editor>
+<script>
+const repl = document.getElementById('repl');
+console.log(repl.editor);
+</script>
+```
+
+or
+
+```html
+<script src="https://unpkg.com/@strudel/repl@latest"></script>
+<div id="strudel"></div>
+<script>
+  const repl = document.createElement('strudel-editor');
+  repl.setAttribute('code', `...`);
+  document.getElementById('strudel').append(repl);
+  console.log(repl.editor);
+</script>
+```
+
+The `.editor` property on the `strudel-editor` web component gives you the instance of [StrudelMirror]() that runs the REPL.

pnpm-lock.yaml

@@ -452,9 +452,6 @@ importers:
 
   packages/web:
     dependencies:
-      '@rollup/plugin-replace':
-        specifier: ^5.0.5
-        version: 5.0.5
       '@strudel/core':
         specifier: workspace:*
         version: link:../core
@@ -471,6 +468,9 @@ importers:
         specifier: workspace:*
         version: link:../webaudio
     devDependencies:
+      '@rollup/plugin-replace':
+        specifier: ^5.0.5
+        version: 5.0.5
       vite:
         specifier: ^5.0.10
         version: 5.0.10
@@ -563,6 +563,9 @@ importers:
       '@strudel/draw':
         specifier: workspace:*
         version: link:../packages/draw
+      '@strudel/embed':
+        specifier: workspace:*
+        version: link:../packages/embed
       '@strudel/hydra':
         specifier: workspace:*
         version: link:../packages/hydra
@@ -3742,6 +3745,7 @@ packages:
     dependencies:
       '@rollup/pluginutils': 5.1.0
       magic-string: 0.30.5
+    dev: true
 
   /@rollup/pluginutils@3.1.0(rollup@2.79.1):
     resolution: {integrity: sha512-GksZ6pr6TpIjHm8h9lSQ8pi8BE9VeubNT0OMJ3B5uZJ8pz73NPiqOtCog/x2/QzM1ENChPKxMDhiQuRHsqc+lg==}
@@ -3767,6 +3771,7 @@ packages:
       '@types/estree': 1.0.0
       estree-walker: 2.0.2
       picomatch: 2.3.1
+    dev: true
 
   /@rollup/rollup-android-arm-eabi@4.9.2:
     resolution: {integrity: sha512-RKzxFxBHq9ysZ83fn8Iduv3A283K7zPPYuhL/z9CQuyFrjwpErJx0h4aeb/bnJ+q29GRLgJpY66ceQ/Wcsn3wA==}
@@ -7168,6 +7173,7 @@ packages:
 
   /estree-walker@2.0.2:
     resolution: {integrity: sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==}
+    dev: true
 
   /estree-walker@3.0.3:
     resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}

website/package.json

@@ -34,6 +34,7 @@
     "@strudel/mini": "workspace:*",
     "@strudel/osc": "workspace:*",
     "@strudel/repl": "workspace:*",
+    "@strudel/embed": "workspace:*",
     "@strudel/serial": "workspace:*",
     "@strudel/soundfonts": "workspace:*",
     "@strudel/tonal": "workspace:*",

website/src/config.ts

@@ -102,6 +102,7 @@ export const SIDEBAR: Sidebar = {
       { text: 'Strudel vs Tidal', link: 'learn/strudel-vs-tidal' },
     ],
     Development: [
+      { text: 'Strudel in your Project', link: 'technical-manual/project-start' },
       { text: 'REPL', link: 'technical-manual/repl' },
       { text: 'Sounds', link: 'technical-manual/sounds' },
       { text: 'Packages', link: 'technical-manual/packages' },

website/src/layouts/MainLayout.astro

@@ -28,6 +28,10 @@ const githubEditUrl = `${CONFIG.GITHUB_EDIT_URL}/${currentFile}`;
     <title>
       {frontmatter.title ? `${frontmatter.title} 🌀 ${CONFIG.SITE.title}` : CONFIG.SITE.title}
     </title>
+    <script>
+      import '@strudel/embed';
+      import '@strudel/repl';
+    </script>
   </head>
 
   <body class="h-app-height text-gray-50 bg-background">

website/src/pages/technical-manual/project-start.mdx

@@ -0,0 +1,122 @@
+---
+title: Using Strudel in your Project
+layout: ../../layouts/MainLayout.astro
+---
+
+# Using Strudel in your Project
+
+This Guide shows you the different ways to get started with using Strudel in your own project.
+
+## Embedding the Strudel REPL
+
+There are 3 quick ways to embed strudel in your website:
+
+1. Embed the strudel website as an iframe directly
+2. Embed the strudel website as an iframe using `@strudel/embed`
+3. Embed the REPL directly using `@strudel/repl`
+
+### Inside an iframe
+
+Using an iframe is the most easy way to embed a studel tune.
+You can embed any pattern of your choice via an iframe and the URL of the pattern of your choice:
+
+```html
+<iframe src="https://strudel.cc/?xwWRfuCE8TAR" width="600" height="300"></iframe>
+```
+
+The URL can be obtained by pressing `share` in the REPL.
+Note that these share links depend on a database, which is not guaranteed to live forever.
+To make sure your code is not lost, you can also use the long url:
+
+```html
+<iframe
+  src="https://strudel.cc/#c2V0Y3BzKDEpCm4oIjwwIDEgMiAzIDQ%2BKjgiKS5zY2FsZSgnRzQgbWlub3InKQoucygiZ21fbGVhZF82X3ZvaWNlIikKLmNsaXAoc2luZS5yYW5nZSguMiwuOCkuc2xvdyg4KSkKLmp1eChyZXYpCi5yb29tKDIpCi5zb21ldGltZXMoYWRkKG5vdGUoIjEyIikpKQoubHBmKHBlcmxpbi5yYW5nZSgyMDAsMjAwMDApLnNsb3coNCkp"
+  width="600"
+  height="300"
+></iframe>
+```
+
+That long URL can just be copy pasted from the URL bar when you're on the strudel website. It always reflects the latest evaluation of your code.
+
+### Inside an iframe via `@strudel/embed`
+
+To simplify the process of emebdding via an iframe, you can use the package `@strudel/embed`:
+
+```html
+<script src="https://unpkg.com/@strudel/embed@latest"></script>
+<strudel-repl>
+  <!--
+setcps(1)
+n("<0 1 2 3 4>*8").scale('G4 minor')
+.s("gm_lead_6_voice")
+.clip(sine.range(.2,.8).slow(8))
+.jux(rev)
+.room(2)
+.sometimes(add(note("12")))
+.lpf(perlin.range(200,20000).slow(4))
+-->
+</strudel-repl>
+```
+
+This will load the strudel website in an iframe, using the code provided within the HTML comments `<!-- -->`.
+The HTML comments are needed to make sure the browser won't interpret it as HTML.
+
+This is the result:
+
+<strudel-repl code={`setcps(1)
+n("<0 1 2 3 4>*8").scale('G4 minor')
+.s("gm_lead_6_voice")
+.clip(sine.range(.2,.8).slow(8))
+.jux(rev)
+.room(2)
+.sometimes(add(note("12")))
+.lpf(perlin.range(200,20000).slow(4))`}>
+</strudel-repl>
+
+For alternative ways to load this package, see [@strudel/embed README](https://github.com/tidalcycles/strudel/tree/main/packages/embed#strudelembed).
+
+### Without an iframe via `@strudel/repl`
+
+Loading strudel directly in your site looks similar to the iframe variant:
+
+```html
+<script src="https://unpkg.com/@strudel/repl@latest"></script>
+<strudel-editor>
+  <!--
+setcps(1)
+n("<0 1 2 3 4>*8").scale('G4 minor')
+.s("gm_lead_6_voice")
+.clip(sine.range(.2,.8).slow(8))
+.jux(rev)
+.room(2)
+.sometimes(add(note("12")))
+.lpf(perlin.range(200,20000).slow(4))
+-->
+</strudel-editor>
+```
+
+Here, we're loading `@strudel/repl` instead of `@strudel/embed`, and the component is called `strudel-editor` instead of `strudel-repl`.
+Yes the naming is a bit confusing..
+
+<strudel-editor code={`setcps(1)
+n("<0 1 2 3 4>*8").scale('G4 minor')
+.s("gm_lead_6_voice")
+.clip(sine.range(.2,.8).slow(8))
+.jux(rev)
+.room(2)
+.sometimes(add(note("12")))
+.lpf(perlin.range(200,20000).slow(4))`}>
+</strudel-editor>
+
+The upside of using the repl without an iframe is that you can pin the strudel version you're using:
+
+```html
+<script src="https://unpkg.com/@strudel/repl@1.0.2"></script>
+<strudel-editor>
+  <!--
+...  
+-->
+</strudel-editor>
+```
+
+This will guarantee your pattern wont break due to changes to the strudel project in the future.