From 7a694197e31af3f4ea896587ae2af70febf203a6 Mon Sep 17 00:00:00 2001
From: Steven Vandevelde <steven@tokono.ma>
Date: Mon, 9 Jun 2025 18:49:42 +0200
Subject: [PATCH] feat: load artwork into artwork controller

---
 .../desktop/artwork-controller/_applet.astro  | 179 ++++++++++++++++--
 .../desktop/artwork-controller/_manifest.json |   2 +-
 .../desktop/artwork-controller/types.d.ts     |   4 -
 .../constituents/pilot/audio/_applet.astro    |   9 +-
 src/pages/engine/audio/_applet.astro          | 108 +++++------
 src/pages/engine/audio/_manifest.json         |  74 ++++----
 src/pages/engine/audio/types.d.ts             |   6 +-
 src/pages/engine/queue/_manifest.json         |   5 +-
 src/pages/engine/queue/types.d.ts             |  14 +-
 src/pages/index.astro                         |  12 ++
 .../orchestrator/input-cache/_applet.astro    |   6 +-
 .../orchestrator/single-queue/_applet.astro   | 117 ++++++------
 src/pages/processor/artwork/_applet.astro     |  55 ++++--
 src/scripts/applets/common.ts                 |  80 +++++---
 src/scripts/themes/desktop/index.ts           |  39 +---
 src/scripts/themes/webamp/index.ts            |   4 +-
 src/styles/diffuse/colors.css                 |  17 ++
 src/styles/diffuse/fonts.css                  |  14 ++
 src/styles/pages/index.css                    |  34 +---
 19 files changed, 480 insertions(+), 299 deletions(-)
 delete mode 100644 src/pages/constituents/desktop/artwork-controller/types.d.ts
 create mode 100644 src/styles/diffuse/colors.css
 create mode 100644 src/styles/diffuse/fonts.css

diff --git a/src/pages/constituents/desktop/artwork-controller/_applet.astro b/src/pages/constituents/desktop/artwork-controller/_applet.astro
index b778142..97e1815 100644
--- a/src/pages/constituents/desktop/artwork-controller/_applet.astro
+++ b/src/pages/constituents/desktop/artwork-controller/_applet.astro
@@ -3,52 +3,197 @@ import "@styles/reset.css";
 import "@styles/variables.css";
 import "@styles/fonts.css";
 import "@styles/icons.css";
+
+import "@styles/diffuse/colors.css";
+import "@styles/diffuse/fonts.css";
 ---
 
 <main>TODO</main>
 
 <style>
   main {
+    background: var(--color-3);
+    background-size: cover;
+    color: var(--color-2);
     padding: var(--space-md);
   }
 </style>
 
+<style is:global>
+  iframe {
+    display: none;
+  }
+</style>
+
 <script>
-  import scope from "astro:scope";
+  import * as Uint8 from "uint8arrays";
 
   import { computed, effect, type Signal, signal } from "spellcaster";
   import { repeat, tags, text } from "spellcaster/hyperscript.js";
+  import { xxh32 } from "xxh32";
 
   import { applets } from "@web-applets/sdk";
 
-  import type { State } from "./types.d.ts";
-
-  const context = applets.register<State>();
+  import type { ManagedOutput } from "@applets/core/types";
+  import { applet, comparable, inputUrl, reactive, wait } from "@scripts/applets/common";
 
   ////////////////////////////////////////////
-  // Initial state
+  // SETUP
   ////////////////////////////////////////////
-  context.data = {
-    isPlaying: false,
+  import type * as AudioEngine from "@applets/engine/audio/types.d.ts";
+  import type * as QueueEngine from "@applets/engine/queue/types.d.ts";
+
+  import type { Artwork } from "@applets/processor/artwork/types";
+
+  const context = applets.register();
+
+  // Initial state
+  const [artwork, setArtwork] = signal<Artwork[]>([]);
+  const [groupId, setGroupId] = signal(crypto.randomUUID());
+  const [isPlaying, setIsPlaying] = signal(false);
+
+  // Applet connections
+  const configurator = {
+    input: await applet("../../../configurator/input"),
+    output: await applet<ManagedOutput>("../../../configurator/output"),
+  };
+
+  const engine = {
+    audio: await applet<AudioEngine.State>("../../engine/audio", { groupId: groupId() }),
+    queue: await applet<QueueEngine.State>("../../engine/queue", { groupId: groupId() }),
+  };
+
+  const orchestrator = {
+    inputCache: await applet("../../../orchestrator/input-cache"),
+  };
+
+  const processor = {
+    artwork: await applet("../../../processor/artwork"),
   };
 
   ////////////////////////////////////////////
-  // Actions
+  // 🎢 QUEUE
   ////////////////////////////////////////////
-  context.setActionHandler("modifyIsPlaying", (isPlaying: boolean) => {
-    // NOTE: Doesn't trigger a `data` event
-    context.data.isPlaying = isPlaying;
-    render();
-  });
 
-  context.setActionHandler("modifyProgress", (progress: number) => {
-    // TODO
+  // TODO: Shuffle, limit amount, etc.
+  async function fillQueue() {
+    await engine.queue.sendAction("add", configurator.output.data.tracks.collection, {
+      timeoutDuration: 60000,
+    });
+  }
+
+  // When the active audio has ended,
+  // shift the queue.
+
+  // NOTE:
+  // This could probably be optimised, but it works.
+
+  reactive(
+    engine.audio,
+    (data) => data.items[engine.queue.data.now?.id ?? Infinity]?.hasEnded ?? false,
+    (hasEnded) => {
+      if (hasEnded) engine.queue.sendAction("shift");
+    },
+  );
+
+  // When the active queue item has changed,
+  // coordinate the audio engine accordingly.
+
+  reactive(
+    engine.queue,
+    (data) => data.now?.id,
+    async () => {
+      const playingNow = engine.queue.data.now;
+      const volume = engine.audio.data.volume;
+
+      // Play new active queue item
+      // TODO: Take URL expiration timestamp into account
+      // TODO: Preload next queue item
+      engine.audio.sendAction(
+        "render",
+        {
+          audio: playingNow
+            ? [
+                {
+                  id: playingNow.id,
+                  isPreload: false,
+                  url: await inputUrl(configurator.input, playingNow.uri),
+                },
+              ]
+            : // NOTE: This probably isn't correct, keep preloads?
+              [],
+          play: playingNow
+            ? {
+                audioId: playingNow.id,
+                volume,
+              }
+            : undefined,
+        },
+        {
+          timeoutDuration: 60000,
+        },
+      );
+
+      // Add more tracks to the queue if needed
+      if (playingNow) fillQueue();
+    },
+  );
+
+  // Add tracks to the queue once the tracks have been loaded.
+
+  wait(configurator.output, (d) => d?.tracks.state === "loaded").then(() => {
+    reactive(configurator.output, (d) => d.tracks.cacheId, fillQueue);
   });
 
+  // Show artwork of active queue item.
+
+  reactive(
+    engine.queue,
+    (data) => comparable(data.future),
+    async () => {
+      const track = engine.queue.data.now || engine.queue.data.future[0];
+
+      console.log(track);
+
+      if (!track) return;
+
+      const art = await processor.artwork.sendAction(
+        "artwork",
+        {
+          cacheId: xxh32(track.uri), // TODO: Probably switch to SHA256 or another more secure hashing algo
+          tags: track.tags,
+          urls: {
+            get: await inputUrl(configurator.input, track.uri, "GET").then((a) => a?.url),
+            head: await inputUrl(configurator.input, track.uri, "HEAD").then((a) => a?.url),
+          },
+        },
+        {
+          timeoutDuration: 60000 * 5,
+        },
+      );
+
+      console.log("Art", art);
+
+      setArtwork(art);
+    },
+  );
+
   ////////////////////////////////////////////
-  // DOM
+  // UI
   ////////////////////////////////////////////
-  // TODO: Events
+
+  effect(() => {
+    const art = artwork();
+
+    // TODO: Remove existing art?
+    if (art.length === 0) return;
+
+    // Show artwork
+    const blob = new Blob([art[0].bytes], { type: art[0].mime });
+    const url = URL.createObjectURL(blob);
+
+    document.querySelector("main")?.setAttribute("style", `background-image: url(${url})`);
+  });
 
   function render() {
     // TODO
diff --git a/src/pages/constituents/desktop/artwork-controller/_manifest.json b/src/pages/constituents/desktop/artwork-controller/_manifest.json
index 9fb2fc3..59ef5d3 100644
--- a/src/pages/constituents/desktop/artwork-controller/_manifest.json
+++ b/src/pages/constituents/desktop/artwork-controller/_manifest.json
@@ -1,6 +1,6 @@
 {
   "name": "diffuse/constituents/desktop/artwork-controller",
-  "title": "",
+  "title": "Diffuse Desktop Theme | Artwork Controller",
   "entrypoint": "index.html",
   "actions": {
     "modifyIsPlaying": {
diff --git a/src/pages/constituents/desktop/artwork-controller/types.d.ts b/src/pages/constituents/desktop/artwork-controller/types.d.ts
deleted file mode 100644
index abb4cae..0000000
--- a/src/pages/constituents/desktop/artwork-controller/types.d.ts
+++ /dev/null
@@ -1,4 +0,0 @@
-export interface State {
-  isPlaying: boolean;
-  seekPosition?: number;
-}
diff --git a/src/pages/constituents/pilot/audio/_applet.astro b/src/pages/constituents/pilot/audio/_applet.astro
index 8618a2a..158e202 100644
--- a/src/pages/constituents/pilot/audio/_applet.astro
+++ b/src/pages/constituents/pilot/audio/_applet.astro
@@ -98,17 +98,18 @@ import "@styles/themes/pilot/variables.css";
 
   import type { State } from "./types.d.ts";
 
+  ////////////////////////////////////////////
+  // SETUP
+  ////////////////////////////////////////////
   const context = applets.register<State>();
 
-  ////////////////////////////////////////////
   // Initial state
-  ////////////////////////////////////////////
   context.data = {
     isPlaying: false,
   };
 
   ////////////////////////////////////////////
-  // Actions
+  // ACTIONS
   ////////////////////////////////////////////
   context.setActionHandler("modifyIsPlaying", (isPlaying: boolean) => {
     // NOTE: Doesn't trigger a `data` event
@@ -123,7 +124,7 @@ import "@styles/themes/pilot/variables.css";
   });
 
   ////////////////////////////////////////////
-  // DOM
+  // UI
   ////////////////////////////////////////////
   document.body.querySelector(".controls__playpause")?.addEventListener("click", () => {
     context.data = { ...context.data, isPlaying: !(context.data?.isPlaying ?? false) };
diff --git a/src/pages/engine/audio/_applet.astro b/src/pages/engine/audio/_applet.astro
index 43d1b8f..6adef80 100644
--- a/src/pages/engine/audio/_applet.astro
+++ b/src/pages/engine/audio/_applet.astro
@@ -1,5 +1,5 @@
 <script>
-  import type { State, Track, TrackState } from "./types";
+  import type { State, Audio, AudioState } from "./types";
   import { register } from "@scripts/applets/common";
 
   ////////////////////////////////////////////
@@ -31,12 +31,12 @@
     context.data = { ...context.data, ...partial };
   }
 
-  function updateItems(trackId: string, partial: Partial<TrackState>): void {
+  function updateItems(audioId: string, partial: Partial<AudioState>): void {
     update({
       ...context.data,
       items: {
         ...(context.data?.items || {}),
-        [trackId]: { ...(context.data?.items?.[trackId] || {}), ...partial },
+        [audioId]: { ...(context.data?.items?.[audioId] || {}), ...partial },
       },
     });
   }
@@ -51,12 +51,12 @@
   context.setActionHandler("seek", seek);
   context.setActionHandler("volume", volume);
 
-  function pause({ trackId }: { trackId: string }) {
-    withAudioNode(trackId, (audio) => audio.pause());
+  function pause({ audioId }: { audioId: string }) {
+    withAudioNode(audioId, (audio) => audio.pause());
   }
 
-  function play({ trackId, volume }: { trackId: string; volume?: number }) {
-    withAudioNode(trackId, (audio) => {
+  function play({ audioId, volume }: { audioId: string; volume?: number }) {
+    withAudioNode(audioId, (audio) => {
       audio.volume = volume ?? 0.5;
       audio.muted = false;
 
@@ -78,13 +78,13 @@
           return; /* The node was removed from the DOM, we can ignore this error */
         const err = "Couldn't play audio automatically. Please resume playback manually.";
         console.error(err, e);
-        updateItems(trackId, { isPlaying: false });
+        updateItems(audioId, { isPlaying: false });
       });
     });
   }
 
-  function reload(args: { play: boolean; progress?: number; trackId: string }) {
-    withAudioNode(args.trackId, (audio) => {
+  function reload(args: { play: boolean; progress?: number; audioId: string }) {
+    withAudioNode(args.audioId, (audio) => {
       if (audio.readyState === 0 || audio.error?.code === 2) {
         audio.load();
 
@@ -93,29 +93,29 @@
         }
 
         if (args.play) {
-          play({ trackId: args.trackId, volume: audio.volume });
+          play({ audioId: args.audioId, volume: audio.volume });
         }
       }
     });
   }
 
-  async function render(args: { play?: { trackId: string; volume?: number }; tracks: Track[] }) {
-    await renderTracks(args.tracks);
-    if (args.play) play({ trackId: args.play.trackId, volume: args.play.volume });
+  async function render(args: { play?: { audioId: string; volume?: number }; audio: Audio[] }) {
+    await renderAudio(args.audio);
+    if (args.play) play({ audioId: args.play.audioId, volume: args.play.volume });
   }
 
-  function seek({ percentage, trackId }: { percentage: number; trackId: string }) {
-    withAudioNode(trackId, (audio) => {
+  function seek({ percentage, audioId }: { percentage: number; audioId: string }) {
+    withAudioNode(audioId, (audio) => {
       if (!isNaN(audio.duration)) {
         audio.currentTime = audio.duration * percentage;
       }
     });
   }
 
-  function volume(args: { trackId?: string; volume: number }) {
+  function volume(args: { audioId?: string; volume: number }) {
     Array.from(container.querySelectorAll('audio[data-is-preload="false"]')).forEach((node) => {
       const audio = node as HTMLAudioElement;
-      if (args.trackId === undefined || args.trackId === audio.id) {
+      if (args.audioId === undefined || args.audioId === audio.id) {
         audio.volume = args.volume;
       }
     });
@@ -124,8 +124,8 @@
   ////////////////////////////////////////////
   // RENDER
   ////////////////////////////////////////////
-  async function renderTracks(tracks: Array<Track>) {
-    const ids = tracks.map((e) => e.id);
+  async function renderAudio(audio: Array<Audio>) {
+    const ids = audio.map((a) => a.id);
     const existingNodes: Record<string, HTMLAudioElement> = {};
 
     // Manage existing nodes
@@ -139,32 +139,32 @@
     });
 
     // Adjust existing and add new
-    await tracks.reduce(async (acc: Promise<void>, track: Track) => {
+    await audio.reduce(async (acc: Promise<void>, item: Audio) => {
       await acc;
 
-      const existingNode = existingNodes[track.id];
+      const existingNode = existingNodes[item.id];
 
       if (existingNode) {
         const isPreload = existingNode.getAttribute("data-is-preload");
         if (isPreload === "true") existingNode.setAttribute("data-did-preload", "true");
 
-        existingNode.setAttribute("data-is-preload", track.isPreload ? "true" : "false");
+        existingNode.setAttribute("data-is-preload", item.isPreload ? "true" : "false");
       } else {
-        await createElement(track);
+        await createElement(item);
       }
     }, Promise.resolve());
 
     // Now playing state
-    const items = tracks.reduce((acc, track) => {
+    const items = audio.reduce((acc, item) => {
       return {
         ...acc,
-        [track.id]: context.data?.items?.[track.id] || {
+        [item.id]: context.data?.items?.[item.id] || {
           duration: 0,
-          id: track.id,
+          id: item.id,
           loadingState: "loading",
           isPlaying: true,
-          isPreload: track.isPreload ?? false,
-          progress: track.progress ?? 0,
+          isPreload: item.isPreload ?? false,
+          progress: item.progress ?? 0,
         },
       };
     }, {});
@@ -172,36 +172,36 @@
     update({ items });
   }
 
-  export async function createElement(track: Track) {
+  export async function createElement(audio: Audio) {
     const source = document.createElement("source");
-    if (track.mimeType) source.setAttribute("type", track.mimeType);
-    source.setAttribute("src", track.url);
+    if (audio.mimeType) source.setAttribute("type", audio.mimeType);
+    source.setAttribute("src", audio.url);
 
     // Audio node
-    const audio = new Audio();
-    audio.setAttribute("id", track.id);
-    audio.setAttribute("crossorigin", "anonymous");
-    audio.setAttribute("data-is-preload", track.isPreload ? "true" : "false");
-    audio.setAttribute("muted", "true");
-    audio.setAttribute("preload", "auto");
-
-    if (track.progress !== undefined) {
-      audio.setAttribute("data-initial-progress", JSON.stringify(track.progress));
+    const node = new Audio();
+    node.setAttribute("id", audio.id);
+    node.setAttribute("crossorigin", "anonymous");
+    node.setAttribute("data-is-preload", audio.isPreload ? "true" : "false");
+    node.setAttribute("muted", "true");
+    node.setAttribute("preload", "auto");
+
+    if (audio.progress !== undefined) {
+      node.setAttribute("data-initial-progress", JSON.stringify(audio.progress));
     }
 
-    audio.appendChild(source);
+    node.appendChild(source);
 
-    audio.addEventListener("canplay", canplayEvent);
-    audio.addEventListener("durationchange", durationchangeEvent);
-    audio.addEventListener("ended", endedEvent);
-    audio.addEventListener("error", errorEvent);
-    audio.addEventListener("pause", pauseEvent);
-    audio.addEventListener("play", playEvent);
-    audio.addEventListener("suspend", suspendEvent);
-    audio.addEventListener("timeupdate", timeupdateEvent);
-    audio.addEventListener("waiting", waitingEvent);
+    node.addEventListener("canplay", canplayEvent);
+    node.addEventListener("durationchange", durationchangeEvent);
+    node.addEventListener("ended", endedEvent);
+    node.addEventListener("error", errorEvent);
+    node.addEventListener("pause", pauseEvent);
+    node.addEventListener("play", playEvent);
+    node.addEventListener("suspend", suspendEvent);
+    node.addEventListener("timeupdate", timeupdateEvent);
+    node.addEventListener("waiting", waitingEvent);
 
-    container?.appendChild(audio);
+    container?.appendChild(node);
   }
 
   ////////////////////////////////////////////
@@ -298,8 +298,8 @@
     if (node) fn(node);
   }
 
-  function withAudioNode(trackId: string, fn: (node: HTMLAudioElement) => void): void {
-    const node = container.querySelector(`audio[id="${trackId}"][data-is-preload="false"]`);
+  function withAudioNode(audioId: string, fn: (node: HTMLAudioElement) => void): void {
+    const node = container.querySelector(`audio[id="${audioId}"][data-is-preload="false"]`);
     if (node) fn(node as HTMLAudioElement);
   }
 </script>
diff --git a/src/pages/engine/audio/_manifest.json b/src/pages/engine/audio/_manifest.json
index efcf2c6..8b3444e 100644
--- a/src/pages/engine/audio/_manifest.json
+++ b/src/pages/engine/audio/_manifest.json
@@ -5,24 +5,24 @@
   "actions": {
     "pause": {
       "title": "Pause",
-      "description": "Pause a track",
+      "description": "Pause audio",
       "params_schema": {
         "type": "object",
         "properties": {
-          "trackId": {
+          "audioId": {
             "type": "string"
           }
         },
-        "required": ["trackId"]
+        "required": ["audioId"]
       }
     },
     "play": {
       "title": "Play",
-      "description": "Play a track",
+      "description": "Play audio",
       "params_schema": {
         "type": "object",
         "properties": {
-          "trackId": {
+          "audioId": {
             "type": "string"
           },
           "volume": {
@@ -30,7 +30,7 @@
             "default": 0.5
           }
         },
-        "required": ["trackId"]
+        "required": ["audioId"]
       }
     },
     "render": {
@@ -39,25 +39,9 @@
       "params_schema": {
         "type": "object",
         "properties": {
-          "play": {
-            "type": "object",
-            "description": "Pass in this object to immediately start playing one of the rendered tracks.",
-            "properties": {
-              "trackId": {
-                "type": "string",
-                "description": "The id of the rendered track we want to play."
-              },
-              "volume": {
-                "type": "number",
-                "default": 0.5,
-                "description": "A number equal to, or between, 0 and 1, that determines how loud the track should play."
-              }
-            },
-            "required": ["trackId"]
-          },
-          "tracks": {
+          "audio": {
             "type": "array",
-            "description": "The tracks we want to render.",
+            "description": "The audio items we want to render. These represent the audio elements that are in the DOM.",
             "items": {
               "type": "object",
               "properties": {
@@ -69,54 +53,70 @@
               },
               "required": ["id", "url"]
             }
+          },
+          "play": {
+            "type": "object",
+            "description": "Pass in this object to immediately start playing one of the rendered audio items.",
+            "properties": {
+              "audioId": {
+                "type": "string",
+                "description": "The id of the rendered audio item we want to play."
+              },
+              "volume": {
+                "type": "number",
+                "default": 0.5,
+                "description": "A number equal to, or between, 0 and 1, that determines how loud the audio should play."
+              }
+            },
+            "required": ["audioId"]
           }
         },
-        "required": ["tracks"]
+        "required": ["audio"]
       }
     },
     "reload": {
       "title": "Reload",
-      "description": "Make sure the audio node with the given track id is loading properly. This should be used when for example, the internet connection comes back and the loading of the track depended on said internet connection.",
+      "description": "Make sure the audio with the given id is loading properly. This should be used when for example, the internet connection comes back and the loading of the audio depended on said internet connection.",
       "params_schema": {
         "type": "object",
         "properties": {
+          "audioId": {
+            "type": "string"
+          },
           "play": {
             "type": "boolean"
           },
           "progress": {
             "type": "number"
-          },
-          "trackId": {
-            "type": "string"
           }
         },
-        "required": ["percentage", "trackId"]
+        "required": ["audioId", "percentage"]
       }
     },
     "seek": {
       "title": "Seek",
-      "description": "Seek a track to a given position",
+      "description": "Seek audio to a given position",
       "params_schema": {
         "type": "object",
         "properties": {
+          "audioId": {
+            "type": "string"
+          },
           "percentage": {
             "type": "number",
             "description": "A number between 0 and 1 that determines the new current position in the audio"
-          },
-          "trackId": {
-            "type": "string"
           }
         },
-        "required": ["percentage", "trackId"]
+        "required": ["audioId", "percentage"]
       }
     },
     "volume": {
       "title": "Volume",
-      "description": "Set the volume of all tracks, or a specific track.",
+      "description": "Set the volume of all audio, or a specific audio node.",
       "params_schema": {
         "type": "object",
         "properties": {
-          "trackId": {
+          "audioId": {
             "type": "string"
           },
           "volume": {
diff --git a/src/pages/engine/audio/types.d.ts b/src/pages/engine/audio/types.d.ts
index aa61738..1ba9eea 100644
--- a/src/pages/engine/audio/types.d.ts
+++ b/src/pages/engine/audio/types.d.ts
@@ -1,9 +1,9 @@
 export interface State {
-  items: Record<string, TrackState>;
+  items: Record<string, AudioState>;
   volume: number;
 }
 
-export interface Track {
+export interface Audio {
   id: string;
   isPreload: boolean;
   mimeType?: string;
@@ -11,7 +11,7 @@ export interface Track {
   url: string;
 }
 
-export interface TrackState {
+export interface AudioState {
   duration: number;
   id: string;
   hasEnded: boolean;
diff --git a/src/pages/engine/queue/_manifest.json b/src/pages/engine/queue/_manifest.json
index e1273e1..1de329e 100644
--- a/src/pages/engine/queue/_manifest.json
+++ b/src/pages/engine/queue/_manifest.json
@@ -13,11 +13,10 @@
             {
               "type": "object",
               "properties": {
-                "expiresAt": { "type": "number" },
                 "id": { "type": "string" },
-                "url": { "type": "string" }
+                "uri": { "type": "string" }
               },
-              "required": ["expiresAt", "id", "url"]
+              "required": ["id", "uri"]
             }
           ]
         }
diff --git a/src/pages/engine/queue/types.d.ts b/src/pages/engine/queue/types.d.ts
index 229c328..4795771 100644
--- a/src/pages/engine/queue/types.d.ts
+++ b/src/pages/engine/queue/types.d.ts
@@ -1,11 +1,7 @@
-export interface QueueItem {
-  expiresAt: number;
-  id: string;
-  url: string;
-}
+import type { Track } from "@applets/core/types";
 
-export interface State {
-  past: QueueItem[];
-  now: QueueItem | null;
-  future: QueueItem[];
+export interface State<Stats = TrackStats, Tags = TrackTags> {
+  past: Track<Stats, Tags>[];
+  now: Track<Stats, Tags> | null;
+  future: Track<Stats, Tags>[];
 }
diff --git a/src/pages/index.astro b/src/pages/index.astro
index 2452d7a..70b453f 100644
--- a/src/pages/index.astro
+++ b/src/pages/index.astro
@@ -133,6 +133,18 @@ const processors = [
         abstraction, you can mix and match as you like. You can even use them on their own.
       </p>
 
+      <p>
+        Some themes may be constructed out of various applets that are not listed here. The reason
+        for that is those applets cannot be used solely on their own, they require an external
+        context to coordinate them.
+      </p>
+
+      <p>
+        There's tradeoffs to both approaches. A particular tradeoff to keep in mind for constituents
+        is that they'll have nested dependencies. So when overriding applets dependencies, the
+        overrides need to passed down the tree.
+      </p>
+
       <List items={constituents} />
     </section>
 
diff --git a/src/pages/orchestrator/input-cache/_applet.astro b/src/pages/orchestrator/input-cache/_applet.astro
index edb7d13..2eb41b2 100644
--- a/src/pages/orchestrator/input-cache/_applet.astro
+++ b/src/pages/orchestrator/input-cache/_applet.astro
@@ -1,6 +1,6 @@
 <script>
   import type { ManagedOutput, ResolvedUri, Track } from "@applets/core/types.d.ts";
-  import { applet, register, waitUntilAppletData } from "@scripts/applets/common";
+  import { applet, register, wait } from "@scripts/applets/common";
 
   ////////////////////////////////////////////
   // SETUP
@@ -22,11 +22,11 @@
     metadata: applet("../../processor/metadata"),
   };
 
-  // Start processing when tracks are loaded
+  // Start processing once settled and tracks are loaded
   context
     .settled()
     .then(() => configurator.output)
-    .then((output) => waitUntilAppletData(output, (d) => d?.tracks.state === "loaded"))
+    .then((output) => wait(output, (d) => d?.tracks.state === "loaded"))
     .then(() => process());
 
   ////////////////////////////////////////////
diff --git a/src/pages/orchestrator/single-queue/_applet.astro b/src/pages/orchestrator/single-queue/_applet.astro
index 7a4512b..4bcd17f 100644
--- a/src/pages/orchestrator/single-queue/_applet.astro
+++ b/src/pages/orchestrator/single-queue/_applet.astro
@@ -1,12 +1,14 @@
 <script>
   import type { ManagedOutput, ResolvedUri, Track } from "@applets/core/types.d.ts";
-  import { applet, reactive, register, waitUntilAppletData } from "@scripts/applets/common";
+  import { applet, inputUrl, reactive, register, wait } from "@scripts/applets/common";
 
   ////////////////////////////////////////////
   // SETUP
   ////////////////////////////////////////////
   import type * as AudioEngine from "@applets/engine/audio/types.d.ts";
   import type * as QueueEngine from "@applets/engine/queue/types.d.ts";
+  import type { Applet } from "@web-applets/sdk";
+  import { undefined } from "astro:schema";
 
   // Register applet
   const context = register();
@@ -27,36 +29,25 @@
   ////////////////////////////////////////////
   context.setActionHandler("fill", fill);
 
+  // TODO: Shuffle, limit track amount, etc.
   async function fill(tracks: Track[]) {
-    const queueItems = await tracks.reduce(
-      async (promise: Promise<QueueEngine.QueueItem[]>, track: Track) => {
-        const acc = await promise;
-        const res = await configurator.input.sendAction<ResolvedUri>(
-          "resolve",
-          {
-            method: "GET",
-            uri: track.uri,
-          },
-          {
-            timeoutDuration: 60000 * 5,
-          },
-        );
-
-        if (!res) return acc;
-
-        return [
-          ...acc,
-          {
-            expiresAt: res.expiresAt,
-            id: track.id,
-            url: res.url,
-          },
-        ];
-      },
-      Promise.resolve([]),
-    );
+    await engine.queue.sendAction("add", tracks, {
+      timeoutDuration: 60000,
+    });
+  }
 
-    await engine.queue.sendAction("add", queueItems);
+  ////////////////////////////////////////////
+  // Connections
+  ////////////////////////////////////////////
+  await context.settled();
+
+  function connect<D, T>(
+    applet: Applet<D>,
+    dataFn: (data: D) => T,
+    effectFn: (t: T, setter: (t: T) => void) => void,
+  ) {
+    if (!context.isMainInstance()) return;
+    return reactive(applet, dataFn, effectFn);
   }
 
   ////////////////////////////////////////////
@@ -64,10 +55,13 @@
   // 🔉 AUDIO
   ////////////////////////////////////////////
 
+  // When the active audio has ended,
+  // shift the queue.
+
   // NOTE:
-  // These could probably be optimised, but it works.
+  // This could probably be optimised, but it works.
 
-  reactive(
+  connect(
     engine.audio,
     (data) => data.items[engine.queue.data.now?.id ?? Infinity]?.hasEnded ?? false,
     (hasEnded) => {
@@ -79,35 +73,47 @@
   // ⚙️ [Connections → Engines]
   // 🚏 QUEUE
   ////////////////////////////////////////////
-  reactive(
+
+  // When the active queue item has changed,
+  // coordinate the audio engine accordingly.
+
+  connect(
     engine.queue,
     (data) => data.now?.id,
-    () => {
+    async () => {
       const playingNow = engine.queue.data.now;
       const volume = engine.audio.data.volume;
 
-      if (!playingNow) {
-        // NOTE: This probably isn't correct, keep preloads?
-        engine.audio.sendAction("render", { tracks: [] });
-        return;
-      }
-
       // Play new active queue item
-      engine.audio.sendAction("render", {
-        tracks: [
-          {
-            id: playingNow.id,
-            isPreload: false,
-            url: playingNow.url,
-          },
-        ],
-        play: {
-          trackId: playingNow.id,
-          volume,
+      // TODO: Take URL expiration timestamp into account
+      // TODO: Preload next queue item
+      engine.audio.sendAction(
+        "render",
+        {
+          audio: playingNow
+            ? [
+                {
+                  id: playingNow.id,
+                  isPreload: false,
+                  url: await inputUrl(configurator.input, playingNow.uri),
+                },
+              ]
+            : // NOTE: This probably isn't correct, keep preloads?
+              [],
+          play: playingNow
+            ? {
+                audioId: playingNow.id,
+                volume,
+              }
+            : undefined,
         },
-      });
+        {
+          timeoutDuration: 60000,
+        },
+      );
 
-      fill(configurator.output.data.tracks.collection);
+      // Add more tracks to the queue if needed
+      if (playingNow) fill(configurator.output.data.tracks.collection);
     },
   );
 
@@ -115,8 +121,11 @@
   // 🎻 [Connections → Configurators]
   // 📦 OUTPUT
   ////////////////////////////////////////////
-  waitUntilAppletData(configurator.output, (d) => d?.tracks.state === "loaded").then(() => {
-    reactive(
+
+  // Add tracks to the queue once the tracks have been loaded.
+
+  wait(configurator.output, (d) => d?.tracks.state === "loaded").then(() => {
+    connect(
       configurator.output,
       (data) => data.tracks.cacheId,
       () => {
diff --git a/src/pages/processor/artwork/_applet.astro b/src/pages/processor/artwork/_applet.astro
index 39f24e8..b15e60a 100644
--- a/src/pages/processor/artwork/_applet.astro
+++ b/src/pages/processor/artwork/_applet.astro
@@ -21,6 +21,8 @@
   };
 
   // Applet connections
+  // TODO: Ideally only configurator, orchestrator and UI applets have nested applets.
+  //       Can we find a way to remove this dependency?
   const processor = {
     metadata: applet("../../processor/metadata"),
   };
@@ -42,12 +44,17 @@
   ////////////////////////////////////////////
   // ACTIONS
   ////////////////////////////////////////////
+  function artwork(request: ArtworkRequest) {
+    return processRequest(request);
+  }
+
   function supply(items: ArtworkRequest[]) {
     const exe = !queue[0];
     queue = [...queue, ...items];
     if (exe) shiftQueue();
   }
 
+  context.setActionHandler("artwork", artwork);
   context.setActionHandler("supply", supply);
 
   ////////////////////////////////////////////
@@ -111,21 +118,31 @@
       .catch(() => musicBrainzCover(remainingReleases.slice(1)));
   }
 
-  async function shiftQueue() {
-    const next = queue.shift();
-    if (!next) return;
-
+  async function processRequest(req: ArtworkRequest): Promise<Artwork[]> {
     // Check if already processed
-    const cache = await IDB.get(`${IDB_PREFIX}/${next.cacheId}`);
-    if (cache && cache.length > 0) return;
+    // TODO: Retry if none was found?
+    const cache = await IDB.get(`${IDB_PREFIX}/${req.cacheId}`);
+    console.log("fromCache", cache);
+    if (cache) return cache;
+
+    console.log(req);
 
     // 🚀
     let art: Artwork[] = [];
 
     // Get metadata + possible artwork from file metadata
     const proc = await processor.metadata;
-    const meta = await proc.sendAction<Extraction>("supply", { ...next, includeArtwork: true });
-    if (!next.tags) next.tags = meta.tags;
+    const meta = await proc.sendAction<Extraction>(
+      "supply",
+      { ...req, includeArtwork: true },
+      {
+        timeoutDuration: 60000 * 5,
+      },
+    );
+
+    if (!req.tags) req.tags = meta.tags;
+
+    console.log(meta);
 
     // Add artwork from metadata
     const fromMeta =
@@ -133,24 +150,34 @@
         return { bytes: a.data, mime: a.format };
       }) || [];
 
+    console.log(fromMeta);
+
     art.push(...fromMeta);
 
     // If no artwork, try finding it on other sources
     if (art.length === 0) {
-      const fromMusicBrainz = await musicBrainz(next);
+      const fromMusicBrainz = await musicBrainz(req);
       art.push(...fromMusicBrainz);
     }
 
     if (art.length === 0) {
-      const fromLastFm = await lastFm(next);
+      const fromLastFm = await lastFm(req);
       art.push(...fromLastFm);
     }
 
     // Save artwork to IDB
-    await IDB.set(`${IDB_ARTWORK_PREFIX}/${next.cacheId}`, art);
-    context.data.artwork[next.cacheId] = art;
+    await IDB.set(`${IDB_ARTWORK_PREFIX}/${req.cacheId}`, art);
+    context.data.artwork[req.cacheId] = art;
+
+    // Fin
+    return art;
+  }
+
+  async function shiftQueue() {
+    const next = queue.shift();
+    if (!next) return;
 
-    // 🏹
-    shiftQueue();
+    await processRequest(next);
+    await shiftQueue();
   }
 </script>
diff --git a/src/scripts/applets/common.ts b/src/scripts/applets/common.ts
index 2b9654e..a7b354b 100644
--- a/src/scripts/applets/common.ts
+++ b/src/scripts/applets/common.ts
@@ -6,18 +6,18 @@ import { type ElementConfigurator, h } from "spellcaster/hyperscript.js";
 import { effect, isSignal, type Signal, signal } from "spellcaster/spellcaster.js";
 import { xxh32 } from "xxh32";
 
-import type { Track } from "@applets/core/types";
+import type { ResolvedUri, Track } from "@applets/core/types";
 
 ////////////////////////////////////////////
-// 🪟 Applet connector
+// 🪟 Applet connecting
 ////////////////////////////////////////////
 export async function applet<D>(
   src: string,
   opts: {
     addSlashSuffix?: boolean;
-    applets?: Record<string, string>;
     container?: HTMLElement | Element;
-    id?: string;
+    frameId?: string;
+    groupId?: string;
     setHeight?: boolean;
   } = {},
 ): Promise<Applet<D>> {
@@ -29,8 +29,14 @@ export async function applet<D>(
         : ""
   }`;
 
-  if (opts.applets) {
-    src = QS.stringifyUrl({ url: src, query: opts.applets });
+  let query: undefined | Record<string, string>;
+
+  if (opts.groupId) {
+    query = { groupId: opts.groupId };
+  }
+
+  if (query) {
+    src = QS.stringifyUrl({ url: src, query });
   }
 
   const existingFrame: HTMLIFrameElement | null = window.document.querySelector(`[src="${src}"]`);
@@ -42,7 +48,7 @@ export async function applet<D>(
   } else {
     frame = document.createElement("iframe");
     frame.src = src;
-    if (opts.id) frame.id = opts.id;
+    if (opts.frameId) frame.id = opts.frameId;
 
     if (opts.container) {
       opts.container.appendChild(frame);
@@ -86,7 +92,7 @@ export type BroadcastedApplet<T> = {
 
   settled(): Promise<void>;
 
-  get id(): string;
+  get instanceId(): string;
   set data(data: T);
 
   codec: {
@@ -99,9 +105,12 @@ export type BroadcastedApplet<T> = {
 };
 
 export function register<DataType = any>() {
-  const channelId = `${location.host}${location.pathname}`;
+  const url = new URL(location.href);
   const scope = applets.register<DataType>();
-  const id = crypto.randomUUID();
+
+  const groupId = url.searchParams.get("groupId") || "main";
+  const channelId = `${location.host}${location.pathname}/${groupId}`;
+  const instanceId = crypto.randomUUID();
 
   let isMainInstance = true;
 
@@ -119,7 +128,7 @@ export function register<DataType = any>() {
       case "PING": {
         channel.postMessage({
           type: "PONG",
-          id: event.data.id,
+          instanceId: event.data.instanceId,
         });
 
         if (isMainInstance) {
@@ -132,7 +141,7 @@ export function register<DataType = any>() {
       }
 
       case "PONG": {
-        if (event.data.id === id) {
+        if (event.data.instanceId === instanceId) {
           isMainInstance = false;
         }
         break;
@@ -143,7 +152,7 @@ export function register<DataType = any>() {
           const result = await scope.actionHandlers[event.data.actionId]?.(...event.data.arguments);
           channel.postMessage({
             type: "actioncomplete",
-            id: event.data.id,
+            actionInstanceId: event.data.actionInstanceId,
             result,
           });
         }
@@ -159,14 +168,14 @@ export function register<DataType = any>() {
 
   // Promise that fullfills whenever it figures out its the main instance or not.
   const promise = new Promise<void>((resolve) => {
-    const id = setTimeout(() => {
+    const timeoutId = setTimeout(() => {
       channel.removeEventListener("message", handler);
       resolve(undefined);
     }, 1000);
 
     const handler = (event: MessageEvent) => {
       if (event.data === "pong" || event.data === "ping") {
-        clearTimeout(id);
+        clearTimeout(timeoutId);
         channel.removeEventListener("message", handler);
         resolve(undefined);
       }
@@ -178,7 +187,7 @@ export function register<DataType = any>() {
   // Send out ping
   channel.postMessage({
     type: "PING",
-    id,
+    instanceId,
   });
 
   // If the data on the main instance changes,
@@ -202,8 +211,8 @@ export function register<DataType = any>() {
       return promise;
     },
 
-    get id() {
-      return id;
+    get instanceId() {
+      return instanceId;
     },
 
     get data() {
@@ -230,15 +239,18 @@ export function register<DataType = any>() {
         }
 
         const actionMessage = {
-          id: crypto.randomUUID(),
-          type: "action",
+          actionInstanceId: crypto.randomUUID(),
           actionId,
+          type: "action",
           arguments: args,
         };
 
         return new Promise((resolve) => {
           const actionCallback = (event: MessageEvent) => {
-            if (event.data?.type === "actioncomplete" && event.data?.id === actionMessage.id) {
+            if (
+              event.data?.type === "actioncomplete" &&
+              event.data?.actionInstanceId === actionMessage.actionInstanceId
+            ) {
               channel.removeEventListener("message", actionCallback);
               resolve(event.data.result);
             }
@@ -276,6 +288,23 @@ export function reactive<D, T>(
   });
 }
 
+////////////////////////////////////////////
+// ⚡️ COMMON ACTION CALLS
+////////////////////////////////////////////
+
+export async function inputUrl(input: Applet, uri: string, method = "GET") {
+  return await input.sendAction<ResolvedUri>(
+    "resolve",
+    {
+      method,
+      uri,
+    },
+    {
+      timeoutDuration: 60000 * 5,
+    },
+  );
+}
+
 ////////////////////////////////////////////
 // 🛠️
 ////////////////////////////////////////////
@@ -352,10 +381,7 @@ export function jsonEncode<T>(a: T): Uint8Array {
   return new TextEncoder().encode(JSON.stringify(a));
 }
 
-export function waitUntilAppletData<A>(
-  applet: Applet<A>,
-  dataFn: (a: A | undefined) => boolean,
-): Promise<void> {
+export function wait<A>(applet: Applet<A>, dataFn: (a: A | undefined) => boolean): Promise<void> {
   return new Promise((resolve) => {
     if (dataFn(applet.data) === true) {
       resolve();
@@ -372,7 +398,3 @@ export function waitUntilAppletData<A>(
     applet.addEventListener("data", callback);
   });
 }
-
-export function waitUntilAppletIsReady(applet: Applet): Promise<void> {
-  return waitUntilAppletData(applet, (data) => !!data?.ready);
-}
diff --git a/src/scripts/themes/desktop/index.ts b/src/scripts/themes/desktop/index.ts
index 27cbd5a..3ad7e9c 100644
--- a/src/scripts/themes/desktop/index.ts
+++ b/src/scripts/themes/desktop/index.ts
@@ -1,5 +1,5 @@
 import * as Uint8 from "uint8arrays";
-import { applet, reactive, waitUntilAppletData } from "@scripts/applets/common";
+import { applet, reactive, wait } from "@scripts/applets/common";
 
 ////////////////////////////////////////////
 // 🎨 Styles
@@ -9,31 +9,6 @@ import "@styles/themes/desktop/index.css";
 ////////////////////////////////////////////
 // 🗂️ Applets
 ////////////////////////////////////////////
-import type * as AudioEngine from "@applets/engine/audio/types.d.ts";
-import type * as QueueEngine from "@applets/engine/queue/types.d.ts";
-import type { ManagedOutput, Track } from "@applets/core/types";
-import type { Urls } from "@applets/processor/artwork/types";
-
-const configurator = {
-  input: await applet("../../configurator/input"),
-  output: await applet<ManagedOutput>("../../configurator/output"),
-};
-
-const engine = {
-  audio: await applet<AudioEngine.State>("../../engine/audio"),
-  queue: await applet<QueueEngine.State>("../../engine/queue"),
-};
-
-const _orchestrator = {
-  input: await applet("../../orchestrator/input-cache"),
-  queue: await applet("../../orchestrator/single-queue"),
-};
-
-const processor = {
-  artwork: await applet("../../processor/artwork"),
-  search: await applet("../../processor/search"),
-};
-
 const ui = {};
 
 ////////////////////////////////////////////
@@ -52,10 +27,8 @@ const ui = {};
 
 // TESTING
 
-waitUntilAppletData(configurator.output, (data) => data?.tracks?.state === "loaded").then(
-  async () => {
-    await processor.search.sendAction("supply", configurator.output.data.tracks.collection);
-    const tracks = await processor.search.sendAction("search", "artist lee last");
-    tracks.forEach((t: Track) => console.log(t.tags));
-  },
-);
+// wait(configurator.output, (data) => data?.tracks?.state === "loaded").then(async () => {
+//   await processor.search.sendAction("supply", configurator.output.data.tracks.collection);
+//   const tracks = await processor.search.sendAction("search", "artist lee last");
+//   tracks.forEach((t: Track) => console.log(t.tags));
+// });
diff --git a/src/scripts/themes/webamp/index.ts b/src/scripts/themes/webamp/index.ts
index a57d4f5..9d14b10 100644
--- a/src/scripts/themes/webamp/index.ts
+++ b/src/scripts/themes/webamp/index.ts
@@ -2,7 +2,7 @@ import type { URLTrack } from "webamp";
 import Webamp from "webamp";
 
 import type { ManagedOutput, ResolvedUri, Track } from "@applets/core/types.d.ts";
-import { applet, waitUntilAppletData } from "@scripts/applets/common";
+import { applet, wait } from "@scripts/applets/common";
 
 ////////////////////////////////////////////
 // 🎨 Styles
@@ -33,7 +33,7 @@ ampNode.style = "height: 100vh; left: 0; position: absolute; top: 0; width: 100%
 document.body.appendChild(ampNode);
 amp.renderWhenReady(ampNode);
 
-waitUntilAppletData(configurator.output, (d) => d?.tracks.state === "loaded").then(loadAndInsert);
+wait(configurator.output, (d) => d?.tracks.state === "loaded").then(loadAndInsert);
 configurator.output.ondata = loadAndInsert;
 
 let inserting = false;
diff --git a/src/styles/diffuse/colors.css b/src/styles/diffuse/colors.css
new file mode 100644
index 0000000..182d2fb
--- /dev/null
+++ b/src/styles/diffuse/colors.css
@@ -0,0 +1,17 @@
+:root {
+  /* Colors */
+  --color-1: oklch(4.1308% 0.25306 109.22);
+  --color-2: oklch(98.369% 0.01834 67.664);
+  --color-3: oklch(26.787% 0.00168 186.65);
+  --accent: oklch(86.947% 0.25527 28.789);
+
+  --bg-color: var(--color-2);
+  --text-color: var(--color-1);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg-color: var(--color-3);
+    --text-color: var(--color-2);
+  }
+}
diff --git a/src/styles/diffuse/fonts.css b/src/styles/diffuse/fonts.css
new file mode 100644
index 0000000..7f7b659
--- /dev/null
+++ b/src/styles/diffuse/fonts.css
@@ -0,0 +1,14 @@
+:root {
+  font-family: "Inter", sans-serif;
+  font-size: var(--fs-base);
+}
+
+@supports (font-variation-settings: normal) {
+  :root {
+    font-family: "InterVariable", sans-serif;
+    font-feature-settings:
+      "zero" 2,
+      "ss03" 2;
+    font-optical-sizing: auto;
+  }
+}
diff --git a/src/styles/pages/index.css b/src/styles/pages/index.css
index 82b06e1..d1a2355 100644
--- a/src/styles/pages/index.css
+++ b/src/styles/pages/index.css
@@ -1,35 +1,5 @@
-@import "../variables.css";
-
-:root {
-  font-family: "Inter", sans-serif;
-  font-size: var(--fs-base);
-
-  /* Colors */
-  --color-1: oklch(4.1308% 0.25306 109.22);
-  --color-2: oklch(98.369% 0.01834 67.664);
-  --color-3: oklch(26.787% 0.00168 186.65);
-  --accent: oklch(86.947% 0.25527 28.789);
-
-  --bg-color: var(--color-2);
-  --text-color: var(--color-1);
-}
-
-@media (prefers-color-scheme: dark) {
-  :root {
-    --bg-color: var(--color-3);
-    --text-color: var(--color-2);
-  }
-}
-
-@supports (font-variation-settings: normal) {
-  :root {
-    font-family: "InterVariable", sans-serif;
-    font-feature-settings:
-      "zero" 2,
-      "ss03" 2;
-    font-optical-sizing: auto;
-  }
-}
+@import "../diffuse/colors.css";
+@import "../diffuse/fonts.css";
 
 body {
   background-color: var(--bg-color);
-- 
2.51.2