aberdeen 1.18.1 → 1.19.0

package/skill/SKILL.md

@@ -17,16 +17,6 @@ Aberdeen is a reactive UI library using fine-grained reactivity via JavaScript P
 8. **Prefix proxied objects** - As a convention, prefix variable names that contain proxied objects with '$' (e.g. `$user`, `$settings`)
 9. **Think about rerenders** - When you read from a proxied object (like `let n = $user.name;`), the containing A(() => {..}) or A('div', () => {}) function will rerun on change - plan on which level you want updates to trigger
 
-# Obtaining info
-
-The complete tutorial follows below. For detailed API reference open these files within the skill directory:
-
-- **[aberdeen](aberdeen.md)** - Core: `A`, `proxy`, `onEach`, `ref`, `derive`, `map`, `multiMap`, `partition`, `count`, `isEmpty`, `peek`, `dump`, `clean`, `insertCss`, `insertGlobalCss`, `mount`, `runQueue`, `darkMode`
-- **[route](route.md)** - Routing: `current`, `go`, `push`, `back`, `up`, `persistScroll`
-- **[dispatcher](dispatcher.md)** - Path matching: `Dispatcher`, `MATCH_REST`, `MATCH_FAILED`
-- **[transitions](transitions.md)** - Animations: `grow`, `shrink`
-- **[prediction](prediction.md)** - Optimistic UI: `applyPrediction`, `applyCanon`
-
 
 # Tutorial
 
@@ -280,7 +270,6 @@ A('div.box color:', $textColor, '#Click me to change color', 'click=', () => {
 
 This way, when `$textColor.value` changes, only the style is updated without recreating the element.
 
-
 ## Observable arrays and sets
 
 You can create observable arrays too. They work just like regular arrays, apart from being observable.
@@ -343,7 +332,6 @@ A('button text=Grow click=', () => $graph.grow());
 
 The type returned by {@link aberdeen.proxy | A.proxy} matches the input type, meaning the type system does not distinguish proxied and unproxied objects. That makes sense, as they have the exact same methods and properties (though proxied objects may have additional side effects).
 
-
 ## Efficient list rendering with A.onEach
 For rendering lists efficiently, Aberdeen provides the {@link aberdeen.onEach | A.onEach} function. It takes three arguments:
 1. The array to iterate over.
@@ -687,18 +675,13 @@ A('button text="Update state" click=', () => {
 
 The A.dump renders recursively using `<ul>` and `<li>` elements, showing all properties and their values. It updates reactively when any proxied data changes. It is intended for debugging, though with some CSS styling you may find it useful in some simple real-world scenarios as well.
 
+## Developer tools
 
-## html-to-aberdeen
-
-Sometimes, you want to just paste a largish block of HTML into your application (and then maybe modify it to bind some actual data). Having to translate HTML to `$` calls manually is little fun, so there's a tool for that:
+Aberdeen has an in-browser inspector for its reactive scope tree. See [developer-tools.md](developer-tools.md).
 
-```sh
-npx html-to-aberdeen
-```
-
-It takes HTML on stdin (paste it and press `ctrl-d` for end-of-file), and outputs JavaScript on stdout.
+## html-to-aberdeen
 
-> Caveat: This tool has been vibe coded (thanks Claude!) with very little code review. As it doesn't use the filesystem nor the network, I'd say it's safe to use though! :-) Also, it happens to work pretty well.
+This tool allows you to convert a block of HTML into Aberdeen syntax. See [html-to-aberdeen.md](html-to-aberdeen.md).
 
 ## Routing
 
@@ -775,154 +758,287 @@ When building interactive applications with client-server communication, Aberdee
 
 ## Full Example: Multi-page App
 
-Here's a complete example (a contact manager) demonstrating routing, state management, CSS, dark mode, and dynamic content:
+Here's a complete example (a contact manager) demonstrating routing, state management, CSS, dark mode, and dynamic content. See [full-example-multi-page-app.md](full-example-multi-page-app.md).
 
-```typescript
-import A from 'aberdeen';
-import * as route from 'aberdeen/route';
-import { Dispatcher } from 'aberdeen/dispatcher';
-import { grow, shrink } from 'aberdeen/transitions';
+## Further reading
 
-class Contact {
-    constructor(
-        public id: number,
-        public firstName: string,
-        public lastName: string,
-        public email: string,
-        public phone: string
-    ) {}
-}
+If you've understood all/most of the above, you should be ready to get going with Aberdeen! You may also find these links helpful:
 
-// Enable link interception for SPA navigation
-route.interceptLinks();
+- [Reference documentation](https://aberdeenjs.org/modules.html)
+- [Examples](https://aberdeenjs.org/#examples)
 
-// Initialize $1-$12 CSS variables for consistent spacing ($2=0.5rem, $3=1rem, $4=2rem, etc.)
-A.setSpacingCssVars();
+# API Reference
 
-// Reactive theme based on system preference
-A(() => {
-    A.cssVars.primary = '#2563eb';
-    A.cssVars.bg = A.darkMode() ? '#0f172a' : '#ffffff';
-    A.cssVars.fg = A.darkMode() ? '#e2e8f0' : '#1e293b';
-    A.cssVars.cardBg = A.darkMode() ? '#1e293b' : '#f8fafc';
-    A.cssVars.border = A.darkMode() ? '#334155' : '#e2e8f0';
-});
+The sections below summarize each module's exports; the linked `.md` files within this skill directory contain detailed reference docs for individual symbols.
 
-// Global styles for semantic HTML elements that apply everywhere
-A.insertGlobalCss({
-    "*": "m:0 p:0",
-    "body": "bg:$bg fg:$fg font-family: system-ui, sans-serif;",
-    "a": "color:$primary text-decoration:none",
-    "a:hover": "text-decoration:underline",
-    "a[role=button]": "bg:$primary fg:white r:8px p:$2",
-});
+## Core (aberdeen)
 
-// Application state
-const $contacts = A.proxy([
-    new Contact(1, 'Emma', 'Wilson', 'emma.wilson@email.com', '555-0101'),
-    new Contact(2, 'James', 'Anderson', 'j.anderson@email.com', '555-0102'),
-    new Contact(3, 'Sofia', 'Martinez', 'sofia.m@email.com', '555-0103'),
-    new Contact(4, 'Liam', 'Brown', 'liam.brown@email.com', '555-0104')
-]);
-
-// Router setup
-const dispatcher = new Dispatcher();
-dispatcher.addRoute(drawHome);
-dispatcher.addRoute('contacts', drawContactList);
-dispatcher.addRoute('contacts', Number, drawContactDetail);
-
-// Main app
-A('div.app', () => {
-    A('nav display:flex gap:$3 p:$3 border-bottom: 1px solid $border;', () => {
-        A('a href=/ text=Home font-weight:', route.current.p.length === 0 ? 'bold' : 'normal');
-        A('a href=/contacts text=Contacts font-weight:', route.current.p[0] === 'contacts' ? 'bold' : 'normal');
-    });
-    A('main p:$3', () => dispatcher.dispatch(route.current.p));
-});
+Import as `import A from 'aberdeen'`. `A` is itself a callable function for building reactive DOM (creating elements, setting attributes, adding content); every other Aberdeen function is also available as a property on it (e.g. `A.proxy`, `A.onEach`).
 
-function drawHome() {
-    A('h1#Contact Manager');
-    A('p#A modern contact list with search, sort, and dark mode support.');
-}
+## [runQueue](runQueue.md) · function
 
-// Contact card styles
-const cardStyle = A.insertCss({
-    "&": "bg:$cardBg border: 1px solid $border; r:8px p:$3 mv:$2 display:block transition: transform 0.2s;",
-    "&:hover": "transform:translateX(4px)",
-    "a&": "color:inherit;",
-});
+Forces the immediate and synchronous execution of all pending reactive updates.
 
-const filterStyle = A.insertCss({
-    "&": "display:flex gap:$3 mv:$3",
-    "> *": "p:$2 r:4px bg:$bg fg:$fg border: 1px solid $border;",
-});
+## [freeze](freeze.md) · function
 
-function drawContactList() {
-    A('h1#Contacts');
-    
-    // Search and sort controls
-    A('div', filterStyle, () => {
-        A('input flex:1 placeholder="Search contacts..." bind=', A.ref(route.current.search, 'q'));
-        A('select bind=', A.ref(route.current.search, 'sort'), () => {
-            A('option value=firstName #First Name');
-            A('option value=lastName #Last Name');
-            A('option value=email #Email');
-        });
-    });
-    
-    // Contact list
-    A('div', () => {
-        const sortBy = route.current.search.sort || 'firstName';
-
-        const $filtered = A.map($contacts, $contact => {
-            const query = route.current.search.q;
-            if (query) {
-                const info = `${$contact.firstName} ${$contact.lastName} ${$contact.email}`;
-                if (!info.toLowerCase().includes(query.toLowerCase())) return; // Skip!
-            }
-            return $contact;
-        });
-        
-        A.onEach($filtered, $contact => {
-            A('a', cardStyle, 'create=', grow, 'destroy=', shrink, `href=/contacts/${$contact.id}`, () => {
-                A('h2', () => {
-                    A('span font-weight:normal text=', $contact.firstName+" ");
-                    A('span text=', $contact.lastName);
-                });
-                A('div text=', $contact.email);
-            });
-        }, $contact => $contact[sortBy].toLowerCase());
-
-        A(`a role=button mt:$3 text="Add new contact" href=/contacts/${$contacts.length}`);
-    });
-}
+Pause processing of reactive updates until the returned *thaw* function is called.
 
-// Detail form styles
-const detailStyle = A.insertCss({
-    "&": "bg:$cardBg border: 1px solid $border; r:8px p:$4 max-width:600px",
-    "label": "display:block font-weight:600 mt:$3 mb:$2",
-    "input": "w:100% p:$2 r:4px border: 1px solid $border; bg:$bg fg:$fg"
-});
+## [invertString](invertString.md) · function
 
-function drawContactDetail(id: number) {
-    $contacts[id] ||= new Contact(id, '', '', '', '');
-    const $contact = $contacts[id];
-    
-    A('a role=button href=/contacts #← Back');
-    
-    A('div mt:$3', detailStyle, () => {
-        A('h2 mb:$2 text=', A.ref($contact, 'firstName'), 'text=', ' ', 'text=', A.ref($contact, 'lastName'));
-        A('label text="First Name" input bind=', A.ref($contact, 'firstName'));
-        A('label text="Last Name" input bind=', A.ref($contact, 'lastName'));
-        A('label text="Email" input type=email bind=', A.ref($contact, 'email'));     
-        A('label text="Phone" input type=tel bind=', A.ref($contact, 'phone'));
-    });
-}
-```
+Creates a new string that has the opposite sort order compared to the input string.
 
-## Further reading
+## [onEach](onEach.md) · function
 
-If you've understood all/most of the above, you should be ready to get going with Aberdeen! You may also find these links helpful:
+## [isEmpty](isEmpty.md) · function
+
+Reactively checks if an observable array, object, Map, or Set is empty.
+
+## [count](count.md) · function
+
+Reactively counts the number of properties in an object.
+
+## [proxy](proxy.md) · function
+
+## [unproxy](unproxy.md) · function
+
+Returns the original, underlying data target from a reactive proxy created by `proxy`.
+If the input `target` is not a proxy, it is returned directly.
+
+## [copy](copy.md) · function
+
+Recursively copies properties or array items from `src` to `dst`.
+It's designed to work efficiently with reactive proxies created by `proxy`.
+
+## [merge](merge.md) · function
+
+Like `copy`, but uses merge semantics. Properties in `dst` not present in `src` are kept.
+`null`/`undefined` in `src` delete properties in `dst`.
+
+## [setSpacingCssVars](setSpacingCssVars.md) · function
+
+Initializes `cssVars[0]` through `cssVars[12]` with an exponential spacing scale.
+
+## [darkMode](darkMode.md) · function
+
+Returns whether the user's browser prefers a dark color scheme.
+
+## [clone](clone.md) · function
+
+Clone an (optionally proxied) object or array.
+
+## [ref](ref.md) · function
+
+Creates a reactive reference (`{ value: T }`-like object) to a specific value
+within a proxied object or array.
+
+## [disableCreateDestroy](disableCreateDestroy.md) · function
+
+Make the `create` and `destroy` special properties no-ops.
+
+## [A](A.md) · function
+
+The core function for building reactive user interfaces in Aberdeen. It creates and inserts new DOM elements
+and sets attributes/properties/event listeners on DOM elements. It does so in a reactive way, meaning that
+changes will be (mostly) undone when the current *scope* is destroyed or will be re-execute.
+
+## [insertCss](insertCss.md) · function
+
+Inserts CSS rules into the document, scoping them with a unique class name.
+
+## [insertGlobalCss](insertGlobalCss.md) · function
+
+Inserts CSS rules globally (unscoped).
+
+## [setErrorHandler](setErrorHandler.md) · function
+
+Sets a custom error handler function for errors that occur asynchronously
+within reactive scopes (e.g., during updates triggered by proxy changes in
+`derive` or | A render functions).
+
+## [clean](clean.md) · function
+
+Registers a cleanup function to be executed just before the current reactive scope
+is destroyed or redraws.
+
+## [derive](derive.md) · function
+
+Creates a reactive scope that automatically re-executes the provided function
+whenever any proxied data (created by `proxy`) read during its last execution changes, storing
+its return value in an observable.
+
+## [mount](mount.md) · function
+
+Attaches a reactive Aberdeen UI fragment to an existing DOM element. Without the use of
+this function, | A will assume `document.body` as its root.
+
+## [unmountAll](unmountAll.md) · function
+
+Removes all Aberdeen-managed DOM nodes and stops all active reactive scopes
+(created by `mount`, `derive`, | A with functions, etc.).
+
+## [peek](peek.md) · function
+
+Executes a function or retrieves a value *without* creating subscriptions in the current reactive scope, and returns its result.
+
+## [map](map.md) · function
+
+When using a Map as `source`.
+
+## [multiMap](multiMap.md) · function
+
+When using an array as `source`.
+
+## [partition](partition.md) · function
+
+When using an object as `array`.
+
+## [dump](dump.md) · function
+
+Renders a live, recursive dump of a proxied data structure (or any value)
+into the DOM at the current | A insertion point.
+
+## EMPTY · constant
+
+**Value:** `unique symbol`
+
+## ValueRef · interface
+
+**Type Parameters:**
+
+- `T`
+
+### valueRef.value · member
+
+**Type:** `T`
+
+## [PromiseProxy](PromiseProxy.md) · interface
+
+When `proxy` is called with a Promise, the returned object has this shape.
+
+## [OPAQUE](OPAQUE.md) · constant
+
+A symbol that controls how Aberdeen handles an object in copy operations and proxy wrapping.
+
+## NO_COPY · constant
+
+Use `OPAQUE` instead. This is an alias kept for backward compatibility.
+
+**Value:** `symbol`
+
+## [cssVars](cssVars.md) · constant
+
+A reactive object containing CSS variable definitions.
+
+## CUSTOM_DUMP · constant
+
+When set on an object or its prototype chain, `dump` calls this as a render function
+(with the object as `this`) instead of its default recursive rendering. If the value is not 
+a function, it's treated as a string to display.
+
+**Value:** `unique symbol`
+
+
+## Routing (aberdeen/route)
+
+## [setLog](setLog.md) · function
+
+Configure logging on route changes.
+
+## [go](go.md) · function
+
+Navigate to a new URL by pushing a new history entry.
+
+## [matchCurrent](matchCurrent.md) · function
+
+Returns `true` if the current route matches `target`.
+
+## [push](push.md) · function
+
+Modify the current route by merging `target` into it (using | A.merge), pushing a new history entry.
+
+## [back](back.md) · function
+
+Try to go back in history to the first entry that matches the given target. If none is found, the given state will replace the current page. This is useful for "cancel" or "close" actions that should return to the previous page if possible, but create a new page if not (for instance when arriving at the current page through a direct link).
+
+## [up](up.md) · function
+
+Navigate up in the path hierarchy, by going back to the first history entry
+that has a shorter path than the current one. If there's none, we just shorten
+the current path.
+
+## [persistScroll](persistScroll.md) · function
+
+Restore and store the vertical and horizontal scroll position for
+the parent element to the page state.
+
+## [interceptLinks](interceptLinks.md) · function
+
+Intercept clicks and Enter key presses on links (`<a>` tags) and use Aberdeen routing
+instead of browser navigation for local paths (paths without a protocol or host).
+
+## [Route](Route.md) · interface
+
+The class for the global `route` object.
+
+## current · constant
+
+The global `Route` object reflecting the current URL and browser history state. Changes you make to this affect the current browser history item (modifying the URL if needed).
+
+**Value:** `Route`
+
+
+## Path matching (aberdeen/dispatcher)
+
+## MATCH_FAILED · constant
+
+Symbol to return when a custom `Dispatcher.addRoute` matcher cannot match a segment.
+
+**Value:** `unique symbol`
+
+## MATCH_REST · constant
+
+Special `Dispatcher.addRoute` matcher that matches the rest of the segments as an array of strings.
+
+**Value:** `unique symbol`
+
+## [Dispatcher](Dispatcher.md) · class
+
+Simple route matcher and dispatcher.
+
+
+## Optimistic UI (aberdeen/prediction)
+
+## [applyPrediction](applyPrediction.md) · function
+
+Run the provided function, while treating all changes to Observables as predictions,
+meaning they will be reverted when changes come back from the server (or some other
+async source).
+
+## [applyCanon](applyCanon.md) · function
+
+Temporarily revert all outstanding predictions, optionally run the provided function
+(which will generally make authoritative changes to the data based on a server response),
+and then attempt to reapply the predictions on top of the new canonical state, dropping
+any predictions that can no longer be applied cleanly (the data has been modified) or
+that were specified in `dropPredictions`.
+
+## Patch · type
+
+Represents a set of changes that can be applied to proxied objects.
+This is an opaque type - its internal structure is not part of the public API.
+
+**Type:** `Map<TargetType, Map<any, [any, any]>>`
+
+
+## Transitions (aberdeen/transitions)
+
+## [grow](grow.md) · function
+
+Do a grow transition for the given element. This is meant to be used as a
+handler for the `create` property.
+
+## [shrink](shrink.md) · function
+
+Do a shrink transition for the given element, and remove it from the DOM
+afterwards. This is meant to be used as a handler for the `destroy` property.
 
-- [Reference documentation](https://aberdeenjs.org/modules.html)
-- [Examples](https://aberdeenjs.org/#examples)

package/skill/applyCanon.md

@@ -0,0 +1,20 @@
+## applyCanon · function
+
+Temporarily revert all outstanding predictions, optionally run the provided function
+(which will generally make authoritative changes to the data based on a server response),
+and then attempt to reapply the predictions on top of the new canonical state, dropping
+any predictions that can no longer be applied cleanly (the data has been modified) or
+that were specified in `dropPredictions`.
+
+All of this is done such that redraws are only triggered if the overall effect is an
+actual change to an `Observable`.
+
+**Signature:** `(canonFunc?: () => void, dropPredictions?: Patch[]) => void`
+
+**Parameters:**
+
+- `canonFunc?: () => void` - The function to run without any predictions applied. This will typically
+make authoritative changes to the data, based on a server response.
+- `dropPredictions: Array<Patch>` (optional) - An optional list of predictions (as returned by `applyPrediction`)
+to undo. Typically, when a server response for a certain request is being handled,
+you'd want to drop the prediction that was done for that request.

package/skill/applyPrediction.md

@@ -0,0 +1,15 @@
+## applyPrediction · function
+
+Run the provided function, while treating all changes to Observables as predictions,
+meaning they will be reverted when changes come back from the server (or some other
+async source).
+
+**Signature:** `(predictFunc: () => void) => Patch`
+
+**Parameters:**
+
+- `predictFunc: () => void` - The function to run. It will generally modify some Observables
+to immediately reflect state (as closely as possible) that we expect the server
+to communicate back to us later on.
+
+**Returns:** A `Patch` object. Don't modify it. This is only meant to be passed to `applyCanon`.

package/skill/back.md

@@ -0,0 +1,11 @@
+## back · function
+
+Try to go back in history to the first entry that matches the given target. If none is found, the given state will replace the current page. This is useful for "cancel" or "close" actions that should return to the previous page if possible, but create a new page if not (for instance when arriving at the current page through a direct link).
+
+Consider using `up` to go up in the path hierarchy.
+
+**Signature:** `(target?: RouteTarget) => void`
+
+**Parameters:**
+
+- `target: RouteTarget` (optional) - The target route to go back to. May be a subset of `Route`, or a string (for `path`), or an array of strings (for `p`).

package/skill/clean.md

@@ -0,0 +1,43 @@
+## clean · function
+
+Registers a cleanup function to be executed just before the current reactive scope
+is destroyed or redraws.
+
+This is useful for releasing resources, removing manual event listeners, or cleaning up
+side effects associated with the scope. Cleaners are run in reverse order of registration.
+
+Scopes are created by functions like `derive`, `mount`, | A (when given a render function),
+and internally by constructs like `onEach`.
+
+**Signature:** `(cleaner: () => void) => void`
+
+**Parameters:**
+
+- `cleaner: () => void` - - The function to execute during cleanup.
+
+**Examples:**
+
+Maintaing a sum for a changing array
+```typescript
+const $numbers = A.proxy([3, 5, 10]);
+let $sum = A.proxy(0);
+
+// Show the array items and maintain the sum
+A.onEach($numbers, (item, index) => {
+A(`code#${index}→${item}`);
+// We'll update $sum.value using peek, as += first does a read, but
+// we don't want to subscribe.
+A.peek(() => $sum.value += item);
+// Clean gets called before each rerun for a certain item index
+// No need for peek here, as the clean code doesn't run in an
+// observer scope.
+A.clean(() => $sum.value -= item);
+})
+
+// Show the sum
+A('h1 text=', $sum);
+
+// Make random changes to the array
+const rnd = () => 0|(Math.random()*20);
+setInterval(() => $numbers[rnd()] = rnd(), 1000);
+```

package/skill/clone.md

@@ -0,0 +1,15 @@
+## clone · function
+
+Clone an (optionally proxied) object or array.
+
+**Signature:** `<T extends object>(src: T) => T`
+
+**Type Parameters:**
+
+- `T extends object` - The type of the objects being copied.
+
+**Parameters:**
+
+- `src: T` - The object or array to clone. If it is proxied, `clone` will subscribe to any changes to the (nested) data structure.
+
+**Returns:** A new unproxied array or object (of the same type as `src`), containing a deep copy of `src`.

package/skill/copy.md

@@ -0,0 +1,40 @@
+## copy · function
+
+Recursively copies properties or array items from `src` to `dst`.
+It's designed to work efficiently with reactive proxies created by `proxy`.
+
+- **Minimizes Updates:** When copying between objects/arrays (proxied or not), if a nested object
+  exists in `dst` with the same constructor as the corresponding object in `src`, `copy`
+  will recursively copy properties into the existing `dst` object instead of replacing it.
+  This minimizes change notifications for reactive (proxied) destinations.
+- **Fast with Proxies:** When copying to/from proxied objects, `copy` uses Aberdeen internals
+  to speed things up (compared to a non-Aberdeen-aware deep copy).
+
+**Signature:** `{ <T extends object>(dst: T, src: T): boolean; <T extends object>(dst: T, dstKey: keyof T, src: T[keyof T]): boolean; }`
+
+**Type Parameters:**
+
+- `T extends object` - The type of the objects being copied.
+
+**Parameters:**
+
+- `dst: T` - - The destination object/array/Map (proxied or unproxied).
+- `src: T` - - The source object/array/Map (proxied or unproxied). It won't be modified.
+
+**Returns:** `true` if any changes were made to `dst`, or `false` if not.
+
+**Throws:**
+
+- Error if attempting to copy an array into a non-array or vice versa.
+
+**Examples:**
+
+Basic Copy
+```typescript
+const $source = A.proxy({ a: 1, b: { c: 2 } });
+const $dest = A.proxy({ b: { d: 3 } });
+A.copy($dest, $source);
+console.log($dest); // proxy({ a: 1, b: { c: 2 } })
+A.copy($dest, 'b', { e: 4 });
+console.log($dest); // proxy({ a: 1, b: { e: 4 } })
+```

package/skill/count.md

@@ -0,0 +1,32 @@
+## count · function
+
+Reactively counts the number of properties in an object.
+
+**Signature:** `(proxied: TargetType) => ValueRef<number>`
+
+**Parameters:**
+
+- `proxied: TargetType` - The observable object to count. In case an `array`, `Map`, or `Set` is passed in, a `ref` to its `.length` or `.size` will be returned.
+
+**Returns:** an observable object for which the `value` property reflects the number of properties in `proxied` with a value other than `undefined`, or the collection size for arrays, Maps, and Sets.
+
+**Examples:**
+
+```typescript
+const $items = A.proxy({x: 3, y: 7} as any);
+const $count = A.count($items);
+
+// Create a DOM text node for the count:
+A('div text=', $count);
+// <div>2</div>
+
+// Or we can use it in an `derive` function:
+A(() => console.log("The count is now", $count.value));
+// The count is now 2
+
+// Adding/removing items will update the count
+$items.z = 12;
+// Asynchronously, after 0ms:
+// <div>3</div>
+// The count is now 3
+```

package/skill/cssVars.md

@@ -0,0 +1,15 @@
+## cssVars · constant
+
+A reactive object containing CSS variable definitions.
+
+Any property you assign to `cssVars` becomes available as a CSS custom property throughout your application.
+
+Use `setSpacingCssVars` to optionally initialize `cssVars[1]` through `cssVars[12]` with an exponential spacing scale.
+
+When you reference a CSS variable in Aberdeen using the `$` prefix (e.g., `$primary`), it automatically resolves to `var(--primary)`.
+For numeric keys (which can't be used directly as CSS custom property names), Aberdeen prefixes them with `m` (e.g., `$3` becomes `var(--m3)`).
+
+When you add the first property to cssVars, Aberdeen automatically creates a reactive `<style>` tag in `<head>`
+containing the `:root` CSS custom property declarations. The style tag is automatically removed if cssVars becomes empty.
+
+**Value:** `Record<string, string>`