@wardic/dom 0.0.0-stage → 1.0.0-rc.2

package/dist/internal/variables.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Variable values in the DOM (#55, ADR-0035 *Amendment (#55)*; CONTEXT.md): a value that is wholly a
+ * `var(--name)`, with or without a fallback, stands for that custom property's value on the element.
+ * `variableValues(element)` is a Key rule bound to one element, which a binding adds to each leg it
+ * builds (`InterpolatorRegistry.withKeyRules`). Motion's rule (`getVariableValue`,
+ * css-variables-conversion.ts:18-53, and `DOMKeyframesResolver.readKeyframes` at 16c6122):
+ *
+ * - Either end that is a Variable value is resolved against the element, once, when the leg is
+ *   built: the custom property's computed value, else its fallback, following a fallback that is
+ *   itself a Variable value up to 4 deep. A numeric result is a number.
+ * - The resolved pair goes on through `next`, so the rules after this one still apply (`"none"` →
+ *   `var(--shadow)` grows from its Animatable none), then blends by value.
+ * - The leg's last frame writes the target as written, so at rest the element follows the custom
+ *   property again; a change mid-leg is followed from there.
+ * - A Variable value that doesn't resolve leaves the pair as written: the rule declines, and it
+ *   switches as a Discrete pair, as Motion's does. A `var()` inside a larger value is text (#158).
+ *
+ * Client-only: it reads the element's computed style, after mount (ADR-0021).
+ *
+ * @module
+ */
+import type * as InterpolatorRegistry from "@wardic/core/InterpolatorRegistry";
+import * as Option from "effect/Option";
+/** A value a key blends: a number or a string. */
+/** What a Variable value resolves to: a number or a string. */
+type Value = number | string;
+/** Whether `value` is a Variable value: a string that's wholly a `var()`. */
+export declare const isVariableValue: (value: unknown) => value is string;
+/**
+ * What a Variable value stands for on `element`: its custom property's computed value, else its
+ * fallback, a fallback that is itself a Variable value followed up to 4 deep. `None` when nothing
+ * resolves. Reads the element's computed style.
+ */
+export declare const resolveVariable: (element: Element, value: string) => Option.Option<Value>;
+/**
+ * The Key rule for `element`'s Variable values: a pair with one at either end blends what they resolve
+ * to on `element`, through the rules after it and then by value, and lands on its target as written. It
+ * declines a pair with none, and one that doesn't resolve.
+ *
+ * @example
+ * yield* buildLegs.pipe(InterpolatorRegistry.withKeyRules([Variables.values(element)]))
+ */
+export declare const variableValues: (element: Element) => InterpolatorRegistry.KeyRule;
+export {};
+//# sourceMappingURL=variables.d.ts.map

package/dist/internal/variables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variables.d.ts","sourceRoot":"","sources":["../../src/internal/variables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,KAAK,oBAAoB,MAAM,mCAAmC,CAAA;AAK9E,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAIvC,kDAAkD;AAClD,+DAA+D;AAC/D,KAAK,KAAK,GAAG,MAAM,GAAG,MAAM,CAAA;AA4C5B,6EAA6E;AAE7E,eAAO,MAAM,eAAe,UAAW,OAAO,KAAG,KAAK,IAAI,MAAoE,CAAA;AAK9H;;;;GAIG;AACH,eAAO,MAAM,eAAe,YAAa,OAAO,SAAS,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAiC,CAAA;AAuCtH;;;;;;;GAOG;AAEH,eAAO,MAAM,cAAc,YAAa,OAAO,KAAG,oBAAoB,CAAC,OAQrE,CAAA"}

package/dist/internal/variables.js

@@ -0,0 +1,92 @@
+import * as Arr from "effect/Array";
+import * as Bool from "effect/Boolean";
+import * as Effect from "effect/Effect";
+import { pipe } from "effect/Function";
+import * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import * as Str from "effect/String";
+/** A Variable value's custom property, and its fallback when it has one (Motion's `parseCSSVariable`). */
+const PARTS_RE = /^var\(\s*(--[\w-]+)\s*(?:,\s*([\s\S]*?))?\s*\)$/;
+/** The cheap first check: a string that starts as a `var()` does. */
+const VAR_START_RE = /^\s*var\(/;
+/** How a character moves the bracket depth. */
+const depthStep = (ch) => Bool.match(ch === "(", { onTrue: () => 1, onFalse: () => Bool.match(ch === ")", { onTrue: () => -1, onFalse: () => 0 }) });
+/** Brackets that close as they open: a fallback that is one value, not the rest of a longer string. */
+const isBalanced = (text) => {
+    const end = Arr.reduce(Str.split(text, ""), 0, (depth, ch) => Bool.match(depth < 0, { onTrue: () => depth, onFalse: () => depth + depthStep(ch) }));
+    return end === 0;
+};
+/**
+ * A Variable value's parts, or `None` for any other value: `var(--name)` or `var(--name, fallback)`,
+ * the fallback's brackets balanced, at any depth of nested `var()`s (a pattern alone stops at one).
+ * So `var(--a, 1px) var(--b)` isn't one: two values side by side.
+ */
+const partsOf = (value) => {
+    // Asked of a string end of every key, each leg (#460): one that doesn't start as one builds nothing.
+    if (!VAR_START_RE.test(value))
+        return Option.none();
+    return pipe(Option.fromNullishOr(PARTS_RE.exec(Str.trim(value))), Option.map(([, name, fallback]) => ({ name, fallback: Option.map(Option.fromUndefinedOr(fallback), Str.trim) })), Option.filter((parts) => Option.match(parts.fallback, { onNone: () => true, onSome: isBalanced })));
+};
+/** How deep a fallback that is itself a Variable value is followed (Motion's `maxDepth`). */
+const MAX_DEPTH = 4;
+/** A numeric string, which a resolved value becomes a number from (Motion's `isNumericalString`). */
+const NUMERIC_RE = /^-?\d*\.?\d+(?:e[-+]?\d+)?$/i;
+/** Whether `value` is a Variable value: a string that's wholly a `var()`. */
+// CONTEXT.md's Variable value.
+export const isVariableValue = (value) => Predicate.isString(value) && Option.isSome(partsOf(value));
+/** A resolved value as a key blends it: a number when it reads as one, else the string. */
+const valueOf = (raw) => Bool.match(NUMERIC_RE.test(raw), { onTrue: () => Number.parseFloat(raw), onFalse: () => raw });
+/**
+ * What a Variable value stands for on `element`: its custom property's computed value, else its
+ * fallback, a fallback that is itself a Variable value followed up to 4 deep. `None` when nothing
+ * resolves. Reads the element's computed style.
+ */
+export const resolveVariable = (element, value) => resolveAt(element, value, 1);
+/** {@link resolveVariable} at `depth`, following a fallback that's itself a Variable value. */
+// #618 (F7): the depth counter was the public function's third parameter.
+const resolveAt = (element, value, depth) => {
+    if (depth > MAX_DEPTH)
+        return Option.none();
+    return Option.flatMap(partsOf(value), ({ name, fallback }) => {
+        const own = Str.trim(getComputedStyle(element).getPropertyValue(name));
+        if (Str.isNonEmpty(own))
+            return Option.some(valueOf(own));
+        return pipe(fallback, Option.filter(Str.isNonEmpty), Option.flatMap((rest) => Bool.match(isVariableValue(rest), {
+            onTrue: () => resolveAt(element, rest, depth + 1),
+            onFalse: () => Option.some(valueOf(rest)),
+        })));
+    });
+};
+/** An end as the leg blends it: a Variable value resolved on `element`, any other value as it is. */
+const endOf = (element, value) => Bool.match(isVariableValue(value), {
+    onTrue: () => resolveVariable(element, value),
+    onFalse: () => Option.some(value),
+});
+/**
+ * A blend that writes its target as written on the run's last Frame: a Variable value rests as the
+ * `var()` itself, so the element follows its custom property again. Per frame: a statement `if`.
+ */
+const landOn = (blend, to) => (t, done) => {
+    if (done)
+        return to;
+    return blend(t, done);
+};
+/**
+ * The Key rule for `element`'s Variable values: a pair with one at either end blends what they resolve
+ * to on `element`, through the rules after it and then by value, and lands on its target as written. It
+ * declines a pair with none, and one that doesn't resolve.
+ *
+ * @example
+ * yield* buildLegs.pipe(InterpolatorRegistry.withKeyRules([Variables.values(element)]))
+ */
+// #55.
+export const variableValues = (element) => ({
+    name: "variable values",
+    blend: (key, from, to, _resolve, next) => {
+        // Per key, each leg (#460): a statement.
+        if (!isVariableValue(from) && !isVariableValue(to))
+            return Option.none();
+        return Option.map(Option.all([endOf(element, from), endOf(element, to)]), ([a, b]) => Effect.map(next(key, a, b), (blend) => landOn(blend, to)));
+    },
+});
+//# sourceMappingURL=variables.js.map

package/dist/internal/variables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variables.js","sourceRoot":"","sources":["../../src/internal/variables.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,GAAG,MAAM,cAAc,CAAA;AACnC,OAAO,KAAK,IAAI,MAAM,gBAAgB,CAAA;AACtC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AACtC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,SAAS,MAAM,kBAAkB,CAAA;AAC7C,OAAO,KAAK,GAAG,MAAM,eAAe,CAAA;AAMpC,0GAA0G;AAC1G,MAAM,QAAQ,GAAG,iDAAiD,CAAA;AAElE,qEAAqE;AACrE,MAAM,YAAY,GAAG,WAAW,CAAA;AAEhC,+CAA+C;AAC/C,MAAM,SAAS,GAAG,CAAC,EAAU,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;AAEpK,uGAAuG;AACvG,MAAM,UAAU,GAAG,CAAC,IAAY,EAAW,EAAE;IAC3C,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK,GAAG,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACnJ,OAAO,GAAG,KAAK,CAAC,CAAA;AAClB,CAAC,CAAA;AAQD;;;;GAIG;AACH,MAAM,OAAO,GAAG,CAAC,KAAa,EAAwB,EAAE;IACtD,qGAAqG;IACrG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,IAAI,EAAE,CAAA;IACnD,OAAO,IAAI,CACT,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EACpD,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAS,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EACvH,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,CACnG,CAAA;AACH,CAAC,CAAA;AAED,6FAA6F;AAC7F,MAAM,SAAS,GAAG,CAAC,CAAA;AAEnB,qGAAqG;AACrG,MAAM,UAAU,GAAG,8BAA8B,CAAA;AAEjD,6EAA6E;AAC7E,+BAA+B;AAC/B,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,KAAc,EAAmB,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAA;AAE9H,2FAA2F;AAC3F,MAAM,OAAO,GAAG,CAAC,GAAW,EAAS,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,CAAA;AAEtI;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAgB,EAAE,KAAa,EAAwB,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAA;AAEtH,+FAA+F;AAC/F,0EAA0E;AAC1E,MAAM,SAAS,GAAG,CAAC,OAAgB,EAAE,KAAa,EAAE,KAAa,EAAwB,EAAE;IACzF,IAAI,KAAK,GAAG,SAAS;QAAE,OAAO,MAAM,CAAC,IAAI,EAAE,CAAA;IAC3C,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE;QAC3D,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAA;QACtE,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAA;QACzD,OAAO,IAAI,CACT,QAAQ,EACR,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,EAC7B,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CACtB,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE;YAChC,MAAM,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC;YACjD,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;SAC1C,CAAC,CAAC,CACN,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC,CAAA;AAED,qGAAqG;AACrG,MAAM,KAAK,GAAG,CAAC,OAAgB,EAAE,KAAY,EAAwB,EAAE,CACrE,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE;IACjC,MAAM,EAAE,GAAG,EAAE,CAAC,eAAe,CAAC,OAAO,EAAE,KAAe,CAAC;IACvD,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;CAClC,CAAC,CAAA;AAEJ;;;GAGG;AACH,MAAM,MAAM,GACV,CAAC,KAAoC,EAAE,EAAS,EAAiC,EAAE,CACnF,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE;IACV,IAAI,IAAI;QAAE,OAAO,EAAE,CAAA;IACnB,OAAO,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;AACvB,CAAC,CAAA;AAEH;;;;;;;GAOG;AACH,OAAO;AACP,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAgB,EAAgC,EAAE,CAAC,CAAC;IACjF,IAAI,EAAE,iBAAiB;IACvB,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE;QACvC,yCAAyC;QACzC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC;YAAE,OAAO,MAAM,CAAC,IAAI,EAAE,CAAA;QACxE,OAAO,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CACnF,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAA;IAC9D,CAAC;CACF,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@wardic/dom",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-rc.2",
+  "description": "The browser environment for Wardic: its clock, renderer, input, probe and projection system, as Effect Layers.",
+  "keywords": [
+    "animation",
+    "motion",
+    "dom",
+    "effect"
+  ],
+  "homepage": "https://wardic.dev",
+  "bugs": "https://github.com/wardiclabs/wardic/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wardiclabs/wardic.git",
+    "directory": "packages/dom"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "The Wardic contributors",
+    "email": "hello@wardic.dev",
+    "url": "https://wardic.dev"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.map",
+    "src",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@wardic/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "@wardic/source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./internal/*": null
+  },
+  "scripts": {
+    "build": "../../node_modules/typescript-7/bin/tsc --build",
+    "typecheck": "../../node_modules/typescript-7/bin/tsc --build",
+    "typecheck:tests": "../../node_modules/typescript-7/bin/tsc -p tsconfig.test.json"
+  },
+  "dependencies": {
+    "@wardic/core": "1.0.0-rc.2",
+    "culori": "^4.0.2"
+  },
+  "peerDependencies": {
+    "effect": "^4.1.1"
+  },
+  "devDependencies": {
+    "@wardic/test": "1.0.0-rc.2"
+  }
+}

package/src/Appear.ts

@@ -0,0 +1,45 @@
+/**
+ * Appear animations: a mount animation a server renders as CSS, played from the first paint, before any
+ * code runs, which the engine takes over at mount from where it has got to. The DOM's half, for any
+ * binding:
+ * - **On a server:** `keyframes` samples an element's spec, its mount animation built with core's
+ *   machines, into one `@keyframes` rule, cached across requests. A render's `sheet` gives each element a
+ *   slot, whose `animation` goes in its inline style, and writes the head's `<style>` once every slot's
+ *   timing is defined.
+ * - **At mount:** `find` the element's animation, check it `matches` the client's own spec, start the run
+ *   `elapsedOf` it in (`Machine.startAt`), and `release` the element in the task that writes the engine's
+ *   first frame.
+ *
+ * @example
+ * import * as Appear from "@wardic/dom/Appear"
+ *
+ * // On a server, a sheet a render:
+ * const render = Appear.sheet()
+ * const slot = render.slot()
+ * slot.define({ spec, delay: 0 }) // `slot.animation` goes in the element's style, `render.css()` in the head
+ * // At mount:
+ * const elapsed = Option.map(Appear.find(element), Appear.elapsedOf)
+ */
+// #48, ADR-0044: the **Handoff**. `@wardic/dom/Appear` (ADR-0041).
+export {
+  adoptChunks,
+  animationOf,
+  CHUNK_ATTRIBUTE,
+  chunkStyle,
+  delayOf,
+  elapsedOf,
+  find,
+  keyframes,
+  type Keyframes,
+  matches,
+  MAX_SECONDS,
+  nameOf,
+  pending,
+  type Play,
+  PREFIX,
+  release,
+  sheet,
+  type Sheet,
+  type Slot,
+  type Spec,
+} from "./internal/appear.ts"

package/src/Color.ts

@@ -0,0 +1,24 @@
+/**
+ * CSS colours: `parse` reads a colour string, `format` writes one, `interpolator` blends two in a colour
+ * space, and `TOKEN` finds a colour inside a longer value, a shadow's say. A hex, `rgb()`, `hsl()` and the
+ * named colours are colours from the start; `registerSpaces` adds every other CSS colour space, so
+ * `oklch()` and `lab()` are colours too, and `interpolator("oklch")` can blend in it.
+ *
+ * @example
+ * import * as Color from "@wardic/dom/Color"
+ *
+ * Color.parse("#bf616a") // Some({ mode: "rgb", r: 0.749, g: 0.38, b: 0.416 })
+ * Color.format({ mode: "rgb", r: 1, g: 0.5, b: 0 }) // "rgb(255, 128, 0)"
+ */
+// `@wardic/dom/Color` (#132, ADR-0041): a colour Interpolator in a culori mode, the DOM's own (`css`,
+// sRGB), its `parse` and `format`, and its token (ADR-0024, ADR-0026); `registerSpaces` (#511).
+export {
+  color as interpolator,
+  cssColor as css,
+  type Color,
+  formatColor as format,
+  parseColor as parse,
+  COLOR_TOKEN as TOKEN,
+  registerSpaces,
+  spacesRegistered,
+} from "./internal/colors.ts"

package/src/DomAnnouncer.ts

@@ -0,0 +1,22 @@
+/**
+ * The DOM's Announcer: a shared live region, an element a screen reader watches and reads out as its
+ * text changes, and the helpers a binding uses to describe a Reorder group's items to one. `layer` is
+ * what `DomLive` provides; `prepare` and `announceIn` work on any document.
+ *
+ * @example
+ * import * as DomAnnouncer from "@wardic/dom/DomAnnouncer"
+ *
+ * DomAnnouncer.prepare(document) // its live region, before the first announcement
+ * DomAnnouncer.announceIn(document, "Picked up Milk, position 2 of 5.")
+ */
+// `@wardic/dom/DomAnnouncer` (#132, ADR-0041): a shared assertive live region (ADR-0037).
+export {
+  AnnouncerDomLive as layer,
+  ANNOUNCER_ATTRIBUTE as ATTRIBUTE,
+  documentOf,
+  instructionsId,
+  instructionsIdOf,
+  showInstructions,
+  prepareAnnouncer as prepare,
+  announceIn,
+} from "./internal/announcer.ts"

package/src/DomClock.ts

@@ -0,0 +1,13 @@
+/**
+ * The DOM's Clock: core's Clock and its Refresh frame source over the browser's `requestAnimationFrame`,
+ * as one Layer that needs nothing. `DomLive` provides it.
+ *
+ * @example
+ * import * as DomClock from "@wardic/dom/DomClock"
+ *
+ * const now = Effect.map(Clock.Clock, (clock) => clock.now()).pipe(Effect.provide(DomClock.layer))
+ */
+// `@wardic/dom/DomClock` (#132, ADR-0041): rAF-driven (ADR-0031).
+export {
+  ClockDomLive as layer,
+} from "./internal/clock.ts"

package/src/DomDefaultTransition.ts

@@ -0,0 +1,16 @@
+/**
+ * The DOM's Default transition, Motion's by value: a spring for the transforms, a 0.3 s ease for the
+ * rest, and a 0.8 s tween through more than two keyframes. `layer` is what `DomLive` provides.
+ *
+ * @example
+ * import * as DomDefaultTransition from "@wardic/dom/DomDefaultTransition"
+ *
+ * DomDefaultTransition.transitionFor("x", 100) // { type: "spring", stiffness: 500, damping: 25, restSpeed: 10 }
+ * DomDefaultTransition.transitionFor("opacity", 1) // a 0.3 s tween
+ */
+// `@wardic/dom/DomDefaultTransition` (#132, ADR-0041): ADR-0051, #357; keyframes #429.
+export {
+  DefaultTransitionDomLive as layer,
+  keyframes,
+  transitionFor,
+} from "./internal/default-transition.ts"

package/src/DomInput.ts

@@ -0,0 +1,22 @@
+/**
+ * The DOM's InputSource: pointer, keyboard and focus events as core's own, mapped from the DOM's names by
+ * `toPointer`, `keyOf`, `kindOf` and `buttonOf`. It isn't in `DomLive`: a binding builds `layer` with the
+ * first gesture an app uses, so an app with none ships no input code.
+ *
+ * @example
+ * import * as DomInput from "@wardic/dom/DomInput"
+ *
+ * DomInput.keyOf("ArrowLeft") // "left"
+ * DomInput.buttonOf(2) // "secondary"
+ */
+// `@wardic/dom/DomInput` (#132, ADR-0041): ADR-0019, ADR-0036 *Amendment (#189)*, ADR-0037. Not in
+// `DomLive`: #511, ADR-0067 decision 14.
+export {
+  InputDomLive as layer,
+  keyOf,
+  kindOf,
+  makeFocusable,
+  buttonOf,
+  toPointer,
+  type Where,
+} from "./internal/input.ts"

package/src/DomInterpolators.ts

@@ -0,0 +1,16 @@
+/**
+ * The DOM's InterpolatorRegistry: core's value kinds with the DOM's colours and complex values, and the
+ * DOM's Key rules. `layer` is what `DomLive` provides; `all` is its kinds, in the order they're tried.
+ *
+ * @example
+ * import * as DomInterpolators from "@wardic/dom/DomInterpolators"
+ *
+ * const registry = yield* InterpolatorRegistry.make(DomInterpolators.all, DomKeyRules.all)
+ * const blend = yield* registry.resolve("#bf616a", "#a3be8c")
+ * blend(0.5) // the colour halfway
+ */
+// `@wardic/dom/DomInterpolators` (#132, ADR-0041): ADR-0024, ADR-0035, ADR-0036.
+export {
+  InterpolatorRegistryDomLive as layer,
+  interpolators as all,
+} from "./internal/interpolators.ts"

package/src/DomKeyRules.ts

@@ -0,0 +1,17 @@
+/**
+ * The DOM's Key rules, for the keys it blends by name. `visibility` keeps `display` and `visibility` at
+ * their start until an animation's last frame when they're hiding the element, and `animatableNone`
+ * grows a shadow, a filter or a fill from nothing when one end is empty. `all` is both, in the order
+ * they're asked.
+ *
+ * @example
+ * import * as DomKeyRules from "@wardic/dom/DomKeyRules"
+ *
+ * const registry = yield* InterpolatorRegistry.make(DomInterpolators.all, [DomKeyRules.visibility])
+ */
+// `@wardic/dom/DomKeyRules` (#132, ADR-0041): ADR-0015, ADR-0035.
+export {
+  keyRules as all,
+  visibility,
+  animatableNone,
+} from "./internal/key-rules.ts"

package/src/DomPositionalKeys.ts

@@ -0,0 +1,16 @@
+/**
+ * The DOM's Positional keys, the keys reduced motion lands at once rather than animating: the
+ * transforms, and the keys that place and size an element's box, `top`, `width` and the rest. `layer`
+ * is what `DomLive` provides.
+ *
+ * @example
+ * import * as DomPositionalKeys from "@wardic/dom/DomPositionalKeys"
+ *
+ * DomPositionalKeys.isPositional("width") // true: it lands at once
+ * DomPositionalKeys.isPositional("opacity") // false: it still fades
+ */
+// `@wardic/dom/DomPositionalKeys` (#132, ADR-0041): ADR-0029, ADR-0036.
+export {
+  PositionalKeysDomLive as layer,
+  isPositional,
+} from "./internal/positional-keys.ts"

package/src/DomProbe.ts

@@ -0,0 +1,15 @@
+/**
+ * The DOM's Probe: boxes from `getBoundingClientRect`, sizes and visibility from the observers, the
+ * viewport, the reduced-motion preference from `matchMedia`, whether the page is shown, and a container's
+ * scroll. `layer` needs the Environment's `AtomRegistry`, which it writes its live values through;
+ * `DomLive` provides both.
+ *
+ * @example
+ * import * as DomProbe from "@wardic/dom/DomProbe"
+ *
+ * const probe = DomProbe.layer.pipe(Layer.provide(AtomRegistry.layer))
+ */
+// `@wardic/dom/DomProbe` (#132, ADR-0041).
+export {
+  ProbeDomLive as layer,
+} from "./internal/probe.ts"

package/src/DomProjectionSystem.ts

@@ -0,0 +1,44 @@
+/**
+ * The DOM's Projection system: `layer` builds it, writing through the Environment's
+ * `FlushGate`, and `make` builds it over any sink, for a binding that wires it itself. Only a binding's
+ * layout feature imports it, so a page that never lays out ships none of it. Closing its Scope stops the
+ * engine: its run, its observers and listeners, and what it forked. Built after the gate, it ends before
+ * it.
+ *
+ * @example
+ * import * as DomProjectionSystem from "@wardic/dom/DomProjectionSystem"
+ *
+ * const layout = DomProjectionSystem.layer().pipe(Layer.provide(FlushGate.layer({ batch: (apply) => apply() })))
+ */
+// The DOM's **Projection system** engine (#548, ADR-0041's `Dom` implementations), apart from
+// `ProjectionSystem`'s key and types (ADR-0067, *Amendment (#548)*). Its members are plain functions.
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import type * as Scope from "effect/Scope"
+import * as FlushGate from "./FlushGate.ts"
+import { PassEnds } from "./internal/pass-ends.ts"
+import * as internal from "./internal/projection.ts"
+import { makeRunner } from "./internal/runner.ts"
+import { ProjectionSystem, type Options, type Services, type Shape, type Sink } from "./ProjectionSystem.ts"
+
+/**
+ * Build the engine over `sink`, the context's Frame loop and Renderer, in the current Scope: what
+ * it forks runs in that Scope, and closing it ends the engine. It's the `ProjectionSystem` in the
+ * context it gives, beside what a Reorder controller over it needs.
+ */
+// The context holds the internal `PassEnds` too (internal/pass-ends.ts, #618), the engine's own, so a
+// ProjectionSystem a binding wraps or replaces in its context still has its Reorder controller hear
+// each Measure pass. Its runner forks on Effect's default scheduler, whatever call built the Layer
+// (`internal/runner.ts`).
+export const make: (sink: Sink, options?: Options) => Effect.Effect<Context.Context<ProjectionSystem | PassEnds>, never, Services | Scope.Scope> =
+  /*#__PURE__*/ Effect.fnUntraced(function* (sink: Sink, options: Options = {}) {
+    // Typed without `dispose` and `onPassEnd`: the Scope ends it, and `PassEnds` hands the other out.
+    const system = internal.makeProjectionSystem(yield* makeRunner<Services>(), sink, options)
+    yield* Effect.addFinalizer(() => Effect.sync(system.dispose))
+    return Context.make(ProjectionSystem, system as Shape).pipe(Context.add(PassEnds, { onPassEnd: system.onPassEnd }))
+  })
+
+/** The engine as a Layer, writing through the Environment's `FlushGate`: built by `make`, ended by the Layer's Scope. */
+export const layer = (options: Options = {}): Layer.Layer<ProjectionSystem | PassEnds, never, FlushGate.FlushGate | Services> =>
+  Layer.effectContext(Effect.flatMap(Effect.service(FlushGate.FlushGate), (gate) => make(gate, options)))

package/src/DomRenderer.ts

@@ -0,0 +1,26 @@
+/**
+ * The DOM's Renderer: `project` turns a Frame's values into a style patch, grouping the transform keys
+ * into one `transform` and drawing a bare number on a length in `px`, and its `commit` writes the patch
+ * onto an element. The rest is for a binding's layout projection: an element's own move, scale, rotation
+ * and opacity, read from its values, and its transform template.
+ *
+ * @example
+ * import * as DomRenderer from "@wardic/dom/DomRenderer"
+ *
+ * DomRenderer.project({ x: 100, opacity: 0.5 }) // { transform: "translateX(100px)", opacity: 0.5 }
+ */
+// `@wardic/dom/DomRenderer` (#132, ADR-0041): ADR-0006, ADR-0034; the **Transform template** (#443);
+// `LENGTH_KEYS` (#522).
+export {
+  RendererDomLive as layer,
+  project,
+  ownScaleOf,
+  ownTranslateOf,
+  ownRotateOf,
+  ownOpacityOf,
+  TEMPLATE_KEY,
+  type TransformTemplate,
+  heldTransformOf,
+  LENGTH_KEYS,
+  type LengthKey,
+} from "./internal/renderer.ts"

package/src/FlushGate.ts

@@ -0,0 +1,81 @@
+/**
+ * The Flush gate: where a binding writes each element's animated values, drawn onto the elements once a
+ * frame. A binding registers each element with its target, writes values as its animations step, and the
+ * gate draws them together, at the end of the frame's animation tick, through the Environment's renderer;
+ * a write made outside a tick, as a drag's move is, asks for a frame of its own. A server render gets
+ * `inert`, which does nothing.
+ *
+ * @example
+ * import * as FlushGate from "@wardic/dom/FlushGate"
+ *
+ * const gate = yield* FlushGate.FlushGate
+ * const unregister = gate.register("card", { target: card })
+ * gate.write("card", { opacity: 0.5 }) // drawn at the next frame
+ */
+// The **Flush gate** (ADR-0006, ADR-0031, ADR-0033, ADR-0034). `@wardic/dom/FlushGate` (#132, ADR-0041). A
+// service built by a Layer (`layer`) and ended by that Layer's Scope: closing it takes the gate's hook off
+// the Frame loop, cancels a pending frame and clears what it held. Its members are plain functions, called
+// per element and per frame. `make` is the scoped constructor, for a binding that wires it itself. `inert`
+// (ADR-0021, decision 9): a value for a binding whose server builds no runtime, or `layerInert` for one
+// whose server runs an Effect program.
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import { Atom } from "effect/reactivity"
+import type * as Scope from "effect/Scope"
+import * as internal from "./internal/gate.ts"
+import { makeRunner } from "./internal/runner.ts"
+
+/** The gate: what a binding registers its elements with and writes their values into. */
+export type Shape = Omit<internal.FlushGate, "dispose">
+
+/** An element's commit target and hooks, given to `register`. */
+export type Sink = internal.FlushSink
+
+/** What a binding hands its gate: the `batch` a frame's Starting-style switches run in. */
+export type Options = internal.FlushGateOptions
+
+/** The services a gate needs from its Environment. */
+export type Services = internal.FlushGateServices
+
+/** The Environment's Flush gate. */
+export class FlushGate extends Context.Service<FlushGate, Shape>()("@wardic/dom/FlushGate") {}
+
+/**
+ * Build a gate over the context's Renderer, Frame loop and Refresh frame source, in the current
+ * Scope: what it forks runs in that Scope, and closing it ends the gate.
+ */
+export const make: (options: Options) => Effect.Effect<Shape, never, Services | Scope.Scope> = Effect.fnUntraced(
+  function* (options: Options) {
+    // The gate itself, typed without `dispose`: the Scope ends it. Its runner forks on Effect's
+    // default scheduler, whatever call built the Layer (`internal/runner.ts`).
+    const gate = internal.makeFlushGate(yield* makeRunner<Services>(), options)
+    yield* Effect.addFinalizer(() => Effect.sync(gate.dispose))
+    return gate
+  })
+
+/** The gate as a Layer: built by `make`, ended by the Layer's Scope. */
+export const layer = (options: Options): Layer.Layer<FlushGate, never, Services> => Layer.effect(FlushGate)(make(options))
+
+const noop = (): void => {}
+
+/** What `inert`'s `valueOf` gives: an Atom that stays `undefined`, since nothing is committed on a server. */
+const NO_VALUE: Atom.Atom<unknown> = Atom.make<unknown>(undefined)
+
+/**
+ * The gate a server render gets: it flushes nothing, so `register` returns an unregister that does
+ * nothing, and the rest do nothing, `afterFlush` included, since no flush comes. Code that takes the gate
+ * at setup and uses it after mount keeps working on a server.
+ */
+// ADR-0021, decision 9.
+export const inert: Shape = Object.freeze({
+  register: () => noop,
+  write: noop,
+  flushPass: noop,
+  release: noop,
+  valueOf: () => NO_VALUE,
+  afterFlush: noop,
+})
+
+/** `inert` as a Layer, for a binding whose server render runs an Effect program. */
+export const layerInert: Layer.Layer<FlushGate> = Layer.succeed(FlushGate, inert)

package/src/MeasuredPair.ts

@@ -0,0 +1,15 @@
+/**
+ * Measured pairs: a key that places or sizes the box, whose two ends are lengths of different types,
+ * `"auto"` against px, `"50%"` against a number, a `calc()`, can't blend as written. Both ends are
+ * measured in px at the end of the task that asks, as Motion's are, so the animation runs between them
+ * and lands on its target as given.
+ *
+ * @example
+ * import * as MeasuredPair from "@wardic/dom/MeasuredPair"
+ *
+ * MeasuredPair.needs("width", "auto", 200) // true
+ * MeasuredPair.needs("opacity", 0, 1) // false
+ */
+// **Measured pairs** (#430, CONTEXT.md, Motion's `DOMKeyframesResolver`). `@wardic/dom/MeasuredPair`: for
+// binding authors.
+export { measure, measured, type Measured, needs, type Requested } from "./internal/measured-pairs.ts"

package/src/OwnValues.ts

@@ -0,0 +1,19 @@
+/**
+ * An element's own values: what its style or its computed style says for a key, read once, the value an
+ * animation starts from, and returns to when nothing else sets it. `valueLike` reads a raw value in the
+ * shape of the key's target.
+ *
+ * @example
+ * import * as OwnValues from "@wardic/dom/OwnValues"
+ *
+ * const own = OwnValues.of(element)
+ * own("opacity") // Some("1"), from its computed style
+ * OwnValues.valueLike("10px", 0) // Some(10)
+ */
+// `@wardic/dom/OwnValues` (#132, ADR-0041): its Base values (ADR-0022).
+export {
+  ownValues as of,
+  styleValueOf,
+  valueLike,
+  type OwnValue,
+} from "./internal/own-values.ts"