@astrale-os/shell-react 0.2.3 → 0.2.5

package/dist/graph/query/neighbors.hook.js

@@ -12,8 +12,10 @@ export function useOut(node, edge, opts) {
 export function useIn(node, edge, opts) {
     return useEndpoint(node, edge, 'in', opts);
 }
-function useEndpoint(node, edge, side, _opts) {
+function useEndpoint(node, edge, side, opts) {
     const schema = isIdleInput(node) ? undefined : schemaOf(node);
+    const single = schema !== undefined && isSingleEndpoint(schema, edge, side);
+    const key = `${node?.id ?? ''}\u0000${edge}\u0000${side}`;
     const run = useCallback(async () => {
         if (isIdleInput(node))
             return null;
@@ -23,22 +25,26 @@ function useEndpoint(node, edge, side, _opts) {
         return result;
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [node?.id, edge, side]);
-    const { data, pending, error, refetch } = useAsyncRead(isIdleInput(node) ? null : run, [
-        node?.id ?? null,
-        edge,
-        side,
-    ]);
+    const { data, pending, error, refetch } = useAsyncRead(isIdleInput(node) ? null : run, key, opts?.keepPrevious === true);
     return useMemo(() => {
         const live = { pending, error, live: false, seq: 0, refetch };
         if (isIdleInput(node))
             return { ...live, node: null, nodes: EMPTY };
-        if (Array.isArray(data))
-            return { ...live, nodes: data };
-        return { ...live, node: (data ?? null) };
-    }, [node, data, pending, error, refetch]);
+        if (single) {
+            const value = Array.isArray(data) ? data[0] : data;
+            return { ...live, node: (value ?? null) };
+        }
+        const values = Array.isArray(data) ? data : data === null || data === undefined ? EMPTY : [data];
+        return { ...live, nodes: values };
+    }, [node, data, pending, error, refetch, single]);
 }
 // ── helpers ──────────────────────────────────────────────────────────────────
 const EMPTY = Object.freeze([]);
+function isSingleEndpoint(schema, edge, side) {
+    const definition = schema.classes[edge];
+    const cardinality = (side === 'out' ? definition?.to : definition?.from)?.cardinality;
+    return cardinality === '1' || cardinality === '0..1';
+}
 function tagEndpoints(result, schema) {
     if (Array.isArray(result))
         for (const r of result)
@@ -47,30 +53,52 @@ function tagEndpoints(result, schema) {
         tagSchema(result, schema);
 }
 /** One-shot async read with pending/error/refetch and stale-response guarding. */
-function useAsyncRead(run, deps) {
-    const [state, setState] = useState({ pending: run !== null, error: undefined });
+function useAsyncRead(run, key, keepPrevious) {
+    const [state, setState] = useState({
+        pending: run !== null,
+        error: undefined,
+        key: run === null ? null : key,
+    });
     const runRef = useRef(run);
     runRef.current = run;
+    const keyRef = useRef(key);
+    keyRef.current = key;
+    const keepPreviousRef = useRef(keepPrevious);
+    keepPreviousRef.current = keepPrevious;
     const seq = useRef(0);
     const refetch = useCallback(() => {
         const current = runRef.current;
+        const currentKey = keyRef.current;
         if (current === null) {
-            setState({ pending: false, error: undefined, data: undefined });
+            setState({ pending: false, error: undefined, data: undefined, key: null });
             return Promise.resolve();
         }
         const my = ++seq.current;
-        setState((s) => ({ ...s, pending: true, error: undefined }));
+        setState((s) => ({
+            data: s.key === currentKey || keepPreviousRef.current === true ? s.data : undefined,
+            pending: true,
+            error: undefined,
+            key: currentKey,
+        }));
         return current().then((data) => {
-            if (my === seq.current)
-                setState({ data, pending: false, error: undefined });
+            if (my === seq.current) {
+                setState({ data, pending: false, error: undefined, key: currentKey });
+            }
         }, (error) => {
-            if (my === seq.current)
-                setState((s) => ({ data: s.data, pending: false, error }));
+            if (my === seq.current) {
+                setState((s) => ({ data: s.data, pending: false, error, key: currentKey }));
+            }
         });
     }, []);
     useEffect(() => {
         void refetch();
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, deps);
-    return { ...state, refetch };
+    }, [key, refetch]);
+    const current = state.key === key;
+    return {
+        data: current || keepPrevious ? state.data : undefined,
+        pending: run !== null && (!current || state.pending),
+        error: current ? state.error : undefined,
+        key: current ? state.key : null,
+        refetch,
+    };
 }

package/dist/schema/binding.d.ts

@@ -4,7 +4,7 @@
  * `createSchemaBoundView` per (session, schema) so a binding — and the BoundNodes
  * it mints — keep referential identity across renders. Each binding is wrapped so
  * every BoundNode it hands back is schema-tagged (the traversal hooks read it
- * back) and its `id → tree path` recorded (the write capability's index).
+ * back) and its raw node recorded (the write capability's index).
  */
 import type { FnMap, NodeRefInput, SchemaBoundView } from '@astrale-os/kernel-client';
 import type { GraphMemory } from '@astrale-os/kernel-client/store';

package/dist/schema/binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/schema/binding.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AACrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AAElE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAIpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAQ5D;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,WAAW,GAClB,eAAe,CAAC,CAAC,EAAE,KAAK,CAAC,CAa3B;AAyCD,YAAY,EAAE,YAAY,EAAE,CAAA"}
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/schema/binding.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AACrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AAElE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAIpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAQ5D;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,WAAW,GAClB,eAAe,CAAC,CAAC,EAAE,KAAK,CAAC,CAa3B;AAmGD,YAAY,EAAE,YAAY,EAAE,CAAA"}

package/dist/schema/binding.js

@@ -1,6 +1,6 @@
 import { createSchemaBoundView } from '@astrale-os/kernel-client';
 import { tagSchema } from './tag.js';
-import { recordPath, writableFor } from './write.js';
+import { recordNode, writableFor } from './write.js';
 /** One tagged binding per (kernel, schema) — shared across the whole tree. */
 const bindingCache = new WeakMap();
 /**
@@ -18,38 +18,82 @@ export function bindingFor(kernel, schema, memory) {
     const cached = bySchema.get(schema);
     if (cached !== undefined)
         return cached;
-    const { writable, pathIndex } = writableFor(kernel, memory);
-    const binding = tagBinding(createSchemaBoundView(writable, schema), schema, pathIndex);
+    const { writable, nodeIndex } = writableFor(kernel, memory);
+    const binding = tagBinding(createSchemaBoundView(writable, schema), schema, nodeIndex);
     bySchema.set(schema, binding);
     return binding;
 }
 /**
  * Wrap a binding so `bind`/`bindAny`/`as` outputs carry a schema tag, and every
- * bound wire node's `id → tree path` is recorded (the write cap's index); the
+ * bound wire node is recorded with its class and path (the write cap's index); the
  * class handles and every other member pass straight through.
  */
-function tagBinding(binding, schema, pathIndex) {
+function tagBinding(binding, schema, nodeIndex) {
+    let taggedClasses;
     const handler = {
         get: (target, prop, receiver) => {
             const value = Reflect.get(target, prop, receiver);
+            if (prop === 'node' || prop === 'create') {
+                return async (...args) => tagBoundResult(await value(...args), schema, nodeIndex);
+            }
             if (prop === 'bind') {
                 return (type, node, opts) => {
-                    recordPath(pathIndex, node);
+                    recordNode(nodeIndex, node);
                     return tagSchema(value(type, node, opts), schema);
                 };
             }
             if (prop === 'bindAny') {
                 return (node) => {
-                    recordPath(pathIndex, node);
+                    recordNode(nodeIndex, node);
                     return tagSchema(value(node), schema);
                 };
             }
+            if (prop === 'classes') {
+                taggedClasses ??= tagClassHandles(value, schema, nodeIndex);
+                return taggedClasses;
+            }
             if (prop === 'as') {
                 const as = value;
-                return (credential) => tagBinding(as(credential), schema, pathIndex);
+                return (credential) => tagBinding(as(credential), schema, nodeIndex);
+            }
+            if (prop === 'withSchema') {
+                return (next) => tagBinding(value(next), next, nodeIndex);
             }
             return value;
         },
     };
     return new Proxy(binding, handler);
 }
+function tagClassHandles(classes, schema, nodeIndex) {
+    const handles = new Map();
+    return new Proxy(classes, {
+        get(target, prop, receiver) {
+            const cached = handles.get(prop);
+            if (cached !== undefined)
+                return cached;
+            const handle = Reflect.get(target, prop, receiver);
+            if (typeof handle !== 'function')
+                return handle;
+            const tagged = new Proxy(handle, {
+                get(handleTarget, member, handleReceiver) {
+                    const value = Reflect.get(handleTarget, member, handleReceiver);
+                    if (member !== 'get')
+                        return value;
+                    return async (...args) => tagBoundResult(await value(...args), schema, nodeIndex);
+                },
+            });
+            handles.set(prop, tagged);
+            return tagged;
+        },
+    });
+}
+function tagBoundResult(result, schema, nodeIndex) {
+    const nodes = Array.isArray(result) ? result : [result];
+    for (const node of nodes) {
+        if (node !== null && typeof node === 'object') {
+            recordNode(nodeIndex, node);
+            tagSchema(node, schema);
+        }
+    }
+    return result;
+}

package/dist/schema/write.d.ts

@@ -1,4 +1,5 @@
 import type { GraphMemory } from '@astrale-os/kernel-client/store';
+import type { Node } from '@astrale-os/kernel-core';
 import type { SessionView } from '../auth/act-as.context.js';
 /**
  * One memory-backed writable kernel per (effective) session view, plus the
@@ -7,9 +8,9 @@ import type { SessionView } from '../auth/act-as.context.js';
  */
 export interface WritableKernel {
     readonly writable: SessionView;
-    readonly pathIndex: Map<string, string>;
+    readonly nodeIndex: Map<string, Node>;
 }
 export declare function writableFor(kernel: SessionView, memory: GraphMemory): WritableKernel;
-/** Record a bound node's `id → tree path` so the write cap can address it. */
-export declare function recordPath(pathIndex: Map<string, string>, node: unknown): void;
+/** Record a bound node's raw value so the write cap retains its class and tree path. */
+export declare function recordNode(nodeIndex: Map<string, Node>, node: unknown): void;
 //# sourceMappingURL=write.d.ts.map

package/dist/schema/write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/schema/write.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AAElE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAE5D;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACxC;AAGD,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,cAAc,CAQpF;AAkDD,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAK9E"}
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/schema/write.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AAClE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAA;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAE5D;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;CACtC;AAGD,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,cAAc,CAQpF;AAqDD,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAO5E"}

package/dist/schema/write.js

@@ -2,8 +2,8 @@ const writableCache = new WeakMap();
 export function writableFor(kernel, memory) {
     let entry = writableCache.get(kernel);
     if (entry === undefined) {
-        const pathIndex = new Map();
-        entry = { writable: withMemoryWrites(kernel, memory, pathIndex), pathIndex };
+        const nodeIndex = new Map();
+        entry = { writable: withMemoryWrites(kernel, memory, nodeIndex), nodeIndex };
         writableCache.set(kernel, entry);
     }
     return entry;
@@ -11,41 +11,46 @@ export function writableFor(kernel, memory) {
 /**
  * Wrap a session view so `updateNode`/`createNode` route through the memory's
  * optimistic write shorthands. `BoundNode.update` addresses a node by `@<id>`,
- * but the memory indexes entities by tree path — so an `@<id>` ref is translated
- * through `pathIndex` (populated at bind time). A ref that is NOT indexed (a node
- * that was never read through a hook) falls back to the raw kernel-client floor:
+ * but the memory needs the node's class and tree path — so an `@<id>` ref is translated
+ * through `nodeIndex` (populated at bind time). A ref that is NOT indexed (a node
+ * that was never bound) falls back to the raw kernel-client floor:
  * it still dispatches, just without the overlay — matching the imperative floor.
  */
-function withMemoryWrites(kernel, memory, pathIndex) {
+function withMemoryWrites(kernel, memory, nodeIndex) {
     const base = kernel;
     const rawUpdate = base.updateNode.bind(base);
     return extendCapabilities(kernel, {
         updateNode: (cls, ref, props) => {
-            const path = treePathFor(pathIndex, ref);
-            return path !== null ? memory.update(path, props) : rawUpdate(cls, ref, props);
+            const node = indexedNode(nodeIndex, ref);
+            return node !== null ? memory.update(node, props) : rawUpdate(cls, ref, props);
         },
         createNode: (cls, at, props) => memory.create(cls, at, props),
         // Credential rebind stays on the raw kernel-client floor (§6 note).
         as: (cred) => base.as(cred),
     });
 }
-/** Clone the complete session capability object before overlaying memory writes. */
+/** Overlay memory writes without materializing a possibly virtual session surface. */
 function extendCapabilities(base, extension) {
-    const result = Object.create(Object.getPrototypeOf(base));
-    Object.defineProperties(result, Object.getOwnPropertyDescriptors(base));
-    Object.defineProperties(result, Object.getOwnPropertyDescriptors(extension));
-    return result;
+    return new Proxy(base, {
+        get(target, prop, receiver) {
+            return Object.prototype.hasOwnProperty.call(extension, prop)
+                ? Reflect.get(extension, prop, extension)
+                : Reflect.get(target, prop, receiver);
+        },
+    });
 }
 /** The tree path an `@<id>` write ref maps to, via the bind-time index; else null. */
-function treePathFor(pathIndex, ref) {
+function indexedNode(nodeIndex, ref) {
     if (typeof ref !== 'string' || !ref.startsWith('@'))
         return null;
-    return pathIndex.get(ref.slice(1)) ?? null;
+    return nodeIndex.get(ref.slice(1)) ?? null;
 }
-/** Record a bound node's `id → tree path` so the write cap can address it. */
-export function recordPath(pathIndex, node) {
-    const n = node;
+/** Record a bound node's raw value so the write cap retains its class and tree path. */
+export function recordNode(nodeIndex, node) {
+    const wrapped = node;
+    const candidate = wrapped?.raw !== null && typeof wrapped?.raw === 'object' ? wrapped.raw : node;
+    const n = candidate;
     if (n !== null && typeof n.id === 'string' && typeof n.path?.raw === 'string') {
-        pathIndex.set(n.id, n.path.raw);
+        nodeIndex.set(n.id, candidate);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/shell-react",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Astrale shell-react — the React face of the shell (provider, hooks, view components)",
   "license": "Apache-2.0",
   "repository": {
@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "@astrale-domains/shell-schema": ">=0.3.2 <1.0.0",
-    "@astrale-os/kernel-client": ">=0.4.6 <1.0.0",
+    "@astrale-os/kernel-client": ">=0.4.7 <1.0.0",
     "@astrale-os/kernel-core": ">=0.7.5 <1.0.0",
     "@astrale-os/kernel-dsl": ">=0.1.4 <1.0.0",
     "jose": "^6.2.3",
@@ -44,7 +44,7 @@
     "react-dom": "^19.2.0",
     "typescript": "~6.0.1-rc",
     "vitest": "^3.2.4",
-    "@astrale-os/shell": "0.3.3"
+    "@astrale-os/shell": "0.3.4"
   },
   "peerDependencies": {
     "@astrale-os/shell": ">=0.2.0 <1.0.0",

package/src/graph/query/neighbors.hook.ts

@@ -39,9 +39,11 @@ function useEndpoint<S extends Schema>(
   node: AnyBoundNode<S> | null | undefined,
   edge: EdgeNames<S>,
   side: 'out' | 'in',
-  _opts?: ReadOptions,
+  opts?: ReadOptions,
 ): EndpointEnvelope<S> {
   const schema = isIdleInput(node) ? undefined : schemaOf(node)
+  const single = schema !== undefined && isSingleEndpoint(schema, edge, side)
+  const key = `${node?.id ?? ''}\u0000${edge}\u0000${side}`
   const run = useCallback(async (): Promise<unknown> => {
     if (isIdleInput(node)) return null
     const result = await (side === 'out' ? node.links.out(edge) : node.links.in(edge))
@@ -50,24 +52,39 @@ function useEndpoint<S extends Schema>(
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [node?.id, edge, side])
 
-  const { data, pending, error, refetch } = useAsyncRead(isIdleInput(node) ? null : run, [
-    node?.id ?? null,
-    edge,
-    side,
-  ])
+  const { data, pending, error, refetch } = useAsyncRead(
+    isIdleInput(node) ? null : run,
+    key,
+    opts?.keepPrevious === true,
+  )
 
   return useMemo<EndpointEnvelope<S>>(() => {
     const live: ReadState = { pending, error, live: false, seq: 0, refetch }
     if (isIdleInput(node)) return { ...live, node: null, nodes: EMPTY }
-    if (Array.isArray(data)) return { ...live, nodes: data as readonly AnyBoundNode<S>[] }
-    return { ...live, node: (data ?? null) as AnyBoundNode<S> | null }
-  }, [node, data, pending, error, refetch])
+    if (single) {
+      const value = Array.isArray(data) ? data[0] : data
+      return { ...live, node: (value ?? null) as AnyBoundNode<S> | null }
+    }
+    const values = Array.isArray(data) ? data : data === null || data === undefined ? EMPTY : [data]
+    return { ...live, nodes: values as readonly AnyBoundNode<S>[] }
+  }, [node, data, pending, error, refetch, single])
 }
 
 // ── helpers ──────────────────────────────────────────────────────────────────
 
 const EMPTY: readonly never[] = Object.freeze([])
 
+function isSingleEndpoint(schema: Schema, edge: string, side: 'out' | 'in'): boolean {
+  const definition = schema.classes[edge] as
+    | {
+        readonly from?: { readonly cardinality?: string }
+        readonly to?: { readonly cardinality?: string }
+      }
+    | undefined
+  const cardinality = (side === 'out' ? definition?.to : definition?.from)?.cardinality
+  return cardinality === '1' || cardinality === '0..1'
+}
+
 function tagEndpoints(result: unknown, schema: Schema): void {
   if (Array.isArray(result)) for (const r of result) tagSchema(r, schema)
   else if (result !== null && result !== undefined) tagSchema(result, schema)
@@ -77,40 +94,66 @@ interface AsyncState<T> {
   data?: T
   pending: boolean
   error: unknown
+  key: string | null
 }
 
 /** One-shot async read with pending/error/refetch and stale-response guarding. */
 function useAsyncRead<T>(
   run: (() => Promise<T>) | null,
-  deps: readonly unknown[],
+  key: string,
+  keepPrevious: boolean,
 ): AsyncState<T> & { refetch(): Promise<void> } {
-  const [state, setState] = useState<AsyncState<T>>({ pending: run !== null, error: undefined })
+  const [state, setState] = useState<AsyncState<T>>({
+    pending: run !== null,
+    error: undefined,
+    key: run === null ? null : key,
+  })
   const runRef = useRef(run)
   runRef.current = run
+  const keyRef = useRef(key)
+  keyRef.current = key
+  const keepPreviousRef = useRef(keepPrevious)
+  keepPreviousRef.current = keepPrevious
   const seq = useRef(0)
 
   const refetch = useCallback((): Promise<void> => {
     const current = runRef.current
+    const currentKey = keyRef.current
     if (current === null) {
-      setState({ pending: false, error: undefined, data: undefined })
+      setState({ pending: false, error: undefined, data: undefined, key: null })
       return Promise.resolve()
     }
     const my = ++seq.current
-    setState((s) => ({ ...s, pending: true, error: undefined }))
+    setState((s) => ({
+      data: s.key === currentKey || keepPreviousRef.current === true ? s.data : undefined,
+      pending: true,
+      error: undefined,
+      key: currentKey,
+    }))
     return current().then(
       (data) => {
-        if (my === seq.current) setState({ data, pending: false, error: undefined })
+        if (my === seq.current) {
+          setState({ data, pending: false, error: undefined, key: currentKey })
+        }
       },
       (error: unknown) => {
-        if (my === seq.current) setState((s) => ({ data: s.data, pending: false, error }))
+        if (my === seq.current) {
+          setState((s) => ({ data: s.data, pending: false, error, key: currentKey }))
+        }
       },
     )
   }, [])
 
   useEffect(() => {
     void refetch()
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, deps)
-
-  return { ...state, refetch }
+  }, [key, refetch])
+
+  const current = state.key === key
+  return {
+    data: current || keepPrevious ? state.data : undefined,
+    pending: run !== null && (!current || state.pending),
+    error: current ? state.error : undefined,
+    key: current ? state.key : null,
+    refetch,
+  }
 }

package/src/schema/binding.ts

@@ -4,7 +4,7 @@
  * `createSchemaBoundView` per (session, schema) so a binding — and the BoundNodes
  * it mints — keep referential identity across renders. Each binding is wrapped so
  * every BoundNode it hands back is schema-tagged (the traversal hooks read it
- * back) and its `id → tree path` recorded (the write capability's index).
+ * back) and its raw node recorded (the write capability's index).
  */
 import type { FnMap, NodeRefInput, SchemaBoundView } from '@astrale-os/kernel-client'
 import type { GraphMemory } from '@astrale-os/kernel-client/store'
@@ -16,7 +16,7 @@ import { createSchemaBoundView } from '@astrale-os/kernel-client'
 import type { SessionView } from '../auth/act-as.context.js'
 
 import { tagSchema } from './tag.js'
-import { recordPath, writableFor } from './write.js'
+import { recordNode, writableFor } from './write.js'
 
 /** One tagged binding per (kernel, schema) — shared across the whole tree. */
 const bindingCache = new WeakMap<object, WeakMap<Schema, unknown>>()
@@ -40,28 +40,37 @@ export function bindingFor<S extends Schema>(
   const cached = bySchema.get(schema)
   if (cached !== undefined) return cached as SchemaBoundView<S, FnMap>
 
-  const { writable, pathIndex } = writableFor(kernel, memory)
-  const binding = tagBinding(createSchemaBoundView(writable, schema), schema, pathIndex)
+  const { writable, nodeIndex } = writableFor(kernel, memory)
+  const binding = tagBinding(createSchemaBoundView(writable, schema), schema, nodeIndex)
   bySchema.set(schema, binding)
   return binding
 }
 
 /**
  * Wrap a binding so `bind`/`bindAny`/`as` outputs carry a schema tag, and every
- * bound wire node's `id → tree path` is recorded (the write cap's index); the
+ * bound wire node is recorded with its class and path (the write cap's index); the
  * class handles and every other member pass straight through.
  */
 function tagBinding<S extends Schema>(
   binding: SchemaBoundView<S, FnMap>,
   schema: S,
-  pathIndex: Map<string, string>,
+  nodeIndex: Map<string, Node>,
 ): SchemaBoundView<S, FnMap> {
+  let taggedClasses: unknown
   const handler: ProxyHandler<SchemaBoundView<S, FnMap>> = {
     get: (target, prop, receiver) => {
       const value = Reflect.get(target, prop, receiver) as unknown
+      if (prop === 'node' || prop === 'create') {
+        return async (...args: unknown[]) =>
+          tagBoundResult(
+            await (value as (...callArgs: unknown[]) => Promise<unknown>)(...args),
+            schema,
+            nodeIndex,
+          )
+      }
       if (prop === 'bind') {
         return (type: string, node: Node, opts?: unknown) => {
-          recordPath(pathIndex, node)
+          recordNode(nodeIndex, node)
           return tagSchema(
             (value as (t: string, n: Node, o?: unknown) => unknown)(type, node, opts),
             schema,
@@ -70,14 +79,22 @@ function tagBinding<S extends Schema>(
       }
       if (prop === 'bindAny') {
         return (node: Node) => {
-          recordPath(pathIndex, node)
+          recordNode(nodeIndex, node)
           return tagSchema((value as (n: Node) => unknown)(node), schema)
         }
       }
+      if (prop === 'classes') {
+        taggedClasses ??= tagClassHandles(value as object, schema, nodeIndex)
+        return taggedClasses
+      }
       if (prop === 'as') {
         const as = value as SchemaBoundView<S, FnMap>['as']
         return (credential: Parameters<typeof as>[0]) =>
-          tagBinding(as(credential), schema, pathIndex)
+          tagBinding(as(credential), schema, nodeIndex)
+      }
+      if (prop === 'withSchema') {
+        return <S2 extends Schema>(next: S2) =>
+          tagBinding((value as SchemaBoundView<S, FnMap>['withSchema'])(next), next, nodeIndex)
       }
       return value
     },
@@ -85,4 +102,45 @@ function tagBinding<S extends Schema>(
   return new Proxy(binding, handler)
 }
 
+function tagClassHandles<S extends Schema>(
+  classes: object,
+  schema: S,
+  nodeIndex: Map<string, Node>,
+): object {
+  const handles = new Map<PropertyKey, unknown>()
+  return new Proxy(classes, {
+    get(target, prop, receiver) {
+      const cached = handles.get(prop)
+      if (cached !== undefined) return cached
+      const handle = Reflect.get(target, prop, receiver) as unknown
+      if (typeof handle !== 'function') return handle
+      const tagged = new Proxy(handle, {
+        get(handleTarget, member, handleReceiver) {
+          const value = Reflect.get(handleTarget, member, handleReceiver) as unknown
+          if (member !== 'get') return value
+          return async (...args: unknown[]) =>
+            tagBoundResult(
+              await (value as (...callArgs: unknown[]) => Promise<unknown>)(...args),
+              schema,
+              nodeIndex,
+            )
+        },
+      })
+      handles.set(prop, tagged)
+      return tagged
+    },
+  })
+}
+
+function tagBoundResult<R>(result: R, schema: Schema, nodeIndex: Map<string, Node>): R {
+  const nodes = Array.isArray(result) ? result : [result]
+  for (const node of nodes) {
+    if (node !== null && typeof node === 'object') {
+      recordNode(nodeIndex, node)
+      tagSchema(node, schema)
+    }
+  }
+  return result
+}
+
 export type { NodeRefInput }

package/src/schema/write.ts

@@ -9,6 +9,7 @@
 import type { CredentialInput } from '@astrale-os/kernel-client'
 import type { PathLike, Properties } from '@astrale-os/kernel-client/graph'
 import type { GraphMemory } from '@astrale-os/kernel-client/store'
+import type { Node } from '@astrale-os/kernel-core'
 
 import type { SessionView } from '../auth/act-as.context.js'
 
@@ -19,15 +20,15 @@ import type { SessionView } from '../auth/act-as.context.js'
  */
 export interface WritableKernel {
   readonly writable: SessionView
-  readonly pathIndex: Map<string, string>
+  readonly nodeIndex: Map<string, Node>
 }
 const writableCache = new WeakMap<object, WritableKernel>()
 
 export function writableFor(kernel: SessionView, memory: GraphMemory): WritableKernel {
   let entry = writableCache.get(kernel)
   if (entry === undefined) {
-    const pathIndex = new Map<string, string>()
-    entry = { writable: withMemoryWrites(kernel, memory, pathIndex), pathIndex }
+    const nodeIndex = new Map<string, Node>()
+    entry = { writable: withMemoryWrites(kernel, memory, nodeIndex), nodeIndex }
     writableCache.set(kernel, entry)
   }
   return entry
@@ -36,15 +37,15 @@ export function writableFor(kernel: SessionView, memory: GraphMemory): WritableK
 /**
  * Wrap a session view so `updateNode`/`createNode` route through the memory's
  * optimistic write shorthands. `BoundNode.update` addresses a node by `@<id>`,
- * but the memory indexes entities by tree path — so an `@<id>` ref is translated
- * through `pathIndex` (populated at bind time). A ref that is NOT indexed (a node
- * that was never read through a hook) falls back to the raw kernel-client floor:
+ * but the memory needs the node's class and tree path — so an `@<id>` ref is translated
+ * through `nodeIndex` (populated at bind time). A ref that is NOT indexed (a node
+ * that was never bound) falls back to the raw kernel-client floor:
  * it still dispatches, just without the overlay — matching the imperative floor.
  */
 function withMemoryWrites(
   kernel: SessionView,
   memory: GraphMemory,
-  pathIndex: Map<string, string>,
+  nodeIndex: Map<string, Node>,
 ): SessionView {
   const base = kernel as unknown as {
     updateNode(cls: PathLike, ref: PathLike, props: Properties): Promise<void>
@@ -54,8 +55,8 @@ function withMemoryWrites(
   const rawUpdate = base.updateNode.bind(base)
   return extendCapabilities(kernel, {
     updateNode: (cls: PathLike, ref: PathLike, props: Properties): Promise<void> => {
-      const path = treePathFor(pathIndex, ref)
-      return path !== null ? memory.update(path, props) : rawUpdate(cls, ref, props)
+      const node = indexedNode(nodeIndex, ref)
+      return node !== null ? memory.update(node, props) : rawUpdate(cls, ref, props)
     },
     createNode: (cls: PathLike, at: PathLike, props?: Properties): Promise<string> =>
       memory.create(cls, at, props),
@@ -64,27 +65,32 @@ function withMemoryWrites(
   })
 }
 
-/** Clone the complete session capability object before overlaying memory writes. */
+/** Overlay memory writes without materializing a possibly virtual session surface. */
 function extendCapabilities<Base extends object, Extension extends object>(
   base: Base,
   extension: Extension,
 ): Base & Extension {
-  const result = Object.create(Object.getPrototypeOf(base)) as Base & Extension
-  Object.defineProperties(result, Object.getOwnPropertyDescriptors(base))
-  Object.defineProperties(result, Object.getOwnPropertyDescriptors(extension))
-  return result
+  return new Proxy(base as Base & Extension, {
+    get(target, prop, receiver) {
+      return Object.prototype.hasOwnProperty.call(extension, prop)
+        ? Reflect.get(extension, prop, extension)
+        : Reflect.get(target, prop, receiver)
+    },
+  })
 }
 
 /** The tree path an `@<id>` write ref maps to, via the bind-time index; else null. */
-function treePathFor(pathIndex: Map<string, string>, ref: PathLike): string | null {
+function indexedNode(nodeIndex: Map<string, Node>, ref: PathLike): Node | null {
   if (typeof ref !== 'string' || !ref.startsWith('@')) return null
-  return pathIndex.get(ref.slice(1)) ?? null
+  return nodeIndex.get(ref.slice(1)) ?? null
 }
 
-/** Record a bound node's `id → tree path` so the write cap can address it. */
-export function recordPath(pathIndex: Map<string, string>, node: unknown): void {
-  const n = node as { id?: unknown; path?: { raw?: unknown } } | null
+/** Record a bound node's raw value so the write cap retains its class and tree path. */
+export function recordNode(nodeIndex: Map<string, Node>, node: unknown): void {
+  const wrapped = node as { raw?: unknown } | null
+  const candidate = wrapped?.raw !== null && typeof wrapped?.raw === 'object' ? wrapped.raw : node
+  const n = candidate as { id?: unknown; path?: { raw?: unknown } } | null
   if (n !== null && typeof n.id === 'string' && typeof n.path?.raw === 'string') {
-    pathIndex.set(n.id, n.path.raw)
+    nodeIndex.set(n.id, candidate as Node)
   }
 }