bireactive 0.3.1 → 0.3.2

package/dist/core/values/transform.js

@@ -1,10 +1,3 @@
-// transform.ts — reactive 2D transform.
-//
-// Invertibles (`add`, `sub`) return `: this` and ride on
-// `Cell#lens(fwd, bwd)`; chained calls compose into a lens chain.
-// Field-lens getters use `fieldLens()`, so writability propagates through
-// nested chains
-// (`Transform.translate.x.value = 5` works on writable receivers).
 import { tween } from "../../animation/index.js";
 import { Cell, fieldLens, reader, readNow } from "../cell.js";
 import { Num } from "./num.js";
@@ -58,8 +51,6 @@ export const metric = (a, b) => vMetric(a.translate, b.translate) +
 const linearImpl = { add, sub, scale };
 export class Transform extends Cell {
     static traits = { linear: linearImpl, lerp, metric, equals };
-    /** Scalar `scale` is the `.scale` Vec field lens, not an eager method;
-     *  scalar-multiply via `Transform.lens(...)` or field writes. */
     constructor(v = DEFAULT) {
         super(v, { equals });
     }
@@ -89,13 +80,13 @@ export class Transform extends Cell {
     get opacity() {
         return fieldLens(this, "opacity", Num);
     }
-    /** Tween-builder, implied by the lerp trait. */
+    /** Tween-builder. */
     to(target, dur, ease) {
         return tween(this, target, dur, ease);
     }
 }
-/** Seed a `Writable<Transform>` from literal values. For reactive
- *  sources, use `Transform.lens(...)` or field-write composition. */
+/** Writable `Transform` from literal fields. For reactive sources use
+ *  `Transform.lens` or field writes. */
 export function transform(init) {
     const tr = new Transform();
     if (init) {

package/dist/core/values/tri.d.ts

@@ -15,19 +15,18 @@ export declare class Tri extends Cell<V> {
     };
     readonly _t: typeof Tri.traits;
     constructor(v?: V);
-    /** Kleene negation. Involution; fixed at `"mixed"`. */
+    /** Kleene negation. */
     not(): this;
-    /** Aggregate over N writable `Bool` / `Tri` children. Read: all-true →
-     *  `true`, all-false → `false`, any disagreement (or any child already
-     *  `"mixed"`) → `"mixed"`. Write: `true` / `false` broadcast to every
-     *  child, recursing through nested aggregates; `"mixed"` is a no-op. */
+    /** AND-aggregate over writable `Bool`/`Tri` children: `true` if all are true,
+     *  `false` if all false, else `"mixed"`. A `true`/`false` write broadcasts to
+     *  every child (recursing into nested aggregates); `"mixed"` is a no-op. */
     static allOf(parents: readonly (Bool | Tri)[]): Writable<Tri>;
-    /** Dual of `allOf` (Kleene OR) over `Bool` / `Tri` children: any-true →
-     *  `true`, all-false → `false`, else (or any child `"mixed"`) →
-     *  `"mixed"`. Same broadcast write policy. */
+    /** OR-aggregate over writable `Bool`/`Tri` children: `true` if any is true,
+     *  `false` if all false, else `"mixed"`. A `true`/`false` write broadcasts to
+     *  every child; `"mixed"` is a no-op. */
     static anyOf(parents: readonly (Bool | Tri)[]): Writable<Tri>;
 }
-/** Writable `Tri`. Strict factory: `Tri.value | Writable<Tri>` in,
- *  `Writable<Tri>` out. Default initial value is `"mixed"`. */
+/** Writable `Tri` from a literal (new cell) or existing writable (passed
+ *  through). Defaults to `"mixed"`. */
 export declare function tri(v?: Init<Tri>): Writable<Tri>;
 export {};

package/dist/core/values/tri.js

@@ -1,8 +1,3 @@
-// tri.ts — three-valued logical type (Kleene logic).
-//
-// `Tri.value ∈ { true, false, "mixed" }` — Bool plus an unknown state
-// fixed under negation. Strong-Kleene AND/OR follow the partial-info
-// reading (`mixed AND false` → `false`, `mixed AND true` → `mixed`).
 import { Cell, SKIP } from "../cell.js";
 const equals = (a, b) => a === b;
 /** Kleene negation: `true` / `false` swap, `"mixed"` is fixed. */
@@ -30,14 +25,13 @@ export class Tri extends Cell {
     constructor(v = "mixed") {
         super(v, { equals });
     }
-    /** Kleene negation. Involution; fixed at `"mixed"`. */
+    /** Kleene negation. */
     not() {
         return this.lens(not, not);
     }
-    /** Aggregate over N writable `Bool` / `Tri` children. Read: all-true →
-     *  `true`, all-false → `false`, any disagreement (or any child already
-     *  `"mixed"`) → `"mixed"`. Write: `true` / `false` broadcast to every
-     *  child, recursing through nested aggregates; `"mixed"` is a no-op. */
+    /** AND-aggregate over writable `Bool`/`Tri` children: `true` if all are true,
+     *  `false` if all false, else `"mixed"`. A `true`/`false` write broadcasts to
+     *  every child (recursing into nested aggregates); `"mixed"` is a no-op. */
     static allOf(parents) {
         return Tri.lens(parents, (vs) => {
             let anyT = false;
@@ -59,9 +53,9 @@ export class Tri extends Cell {
             return parents.map(() => target);
         });
     }
-    /** Dual of `allOf` (Kleene OR) over `Bool` / `Tri` children: any-true →
-     *  `true`, all-false → `false`, else (or any child `"mixed"`) →
-     *  `"mixed"`. Same broadcast write policy. */
+    /** OR-aggregate over writable `Bool`/`Tri` children: `true` if any is true,
+     *  `false` if all false, else `"mixed"`. A `true`/`false` write broadcasts to
+     *  every child; `"mixed"` is a no-op. */
     static anyOf(parents) {
         return Tri.lens(parents, (vs) => {
             let anyT = false;
@@ -86,8 +80,8 @@ export class Tri extends Cell {
         });
     }
 }
-/** Writable `Tri`. Strict factory: `Tri.value | Writable<Tri>` in,
- *  `Writable<Tri>` out. Default initial value is `"mixed"`. */
+/** Writable `Tri` from a literal (new cell) or existing writable (passed
+ *  through). Defaults to `"mixed"`. */
 export function tri(v = "mixed") {
     if (v instanceof Tri)
         return v;

package/dist/core/values/vec.d.ts

@@ -21,6 +21,9 @@ export declare const scaleAbout: (v: V, p: V, k: number) => V;
  *  (y-down screen coords flip the visual sense). Returns `c` if `p` is
  *  inside or on the circle. */
 export declare function tangentPoint(p: V, c: V, r: number, side?: 1 | -1): V;
+/** Representative of cyclic angle `target` closest to `current`
+ *  (shortest-arc inverse). */
+export declare const nearestAngle: (target: number, current: number) => number;
 export declare class Vec extends Cell<V> {
     static traits: {
         linear: Linear<V>;
@@ -34,11 +37,9 @@ export declare class Vec extends Cell<V> {
     constructor(v?: V);
     add(b: Val<V>): this;
     sub(b: Val<V>): this;
-    /** Uniform scale by `k` about `pivot` (default origin). Inverse scales
-     *  by `1/k`; exact bijection for `k ≠ 0`. */
+    /** Uniform scale by `k` about `pivot` (default origin). Invertible when k ≠ 0. */
     scale(k: Val<number>, pivot?: Val<V>): this;
-    /** Rotate by `angle` (radians) about `pivot` (default origin). Inverse
-     *  rotates by `−angle`; exact bijection. */
+    /** Rotate by `angle` (radians) about `pivot` (default origin). */
     rotate(angle: Val<number>, pivot?: Val<V>): this;
     offset(dx: Val<number>, dy: Val<number>): this;
     up(n: Val<number>): this;
@@ -52,27 +53,11 @@ export declare class Vec extends Cell<V> {
     get x(): this extends import("../index.js").WritableBrand ? Writable<Num> : Num;
     get y(): this extends import("../index.js").WritableBrand ? Writable<Num> : Num;
     get magnitude(): Num;
-    /** Tween-builder; `this: Writable<Vec>` gates the call to writable
-     *  receivers. */
+    /** Tween-builder. */
     to(this: Writable<Vec>, target: V, dur: Val<number>, ease?: Easing): Tween<V>;
 }
-/** Writable `Vec` at `(x, y)`. Each axis is a literal `number` (lifted
- *  to a fresh seed) or an existing `Writable<Num>` (identity passthrough).
- *  RO sources are rejected at the type level — use `Vec.derive(...)` for
- *  reactive RO tracking, or `cell.value` to snapshot. Lock an axis with
- *  `Num.pin(c)`: `vec(slider, Num.pin(100))`. */
+/** Writable `Vec` at `(x, y)`. Each axis is a literal (new cell) or existing
+ *  writable (passed through); for read-only sources use `Vec.derive`. Lock an
+ *  axis with `Num.pin`: `vec(slider, Num.pin(100))`. */
 export declare function vec(x?: Init<Num>, y?: Init<Num>): Writable<Vec>;
-/** Policy for `polar`'s inverse — which inputs absorb a write:
- *
- *  - `rotate`    — c fixed; write r and a to land on target.
- *  - `translate` — r and a fixed; shift c by Δ.
- *  - `radial`    — c and a fixed; project the drag onto the ray.
- *  - `circular`  — c and r fixed; project the drag onto the circle. */
-export type PolarPolicy = "rotate" | "translate" | "radial" | "circular";
-/** Vec at polar offset from `center`: `center + (r·cos a, r·sin a)`.
- *  Bidirectional; each input is a literal (lifted to a fresh seed) or an
- *  existing writable cell. RO inputs are rejected at the type level.
- *  `policy` selects which inputs absorb writes; lock one with
- *  `Num.pin(c)`: `polar(c, Num.pin(100), a)`. */
-export declare function polar(center: Init<Vec>, r: Init<Num>, a: Init<Num>, policy?: PolarPolicy): Writable<Vec>;
 export {};

package/dist/core/values/vec.js

@@ -1,10 +1,5 @@
-// vec.ts — reactive 2D point.
-//
-// Invertibles return `: this` and ride on `Cell#lens(fwd, bwd)`;
-// chained calls compose into a lens chain. Field-lens getters use
-// `fieldLens()` (propagates writability); `cachedDerive()` wraps RO views.
 import { tween } from "../../animation/index.js";
-import { Cell, cachedDerive, fieldLens, reader, readNow, SKIP, } from "../cell.js";
+import { Cell, cachedDerive, fieldLens, reader, readNow, } from "../cell.js";
 import { Num, num } from "./num.js";
 export const add = (a, b) => ({ x: a.x + b.x, y: a.y + b.y });
 export const sub = (a, b) => ({ x: a.x - b.x, y: a.y - b.y });
@@ -51,7 +46,7 @@ export function tangentPoint(p, c, r, side = -1) {
 const wrapToPi = (x) => x - 2 * Math.PI * Math.round(x / (2 * Math.PI));
 /** Representative of cyclic angle `target` closest to `current`
  *  (shortest-arc inverse). */
-const nearestAngle = (target, current) => current + wrapToPi(target - current);
+export const nearestAngle = (target, current) => current + wrapToPi(target - current);
 const linearImpl = { add, sub, scale };
 const packImpl = {
     dim: 2,
@@ -94,8 +89,7 @@ export class Vec extends Cell {
             return { x: n.x + o.x, y: n.y + o.y };
         });
     }
-    /** Uniform scale by `k` about `pivot` (default origin). Inverse scales
-     *  by `1/k`; exact bijection for `k ≠ 0`. */
+    /** Uniform scale by `k` about `pivot` (default origin). Invertible when k ≠ 0. */
     scale(k, pivot) {
         const kf = reader(k);
         const pf = pivot === undefined ? undefined : reader(pivot);
@@ -107,8 +101,7 @@ export class Vec extends Cell {
             return pf ? scaleAbout(n, pf(), 1 / k) : { x: n.x / k, y: n.y / k };
         });
     }
-    /** Rotate by `angle` (radians) about `pivot` (default origin). Inverse
-     *  rotates by `−angle`; exact bijection. */
+    /** Rotate by `angle` (radians) about `pivot` (default origin). */
     rotate(angle, pivot = ORIGIN) {
         const af = reader(angle);
         const pf = reader(pivot);
@@ -119,7 +112,6 @@ export class Vec extends Cell {
         const yf = reader(dy);
         return this.lens(v => ({ x: v.x + xf(), y: v.y + yf() }), n => ({ x: n.x - xf(), y: n.y - yf() }));
     }
-    // Axis-aligned offset sugar — same fwd/bwd shape as offset.
     up(n) {
         const f = reader(n);
         return this.lens(v => ({ x: v.x, y: v.y - f() }), o => ({ x: o.x, y: o.y + f() }));
@@ -157,68 +149,21 @@ export class Vec extends Cell {
     get magnitude() {
         return cachedDerive(this, "magnitude", Num, v => Math.hypot(v.x, v.y));
     }
-    /** Tween-builder; `this: Writable<Vec>` gates the call to writable
-     *  receivers. */
+    /** Tween-builder. */
     to(target, dur, ease) {
         return tween(this, target, dur, ease);
     }
 }
-/** @internal — 2-input lens over two writable `Num`s; `vec()` delegates
- *  here after lifting literals. */
+/** Lens combining two writable `Num`s into a `Vec`. */
 function axes(x, y) {
-    // The view fully reconstructs both axes (1-arg bwd ⇒ no source read).
     return Vec.lens([x, y], ([xv, yv]) => ({ x: xv, y: yv }), v => [v.x, v.y]);
 }
-/** Writable `Vec` at `(x, y)`. Each axis is a literal `number` (lifted
- *  to a fresh seed) or an existing `Writable<Num>` (identity passthrough).
- *  RO sources are rejected at the type level — use `Vec.derive(...)` for
- *  reactive RO tracking, or `cell.value` to snapshot. Lock an axis with
- *  `Num.pin(c)`: `vec(slider, Num.pin(100))`. */
+/** Writable `Vec` at `(x, y)`. Each axis is a literal (new cell) or existing
+ *  writable (passed through); for read-only sources use `Vec.derive`. Lock an
+ *  axis with `Num.pin`: `vec(slider, Num.pin(100))`. */
 export function vec(x = 0, y = 0) {
     if (typeof x === "number" && typeof y === "number") {
         return new Vec({ x, y });
     }
     return axes(num(x), num(y));
 }
-/** Vec at polar offset from `center`: `center + (r·cos a, r·sin a)`.
- *  Bidirectional; each input is a literal (lifted to a fresh seed) or an
- *  existing writable cell. RO inputs are rejected at the type level.
- *  `policy` selects which inputs absorb writes; lock one with
- *  `Num.pin(c)`: `polar(c, Num.pin(100), a)`. */
-export function polar(center, r, a, policy = "rotate") {
-    // Lift literals; already-writable inputs pass through by identity.
-    const cSig = center instanceof Vec ? center : vec(center.x, center.y);
-    const rSig = num(r);
-    const aSig = num(a);
-    const project = (c, rv, av) => ({
-        x: c.x + rv * Math.cos(av),
-        y: c.y + rv * Math.sin(av),
-    });
-    let bwd;
-    switch (policy) {
-        case "rotate":
-            bwd = (p, [cv, , av]) => {
-                const dx = p.x - cv.x;
-                const dy = p.y - cv.y;
-                return [SKIP, Math.hypot(dx, dy), nearestAngle(Math.atan2(dy, dx), av)];
-            };
-            break;
-        case "translate":
-            bwd = (p, [cv, rv, av]) => {
-                const f = project(cv, rv, av);
-                return [{ x: cv.x + (p.x - f.x), y: cv.y + (p.y - f.y) }, SKIP, SKIP];
-            };
-            break;
-        case "radial":
-            bwd = (p, [cv, , av]) => {
-                const dx = p.x - cv.x;
-                const dy = p.y - cv.y;
-                return [SKIP, dx * Math.cos(av) + dy * Math.sin(av), SKIP];
-            };
-            break;
-        case "circular":
-            bwd = (p, [cv, , av]) => [SKIP, SKIP, nearestAngle(Math.atan2(p.y - cv.y, p.x - cv.x), av)];
-            break;
-    }
-    return Vec.lens([cSig, rSig, aSig], ([c, rv, av]) => project(c, rv, av), bwd);
-}

package/dist/index.d.ts

@@ -1,20 +1,9 @@
-/** @group Reactivity */
-/** @group Animation */
 export * from "./animation/index.js";
-/** @group Utilities */
 export * from "./assert/index.js";
-/** @group Rendering */
 export { type CodeOpts, CodeShape, code, codeStyles, type Token, tokenize } from "./code/index.js";
-/** @group Utilities */
-export * from "./coll.js";
 export * from "./core/index.js";
-/** @group Utilities */
 export * from "./ext/index.js";
-/** @group Shapes */
 export * from "./shapes/index.js";
-/** @group Rendering */
 export * from "./tex/index.js";
-/** @group Utilities */
 export { allNodes, atPath, isLeaf, leavesOf, node as treeNode, nodeCount, type TreeNode, walkTree, } from "./tree.js";
-/** @group Web */
 export * from "./web/index.js";

package/dist/index.js

@@ -1,22 +1,12 @@
-/** @group Reactivity */
-/** @group Animation */
+// API-reference groups are assigned by source folder in theme/group-by-source.mjs.
 export * from "./animation/index.js";
-/** @group Utilities */
 export * from "./assert/index.js";
 // `code` and `tex` both export `Part`; re-export `code`'s other symbols
 // explicitly so the wildcard below lets `tex`'s `Part` win.
-/** @group Rendering */
 export { CodeShape, code, codeStyles, tokenize } from "./code/index.js";
-/** @group Utilities */
-export * from "./coll.js";
 export * from "./core/index.js";
-/** @group Utilities */
 export * from "./ext/index.js";
-/** @group Shapes */
 export * from "./shapes/index.js";
-/** @group Rendering */
 export * from "./tex/index.js";
-/** @group Utilities */
 export { allNodes, atPath, isLeaf, leavesOf, node as treeNode, nodeCount, walkTree, } from "./tree.js";
-/** @group Web */
 export * from "./web/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bireactive",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Bi-directional reactive programming.",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,9 +33,10 @@
   ],
   "scripts": {
     "dev": "vite --host",
-    "site": "vite build && typedoc && vitepress build docs",
-    "docs": "typedoc && vitepress build docs",
-    "docs:dev": "typedoc && vitepress dev docs --port 5556",
+    "site": "vite build && typedoc",
+    "docs": "typedoc",
+    "docs:dev": "typedoc --watch",
+    "docs:preview": "python3 -m http.server 5556 --directory dist-web/api",
     "preview": "vite preview",
     "prebuild": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json --resolve-full-paths",
@@ -62,6 +63,7 @@
     "@biomejs/biome": "2.4.15",
     "@preact/signals-core": "^1.14.2",
     "@types/node": "^22.0.0",
+    "@typhonjs-typedoc/typedoc-theme-dmt": "^0.4.0",
     "alien-signals": "^3.2.1",
     "fast-check": "^4.8.0",
     "gray-matter": "^4.0.3",
@@ -71,14 +73,11 @@
     "reactive-framework-test-suite": "^0.0.2",
     "tsc-alias": "^1.8.17",
     "typedoc": "^0.28.19",
-    "typedoc-plugin-markdown": "^4.12.0",
-    "typedoc-vitepress-theme": "^1.1.3",
     "typescript": "^6.0.3",
     "vite": "^7.3.3",
     "vite-node": "^5.3.0",
     "vite-plugin-top-level-await": "^1.6.0",
     "vite-plugin-wasm": "^3.6.0",
-    "vitepress": "^1.6.4",
     "vitest": "^4.1.7"
   },
   "keywords": [

package/dist/coll.d.ts

@@ -1,74 +0,0 @@
-import { type Cell, type Read, type Writable } from "./core/index.js";
-/** Accessor for an element's writable field cell. Forward reads `.value`;
- *  the backward pass writes it. */
-export type Accessor<E, V> = (e: E) => Writable<Cell<V>>;
-/** A forward test over an element's fields, optionally assertable —
- *  `assert(e)` makes the test pass by writing fields. */
-export interface FieldPred<E> {
-    (e: E): boolean;
-    assert?: (e: E) => void;
-}
-export interface Group<K, E> {
-    key: K;
-    items: readonly E[];
-}
-export interface GroupOpts<E, K> {
-    /** Fixed key order; seeds empty buckets and pins column order. */
-    order?: readonly K[];
-    /** Order field within each group; enables `move(e, key, index)`. */
-    sort?: Accessor<E, number>;
-}
-/** `field === value`, assertable by writing the field. */
-export declare function is<E, V>(field: Accessor<E, V>, value: V): FieldPred<E>;
-/** Conjunction; asserts every clause. */
-export declare function allPass<E>(...preds: readonly FieldPred<E>[]): FieldPred<E>;
-/** Read-only projection with chainable structural lenses. */
-export declare class View<E> {
-    protected readonly list: Read<readonly E[]>;
-    readonly key: (e: E) => unknown;
-    protected readonly parent: View<E> | null;
-    protected constructor(list: Read<readonly E[]>, key: (e: E) => unknown, parent: View<E> | null);
-    /** Current members; tracked when read in an effect/derive. */
-    get items(): readonly E[];
-    /** The source collection at the head of the chain. */
-    get root(): Coll<E>;
-    /** Make `e` appear in this view: satisfy own constraint, recursively up. */
-    assertContains(e: E): void;
-    protected assertSelf(_e: E): void;
-    filter(pred: FieldPred<E>): View<E>;
-    sortBy(field: Accessor<E, number>): SortView<E>;
-    groupBy<K>(field: Accessor<E, K>, opts?: GroupOpts<E, K>): GroupView<K, E>;
-    map<F>(f: (e: E) => F): Read<readonly F[]>;
-    /** Remove `e` from the source. */
-    remove(e: E): void;
-}
-/** A writable source collection. */
-export declare class Coll<E> extends View<E> {
-    #private;
-    constructor(items: readonly E[], key: (e: E) => unknown);
-    assertContains(e: E): void;
-    insert(e: E, at?: number): void;
-    removeFromSource(e: E): void;
-}
-/** Sorted view. `move` writes the order field between the drop neighbours. */
-export declare class SortView<E> extends View<E> {
-    #private;
-    constructor(parent: View<E>, field: Accessor<E, number>);
-    move(e: E, to: number): void;
-}
-/** Grouped view. `move`/`insert` write the group field (and, with a `sort`
- *  field, the order field). Backward composition runs the parent chain. */
-export declare class GroupView<K, E> {
-    #private;
-    readonly groups: Read<readonly Group<K, E>[]>;
-    constructor(parent: View<E>, field: Accessor<E, K>, opts?: GroupOpts<E, K>);
-    get value(): readonly Group<K, E>[];
-    map<F>(f: (g: Group<K, E>) => F): Read<readonly F[]>;
-    /** Place `e` in group `toKey` at `index`. Inserts it into the source if
-     *  it isn't there yet, asserts every upstream filter, then writes the
-     *  group key and order field — all in one batch. */
-    move(e: E, toKey: K, index?: number): void;
-    insert(e: E, toKey: K, index?: number): void;
-    remove(e: E): void;
-}
-export declare function coll<E>(items: readonly E[], key: (e: E) => unknown): Coll<E>;