feat: Initial output storages and improved storage configurator

deno.lock

···
         "npm:astro@^5.7.4",
         "npm:iconoir@^7.11.0",
         "npm:idb-keyval@^6.2.1",
-        "npm:spellcaster@^5.0.2",
+        "npm:native-file-system-adapter@^3.0.1",
         "npm:throttle-debounce@^5.0.2",
         "npm:xxh32@^2.0.5"
       ]

package-lock.json

···
         "@web-applets/sdk": "file:../../unternet-co/web-applets/sdk/",
         "iconoir": "^7.11.0",
         "idb-keyval": "^6.2.1",
-        "spellcaster": "^5.0.2",
+        "native-file-system-adapter": "^3.0.1",
+        "spellcaster": "icidasset/spellcaster#fix/hyper-data",
         "throttle-debounce": "^5.0.2",
         "xxh32": "^2.0.5"
       },
···
         }
       }
     },
+    "node_modules/fetch-blob": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/fetch-blob/-/fetch-blob-3.2.0.tgz",
+      "integrity": "sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/jimmywarting"
+        },
+        {
+          "type": "paypal",
+          "url": "https://paypal.me/jimmywarting"
+        }
+      ],
+      "optional": true,
+      "dependencies": {
+        "node-domexception": "^1.0.0",
+        "web-streams-polyfill": "^3.0.3"
+      },
+      "engines": {
+        "node": "^12.20 || >= 14.13"
+      }
+    },
     "node_modules/flattie": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/flattie/-/flattie-1.1.1.tgz",
···
         "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
       }
     },
+    "node_modules/native-file-system-adapter": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/native-file-system-adapter/-/native-file-system-adapter-3.0.1.tgz",
+      "integrity": "sha512-ocuhsYk2SY0906LPc3QIMW+rCV3MdhqGiy7wV5Bf0e8/5TsMjDdyIwhNiVPiKxzTJLDrLT6h8BoV9ERfJscKhw==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/jimmywarting"
+        },
+        {
+          "type": "paypal",
+          "url": "https://paypal.me/jimmywarting"
+        }
+      ],
+      "engines": {
+        "node": ">=14.8.0"
+      },
+      "optionalDependencies": {
+        "fetch-blob": "^3.2.0"
+      }
+    },
     "node_modules/neotraverse": {
       "version": "0.6.18",
       "resolved": "https://registry.npmjs.org/neotraverse/-/neotraverse-0.6.18.tgz",
···
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/node-domexception": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/node-domexception/-/node-domexception-1.0.0.tgz",
+      "integrity": "sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==",
+      "deprecated": "Use your platform's native DOMException instead",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/jimmywarting"
+        },
+        {
+          "type": "github",
+          "url": "https://paypal.me/jimmywarting"
+        }
+      ],
+      "optional": true,
+      "engines": {
+        "node": ">=10.5.0"
+      }
+    },
     "node_modules/node-fetch": {
       "version": "2.7.0",
       "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.7.0.tgz",
···
       }
     },
     "node_modules/signal-polyfill": {
-      "version": "0.1.2",
-      "resolved": "https://registry.npmjs.org/signal-polyfill/-/signal-polyfill-0.1.2.tgz",
-      "integrity": "sha512-HT9d+L9NMiTzMxb/tU2Baym6129ROyRETSjvchvSkQa7wN0+SrG/IUlsaBLqKn2c+4mlze6CgQBEvgBjxOpiaQ=="
+      "version": "0.2.2",
+      "resolved": "https://registry.npmjs.org/signal-polyfill/-/signal-polyfill-0.2.2.tgz",
+      "integrity": "sha512-p63Y4Er5/eMQ9RHg0M0Y64NlsQKpiu6MDdhBXpyywRuWiPywhJTpKJ1iB5K2hJEbFZ0BnDS7ZkJ+0AfTuL37Rg=="
     },
     "node_modules/simple-swizzle": {
       "version": "0.2.2",
···
     },
     "node_modules/spellcaster": {
       "version": "5.0.2",
-      "resolved": "https://registry.npmjs.org/spellcaster/-/spellcaster-5.0.2.tgz",
-      "integrity": "sha512-suCHnQlCyXAV1OCrL0jEjE8lCK+f2bfmnvBfIqkG6Q3fNiQ7mAaeXtSyEKCI5p2ifSieC5bS/59EcIfDh5PWMA==",
+      "resolved": "git+ssh://[e-mail]/icidasset/spellcaster.git#85038476a872463bb8ef4687418cecb1dd4807f1",
       "dependencies": {
-        "signal-polyfill": "^0.1.0"
+        "signal-polyfill": "^0.2.0"
       }
     },
     "node_modules/string-width": {
···
       "funding": {
         "type": "github",
         "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/web-streams-polyfill": {
+      "version": "3.3.3",
+      "resolved": "https://registry.npmjs.org/web-streams-polyfill/-/web-streams-polyfill-3.3.3.tgz",
+      "integrity": "sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==",
+      "optional": true,
+      "engines": {
+        "node": ">= 8"
       }
     },
     "node_modules/webidl-conversions": {

package.json

···
     "@web-applets/sdk": "file:../../unternet-co/web-applets/sdk/",
     "iconoir": "^7.11.0",
     "idb-keyval": "^6.2.1",
-    "spellcaster": "^5.0.2",
+    "native-file-system-adapter": "^3.0.1",
+    "spellcaster": "icidasset/spellcaster#fix/hyper-data",
     "throttle-debounce": "^5.0.2",
     "xxh32": "^2.0.5"
   },

src/applets/configurator/storage/output/applet.astro

···
 <main class="container">
   <h1>Storage configuration</h1>
-  <p>Here you can select one or more storages (applets) to keep your user data on.</p>
+  <p>
+    Here you can select where you want to keep your user data.
+    <br />
+    By default this will be your browser.
+    <br />
+    Click or tap on one to activate it.
+  </p>
   <div id="options">
-    <p>
-      <span class="with-icon">
-        <i class="iconoir-app-window"></i>
-        <strong>Browser storage</strong>
-      </span>
-
-      <br />
-
-      <span class="pico-color-jade-500 with-icon">
-        <i class="iconoir-check-circle-solid"></i>
-        Activated
-      </span>
-    </p>
-    <p>
-      <span class="with-icon">
-        <i class="iconoir-laptop"></i>
-        <strong>Device storage</strong>
-      </span>
-
-      <br />
-
-      <span class="pico-color-amber-500 with-icon">
-        <i class="iconoir-settings"></i>
-        Needs configuration
-      </span>
-    </p>
-    <p>
-      <span class="with-icon">
-        <i class="iconoir-cloud"></i>
-        <strong>Dropbox</strong>
-      </span>
-
-      <br />
-
-      <span class="pico-color-grey-500 with-icon">
-        <i class="iconoir-xmark-circle"></i>
-        Deactivated
-      </span>
-    </p>
+    <span class="with-icon">
+      <i class="iconoir-bonfire"></i>
+      <small>Just a moment, loading storage options.</small>
+    </span>
   </div>
+  <div id="iframes"></div>
 </main>
 
 <style>
   @import "../../../../styles/configurator.css";
 
+  #iframes {
+    display: none;
+  }
+
   .with-icon {
     align-items: center;
     display: inline-flex;
-    gap: 6px;
+    gap: 10px;
+  }
+
+  [data-storage] {
+    cursor: pointer;
   }
 </style>
 
 <script>
+  // @ts-ignore
+  import scope from "astro:scope";
   import * as IDB from "idb-keyval";
+  import { type Signal, computed, effect, signal } from "spellcaster/spellcaster.js";
+  import { repeat, text } from "spellcaster/hyperscript.js";
   import { applets } from "@web-applets/sdk";
 
-  type Getter = ({ name }: { name: string }) => Promise<Uint8Array | undefined>;
-  type Setter = ({ data, name }: { data: Uint8Array; name: string }) => Promise<void>;
+  import { applet, hs } from "../../../../scripts/theme";
+  import { OutputGetter, OutputSetter } from "../../../core/types";
+
+  const METHODS = ["browser", "device"] as const;
+
+  type Method = (typeof METHODS)[number];
+  type List<M extends Method = Method> = Map<string, ListItem<M>>;
+  type ListItem<M> = { activated: boolean; icon: string; method: M; title: string };
+
+  const DEFAULT_METHOD: Method = "browser";
+  const LOCALSTORAGE_KEY = "applets/configurator/storage/output/active-storage";
 
   ////////////////////////////////////////////
   // SETUP
   ////////////////////////////////////////////
   const context = applets.register();
+  const container = document.getElementById("iframes");
+  if (!container) throw new Error("Missing iframe container");
 
   // TODO: Should migrate + merge data when switching storages
 
+  // Applet connections
+  const storage = {
+    output: {
+      indexedDB: await applet("../../../storage/output/indexed-db/", { container }),
+      nativeFs: await applet("../../../storage/output/native-fs/", { container }),
+    },
+  };
+
   // Initial state
   context.data = undefined;
 
+  // Signals
+  const stored = localStorage.getItem(LOCALSTORAGE_KEY);
+  const [active, setActive] = signal<Method>(
+    stored && METHODS.includes(stored as Method) ? (stored as Method) : DEFAULT_METHOD,
+  );
+
+  effect(() => {
+    localStorage.setItem(LOCALSTORAGE_KEY, active());
+  });
+
+  // Mount + Unmount
+  async function mountStorageMethod(method: Method) {
+    switch (method) {
+      case "browser":
+        await storage.output.indexedDB.sendAction("mount");
+        break;
+      case "device":
+        await storage.output.nativeFs.sendAction("mount");
+        break;
+    }
+  }
+
+  async function unmountStorageMethod(method: Method) {
+    switch (method) {
+      case "browser":
+        await storage.output.indexedDB.sendAction("unmount");
+        break;
+      case "device":
+        await storage.output.nativeFs.sendAction("unmount");
+        break;
+    }
+  }
+
   ////////////////////////////////////////////
-  // ACTIONS
+  // UI
   ////////////////////////////////////////////
-  context.setActionHandler("get", get);
-  context.setActionHandler("put", put);
+  const list = computed<List>(() => {
+    const a = active();
+
+    return new Map([
+      [
+        `browser-${a === "browser"}`,
+        {
+          title: "Browser storage",
+          icon: "iconoir-app-window",
+          method: "browser",
+          activated: a === "browser",
+        },
+      ],
+      [
+        `device-${a === "device"}`,
+        {
+          title: "Device storage",
+          icon: "iconoir-laptop",
+          method: "device",
+          activated: a === "device",
+        },
+      ],
+    ]);
+  });
+
+  const Item = (signal: Signal<ListItem<Method>>) => {
+    const item = signal();
 
-  function selectedStorage() {
-    return localStorage.getItem("storage") || "indexeddb";
+    return hs(
+      "p",
+      scope,
+      {
+        onclick: clickHandler(item.method),
+        style: "cursor: pointer",
+      },
+      [
+        hs("span", scope, { className: "with-icon" }, [
+          hs("i", scope, { className: item.icon }),
+          hs("strong", scope, {}, text(item.title)),
+        ]),
+        hs("br", scope),
+        hs(
+          "span",
+          scope,
+          {
+            className:
+              "with-icon " + (item.activated ? "pico-color-jade-500" : "pico-color-grey-500"),
+          },
+          [
+            hs("i", scope, {
+              className: item.activated ? "iconoir-check-circle-solid" : "iconoir-xmark-circle",
+            }),
+            hs("span", scope, {}, text(item.activated ? "Activated" : "Deactivated")),
+          ],
+        ),
+      ],
+    );
+  };
+
+  const Options = computed(() => hs("div", scope, { id: "options" }, repeat(list, Item)));
+  document.getElementById("options")?.replaceWith(Options());
+
+  function clickHandler(method: Method) {
+    return async () => {
+      const currentlyActive = active();
+      if (currentlyActive === method) return;
+      if (currentlyActive) unmountStorageMethod(currentlyActive);
+
+      await mountStorageMethod(method);
+      setActive(method);
+    };
   }
 
-  async function get(args: Parameters<Getter>[0]) {
-    let data;
+  ////////////////////////////////////////////
+  // ACTIONS
+  ////////////////////////////////////////////
+  const get: OutputGetter = async (args) => {
+    let data: Uint8Array | undefined;
 
-    switch (selectedStorage()) {
-      case "indexeddb": {
-        data = await idbGet(args);
+    switch (active()) {
+      case "browser": {
+        // TODO
+        await storage.output.indexedDB.sendAction("get", args);
+        data = storage.output.indexedDB.data as Uint8Array | undefined;
+        break;
+      }
+      case "device": {
+        // TODO
+        await storage.output.nativeFs.sendAction("get", args);
+        data = storage.output.nativeFs.data as Uint8Array | undefined;
         break;
       }
     }
···
     } else {
       context.data = undefined;
     }
-  }
 
-  async function put(args: Parameters<Setter>[0]) {
-    switch (selectedStorage()) {
-      case "indexeddb":
-        return await idbPut(args);
+    return data;
+  };
+
+  const put: OutputSetter = async (args) => {
+    switch (active()) {
+      case "browser":
+        await storage.output.indexedDB.sendAction("put", args);
+        break;
+      case "device":
+        await storage.output.nativeFs.sendAction("put", args);
+        break;
     }
-  }
-
-  ////////////////////////////////////////////
-  // [Storages]
-  // INDEXED DB
-  ////////////////////////////////////////////
-  const idbGet: Getter = async ({ name }) => {
-    return await IDB.get(name);
   };
 
-  const idbPut: Setter = async ({ data, name }) => {
-    return await IDB.set(name, data);
-  };
+  context.setActionHandler("get", get);
+  context.setActionHandler("put", put);
 </script>

src/applets/configurator/storage/output/manifest.json

···
         "type": "object",
         "properties": {
           "name": { "type": "string" }
-        }
+        },
+        "required": ["name"]
       }
     },
     "put": {
···
         "properties": {
           "data": { "type": "object" },
           "name": { "type": "string" }
-        }
+        },
+        "required": ["data", "name"]
       }
     }
   }

src/applets/core/types.d.ts

···
+/* OUTPUT */
+
 export interface Output<T = TrackTags> {
   sources: Source[];
   tracks: Track<T>[];
 }
 
+export type OutputGetter = ({ name }: { name: string }) => Promise<Uint8Array | undefined>;
+export type OutputSetter = ({ data, name }: { data: Uint8Array; name: string }) => Promise<void>;
+
 /* SOURCES */
+// TODO: Rename to input?
 
 export interface Source<Meta = Record<string, string>> {
   id: string;

src/applets/orchestrator/storage/applet.astro

···
   import { applets } from "@web-applets/sdk";
 
   import type { Output, Source, Track } from "../../core/types.d.ts";
-  import { applet, reactive } from "../../../scripts/theme";
+  import { applet } from "../../../scripts/theme";
 
   ////////////////////////////////////////////
   // SETUP
···
   async function loadSources(): Promise<Source[]> {
     // TODO: This is not concurrency safe!
     await configurator.storage.output.sendAction("get", {
-      name: "sources",
+      name: "sources.json",
     });
 
     const data = configurator.storage.output.data;
-    if (!data) return [SAMPLE_SOURCE];
+
+    if (!data) {
+      saveSources([SAMPLE_SOURCE]);
+      return [SAMPLE_SOURCE];
+    }
+
     return decode(data as Uint8Array);
   }
 
   async function loadTracks(): Promise<Track[]> {
     // TODO: This is not concurrency safe!
     await configurator.storage.output.sendAction("get", {
-      name: "tracks",
+      name: "tracks.json",
     });
 
     const data = configurator.storage.output.data;
-    if (!data) return SAMPLE_TRACKS;
+
+    if (!data) {
+      saveTracks(SAMPLE_TRACKS);
+      return SAMPLE_TRACKS;
+    }
+
     return decode(data as Uint8Array);
   }
 
···
     const data = encode(sources);
 
     configurator.storage.output.sendAction("put", {
-      name: "sources",
+      name: "sources.json",
       data,
     });
   }
···
     const data = encode(tracks);
 
     configurator.storage.output.sendAction("put", {
-      name: "tracks",
+      name: "tracks.json",
       data,
     });
   }

src/applets/storage/output/indexed-db/applet.astro

···
+<script>
+  import * as IDB from "idb-keyval";
+  import { applets } from "@web-applets/sdk";
+
+  import type { OutputGetter, OutputSetter } from "../../../core/types.d.ts";
+
+  ////////////////////////////////////////////
+  // SETUP
+  ////////////////////////////////////////////
+  const IDB_PREFIX = "@applets/storage/output/indexed-db";
+  const context = applets.register();
+
+  ////////////////////////////////////////////
+  // ACTIONS
+  ////////////////////////////////////////////
+  const get: OutputGetter = async ({ name }) => {
+    return await IDB.get(`${IDB_PREFIX}/${name}`);
+  };
+
+  const put: OutputSetter = async ({ data, name }) => {
+    return await IDB.set(`${IDB_PREFIX}/${name}`, data);
+  };
+
+  const mount = async () => {};
+
+  const unmount = async () => {};
+
+  context.setActionHandler("get", get);
+  context.setActionHandler("put", put);
+  context.setActionHandler("mount", mount);
+  context.setActionHandler("unmount", unmount);
+</script>

src/applets/storage/output/indexed-db/manifest.json

···
+{
+  "name": "diffuse/storage/output/indexed-db",
+  "title": "Diffuse Storage | Output | IndexedDB",
+  "entrypoint": "index.html",
+  "actions": {
+    "get": {
+      "title": "Get",
+      "description": "Retrieve data.",
+      "params_schema": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" }
+        },
+        "required": ["name"]
+      }
+    },
+    "put": {
+      "title": "Put",
+      "description": "Store data.",
+      "params_schema": {
+        "type": "object",
+        "properties": {
+          "data": { "type": "object" },
+          "name": { "type": "string" }
+        },
+        "required": ["data", "name"]
+      }
+    },
+    "mount": {
+      "title": "Mount",
+      "description": "Prepare for usage."
+    },
+    "unmount": {
+      "title": "Unmount",
+      "description": "Callback after usage."
+    }
+  }
+}

src/applets/storage/output/native-fs/applet.astro

···
+<script>
+  import * as IDB from "idb-keyval";
+  import { applets } from "@web-applets/sdk";
+  import { type FileSystemDirectoryHandle, showDirectoryPicker } from "native-file-system-adapter";
+
+  import type { OutputGetter, OutputSetter } from "../../../core/types.d.ts";
+
+  ////////////////////////////////////////////
+  // SETUP
+  ////////////////////////////////////////////
+  const IDB_PREFIX = "@applets/storage/output/native-fs";
+  const IDB_DEVICE_KEY = `${IDB_PREFIX}/device`;
+
+  const context = applets.register();
+
+  ////////////////////////////////////////////
+  // ACTIONS
+  ////////////////////////////////////////////
+  const get: OutputGetter = async ({ name }) => {
+    const handle: FileSystemDirectoryHandle | null = await IDB.get(IDB_DEVICE_KEY);
+    if (!handle) throw new Error("Storage not configured properly, handle not found.");
+
+    try {
+      const fileHandle = await handle.getFileHandle(name);
+      const file = await fileHandle.getFile();
+      const data = await file.bytes();
+      // TODO: Should be able to just return the data in the handler
+      context.data = data;
+      return data;
+    } catch (err) {
+      context.data = undefined;
+      return undefined;
+    }
+  };
+
+  const put: OutputSetter = async ({ data, name }) => {
+    const handle: FileSystemDirectoryHandle | null = await IDB.get(IDB_DEVICE_KEY);
+    if (!handle) throw new Error("Storage not configured properly, handle not found.");
+    const fileHandle = await handle.getFileHandle(name, { create: true });
+    const stream = await fileHandle.createWritable();
+    await stream.write(data);
+    await stream.close();
+  };
+
+  const mount = async () => {
+    const existingHandle = await IDB.get(IDB_DEVICE_KEY);
+    if (!existingHandle) {
+      const directoryHandle = await showDirectoryPicker();
+      await IDB.set(IDB_DEVICE_KEY, directoryHandle);
+      await directoryHandle.requestPermission({ mode: "readwrite" });
+    }
+  };
+
+  const unmount = async () => {
+    try {
+      await IDB.del(IDB_DEVICE_KEY);
+    } catch (err) {}
+  };
+
+  context.setActionHandler("get", get);
+  context.setActionHandler("put", put);
+  context.setActionHandler("mount", mount);
+  context.setActionHandler("unmount", unmount);
+</script>

src/applets/storage/output/native-fs/manifest.json

···
+{
+  "name": "diffuse/storage/output/native-fs",
+  "title": "Diffuse Storage | Output | Native File System",
+  "entrypoint": "index.html",
+  "actions": {
+    "get": {
+      "title": "Get",
+      "description": "Retrieve data.",
+      "params_schema": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" }
+        },
+        "required": ["name"]
+      }
+    },
+    "put": {
+      "title": "Put",
+      "description": "Store data.",
+      "params_schema": {
+        "type": "object",
+        "properties": {
+          "data": { "type": "object" },
+          "name": { "type": "string" }
+        },
+        "required": ["data", "name"]
+      }
+    },
+    "mount": {
+      "title": "Mount",
+      "description": "Prepare for usage."
+    },
+    "unmount": {
+      "title": "Unmount",
+      "description": "Callback after usage."
+    }
+  }
+}

src/pages/index.astro

···
   { url: "orchestrator/storage/", title: "Storage" },
 ];
 
-const storages = [];
+const storages = [
+  { url: "storage/output/indexed-db", title: "Output / IndexedDB" },
+  { url: "storage/output/native-fs", title: "Output / Native File System" },
+];
+
+const processors = [];
 
 const themes = [{ url: "themes/pilot/", title: "Pilot" }];
 ---
···
 
     <section>
       <h2>Applets</h2>
+
+      <h3>Configurators</h3>
+
+      <p>
+        <em
+          >Applets that serve as an intermediate in order to make a particular kind of applet
+          configurable. In other words, these allow for an applet to be swapped out with another
+          that takes the same actions and data output.</em
+        >
+      </p>
+
+      <ul>
+        {
+          configurators.map((item: any) => (
+            <li>
+              <a href={item.url}>{item.title}</a>
+            </li>
+          ))
+        }
+      </ul>
 
       <h3>Engines</h3>
 
···
         }
       </ul>
 
-      <h3>Storages</h3>
+      <h3>Processors</h3>
 
       <p>
         <em
-          >Input and output managers of the system. Where input is audio files or streams, and
-          output is derived data such as a music playlist.</em
+          >These applets interact with the bytes provided by the data storage applets, or provide
+          to. This processed data can then be passed on to the UI layer and engine applets.</em
         >
       </p>
 
       <ul>
         {
-          storages.map((item: any) => (
+          processors.map((item: any) => (
             <li>
               <a href={item.url}>{item.title}</a>
             </li>
···
         }
       </ul>
 
-      <h3>Processors</h3>
-
-      <p>
-        <em
-          >These applets interact with the bytes provided by the data storage applets, or provide
-          to. This processed data can then be passed on to the UI layer and engine applets.</em
-        >
-      </p>
-
-      <h3>Configurators</h3>
+      <h3>Storages</h3>
 
       <p>
         <em
-          >Applets that serve as an intermediate in order to make a particular kind of applet
-          configurable. In other words, these allow for an applet to be swapped out with another
-          that takes the same actions and data output.</em
+          >Input and output managers of the system. Where input is audio files or streams, and
+          output is derived data such as a music playlist.</em
         >
       </p>
 
       <ul>
         {
-          configurators.map((item: any) => (
+          storages.map((item: any) => (
             <li>
               <a href={item.url}>{item.title}</a>
             </li>

src/scripts/theme.ts

···
 import type { Applet, AppletEvent } from "@web-applets/sdk";
 
 import { applets } from "@web-applets/sdk";
-import { effect, signal } from "spellcaster/spellcaster.js";
+import { ElementConfigurator, h } from "spellcaster/hyperscript.js";
+import { effect, isSignal, sample, Signal, signal } from "spellcaster/spellcaster.js";
 import { xxh32 } from "xxh32";
 
 ////////////////////////////////////////////
···
   opts: {
     addSlashSuffix?: boolean;
     context?: Window;
+    container?: HTMLElement;
     id?: string;
     setHeight?: boolean;
   } = {},
···
     frame.src = src;
     if (opts.id) frame.id = opts.id;
 
-    (opts.context || window).document.body.appendChild(frame);
+    if (opts.container) {
+      opts.container.appendChild(frame);
+    } else {
+      (opts.context || window).document.body.appendChild(frame);
+    }
   }
 
   if (frame.contentWindow === null) {
···
 ////////////////////////////////////////////
 // 🛠️
 ////////////////////////////////////////////
+export function addScope<O extends Object>(astroScope: string, object: O): O {
+  return {
+    ...object,
+    [`data-astro-cid-${astroScope}`]: "",
+  };
+}
+
 export function comparable(value: unknown) {
   return xxh32(JSON.stringify(value));
+}
+
+export function hs(
+  tag: string,
+  astroScope: string,
+  props?: Record<string, unknown> | Signal<Record<string, unknown>>,
+  configure?: ElementConfigurator,
+) {
+  const propsWithScope =
+    props && isSignal(props)
+      ? () => addScope(astroScope, props())
+      : addScope(astroScope, props || {});
+
+  return h(tag, propsWithScope, configure);
 }
 
 export function isPrimitive(test: unknown) {