forked from
tokono.ma/diffuse
A music player that connects to your cloud/distributed storage.
chore: docs
+24
-12
+17
-5
AGENTS.md
+17
-5
AGENTS.md
···
1
-
# Agent instructions
1
+
# Agent guide
2
2
3
-
* This project is a collection of custom elements for the web. Additionally it uses web workers and signals (using the 'alien-signals' library).
4
-
* The code is written in Javascript with Typescript annotations.
5
-
* Templates are written using the Vento templating language.
6
-
* Custom elements use 'lit-html' templates.
3
+
Before you write any code, read:
4
+
5
+
- The **why** document: `src/index.vto`
6
+
(there might be a compiled version `dist/index.html`, if so prefer that)
7
+
- The **how** document: `docs/ARCHITECTURE.md`
8
+
9
+
10
+
## Your responsibilities
11
+
12
+
As an agent, your job is to:
13
+
- Keep the architecture described in `docs/ARCHITECTURE.md` intact.
14
+
- Preserve the overall goals and constraints described in the 'why' document.
15
+
16
+
If you are unsure how to implement something:
17
+
- Prefer a small, clean, testable implementation that matches the intent.
18
+
- Do **not** invent new architecture without clear justification in comments.
+7
-7
DESIGN.md
docs/ARCHITECTURE.md
+7
-7
DESIGN.md
docs/ARCHITECTURE.md
···
1
-
# Design
2
-
3
-
## Architecture
1
+
# Architecture
4
2
5
3
Diffuse provides a set of custom (DOM) elements (aka. web components) that can be combined into a working audio player or media browser living in a web view.
6
4
7
5
8
-
### Components / Elements
6
+
## Components / Elements
9
7
10
8
There are various categories of these elements, and may have subcategories. Each element lives in its own directory, containing the code, documentation and other assets associated with that element. The directory for the elements is `src/components/`, each subdirectory is a category which in turn may have one or more subcategories. If a directory has an `element.js` then that directory represents the element, not a subcategory.
11
9
···
19
17
- The category named 'orchestrator'. These are compositions of other components, meaning they consume other components. These have attributes ending with `-selector` which is a DOM selector that points at the component that is the dependency.
20
18
- The category named 'configurator'. These take other components as DOM children with the same actions/methods as the configurator itself. They serve to delegate or combine.
21
19
20
+
A lot of components will have a worker (located in `worker.js` besides the `element.js`) which is connected to the element using `this.workerProxy()` in the constructor. The proxy itself may be stored on the class instance, but it is usually not required.
22
21
23
-
### Definitions
22
+
23
+
## Definitions
24
24
25
25
`src/definitions/` are lexicons, JSON schemas that describe data in the system.
26
26
27
27
28
-
### Themes
28
+
## Themes
29
29
30
30
Like orchestrator components, these are compositions of elements. Unlike orchestrators however, it doesn't compose by the use of selectors, instead we write the custom elements as HTML and use the DOM as the composition layer. Alternatively, custom elements can be created in Javascript and then added to the DOM from there.
31
31
32
32
33
-
### Other directories
33
+
## Other directories
34
34
35
35
- `src/common`: Common Javascript code shared by various components and/or themes.
36
36
- `src/styles`: Common CSS shared by themes, the index page or constituents (part of themes).