···11+# Diffuse
22+33+Diffuse is a few things:
44+55+- A collection of custom DOM elements (aka. web components) that allow you to build an audio player, do audio metadata processing, list audio files and streams from various sources/apis/servers, define how to save or sync user-data, etc.
66+- A HTML loader that loads "interfaces" from the local user-data cache, the default set from Diffuse, HTTP(S) URLs, or [AT Protocol](https://atproto.com) URIs. When you load an interface, it's supplied with optional "features", from your configured storage, which are also pieces of HTML. These pieces are called "facets".
77+- A default configuration of the custom elements that's called "the foundation". This is used throughout the default set of facets. This foundation is configured so that the facets can communicate across tabs/frames; this is done by setting the element's `group` attribute.
88+- A collection of data schemas in the form of atproto [lexicons](https://atproto.com/specs/lexicon). These live in the `definitions` directory.
99+1010+1111+1212+## Details
1313+1414+- Custom elements live under the `components` directory. The elements [page](./elements/) lists all the custom elements along with a description. It also has links to the script for each element.
1515+- Interface facets are loaded by the loader that lives under the `l` directory. It supports various query parameters:
1616+ * `uri`: Load from HTTP(S) or the AT Protocol (`at` scheme)
1717+ * `id`: Load from local user-data storage cache (indexedDB)
1818+ * `path`: Load from default Diffuse set, path to HTML file in the project.
1919+- Feature facets that are enabled in the user's storage are loaded automatically before any interface is loaded through the loader.
2020+- Every interface facet MUST remove the loading animation using `foundation.ready()`, and ideally it would set the document title as well using `foundation.setup({ title })`.
2121+- Elements that are configured to be part of a `group` use a `BroadcastChannel` to communicate and/or use a `SharedWorker`.
2222+- Data schemas are originally defined as lexicon JSON files. From this Typescript files/types are generated.
2323+- HTML is injected into a `<div id="container"></div>` element in the body. Facets don't have a doctype or `<html>` element or `<head>` element.
2424+- The loader configures a `<base>` element, every relative url is relative to the root of the project. Every Diffuse page defines an import map which specifies `~` as the root.
2525+- Most elements use the signal functions from `~/common/signals.js` which turn uses the `alien-signals` library.
2626+- An example of a facet you should check is `~/themes/blur/artwork-controller/facet/index.html`
2727+- Signals are usually not exposed in their entirery from the custom elements, just their getter.
2828+2929+3030+3131+## Instructions
3232+3333+- When you're asked to build an "interface", that would be a facet of the `interactive` kind. Similarly, when asked to build a "feature", you'd create a facet of the `prelude` kind.