@zakkster/lite-project 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to `@zakkster/lite-project` are documented here. The format
+follows Keep a Changelog; this project adheres to semantic versioning.
+
+## [1.0.0] - 2026-06-25
+
+First stable release. Zero-GC projections for `@zakkster/lite-signal`.
+
+### Added
+
+- **`project(source)`** — a granular, derived, non-mutating draft overlay over
+  any keyed reactive source. Each touched key owns one overlay signal + one
+  projected computed, created lazily inside `createRoot` (so they outlive the
+  consumer that first reads the key) and recycled by `dispose()`.
+  - `get` / `set` / `clear` / `commit` / `revert`, plus `commit(key)` for a
+    partial (single-key) commit
+  - **reactive dirty state:** `dirtyCount()` / `isDirty()` are tracked (back an
+    "unsaved changes" badge or a Save button with no polling), backed by one
+    fixed signal per projection whose updates are allocation-free
+  - `isOverlaid` / `overlaidCount` / `peek` (untracked diagnostics)
+  - `forEachOverlay` (iterate overlaid keys) and `reconcileAll(policy?)`
+    (full-snapshot reconciliation)
+- **The three properties**, each test-covered: granular (overlaying A never
+  re-runs a consumer of B), derived (revert / source changes flow through), and
+  non-mutating with **masking** (a source change under an overlay is suppressed
+  by the engine's `Object.is` short-circuit — the optimistic value is stable
+  under source noise).
+- **`createProjector(reg)`** — bind the primitives to any lite-signal registry
+  (default namespace, or an isolated `createRegistry` graph).
+- **`keyedStore(initial?)`** — a minimal built-in keyed reactive source.
+- **Reconciliation:** `confirmOnEcho` (default echo policy) and
+  `makeReconciler(view, policy?)` (per-key event handler for sources with an
+  incoming-update channel).
+- **Source adapters:** `fromAccessors`, `fromProxy`.
+- **Library adapters:** `projectStore` (per-key-granular drafts over
+  `@zakkster/lite-store`, commit-writes-through) and `projectRoom`
+  (presentation-only optimistic drafts over a `@zakkster/lite-room` LWW-Map;
+  subscribes through the coarse `entries` signal and auto-reconciles, with
+  `commit()` promoting via `room.storage.set`).
+
+### Verified
+
+- Zero steady-state allocation: 200k overlay toggles on warmed keys leave
+  `poolGrowths` and `totalAllocations` flat. Documented non-claim: the first
+  touch of a new key allocates its slot + two pooled nodes.
+- 20 tests under `node:test` (core projection, integration helpers, and the
+  store / room adapters against faithful stand-ins of their documented surfaces).
+
+### Notes
+
+- Peer dependency `@zakkster/lite-signal` `^1.5.0` (requires `createRoot`).
+- Derived-shape lenses (`select` / `filter` / `map`) are planned for a future
+  minor on the same per-key-computed substrate.
+
+[1.0.0]: https://github.com/PeshoVurtoleta/lite-project/releases/tag/v1.0.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zahary Shinikchiev <shinikchiev@yahoo.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Project.d.ts

@@ -0,0 +1,187 @@
+// Type declarations for @zakkster/lite-project v1.0.0
+// Zero-GC projections for @zakkster/lite-signal.
+// (c) 2026 Zahary Shinikchiev <shinikchiev@yahoo.com> -- MIT
+
+/**
+ * A reactive keyed source a projection can wrap. Any object with a reactive
+ * `get(key)` and a `set(key, value)` qualifies (the built-in `keyedStore`, a
+ * lite-store proxy via `fromProxy`, a plain pair via `fromAccessors`, ...).
+ */
+export interface ProjectionSource<K extends PropertyKey = PropertyKey, V = unknown> {
+    /** Reactive read: tracks the cell backing `key`. */
+    get(key: K): V;
+    /** Write the underlying value for `key`. */
+    set(key: K, value: V): void;
+}
+
+/**
+ * Reconciliation policy. Given the current authoritative value, the staged
+ * overlay value, and the key, return `true` to DROP the overlay (it is
+ * "confirmed" -- the source has caught up), `false` to keep it (a conflict the
+ * view should keep masking). Defaults to {@link confirmOnEcho}.
+ */
+export type ReconcilePolicy<K extends PropertyKey = PropertyKey, V = unknown> =
+    (authoritative: V, overlayValue: V, key: K) => boolean;
+
+/**
+ * A projection handle: a granular, derived, non-mutating draft overlay over a
+ * keyed source. Each touched key owns one overlay signal + one projected
+ * computed, created lazily and recycled by {@link Projection.dispose}.
+ */
+export interface Projection<K extends PropertyKey = PropertyKey, V = unknown> {
+    /** Reactive: the overlay value if one is staged for `key`, else the source value. */
+    get(key: K): V;
+    /** Stage an EPHEMERAL overlay for `key`. The source is NOT mutated. */
+    set(key: K, value: V): void;
+    /** Drop one key's overlay (revert that key to the source). */
+    clear(key: K): void;
+    /** Untracked diagnostic: is `key` currently overlaid? */
+    isOverlaid(key: K): boolean;
+    /** Untracked diagnostic: number of currently-overlaid keys. */
+    overlaidCount(): number;
+    /**
+     * TRACKED reactive count of staged overlays. Read it inside an effect/computed
+     * to drive an "unsaved changes" badge or enable/disable Save without polling.
+     * (Backed by one fixed signal per projection; updates are allocation-free.)
+     */
+    dirtyCount(): number;
+    /** TRACKED reactive `dirtyCount() > 0`. */
+    isDirty(): boolean;
+    /** Untracked effective read (overlay if staged, else source) -- does not subscribe. */
+    peek(key: K): V;
+    /** Iterate currently-overlaid keys with their overlay values (untracked). */
+    forEachOverlay(fn: (key: K, value: V) => void): void;
+    /**
+     * Full-snapshot reconciliation: drop every overlay the policy considers
+     * confirmed against the current (untracked) source value. Presentation-only --
+     * the source owns the real write.
+     */
+    reconcileAll(policy?: ReconcilePolicy<K, V>): void;
+    /** Write staged overlays into the source, then clear them. With `key`, commits just that key. */
+    commit(key?: K): void;
+    /** Drop all overlays. */
+    revert(): void;
+    /** Recycle every projection-owned node back to the lite-signal pool. */
+    dispose(): void;
+}
+
+/**
+ * Minimal built-in keyed reactive source: one lazily-created signal per key.
+ * Provided so a projection has something to wrap out of the box; for richer
+ * needs use a lite-store proxy (via {@link fromProxy}) instead.
+ */
+export interface KeyedStore<K extends PropertyKey = PropertyKey, V = unknown> {
+    /** Reactive read (tracks `key`'s signal). `undefined` until set. */
+    get(key: K): V | undefined;
+    /** Write `key`'s signal (fires consumers through Object.is). */
+    set(key: K, value: V): void;
+    /** Untracked: has `key` ever been touched? */
+    has(key: K): boolean;
+    /** Untracked: iterator over touched keys. */
+    keys(): IterableIterator<K>;
+}
+
+/**
+ * The subset of a lite-signal registry the projector needs. Pass the default
+ * namespace, or a `createRegistry({...})` result for an isolated graph.
+ */
+export interface ProjectorRegistry {
+    signal(initial: unknown, opts?: unknown): unknown;
+    computed(fn: () => unknown, opts?: unknown): unknown;
+    createRoot<T>(fn: () => T): T;
+    dispose(handle: unknown): void;
+    untrack<T>(fn: () => T): T;
+}
+
+/** The registry-bound projection primitives returned by {@link createProjector}. */
+export interface Projector {
+    project<K extends PropertyKey = PropertyKey, V = unknown>(
+        source: ProjectionSource<K, V>,
+    ): Projection<K, V>;
+    keyedStore<K extends PropertyKey = PropertyKey, V = unknown>(
+        initial?: Record<PropertyKey, V>,
+    ): KeyedStore<K, V>;
+}
+
+/** Bind the projection primitives to a lite-signal registry. */
+export function createProjector(reg: ProjectorRegistry): Projector;
+
+/** Project a keyed source (default registry). */
+export function project<K extends PropertyKey = PropertyKey, V = unknown>(
+    source: ProjectionSource<K, V>,
+): Projection<K, V>;
+
+/** Minimal built-in keyed reactive source (default registry). */
+export function keyedStore<K extends PropertyKey = PropertyKey, V = unknown>(
+    initial?: Record<PropertyKey, V>,
+): KeyedStore<K, V>;
+
+/**
+ * Default reconciliation policy: an overlay is confirmed once the authoritative
+ * value equals the optimistic one (the source echoed it back). `Object.is`.
+ */
+export function confirmOnEcho(authoritative: unknown, overlayValue: unknown): boolean;
+
+/** Shape a plain accessor pair into a projection source. */
+export function fromAccessors<K extends PropertyKey = PropertyKey, V = unknown>(
+    get: (key: K) => V,
+    set: (key: K, value: V) => void,
+): ProjectionSource<K, V>;
+
+/**
+ * Shape a property-style reactive store (a Proxy, or a lite-store proxy) into a
+ * projection source. `obj[key]` must be a TRACKED read and `obj[key] = v` a write.
+ */
+export function fromProxy<V = unknown>(
+    obj: Record<PropertyKey, V>,
+): ProjectionSource<PropertyKey, V>;
+
+/**
+ * Per-key reconciler for an authoritative source with an incoming-update event
+ * (a CRDT room, a socket). Wire the returned handler to that event: when an
+ * update arrives for an overlaid key and `policy` confirms it, the overlay is
+ * dropped. Presentation-only -- the source owns the real write and merge.
+ */
+export function makeReconciler<K extends PropertyKey = PropertyKey, V = unknown>(
+    view: Pick<Projection<K, V>, "isOverlaid" | "peek" | "clear">,
+    policy?: ReconcilePolicy<K, V>,
+): (key: K, authoritativeValue: V) => void;
+
+// ---- library adapters --------------------------------------------------------
+
+/**
+ * Project a @zakkster/lite-store proxy as a DRAFT overlay. Inherits lite-store's
+ * per-key granularity; `commit()` writes drafts through to the store. Projects
+ * the top-level keys of the given proxy (pass a nested proxy to project deeper).
+ */
+export function projectStore<V = unknown>(
+    store: Record<PropertyKey, V>,
+): Projection<PropertyKey, V>;
+
+/** The subset of a @zakkster/lite-room handle that {@link projectRoom} consumes. */
+export interface RoomLike {
+    storage: {
+        get(key: string): unknown;
+        set(key: string, value: unknown): boolean | void;
+        /** The coarse `entries` change signal (read to subscribe). */
+        entries(): unknown;
+    };
+}
+
+/** Options for {@link projectRoom}. */
+export interface ProjectRoomOptions {
+    /** Reconciliation policy; defaults to {@link confirmOnEcho}. */
+    policy?: ReconcilePolicy<string, unknown>;
+}
+
+/**
+ * Project a @zakkster/lite-room's LWW-Map (`room.storage`) as a DRAFT layer for
+ * optimistic / tentative UI. `set` stages a local draft, `commit()` promotes it
+ * via `room.storage.set` (writes + syncs), and an auto-reconcile drops drafts the
+ * authoritative state catches up to while leaving conflicts masked. The returned
+ * handle's `dispose()` also stops the reconcile effect.
+ */
+export function projectRoom(
+    room: RoomLike,
+    opts?: ProjectRoomOptions,
+): Projection<string, unknown>;

package/Project.js

@@ -0,0 +1,419 @@
+/**
+ * @zakkster/lite-project v1.0.0 -- zero-GC projections for @zakkster/lite-signal.
+ * -----------------------------------------------------------------------------
+ * A projection is a granular, derived, NON-MUTATING reactive view over a keyed
+ * source: a lens that can carry ephemeral overlays (optimistic edits, merges,
+ * "pending" state) without touching the underlying data, then commit() those
+ * overlays into the source or revert() them. It is the "Beyond Signals"
+ * projection primitive, built on lite-signal's pool so the steady state allocates
+ * nothing the engine can avoid.
+ *
+ * -- THE THREE PROPERTIES --
+ *   granular     reading key K subscribes only to K's effective value; overlaying
+ *                key A never re-runs a consumer of key B (each projected key is its
+ *                own computed).
+ *   derived      get(key) is reactive: it tracks BOTH the overlay and the source
+ *                cell, so a revert (or a source change after a revert) flows through.
+ *   non-mutating set(key, v) writes an overlay ONLY; the source is untouched until
+ *                commit(). revert() drops the overlay layer entirely. While a key is
+ *                overlaid, a source change to that key is masked (the projected value
+ *                stays the overlay) and -- thanks to the engine's Object.is short-
+ *                circuit -- does NOT churn downstream consumers. The optimistic value
+ *                is stable under source noise.
+ *
+ * -- OWNERSHIP (why createRoot) --
+ * Per-key nodes are created LAZILY, on the first get/set of a key -- which happens
+ * inside whatever consumer effect first reads that key. Without detachment the
+ * projected computed would be ADOPTED by that consumer and cascade-disposed on its
+ * next re-run, silently breaking the projection. createRoot() detaches owner +
+ * observer for the creation, so the nodes are unowned and survive; the projection
+ * disposes them itself (dispose()). The overlay signal is safe regardless (plain
+ * signals are never adopted), but the computed needs the detached scope.
+ *
+ * -- ZERO-GC, AND THE HONEST NON-CLAIM --
+ * PASS: get / set / clear on an ALREADY-TOUCHED key allocate nothing -- a computed
+ *       read, or a Map.get + a signal write. Overlay churn over a bounded key set
+ *       (toggle pending on/off, the realistic optimistic-UI shape) pulls no node from
+ *       the pool and never grows it.
+ * NOT claimed: the FIRST touch of a brand-new key. It allocates a slot record + a Map
+ *       entry (JS handles) and two pooled nodes (overlay signal + projected computed).
+ *       The nodes come from the pool (poolGrowth 0 after warm-up); the slot/Map entry
+ *       are the public-handle cost, the same split @zakkster/lite-signal itself draws
+ *       between pooled internals and escaping handles. Warm the keys you will churn.
+ *
+ * Registry-parametric: createProjector(reg) binds to any registry (the default one,
+ * or a createRegistry({...}) for isolated tests). Default-bound `project` /
+ * `keyedStore` are exported for the common case.
+ *
+ * MIT (c) Zahary Shinikchiev
+ */
+
+import {
+    signal as _signal,
+    computed as _computed,
+    createRoot as _createRoot,
+    dispose as _dispose,
+    untrack as _untrack,
+    effect as _effect,
+    batch as _batch,
+} from "@zakkster/lite-signal";
+
+// Module-level sentinel for "this key has no overlay". A unique symbol, never a
+// per-operation allocation. Stored directly in the overlay signal's value slot, so
+// "absent" and "present with value V" share one node and one field -- no boxing.
+const ABSENT = Symbol("projection.absent");
+
+/**
+ * Bind the projection primitives to a registry. Pass the default-registry
+ * namespace for normal use, or a `createRegistry({...})` result for an isolated
+ * graph (tests, the zero-GC gate).
+ *
+ * @param {{signal:Function, computed:Function, createRoot:Function, dispose:Function}} reg
+ * @returns {{project:Function, keyedStore:Function}}
+ */
+export function createProjector(reg) {
+    const signal = reg.signal;
+    const computed = reg.computed;
+    const createRoot = reg.createRoot;
+    const dispose = reg.dispose;
+    const untrack = reg.untrack;
+    // commit / revert / reconcileAll write many signals in a loop; batch coalesces
+    // them (and the dirty-counter write) into ONE propagation so a multi-key
+    // consumer never observes a torn, partially-applied snapshot. Fallback keeps a
+    // minimal custom registry working (unbatched == synchronous, as before).
+    const batch = reg.batch || ((fn) => { fn(); });
+
+    /**
+     * Minimal keyed reactive source: one lazily-created signal per key. Provided so
+     * a projection has something to wrap out of the box; any object with reactive
+     * `get(key)` and `set(key, value)` works equally (e.g. lite-store).
+     *
+     * @param {Record<PropertyKey, unknown>} [initial] Optional seed entries.
+     * @returns {{get:(key:PropertyKey)=>unknown, set:(key:PropertyKey, v:unknown)=>void,
+     *           has:(key:PropertyKey)=>boolean, keys:()=>IterableIterator<PropertyKey>}}
+     */
+    function keyedStore(initial) {
+        const cells = new Map();
+        const cell = (key) => {
+            let c = cells.get(key);
+            if (c === undefined) { c = signal(undefined); cells.set(key, c); }
+            return c;
+        };
+        if (initial !== undefined) for (const k in initial) cell(k).set(initial[k]);
+        return {
+            get: (key) => cell(key)(),
+            set: (key, v) => cell(key).set(v),
+            has: (key) => cells.has(key),
+            keys: () => cells.keys(),
+        };
+    }
+
+    /**
+     * Project a keyed source. The returned handle reads through an ephemeral overlay
+     * and can commit / revert it.
+     *
+     * @param {{get:(key:PropertyKey)=>unknown, set:(key:PropertyKey, v:unknown)=>void}} source
+     * @returns {{
+     *   get:(key:PropertyKey)=>unknown,         // reactive: overlay value if set, else source
+     *   set:(key:PropertyKey, v:unknown)=>void,  // stage an EPHEMERAL overlay (source untouched)
+     *   clear:(key:PropertyKey)=>void,           // drop one key's overlay (revert that key)
+     *   isOverlaid:(key:PropertyKey)=>boolean,   // untracked diagnostic
+     *   overlaidCount:()=>number,                // untracked diagnostic
+     *   dirtyCount:()=>number,                   // TRACKED: count of staged overlays (reactive)
+     *   isDirty:()=>boolean,                     // TRACKED: any staged overlays? (reactive)
+     *   peek:(key:PropertyKey)=>unknown,         // untracked effective read (no subscribe)
+     *   forEachOverlay:(fn:(key:PropertyKey, value:unknown)=>void)=>void, // iterate overlaid keys (untracked)
+     *   reconcileAll:(policy?:(authoritative:unknown, overlayValue:unknown, key:PropertyKey)=>boolean)=>void, // drop confirmed overlays
+     *   commit:(key?:PropertyKey)=>void,         // write one key's overlay, or all, into the source then clear
+     *   revert:()=>void,                         // drop all overlays
+     *   dispose:()=>void,                        // recycle every projection-owned node to the pool
+     * }}
+     */
+    function project(source) {
+        // key -> { ov: overlay signal (ABSENT | value), read: projected computed }.
+        // Lazily populated. One entry per touched key, retained until dispose().
+        const slots = new Map();
+
+        const slotFor = (key) => {
+            let s = slots.get(key);
+            if (s === undefined) {
+                // Detach owner+observer for creation: these nodes outlive the consumer
+                // that first reads `key`, and the projection -- not that consumer --
+                // owns their disposal. (See header: OWNERSHIP.)
+                s = createRoot(() => {
+                    const ov = signal(ABSENT);
+                    const read = computed(() => {
+                        const o = ov();              // track the overlay
+                        const base = source.get(key); // track the source cell too
+                        return o === ABSENT ? base : o;
+                    });
+                    return { ov, read };
+                });
+                slots.set(key, s);
+            }
+            return s;
+        };
+
+        // Reactive dirty state. ONE fixed signal per projection (created detached so
+        // dispose() owns its teardown, like the per-key nodes). `dirty` is the
+        // source-of-truth count of staged overlays, mirrored into the signal on every
+        // presence transition (absent<->value). Bumping it allocates nothing -- a
+        // number set, marking subscribers without allocation -- so the zero-GC churn
+        // property holds even with a Save button subscribed to isDirty().
+        const dirtySig = createRoot(() => signal(0));
+        let dirty = 0;
+
+        return {
+            get: (key) => slotFor(key).read(),
+            set: (key, v) => {
+                const s = slotFor(key);
+                const wasAbsent = s.ov.peek() === ABSENT;
+                s.ov.set(v);
+                if (wasAbsent) { dirty++; dirtySig.set(dirty); }
+            },
+            clear: (key) => {
+                const s = slots.get(key);
+                if (s !== undefined && s.ov.peek() !== ABSENT) {
+                    s.ov.set(ABSENT);
+                    dirty--; dirtySig.set(dirty);
+                }
+            },
+            isOverlaid: (key) => {
+                const s = slots.get(key);
+                return s !== undefined && s.ov.peek() !== ABSENT;
+            },
+            // Reactive dirty state (tracked) -- for "unsaved changes" badges and
+            // enabling/disabling Save without polling. isOverlaid / overlaidCount above
+            // stay UNTRACKED for diagnostic reads that must not subscribe.
+            dirtyCount: () => dirtySig(),
+            isDirty: () => dirtySig() > 0,
+            // Untracked effective read (overlay if set, else source) -- for
+            // reconciliation policies and imperative inspection, without subscribing.
+            peek: (key) => {
+                const s = slots.get(key);
+                if (s === undefined) return untrack(() => source.get(key));
+                const o = s.ov.peek();
+                return o === ABSENT ? untrack(() => source.get(key)) : o;
+            },
+            // Iterate currently-overlaid keys (untracked). Cold path.
+            forEachOverlay: (fn) => {
+                for (const [key, s] of slots) {
+                    const o = s.ov.peek();
+                    if (o !== ABSENT) fn(key, o);
+                }
+            },
+            // Full-snapshot reconciliation: drop every overlay the policy considers
+            // confirmed against the CURRENT (untracked) source value. For sources that
+            // sync wholesale rather than per-key. Presentation-only -- the source owns
+            // the real write; this only decides what the local view stops overriding.
+            reconcileAll: (policy) => {
+                const pol = policy || confirmOnEcho;
+                batch(() => {
+                    let dropped = 0;
+                    for (const [key, s] of slots) {
+                        const o = s.ov.peek();
+                        if (o !== ABSENT) {
+                            const authoritative = untrack(() => source.get(key));
+                            if (pol(authoritative, o, key)) { s.ov.set(ABSENT); dropped++; }
+                        }
+                    }
+                    if (dropped) { dirty -= dropped; dirtySig.set(dirty); }
+                });
+            },
+            overlaidCount: () => {
+                let n = 0;
+                for (const s of slots.values()) if (s.ov.peek() !== ABSENT) n++;
+                return n;
+            },
+            commit: (key) => {
+                // Cold path (a user "save"): may iterate + write the source freely.
+                // commit(key) writes one overlay; commit() writes all. (Keys are
+                // PropertyKey, never undefined, so `key === undefined` means "all".)
+                batch(() => {
+                    if (key !== undefined) {
+                        const s = slots.get(key);
+                        if (s !== undefined) {
+                            const o = s.ov.peek();
+                            if (o !== ABSENT) {
+                                source.set(key, o); s.ov.set(ABSENT);
+                                dirty--; dirtySig.set(dirty);
+                            }
+                        }
+                        return;
+                    }
+                    let changed = false;
+                    for (const [k, s] of slots) {
+                        const o = s.ov.peek();
+                        if (o !== ABSENT) { source.set(k, o); s.ov.set(ABSENT); changed = true; }
+                    }
+                    if (changed) { dirty = 0; dirtySig.set(0); }
+                });
+            },
+            revert: () => {
+                batch(() => {
+                    let changed = false;
+                    for (const s of slots.values()) {
+                        if (s.ov.peek() !== ABSENT) { s.ov.set(ABSENT); changed = true; }
+                    }
+                    if (changed) { dirty = 0; dirtySig.set(0); }
+                });
+            },
+            dispose: () => {
+                // createRoot left these unowned, so nothing auto-disposes them.
+                // Dispose the computed before its overlay so the read never re-evaluates
+                // against a recycled signal.
+                for (const s of slots.values()) { dispose(s.read); dispose(s.ov); }
+                dispose(dirtySig);
+                slots.clear();
+                dirty = 0;
+            },
+        };
+    }
+
+    return { project, keyedStore };
+}
+
+// Default-registry convenience: project / keyedStore bound to the default registry,
+// for the common single-registry case.
+const _default = createProjector({
+    signal: _signal,
+    computed: _computed,
+    createRoot: _createRoot,
+    dispose: _dispose,
+    untrack: _untrack,
+    batch: _batch,
+});
+
+export const project = _default.project;
+export const keyedStore = _default.keyedStore;
+
+// ---- integration helpers (registry-independent) ------------------------------
+
+/**
+ * Default reconciliation policy: an overlay is confirmed once the authoritative
+ * value equals the optimistic one (the source echoed it back). Object.is.
+ *
+ * @param {unknown} authoritative The value the source now holds.
+ * @param {unknown} overlayValue  The optimistic value staged in the projection.
+ * @returns {boolean}             true => drop the overlay.
+ */
+export function confirmOnEcho(authoritative, overlayValue) {
+    return Object.is(authoritative, overlayValue);
+}
+
+/**
+ * Shape a plain accessor pair into a projection source.
+ * @param {(key:PropertyKey)=>unknown} get  Reactive read.
+ * @param {(key:PropertyKey, v:unknown)=>void} set Write.
+ */
+export function fromAccessors(get, set) { return { get, set }; }
+
+/**
+ * Shape a property-style reactive store (e.g. a proxy, or lite-store's proxy
+ * surface) into a projection source. `obj[key]` must be a TRACKED read and
+ * `obj[key] = v` a write.
+ * @param {object} obj
+ */
+export function fromProxy(obj) {
+    return { get: (k) => obj[k], set: (k, v) => { obj[k] = v; } };
+}
+
+/**
+ * Per-key reconciler for an authoritative source that emits incoming-update
+ * events (a CRDT room, a socket). Wire the returned handler to that event: when
+ * an update arrives for an overlaid key and `policy` considers it confirmed, the
+ * optimistic overlay is dropped. Presentation-only -- the source / CRDT owns the
+ * real write and the merge; this only decides when the local view stops overriding.
+ *
+ * @example
+ *   const onUpdate = makeReconciler(view);          // echo policy
+ *   room.onUpdate(onUpdate);                          // room fires (key, authoritativeValue)
+ *
+ * @param {{isOverlaid:Function, peek:Function, clear:Function}} view A project() handle.
+ * @param {(authoritative:unknown, overlayValue:unknown, key:PropertyKey)=>boolean} [policy]
+ * @returns {(key:PropertyKey, authoritativeValue:unknown)=>void}
+ */
+export function makeReconciler(view, policy) {
+    const pol = policy || confirmOnEcho;
+    return (key, authoritativeValue) => {
+        if (view.isOverlaid(key) && pol(authoritativeValue, view.peek(key), key)) view.clear(key);
+    };
+}
+
+// ---- library adapters (default registry) -------------------------------------
+// lite-store and lite-room both bind the default lite-signal registry, so these
+// adapters use the default-bound `project` and `_effect`. They are written
+// against the published surfaces of @zakkster/lite-store v1.0.0 and
+// @zakkster/lite-room.
+
+/**
+ * Project a @zakkster/lite-store proxy as a DRAFT overlay. lite-store gives
+ * per-key signals (a property becomes reactive the first time it is read in a
+ * reactive scope), so the projection inherits that granularity: overlaying or
+ * committing one key only re-runs consumers of that key.
+ *
+ *   - set(key, value)  stage a draft (the store is NOT mutated)
+ *   - commit()         write drafts through (`store[key] = draft`), firing the
+ *                      store's per-key signals
+ *   - revert()         discard all drafts
+ *   - clear(key)       discard one draft
+ *
+ * Projects the TOP-LEVEL keys of the given proxy. To project a nested object,
+ * pass the nested proxy: `projectStore(s.user)` (lite-store hands out a child
+ * proxy on property access, and that child has its own per-key signals).
+ *
+ * @param {object} store A lite-store proxy from `store(...)`.
+ * @returns {object} A projection handle (get/set/clear/commit/revert/isOverlaid/peek/...).
+ */
+export function projectStore(store) {
+    return project(fromProxy(store));
+}
+
+/**
+ * Project a @zakkster/lite-room's LWW-Map (`room.storage`) as a DRAFT layer for
+ * optimistic / tentative UI. Room storage is authoritative and CRDT-merged, so
+ * the projection never participates in the merge -- it only decides what the
+ * local view tentatively overrides:
+ *
+ *   - set(key, value)  stage a draft -- local only, NOT synced, CRDT untouched
+ *   - commit()         promote drafts via `room.storage.set` (writes + syncs)
+ *   - revert()         discard drafts
+ *   - auto-reconcile   whenever authoritative storage changes, drafts the policy
+ *                      considers confirmed are dropped; a CONFLICTING
+ *                      authoritative value leaves the draft masked (the engine's
+ *                      Object.is short-circuit suppresses the flicker)
+ *
+ * room.storage is COARSE -- a single `entries` signal fires on any change and
+ * `get(key)` is a plain (non-reactive) Map read -- so the source adapter
+ * subscribes through `entries()` before reading, and the projection inherits
+ * that coarse granularity (any storage change re-evaluates every projected key).
+ * Per-key room signals would refine both layers at once. Only `room.storage` is
+ * projectable this way; sets / lists / texts have non-keyed shapes.
+ *
+ * @param {object} room A room handle from `createRoom(...)`.
+ * @param {{policy?: (authoritative:unknown, draft:unknown, key:PropertyKey)=>boolean}} [opts]
+ *        Reconciliation policy; defaults to confirmOnEcho (drop when authoritative === draft).
+ * @returns {object} A projection handle whose dispose() also stops the reconcile effect.
+ */
+export function projectRoom(room, opts) {
+    const policy = (opts && opts.policy) || confirmOnEcho;
+    const source = {
+        // Subscribe to the coarse `entries` signal so the projected read reacts
+        // to any authoritative change, then return the current value for `key`.
+        get: (key) => { room.storage.entries(); return room.storage.get(key); },
+        set: (key, value) => room.storage.set(key, value),
+    };
+    const view = project(source);
+    // Drop confirmed drafts whenever authoritative state changes. The effect
+    // tracks `entries` (not overlays/projected computeds), so view.clear() inside
+    // reconcileAll never re-triggers it -> no loop. reconcileAll reads the source
+    // untracked, so it adds no dependency.
+    const stopReconcile = _effect(() => {
+        room.storage.entries();
+        view.reconcileAll(policy);
+    });
+    return {
+        ...view,
+        dispose: () => { stopReconcile(); view.dispose(); },
+    };
+}

package/README.md

@@ -0,0 +1,162 @@
+# @zakkster/lite-project
+
+[![npm version](https://img.shields.io/npm/v/@zakkster/lite-project.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-project)
+![Zero-GC](https://img.shields.io/badge/Zero--GC-Hot%20path-00C853?style=for-the-badge&logo=leaf&logoColor=white)
+[![sponsor](https://img.shields.io/badge/sponsor-PeshoVurtoleta-ea4aaa.svg?logo=github)](https://github.com/sponsors/PeshoVurtoleta)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-project?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-project)
+[![npm downloads](https://img.shields.io/npm/dm/@zakkster/lite-project?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-project)
+[![npm total downloads](https://img.shields.io/npm/dt/@zakkster/lite-project?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-project)
+[![lite-signal peer](https://img.shields.io/badge/peer-lite--signal-blue?style=for-the-badge)](https://github.com/PeshoVurtoleta/lite-signal)
+![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+
+**Zero-GC projections for [@zakkster/lite-signal](https://www.npmjs.com/package/@zakkster/lite-signal).**
+
+A *projection* is a granular, derived, **non-mutating** reactive view over a keyed source — a lens that carries ephemeral overlays (optimistic edits, drafts, "pending" state) without touching the underlying data, then `commit()`s those overlays into the source or `revert()`s them. It is the "Beyond Signals" projection primitive, built on lite-signal's node pool so the steady state allocates nothing the engine can avoid.
+
+```mermaid
+flowchart LR
+  subgraph per-key
+    O["overlay signal<br/>(ABSENT | value)"]
+    S["source cell"]
+    P{{"projected computed<br/>overlay ?? source"}}
+    O -- tracked --> P
+    S -- tracked --> P
+  end
+  P --> C["consumer<br/>(effect / UI)"]
+  C -. "set(key, v)" .-> O
+  O -. "commit()" .-> S
+  S -. "clear() / reconcile" .-> O
+```
+
+Each touched key owns **one overlay signal + one projected computed**. Reading a key tracks its effective value (overlay if staged, else source); overlaying key `A` never re-runs a consumer of key `B`.
+
+---
+
+## Install
+
+```sh
+npm i @zakkster/lite-project
+```
+
+Peer dependency: `@zakkster/lite-signal` `^1.5.0` (the projection relies on `createRoot`, which landed in 1.5.0).
+
+## Quick start
+
+```js
+import { project, keyedStore } from "@zakkster/lite-project";
+import { effect } from "@zakkster/lite-signal";
+
+const store = keyedStore({ title: "untitled" });   // any reactive get/set source
+const draft = project(store);
+
+effect(() => console.log("showing:", draft.get("title")));   // "untitled"
+
+draft.set("title", "Draft name");   // optimistic: prints "Draft name"
+store.get("title");                 // still "untitled" -- source untouched
+
+draft.commit();                     // writes the overlay into the store
+draft.isOverlaid("title");          // false
+```
+
+## The three properties
+
+- **granular** — reading key `K` subscribes only to `K`'s effective value (each projected key is its own computed). Overlaying one key never re-runs another key's consumer.
+- **derived** — `get(key)` is reactive: it tracks **both** the overlay and the source cell, so a `revert()` (or a source change after a revert) flows through.
+- **non-mutating** — `set(key, v)` writes an overlay **only**; the source is untouched until `commit()`. While a key is overlaid, a source change to it is *masked* (the projected value stays the overlay) and, thanks to the engine's `Object.is` short-circuit, does **not** churn downstream consumers. The optimistic value is stable under source noise — no flicker.
+
+## Reactive dirty state
+
+`dirtyCount()` and `isDirty()` are **tracked** — read them in an effect/computed to drive an "unsaved changes" badge or a Save button with no polling. (`isOverlaid` / `overlaidCount` stay untracked for diagnostic reads that must not subscribe.)
+
+```js
+effect(() => { saveButton.disabled = !draft.isDirty(); });   // re-runs only on clean<->dirty flips
+
+draft.set("title", "x");   // -> isDirty() true, button enabled
+draft.commit("title");     // commit just one field; -> back to clean
+```
+
+Updating the dirty count is allocation-free (a single fixed signal per projection, bumped on each presence transition), so the zero-GC property holds even with the Save effect subscribed.
+
+## Zero-GC
+
+In steady state the projection allocates nothing: toggling an overlay on a key you have already touched reuses its pooled nodes (verified — 200k overlay toggles on warmed keys leave `poolGrowths` and `totalAllocations` flat). The honest non-claim: the *first* touch of a **new** key allocates a slot record, a Map entry, and two pooled nodes (one overlay signal, one projected computed). Warm the keys you churn.
+
+## API
+
+### `createProjector(reg) -> { project, keyedStore }`
+
+Bind the primitives to a lite-signal registry. Pass the default namespace for normal use, or a `createRegistry({...})` result for an isolated graph (tests, the zero-GC gate). The package also exports `project` and `keyedStore` pre-bound to the default registry for the common case.
+
+### `project(source) -> Projection`
+
+`source` is any object with a reactive `get(key)` and a `set(key, value)`. Returns a handle:
+
+| method | description |
+| --- | --- |
+| `get(key)` | reactive: overlay value if staged, else the source value |
+| `set(key, value)` | stage an **ephemeral** overlay (source untouched) |
+| `clear(key)` | drop one key's overlay (revert that key) |
+| `commit(key?)` | write one key's overlay (or, with no arg, all) into the source, then clear |
+| `revert()` | drop all overlays |
+| `dirtyCount()` | **tracked / reactive**: count of staged overlays — wire a Save badge to it |
+| `isDirty()` | **tracked / reactive**: `dirtyCount() > 0` |
+| `isOverlaid(key)` | untracked diagnostic: is the key overlaid? |
+| `overlaidCount()` | untracked diagnostic: number of overlaid keys |
+| `peek(key)` | untracked effective read (no subscribe) |
+| `forEachOverlay(fn)` | iterate overlaid keys + values (untracked) |
+| `reconcileAll(policy?)` | drop overlays the policy confirms against the current source |
+| `dispose()` | recycle every projection-owned node back to the pool |
+
+### `keyedStore(initial?) -> { get, set, has, keys }`
+
+A minimal built-in keyed reactive source: one lazily-created signal per key. Handy when you do not need a full lite-store.
+
+### Reconciliation helpers
+
+- `confirmOnEcho(authoritative, overlay)` — default policy: confirmed once `Object.is(authoritative, overlay)` (the source echoed the optimistic value back).
+- `makeReconciler(view, policy?)` — returns a per-key handler `(key, authoritativeValue) => void` for a source that emits incoming-update events. When an update arrives for an overlaid key and the policy confirms it, the overlay is dropped.
+
+### Source adapters
+
+- `fromAccessors(get, set)` — shape a plain accessor pair into a source.
+- `fromProxy(obj)` — shape a property-style reactive store (a Proxy, a lite-store proxy) into a source; `obj[key]` must be a tracked read.
+
+## Library adapters
+
+### `projectStore(store)` — drafts over [lite-store](https://www.npmjs.com/package/@zakkster/lite-store)
+
+```js
+import { projectStore } from "@zakkster/lite-project";
+import { store } from "@zakkster/lite-store";
+
+const s = store({ name: "alice", age: 30 });
+const draft = projectStore(s);
+
+draft.set("name", "bob");   // draft only; s.name is still "alice"
+draft.commit();             // s.name === "bob"
+```
+
+lite-store gives per-key signals, so the projection stays granular: overlaying or committing one key only re-runs that key's consumers. Projects the **top-level** keys of the given proxy — pass a nested proxy (`projectStore(s.user)`) to project deeper.
+
+### `projectRoom(room, { policy })` — optimistic drafts over [lite-room](https://www.npmjs.com/package/@zakkster/lite-room)
+
+```js
+import { projectRoom } from "@zakkster/lite-project";
+
+const draft = projectRoom(room);   // over room.storage (LWW-Map)
+
+draft.set("cell:A1", "=SUM(B:B)"); // local optimistic edit, NOT synced
+draft.commit();                    // promotes via room.storage.set (writes + syncs to peers)
+```
+
+Room storage is authoritative and CRDT-merged, so the projection is **presentation-only**: it never joins the merge. `set` stages a local draft, `commit()` promotes it through `room.storage.set`, and an auto-reconcile drops drafts once the authoritative value catches up (echo) while leaving a conflicting authoritative value **masked** (no flicker). Because `room.storage` is coarse (a single `entries` signal, a plain non-reactive `get`), the adapter subscribes through `entries()` and the projection inherits that coarse granularity. Call `dispose()` to stop the reconcile effect. Only `room.storage` is projectable this way; sets / lists / texts have non-keyed shapes.
+
+## Conventions
+
+ESM only. ASCII source. `node:test`. MIT.
+
+## License
+
+MIT (c) 2026 Zahary Shinikchiev

package/llms.txt

@@ -0,0 +1,74 @@
+# @zakkster/lite-project
+
+> Zero-GC projections for @zakkster/lite-signal: granular, derived, non-mutating
+> reactive overlays over a keyed source, with commit / revert / reconcile, plus
+> draft adapters for lite-store and lite-room.
+
+A projection is a lens over a keyed reactive source. It carries EPHEMERAL
+overlays (optimistic edits, drafts, pending state) without mutating the source,
+then commit()s them in or revert()s them out. Each touched key gets its own
+overlay signal + projected computed, so the view is granular and the steady
+state allocates nothing the engine can avoid.
+
+Peer dependency: @zakkster/lite-signal ^1.5.0 (uses createRoot). ESM only. MIT.
+
+## Mental model
+
+- overlay signal per key: ABSENT sentinel | value.
+- projected computed per key: reads overlay if set, else source.get(key); tracks BOTH.
+- get(key) is reactive. set(key,v) writes the OVERLAY only (source untouched).
+- commit() writes overlays into source then clears. revert() drops all overlays.
+- masking: while a key is overlaid, a source change to it is suppressed by the
+  engine's Object.is short-circuit -> the optimistic value is stable, no flicker.
+
+## Entry points
+
+- createProjector(reg) -> { project, keyedStore }   // bind to any lite-signal registry
+- project(source) -> Projection                       // default registry
+- keyedStore(initial?) -> { get, set, has, keys }     // minimal built-in source
+
+## Projection handle
+
+get(key) | set(key,value) | clear(key) | commit(key?) [one key or all] | revert() |
+dirtyCount() [TRACKED reactive] | isDirty() [TRACKED reactive] |
+isOverlaid(key) | overlaidCount() | peek(key) [untracked effective read] |
+forEachOverlay(fn) | reconcileAll(policy?) | dispose() [recycle all owned nodes]
+
+## Source = any { get(key): reactive, set(key, value) }
+
+- fromAccessors(get, set) -> source
+- fromProxy(obj) -> source            // obj[key] tracked read, obj[key]=v write
+
+## Reconciliation
+
+- confirmOnEcho(authoritative, overlay) -> Object.is(...)   // default policy
+- makeReconciler(view, policy?) -> (key, authoritativeValue) => void
+  // per-key handler for a source with an incoming-update event; drops the
+  // overlay when the policy confirms it. Conflicts stay masked.
+
+## Library adapters
+
+- projectStore(store)            // lite-store proxy. Per-key granular drafts;
+                                 // commit() writes through store[key]=v.
+                                 // Top-level keys; pass a nested proxy to go deeper.
+- projectRoom(room, {policy?})   // lite-room room.storage (LWW-Map).
+                                 // Presentation-only optimistic drafts: set = local
+                                 // draft (not synced), commit() = room.storage.set
+                                 // (writes + syncs), auto-reconcile drops confirmed
+                                 // drafts via the coarse `entries` signal; conflicts
+                                 // stay masked. dispose() stops the reconcile effect.
+                                 // CRDT owns the merge; the projection never joins it.
+
+## Zero-GC
+
+Steady state: re-overlaying a warmed key reuses pooled nodes (200k toggles ->
+poolGrowths/totalAllocations flat). First touch of a NEW key allocates its slot,
+a Map entry, and two pooled nodes. Warm the keys you churn.
+
+## Gotchas
+
+- createRoot is REQUIRED (1.5.0+): per-key nodes are created lazily inside the
+  consumer that first reads the key; without detachment they would be adopted by
+  that consumer and cascade-disposed on its next re-run. createRoot detaches them.
+- A projection only refines what the source exposes: over lite-room's coarse
+  storage it is coarse (any storage change re-evaluates every projected key).

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@zakkster/lite-project",
+  "version": "1.0.0",
+  "description": "Zero-GC projections for @zakkster/lite-signal: granular, derived, non-mutating reactive overlays with commit / revert / reconcile, and draft adapters for lite-store and lite-room.",
+  "type": "module",
+  "main": "./Project.js",
+  "module": "./Project.js",
+  "types": "./Project.d.ts",
+  "exports": {
+    ".": {
+      "node": "./Project.js",
+      "types": "./Project.d.ts",
+      "import": "./Project.js",
+      "default": "./Project.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "Project.js",
+    "Project.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "llms.txt",
+    "LICENSE.txt"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "peerDependencies": {
+    "@zakkster/lite-signal": ">=1.5.0-alpha"
+  },
+  "keywords": [
+    "reactive",
+    "signals",
+    "projection",
+    "lens",
+    "optimistic-ui",
+    "overlay",
+    "zero-gc",
+    "esm",
+    "lite-signal"
+  ],
+  "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeshoVurtoleta/lite-project.git"
+  },
+  "homepage": "https://github.com/PeshoVurtoleta/lite-project#readme",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/PeshoVurtoleta"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}