@treenity/react 3.0.0

package/src/bind/engine.ts

@@ -0,0 +1,198 @@
+// Binding engine — scans cache for $ref+$map fields, subscribes to sources,
+// evaluates on change, writes to computed store.
+// Supports $ref: "." (self) and @/path.field ref args in $map expressions.
+
+import * as cache from '#cache';
+import { trpc } from '#trpc';
+import { isRef, type NodeData, type Ref } from '@treenity/core/core';
+import { clearComputed, getComputed, setComputed } from './computed';
+import { evaluateRef, extractArgPaths, hasOnce, isCollectionRef } from './eval';
+
+type Unsub = () => void;
+
+// Active bindings: targetPath → field → { ref, unsub }
+const active = new Map<string, Map<string, { ref: Ref; unsub: Unsub }>>();
+
+// Collection paths with active SSE watches
+const watchedCollections = new Set<string>();
+// Single-node paths already fetched
+const fetchedNodes = new Set<string>();
+
+const ctx = {
+  getNode: (p: string) => cache.get(p),
+  getChildren: (p: string) => cache.getChildren(p),
+};
+
+/** Fetch collection children from server into cache */
+function fetchChildren(path: string): void {
+  trpc.getChildren
+    .query({ path, watch: true, watchNew: true })
+    .then((r: any) => cache.putMany(r.items as NodeData[], path));
+}
+
+/** Ensure source data is in cache by fetching from server */
+function ensureInCache(path: string, collection: boolean): void {
+  if (collection) {
+    if (!watchedCollections.has(path)) {
+      watchedCollections.add(path);
+      fetchChildren(path);
+    }
+  } else {
+    if (fetchedNodes.has(path)) return;
+    fetchedNodes.add(path);
+    trpc.get.query({ path }).then((n: any) => {
+      if (n) cache.put(n as NodeData);
+    });
+  }
+}
+
+function evaluate(targetPath: string, field: string, ref: Ref): void {
+  // Resolve $ref: "." → actual target path before eval
+  const resolved = ref.$ref === '.' ? { ...ref, $ref: targetPath } : ref;
+  try {
+    const value = evaluateRef(resolved, ctx);
+    setComputed(targetPath, field, value);
+  } catch (e) {
+    console.warn(`[bind] eval error ${targetPath}.${field}:`, e);
+  }
+}
+
+function registerBinding(targetPath: string, field: string, ref: Ref): void {
+  const once = hasOnce(ref);
+  const unsubs: Unsub[] = [];
+  const cb = () => evaluate(targetPath, field, ref);
+
+  const mainPath = ref.$ref === '.' ? targetPath : ref.$ref;
+  const collection = isCollectionRef(ref);
+
+  if (mainPath !== targetPath) {
+    ensureInCache(mainPath, collection);
+  }
+
+  // `once` — evaluate once, no reactive subscription
+  if (!once) {
+    unsubs.push(
+      collection
+        ? cache.subscribeChildren(mainPath, cb)
+        : cache.subscribePath(mainPath, cb),
+    );
+
+    for (const argPath of extractArgPaths(ref)) {
+      unsubs.push(cache.subscribePath(argPath, cb));
+      ensureInCache(argPath, false);
+    }
+  }
+
+  if (!active.has(targetPath)) active.set(targetPath, new Map());
+  active.get(targetPath)!.set(field, { ref, unsub: () => unsubs.forEach(u => u()) });
+
+  evaluate(targetPath, field, ref);
+}
+
+function unregisterAll(targetPath: string): void {
+  const bindings = active.get(targetPath);
+  if (!bindings) return;
+  for (const { unsub } of bindings.values()) unsub();
+  active.delete(targetPath);
+  clearComputed(targetPath);
+}
+
+/** Scan a single node for $ref+$map fields, register/update bindings */
+function scanNode(node: NodeData): void {
+  const path = node.$path;
+  const newRefs = new Map<string, Ref>();
+
+  // Scan node-level fields
+  for (const [key, value] of Object.entries(node)) {
+    if (key.startsWith('$')) continue;
+    if (isRef(value) && value.$map) {
+      newRefs.set(key, value as Ref);
+    }
+    // Scan sub-component fields
+    if (typeof value === 'object' && value !== null && '$type' in value) {
+      for (const [subKey, subVal] of Object.entries(value)) {
+        if (subKey.startsWith('$')) continue;
+        if (isRef(subVal) && (subVal as Ref).$map) {
+          newRefs.set(`${key}.${subKey}`, subVal as Ref);
+        }
+      }
+    }
+  }
+
+  const existing = active.get(path);
+
+  // No bindings before or after — nothing to do
+  if (!existing && newRefs.size === 0) return;
+
+  // Remove stale bindings
+  if (existing) {
+    for (const [field, { unsub }] of existing) {
+      if (!newRefs.has(field)) {
+        unsub();
+        existing.delete(field);
+      }
+    }
+    if (existing.size === 0 && newRefs.size === 0) {
+      active.delete(path);
+      clearComputed(path);
+      return;
+    }
+  }
+
+  // Register new/updated bindings
+  for (const [field, ref] of newRefs) {
+    const prev = existing?.get(field);
+    // Skip if same expression
+    if (prev && prev.ref.$ref === ref.$ref && prev.ref.$map === ref.$map) continue;
+    // Unregister old
+    if (prev) prev.unsub();
+    registerBinding(path, field, ref);
+  }
+}
+
+function handleRemove(path: string): void {
+  unregisterAll(path);
+}
+
+/** Start the binding engine. Returns cleanup function. */
+export function startBindEngine(): () => void {
+  // 1. Scan all existing nodes in cache
+  for (const [, node] of cache.raw()) {
+    scanNode(node);
+  }
+
+  // 2. Reactive: scan each node as it arrives/changes — instant, no polling
+  const unsubPut = cache.onNodePut((path) => {
+    const node = cache.get(path);
+    if (node) scanNode(node);
+  });
+
+  // 3. Detect removed nodes — clean up stale bindings
+  const unsubGlobal = cache.subscribeGlobal(() => {
+    for (const path of active.keys()) {
+      if (!cache.get(path)) handleRemove(path);
+    }
+  });
+
+  // Dev debug — inspect binding engine state from console
+  if (typeof window !== 'undefined') {
+    (window as any).__bind = {
+      active: () => Object.fromEntries([...active].map(([k, v]) => [k, [...v.keys()]])),
+      watched: () => [...watchedCollections],
+      fetched: () => [...fetchedNodes],
+      computed: () => {
+        const result: Record<string, unknown> = {};
+        for (const p of active.keys()) result[p] = getComputed(p);
+        return result;
+      },
+    };
+  }
+
+  return () => {
+    unsubPut();
+    unsubGlobal();
+    for (const path of [...active.keys()]) unregisterAll(path);
+    watchedCollections.clear();
+    fetchedNodes.clear();
+  };
+}

package/src/bind/eval.ts

@@ -0,0 +1,108 @@
+// $ref + $map evaluator
+// Resolves source from $ref, applies $map pipeline
+// #field (self) and #/path.field (external) args resolved from context
+
+import type { NodeData, Ref } from '@treenity/core/core';
+import { isRefArg, type MapExpr, parseMapExpr, type PipeArg } from './parse';
+import { getPipe } from './pipes';
+
+export type BindCtx = {
+  getNode: (path: string) => NodeData | undefined;
+  getChildren: (path: string) => NodeData[];
+};
+
+// Collection pipe names — when first step is one of these, resolve source as children
+const COLLECTION_PIPES = new Set(['last', 'first', 'count', 'avg', 'max', 'min', 'sum', 'map']);
+
+// Parsed expression cache
+const exprCache = new Map<string, MapExpr>();
+
+function getCachedExpr(map: string): MapExpr {
+  let expr = exprCache.get(map);
+  if (!expr) {
+    expr = parseMapExpr(map);
+    exprCache.set(map, expr);
+  }
+  return expr;
+}
+
+/** Resolve a pipe argument — ref args looked up from context, scalars pass through */
+function resolveArg(arg: PipeArg, ctx: BindCtx, refPath: string): unknown {
+  if (!isRefArg(arg)) return arg;
+  const path = arg.$ref === '.' ? refPath : arg.$ref;
+  let val: unknown = ctx.getNode(path);
+  for (const f of arg.fields) {
+    if (val == null || typeof val !== 'object') return undefined;
+    val = (val as Record<string, unknown>)[f];
+  }
+  return val;
+}
+
+export function evaluateRef(ref: Ref, ctx: BindCtx): unknown {
+  // Plain ref without $map — resolve to node
+  if (!ref.$map) {
+    return ctx.getNode(ref.$ref);
+  }
+
+  const expr = getCachedExpr(ref.$map);
+  const firstStep = expr.steps[0];
+
+  // Determine source: children (if first pipe is collection) or single node
+  let value: unknown;
+  if (firstStep?.type === 'pipe' && COLLECTION_PIPES.has(firstStep.name)) {
+    value = ctx.getChildren(ref.$ref);
+  } else {
+    value = ctx.getNode(ref.$ref);
+  }
+
+  // Apply pipeline left-to-right
+  for (const step of expr.steps) {
+    if (value === undefined || value === null) return undefined;
+
+    if (step.type === 'field') {
+      value = (value as Record<string, unknown>)[step.name];
+    } else {
+      const fn = getPipe(step.name);
+      if (!fn) {
+        console.warn(`[bind] unknown pipe: ${step.name}`);
+        return undefined;
+      }
+      const resolved = step.args.map(a => resolveArg(a, ctx, ref.$ref));
+      value = fn(value, ...resolved);
+    }
+  }
+
+  return value;
+}
+
+/** Check if first pipe in $map is a collection pipe (needs children subscription) */
+export function isCollectionRef(ref: Ref): boolean {
+  if (!ref.$map) return false;
+  const expr = getCachedExpr(ref.$map);
+  const first = expr.steps[0];
+  return first?.type === 'pipe' && COLLECTION_PIPES.has(first.name);
+}
+
+/** Check if $map contains `once` pipe — disables reactive subscription */
+export function hasOnce(ref: Ref): boolean {
+  if (!ref.$map) return false;
+  const expr = getCachedExpr(ref.$map);
+  return expr.steps.some(s => s.type === 'pipe' && s.name === 'once');
+}
+
+/** Extract all external #/path refs from a $map expression (for subscriptions) */
+export function extractArgPaths(ref: Ref): string[] {
+  if (!ref.$map) return [];
+  const expr = getCachedExpr(ref.$map);
+  const paths: string[] = [];
+  for (const step of expr.steps) {
+    if (step.type === 'pipe') {
+      for (const arg of step.args) {
+        if (isRefArg(arg) && arg.$ref !== '.') {
+          paths.push(arg.$ref);
+        }
+      }
+    }
+  }
+  return paths;
+}

package/src/bind/hook.ts

@@ -0,0 +1,112 @@
+// React hooks for computed bindings
+
+import * as cache from '#cache';
+import { set, usePath } from '#hooks';
+import { isRef, type NodeData } from '@treenity/core/core';
+import { useCallback, useMemo, useSyncExternalStore } from 'react';
+import { useSnapshot } from 'valtio';
+import { proxy } from 'valtio/vanilla';
+import { getComputed, getComputedProxy, subscribeComputed } from './computed';
+import { evaluateRef, extractArgPaths, isCollectionRef } from './eval';
+
+const EMPTY_PROXY = proxy<Record<string, unknown>>({});
+
+/** Reactive access to computed binding values for a node */
+export function useComputed(path: string): Record<string, unknown> {
+  // Structural: detect proxy creation (first computed value for this path)
+  useSyncExternalStore(
+    useCallback((cb: () => void) => subscribeComputed(path, cb), [path]),
+    useCallback(() => getComputed(path), [path]),
+  );
+
+  // Field-level: re-render only when accessed computed fields change
+  const p = getComputedProxy(path);
+  return useSnapshot(p ?? EMPTY_PROXY) as Record<string, unknown>;
+}
+
+/** Node with computed bindings merged — raw + computed overlay */
+export function useResolvedNode(path: string): [NodeData | undefined, (next: NodeData) => Promise<void>] {
+  const node = usePath(path);
+  const computed = useComputed(path);
+
+  if (!node) return [undefined, set];
+
+  // Check if node has any $ref+$map bindings that need resolving
+  const hasComputed = Object.keys(computed).length > 0;
+  const hasBindings = Object.values(node).some(v => isRef(v) && (v as any).$map);
+  if (!hasComputed && !hasBindings) return [node, set];
+
+  const merged = { ...node } as Record<string, unknown>;
+
+  // Apply computed values
+  for (const [key, value] of Object.entries(computed)) {
+    // Support dotted keys for sub-component fields (e.g. "mesh.width")
+    if (key.includes('.')) {
+      const [comp, field] = key.split('.');
+      if (merged[comp] && typeof merged[comp] === 'object') {
+        merged[comp] = { ...(merged[comp] as object), [field]: value };
+      }
+    } else {
+      merged[key] = value;
+    }
+  }
+
+  // Strip unresolved $ref+$map bindings — computed not ready yet, use 0 default
+  // Without this, raw ref objects leak to consumers (e.g. Three.js rotation={[0, {$ref:...}, 0]} → NaN)
+  for (const key of Object.keys(merged)) {
+    if (key.startsWith('$')) continue;
+    const v = merged[key];
+    if (isRef(v) && (v as any).$map) {
+      merged[key] = 0;
+    }
+    // Sub-component fields
+    if (v && typeof v === 'object' && !isRef(v) && '$type' in (v as any)) {
+      let changed = false;
+      const comp = { ...(v as Record<string, unknown>) };
+      for (const sk of Object.keys(comp)) {
+        if (sk.startsWith('$')) continue;
+        if (isRef(comp[sk]) && (comp[sk] as any).$map) {
+          comp[sk] = 0;
+          changed = true;
+        }
+      }
+      if (changed) merged[key] = comp;
+    }
+  }
+
+  return [merged as NodeData, set];
+}
+
+const evalCtx = {
+  getNode: (p: string) => cache.get(p),
+  getChildren: (p: string) => cache.getChildren(p),
+};
+
+/** Evaluate a $ref+$map expression reactively — no node needed */
+export function useEvalRef(path: string, map: string): unknown {
+  const ref = useMemo(() => ({ $ref: path, $map: map }), [path, map]);
+
+  // Subscribe to all relevant paths: main source + @/path args
+  const subscribe = useCallback((cb: () => void) => {
+    const unsubs: (() => void)[] = [];
+
+    unsubs.push(
+      isCollectionRef(ref)
+        ? cache.subscribeChildren(path, cb)
+        : cache.subscribePath(path, cb),
+    );
+
+    for (const argPath of extractArgPaths(ref)) {
+      unsubs.push(cache.subscribePath(argPath, cb));
+    }
+
+    return () => unsubs.forEach(u => u());
+  }, [ref, path]);
+
+  const getSnapshot = useCallback(() => {
+    try { return evaluateRef(ref, evalCtx); }
+    catch { return undefined; }
+  }, [ref]);
+
+  return useSyncExternalStore(subscribe, getSnapshot);
+}

package/src/bind/parse.ts

@@ -0,0 +1,104 @@
+// $map expression parser
+// Syntax: selector.field | pipe1(args) | pipe2(args)
+// Source path lives in $ref, not here — parser handles $map content only
+//
+// Access modes:
+//   .field         = drill into current pipe value
+//   #field         = lookup from source node ($ref path) — like URI fragment
+//   #/path.field   = lookup from external node — absolute path after #
+
+export type RefArg = { $ref: string; fields: string[] };
+export type PipeArg = number | string | RefArg;
+
+export type MapExpr = { steps: PipeStep[] };
+
+export type PipeStep =
+  | { type: 'pipe'; name: string; args: PipeArg[] }
+  | { type: 'field'; name: string };
+
+export function isRefArg(arg: PipeArg): arg is RefArg {
+  return typeof arg === 'object' && arg !== null && '$ref' in arg;
+}
+
+const PIPE_RE = /^([a-zA-Z_]\w*)\(([^)]*)\)(.*)$/;
+
+function parseArg(s: string): PipeArg {
+  const t = s.trim();
+
+  // # = node ref: #field (self), #/path.field (external)
+  if (t.startsWith('#')) {
+    const rest = t.slice(1);
+    if (rest.startsWith('/')) {
+      // External: #/path.field
+      const dotIdx = rest.indexOf('.');
+      if (dotIdx === -1) return { $ref: rest, fields: [] };
+      return { $ref: rest.slice(0, dotIdx), fields: rest.slice(dotIdx + 1).split('.') };
+    }
+    // Self: #field or #comp.field
+    return { $ref: '.', fields: rest.length ? rest.split('.') : [] };
+  }
+
+  const n = Number(t);
+  return Number.isFinite(n) ? n : t;
+}
+
+function parseSegment(raw: string): PipeStep[] {
+  const s = raw.trim();
+  if (!s) return [];
+
+  // #field — self-ref field access (like URI fragment)
+  if (s.startsWith('#') && !s.startsWith('#/')) {
+    const rest = s.slice(1);
+    return rest.split('.').map(name => ({ type: 'field' as const, name }));
+  }
+
+  // Pure field chain: .foo.bar — drill into pipe value
+  if (s.startsWith('.')) {
+    return parseFieldChain(s);
+  }
+
+  // pipe(args) optionally followed by .field chain
+  const m = PIPE_RE.exec(s);
+  if (m) {
+    const steps: PipeStep[] = [{
+      type: 'pipe',
+      name: m[1],
+      args: m[2] ? m[2].split(',').map(parseArg) : [],
+    }];
+    if (m[3]) steps.push(...parseFieldChain(m[3]));
+    return steps;
+  }
+
+  // Bare name (round, abs): pipe with no args, optionally followed by .field
+  const bare = /^([a-zA-Z_]\w*)(.*)$/.exec(s);
+  if (bare) {
+    const steps: PipeStep[] = [{ type: 'pipe', name: bare[1], args: [] }];
+    if (bare[2]) steps.push(...parseFieldChain(bare[2]));
+    return steps;
+  }
+
+  return [];
+}
+
+function parseFieldChain(s: string): PipeStep[] {
+  const steps: PipeStep[] = [];
+  let rest = s;
+  while (rest) {
+    const m = /^\.([a-zA-Z_$]\w*)(.*)$/.exec(rest);
+    if (!m) break;
+    steps.push({ type: 'field', name: m[1] });
+    rest = m[2];
+  }
+  return steps;
+}
+
+export function parseMapExpr(expr: string): MapExpr {
+  const parts = expr.split('|').map(s => s.trim());
+  const steps: PipeStep[] = [];
+
+  for (const part of parts) {
+    steps.push(...parseSegment(part));
+  }
+
+  return { steps };
+}

package/src/bind/pipes.ts

@@ -0,0 +1,71 @@
+// Pipe registry — Angular-style transforms for $map expressions
+
+import type { NodeData } from '@treenity/core/core';
+
+export type PipeFn = (input: unknown, ...args: unknown[]) => unknown;
+
+const registry = new Map<string, PipeFn>();
+
+export function registerPipe(name: string, fn: PipeFn): void {
+  registry.set(name, fn);
+}
+
+export function getPipe(name: string): PipeFn | undefined {
+  return registry.get(name);
+}
+
+// ── Collection pipes ──
+
+registerPipe('last', (input) => {
+  const arr = input as NodeData[];
+  return arr.length ? arr[arr.length - 1] : undefined;
+});
+
+registerPipe('first', (input) => {
+  const arr = input as NodeData[];
+  return arr.length ? arr[0] : undefined;
+});
+
+registerPipe('count', (input) => (input as unknown[]).length);
+
+registerPipe('map', (input, field) => {
+  return (input as Record<string, unknown>[]).map(item => item[field as string]);
+});
+
+registerPipe('sum', (input) => {
+  return (input as number[]).reduce((a, b) => a + b, 0);
+});
+
+registerPipe('avg', (input) => {
+  const arr = input as number[];
+  return arr.length ? arr.reduce((a, b) => a + b, 0) / arr.length : 0;
+});
+
+registerPipe('max', (input) => Math.max(...(input as number[])));
+
+registerPipe('min', (input) => Math.min(...(input as number[])));
+
+// ── Scalar pipes ──
+
+registerPipe('div', (input, n) => (input as number) / (n as number));
+
+registerPipe('mul', (input, n) => (input as number) * (n as number));
+
+registerPipe('add', (input, n) => (input as number) + (n as number));
+
+registerPipe('sub', (input, n) => (input as number) - (n as number));
+
+registerPipe('clamp', (input, min, max) =>
+  Math.min(Math.max(input as number, min as number), max as number));
+
+registerPipe('round', (input) => Math.round(input as number));
+
+registerPipe('abs', (input) => Math.abs(input as number));
+
+registerPipe('floor', (input) => Math.floor(input as number));
+
+registerPipe('ceil', (input) => Math.ceil(input as number));
+
+// ── Reactivity control ──
+
+registerPipe('once', (input) => input);