Diffuse Facet
Developmentdiffuse-facetDiffuse Facet is an Agent Skill for development published in the icidasset/diffuse repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Create an interface or feature facet for Diffuse (elements.diffuse.sh)
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/icidasset/diffuse/blob/HEAD/src/skills/diffuse-facet/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/diffuse-facet, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Create a Diffuse facet and produce the HTML ready to paste into the create/ page.
Step 1 — Read the docs
Use the read tool to read these files:
docs/architecture.txt— system overview, facet rules, foundation APIdocs/elements.txt— all available custom elements with code examplesdocs/foundation.js— the foundation code mentioned throughout this documentexample/index.html— a representative interface facet to use as a reference- Any specific definition you need (e.g.
docs/definitions/output/track.jsonfor the track schema) docs/definitions/index.ts— TypeScript types for all data structures
Step 2 — Clarify intent
If the user hasn't described what the facet should do, ask one plain-language question before proceeding.
Step 3 — Write the facet
Facets are HTML fragments (no <!doctype>, <html>, or <head>). The loader injects them into <div id="container"> and sets a <base> pointing at the Diffuse build root, so all relative URLs resolve from there. The import map exposes ~/ as the root alias.
Mandatory rules
foundation.ready()must be called on every interface facet — it removes the loading spinner. Omitting it leaves the screen stuck on loading.foundation.setup({ title })should be called to set the document title.- Always check the definitions fetched in Step 1 for the exact shape of any data you access — never assume top-level fields exist. For example, track metadata lives under
track.tags.*, not at the top level. - Signal reader functions (
queue.now,queue.past,queue.future, …) must be called insideeffect()to be reactive. - Do not import modules with top-level
awaitfrom Worker scripts — it causes RPC messages to be dropped. - Use
@paramannotations above functions, not inline@typein parameter lists.
Skeleton
<style>
@import "./styles/base.css";
@import "./styles/diffuse/facet.css";
@import "./vendor/@phosphor-icons/web/fill/style.css"; /* or /bold/ */
@layer base, diffuse;
/* facet-specific styles */
</style>
<main>
<!-- markup -->
</main>
<script type="module">
import foundation from "~/common/foundation.js";
import { effect } from "~/common/signal.js";
foundation.setup({ title: "My Facet | Diffuse" });
// wire up elements …
foundation.ready();
</script>
Standard two-column layout
<main>
<div class="facet__left">
<a href="./dashboard/" class="diffuse-logo-container">
<svg viewBox="0 0 902 134" width="160">
<title>Diffuse</title>
<use href="images/diffuse-current.svg#diffuse"></use>
</svg>
</a>
<h1>Title</h1>
<p>Description.</p>
</div>
<div class="facet__right">
<!-- main content -->
</div>
</main>
For a centered or full-screen layout (player, dialog, etc.) override body and main in the facet's <style> block directly.
Example foundation usage
await foundation.orchestrator.queueAudio();
await foundation.orchestrator.mediaSession();
const [audio, ctl, queue] = await Promise.all([
foundation.engine.audio(),
foundation.orchestrator.controller(),
foundation.engine.queue(),
]);
await customElements.whenDefined(ctl.localName);
Reactivity
Signals are used for reactivity, see the ~/common/signal.js javascript file for the code. It's based on the alien-signals library.
effect(() => {
const track = ctl.currentTrack(); // computed — call like a fn
const isPlaying = ctl.isPlaying();
const audioState = ctl.audio(); // AudioStateReadOnly | undefined
if (audioState) {
const progress = audioState.progress(); // 0–1
const current = audioState.currentTime();
const duration = audioState.duration();
}
const now = queue.now(); // SignalReader — call like a fn
const past = queue.past();
const future = queue.future();
});
Audio control
audio.play({ audioId: queue.now().id });
audio.pause({ audioId: queue.now().id });
audio.seek({ audioId: queue.now().id, percentage: 0.5 }); // 0–1
queue.shift(); // next track
queue.unshift(); // previous track
Additional requirements and notes
- When working with track lists, realise that there could be a huge number of tracks that you need to work with (eg. 20000 tracks). Implement a custom virtual scroll (see the winamp or blur browser elements for examples).
- Prefer the lit-html library as the templating/rendering engine. It is available from
~/vendor/lit-html/index.js(among some other libraries such as:idb-keyval,throttle-debounce, several@atcutelibraries, andkmenu-core). Always make sure to use the~/vendor/prefix for libraries, you're not working in an enviroment that bundles code. - Prefer to fetch the tracks from the
scoped-tracksorchestrator element. - Always prefer to use an orchestrator or another component instead of reimplementing logic yourself.
- Be mindful of performance.
Step 4 — Deliver
Output the complete facet HTML in a code block. Tell the user to open the create/ page in Diffuse, paste it in, and load it.