@astrale-os/shell-react 0.2.9 → 0.2.10-beta.3

package/src/session/provider.tsx

@@ -1,94 +1,54 @@
-import type { MemoryEvent } from '@astrale-os/kernel-client/store'
 import type { Shell, ShellConfig } from '@astrale-os/shell'
 import type { ReactElement, ReactNode } from 'react'
 
 import { createShell } from '@astrale-os/shell'
-/**
- * ShellProvider — the composition root (API §2, SPEC §5): owns the shell boot
- * state machine (a config OR a prebuilt Shell; `createShell → init → whoami →
- * ready`), seats `ShellContext` and `GraphContext`, and registers its boot-retry
- * into the per-shell connection store. One live shell per mounted provider,
- * StrictMode/HMR-safe (deferred teardown), keyed on config identity. Children
- * render only at `ready`, so useShell/useSelf are synchronous below.
- */
-import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from 'react'
+import { useCallback, useEffect, useReducer, useRef, useState } from 'react'
 
-import type { GraphMemory } from '../graph/graph.context.js'
 import type { BootRef } from './boot/ownership.js'
 import type { SelfNode } from './session.context.js'
 
 import { primeUser } from '../application/user/user.store.js'
 import { GraphContext } from '../graph/graph.context.js'
-import { baseMemoryFor, setMemoryErrorSink } from '../graph/memory/base.js'
+import { resolveGraphStoreScope, retainStore, storeFor } from '../graph/store.js'
 import { configIdentity, isShellConfig, resolveSelf } from './boot/boot.js'
 import { cancelTeardown, disposeShell, scheduleTeardown } from './boot/ownership.js'
 import { bootReducer, INITIAL_BOOT } from './boot/status.js'
 import { connectionStore } from './connection/connection.store.js'
 import { ShellContext } from './session.context.js'
 
-/** Global error channel payload (API §2). */
-export type ShellError =
-  | { kind: 'refresh'; shape: unknown; error: unknown }
-  | { kind: 'mutation'; mutationId: string; error: unknown }
-  | { kind: 'connection'; error: unknown }
+export type ShellError = { readonly kind: 'connection'; readonly error: unknown }
 
 export interface ShellProviderProps {
-  /**
-   * Shell config — or a prebuilt Shell (tests, storybook). Keyed by identity: a
-   * config change disposes and reboots.
-   */
-  config: ShellConfig | Shell
-  /** Rendered until status === 'ready'. Default: null. */
-  fallback?: ReactNode
-  /** Rendered when boot fails; `retry` re-runs init. Default: rethrow to the nearest boundary. */
-  errorFallback?: (error: unknown, retry: () => void) => ReactNode
-  /** Global error channel: warm-read refresh failures, rolled-back mutations, watch drops. */
-  onError?: (error: ShellError) => void
-  children: ReactNode
-}
-
-/**
- * Map a memory event to the documented `ShellError` union (API §2). `refresh`
- * (warm-read revalidation failure) and `mutation` (rolled-back write) are the
- * two the channel promises; `divergence`/`invariant` are Tier-0/dev tripwires
- * outside the union and are not bridged here.
- */
-function toShellError(event: MemoryEvent): ShellError | null {
-  switch (event.kind) {
-    case 'refresh':
-      return { kind: 'refresh', shape: event.shape, error: event.error }
-    case 'mutation':
-      return { kind: 'mutation', mutationId: event.mutationId, error: event.error }
-    default:
-      return null
-  }
+  /** A Shell configuration or an already-constructed Shell capability. */
+  readonly config: ShellConfig | Shell
+  readonly fallback?: ReactNode
+  readonly errorFallback?: (error: unknown, retry: () => void) => ReactNode
+  readonly onError?: (error: ShellError) => void
+  readonly children: ReactNode
 }
 
+/** Own and initialize exactly one Shell for a React subtree. */
 export function ShellProvider(props: ShellProviderProps): ReactElement | null {
   const { config, fallback, errorFallback, onError, children } = props
-
   const [state, dispatch] = useReducer(bootReducer, INITIAL_BOOT)
   const [attempt, setAttempt] = useState(0)
-
   const bootRef = useRef<BootRef>({ key: null, shell: null, generation: 0 })
   const configRef = useRef(config)
   configRef.current = config
   const onErrorRef = useRef(onError)
   onErrorRef.current = onError
-
   const configKey = configIdentity(config)
 
   const startBoot = useCallback((ref: BootRef) => {
     const generation = (ref.generation += 1)
     dispatch({ type: 'connecting' })
-
     let shell: Shell
-    const current = configRef.current
     try {
+      const current = configRef.current
       shell = isShellConfig(current) ? createShell(current) : current
-    } catch (err) {
-      dispatch({ type: 'error', error: err })
-      onErrorRef.current?.({ kind: 'connection', error: err })
+    } catch (error) {
+      dispatch({ type: 'error', error })
+      onErrorRef.current?.({ kind: 'connection', error })
       return
     }
     ref.shell = shell
@@ -99,33 +59,29 @@ export function ShellProvider(props: ShellProviderProps): ReactElement | null {
         if (generation !== ref.generation) return
         const self: SelfNode | null = await resolveSelf(shell)
         if (generation !== ref.generation) return
-        // Pre-resolve the OS-plane user binding (API §2/§12.2) — NON-FATAL: a
-        // missing OS plane marks it unavailable without failing boot (whoami above
-        // stays the fatal gate). Seeds the user store so `useUser` is synchronous.
         await primeUser(shell)
         if (generation !== ref.generation) return
-        dispatch({ type: 'ready', runtime: { shell, self } })
-      } catch (err) {
+        const storeScope = await resolveGraphStoreScope(shell, self)
         if (generation !== ref.generation) return
-        dispatch({ type: 'error', error: err })
-        onErrorRef.current?.({ kind: 'connection', error: err })
+        const graph = storeFor(shell, storeScope)
+        dispatch({
+          type: 'ready',
+          runtime: { shell, self, storeScope, store: graph.store, ownsStore: graph.owned },
+        })
+      } catch (error) {
+        if (generation !== ref.generation) return
+        dispatch({ type: 'error', error })
+        onErrorRef.current?.({ kind: 'connection', error })
       }
     })()
   }, [])
 
   useEffect(() => {
     const ref = bootRef.current
-    // The shell this provider will run with once the effect settles: a prebuilt
-    // Shell is the config object itself; a config-built one is whatever this
-    // instance already booted (adopted on a StrictMode/HMR re-setup). Cancel any
-    // pending deferred teardown for it before deciding — this also cancels a
-    // teardown another provider scheduled for the SAME prebuilt Shell.
     const current = configRef.current
     const adopting = isShellConfig(current) ? ref.shell : current
     if (adopting !== null) cancelTeardown(adopting)
-
     if (ref.key !== configKey) {
-      // First boot, config change, or a retry that cleared the key: reboot fresh.
       if (ref.shell !== null) {
         cancelTeardown(ref.shell)
         disposeShell(ref.shell)
@@ -134,12 +90,7 @@ export function ShellProvider(props: ShellProviderProps): ReactElement | null {
       ref.shell = null
       startBoot(ref)
     }
-    // Same key already booting/booted → adopt (StrictMode's second setup).
-
     return () => {
-      // Defer teardown one macrotask; a synchronous re-setup (StrictMode/HMR or a
-      // different provider adopting the same prebuilt Shell) cancels it first and
-      // keeps the same live shell.
       if (ref.shell !== null) scheduleTeardown(ref.shell, ref)
       else ref.key = null
     }
@@ -154,52 +105,32 @@ export function ShellProvider(props: ShellProviderProps): ReactElement | null {
     }
     ref.key = null
     dispatch({ type: 'connecting' })
-    setAttempt((a) => a + 1)
+    setAttempt((value) => value + 1)
   }, [])
 
-  // The base (default-scope) memory for the booted Shell — the SAME instance
-  // the graph/schema/nav hooks read through `graph/memory/scope.ts`. Seated in
-  // `GraphContext` so selection's liveness has a source; null until ready.
   const shell = state.runtime?.shell ?? null
-  const memory = useMemo<GraphMemory | null>(
-    () => (shell === null ? null : baseMemoryFor(shell)),
-    [shell],
-  )
-
-  // Bridge the memory's event channel onto the provider `onError` (API §2/§8):
-  // warm-refresh failures and rolled-back mutations surface here rather than being
-  // swallowed. Registered while the booted shell is live; cleared on teardown.
   useEffect(() => {
-    if (shell === null) return
-    setMemoryErrorSink(shell, (event) => {
-      const mapped = toShellError(event)
-      if (mapped !== null) onErrorRef.current?.(mapped)
-    })
-    return () => setMemoryErrorSink(shell, null)
-  }, [shell])
+    if (shell !== null) connectionStore(shell).setRetry(retry)
+  }, [shell, retry])
 
-  // Register this provider's boot-retry into the shell's connection store (rule 3),
-  // so `useConnection().retry` re-runs boot. Status/seq stay a stub ('ready'/0)
-  // until the transport-status + result-`seq` feed lands, with no surface change.
+  const store = state.runtime?.store ?? null
+  const storeScope = state.runtime?.storeScope ?? null
   useEffect(() => {
-    if (shell === null) return
-    connectionStore(shell).setRetry(retry)
-  }, [shell, retry])
+    if (shell === null || store === null || storeScope === null) return
+    return retainStore(storeFor(shell, storeScope))
+  }, [shell, store, storeScope])
 
   if (state.status === 'error') {
-    // Wrapped in a fragment so the component's declared return type stays
-    // `ReactElement | null` — valid JSX under @types/react 18 AND 19 (the react
-    // peer range is >=18), even though `errorFallback`/`fallback` yield ReactNode.
     if (errorFallback !== undefined) return <>{errorFallback(state.error, retry)}</>
     throw state.error
   }
   if (state.status !== 'ready' || state.runtime === null) {
-    return fallback !== undefined ? <>{fallback}</> : null
+    return fallback === undefined ? null : <>{fallback}</>
   }
 
   return (
     <ShellContext.Provider value={state.runtime}>
-      <GraphContext.Provider value={memory}>{children}</GraphContext.Provider>
+      <GraphContext.Provider value={state.runtime.store}>{children}</GraphContext.Provider>
     </ShellContext.Provider>
   )
 }

package/src/session/session.context.ts

@@ -1,3 +1,4 @@
+import type { GraphStore } from '@astrale-os/kernel-client/store'
 import type { KernelClient, Shell } from '@astrale-os/shell'
 
 /**
@@ -7,6 +8,8 @@ import type { KernelClient, Shell } from '@astrale-os/shell'
  */
 import { createContext } from 'react'
 
+import type { GraphStoreScope } from '../graph/store.js'
+
 /**
  * whoami's node type, derived from the auth surface so shell-react needs no
  * direct `@astrale-os/kernel-core` dependency (`Node` is not yet re-exported by
@@ -22,6 +25,9 @@ export interface ShellRuntime {
    * bound kernel exposes no auth surface (a bare prebuilt Shell in tests).
    */
   readonly self: SelfNode | null
+  readonly storeScope: GraphStoreScope
+  readonly store: GraphStore
+  readonly ownsStore: boolean
 }
 export const ShellContext = createContext<ShellRuntime | null>(null)
 ShellContext.displayName = 'AstraleShellContext'

package/src/window/adopt.ts

@@ -14,7 +14,6 @@ export interface AdoptRecord {
   readonly window: Window
   readonly slot: StageSlot
   readonly state: WindowState
-  readonly targetId: string | undefined
   /** Close the window, release its slot, drop it from the registry (fired if unadopted). */
   dispose(): void
 }

package/src/window/hooks/target-node.hook.ts

@@ -1,94 +1,29 @@
-import type { KernelClient } from '@astrale-os/shell'
+import type { Node } from '@astrale-os/sdk/graph/node'
 
-/**
- * useTargetNode (API §10) — inside a sandboxed view, the node it was opened on.
- * The id starts from `shell.targetNodeId` (handshake) and a host `setTarget`
- * intent retargets it; the id resolves to a live `Node` through the shell kernel.
- *
- * Honest subset (flagged): the read is a one-shot `kernel.get` re-run on id
- * change, not a memory watch, so `live` is false. Once composed with `useNode(id)`
- * it becomes real stale-while-revalidate liveness with no consumer change.
- */
-import { useCallback, useEffect, useRef, useState } from 'react'
+import { Path } from '@astrale-os/sdk/graph/path'
+import { useCallback, useMemo, useSyncExternalStore } from 'react'
 
-import type { ReadState } from '../../graph/memory/read/envelope.js'
-import type { Node } from '../lifecycle/mount.js'
+import type { GraphResource } from '../../graph/resource.js'
 
-import { idleReadState } from '../../graph/memory/read/idle.js'
+import { useDynamicObject } from '../../schema/object.hook.js'
 import { useShell } from '../../session/shell.hook.js'
 
-export interface NodeResult extends ReadState {
-  readonly node: Node | null
-}
-
-/** Address a bare node id by graph id (`@<id>`); pass paths/anchors through. */
-function toRef(id: string): string {
-  return id.startsWith('/') || id.startsWith('@') ? id : `@${id}`
-}
-
-interface ReadSnapshot {
-  readonly node: Node | null
-  readonly pending: boolean
-  readonly error: unknown
+/**
+ * Read the canonical target admitted by the parent handshake and subsequent
+ * parent-owned hot swaps without remounting this View document.
+ */
+export function useTargetNode(): GraphResource<Node | null> {
+  return useDynamicObject(useTargetPath())
 }
 
-const IDLE_READ: ReadSnapshot = { node: null, pending: false, error: undefined }
-
-export function useTargetNode(): NodeResult {
+/** Reactive canonical target Path; null represents an explicit parent clear. */
+export function useTargetPath(): Path | null {
   const shell = useShell()
-  const [id, setId] = useState<string | null>(() => shell.targetNodeId ?? null)
-
-  useEffect(() => {
-    const parent = shell.parent
-    if (parent === null) return
-    return parent.on('intent', (message) => {
-      if (message.envelope.name !== 'setTarget') return
-      const nodeId = (message.envelope.payload as { nodeId?: string }).nodeId
-      if (typeof nodeId === 'string') setId(nodeId)
-    })
-  }, [shell])
-
-  return useNodeRead(shell.kernel, id)
-}
-
-/** One-shot get + refetch, in the read envelope. The graph-module seam. */
-function useNodeRead(kernel: KernelClient, id: string | null): NodeResult {
-  const [snap, setSnap] = useState<ReadSnapshot>(IDLE_READ)
-  const aliveRef = useRef(true)
-  useEffect(() => {
-    aliveRef.current = true
-    return () => {
-      aliveRef.current = false
-    }
-  }, [])
-
-  const load = useCallback(async (): Promise<void> => {
-    if (id === null) {
-      if (aliveRef.current) setSnap(IDLE_READ)
-      return
-    }
-    if (aliveRef.current) setSnap((s) => ({ node: s.node, pending: true, error: undefined }))
-    try {
-      const node = await kernel.get(toRef(id))
-      if (aliveRef.current) setSnap({ node: node ?? null, pending: false, error: undefined })
-    } catch (error) {
-      if (aliveRef.current) setSnap((s) => ({ node: s.node, pending: false, error }))
-    }
-  }, [kernel, id])
-
-  useEffect(() => {
-    void load()
-  }, [load])
-
-  if (id === null) {
-    return { ...idleReadState(), node: null }
-  }
-  return {
-    node: snap.node,
-    pending: snap.pending,
-    error: snap.error,
-    live: false,
-    seq: 0,
-    refetch: load,
-  }
+  const subscribe = useCallback(
+    (listener: () => void) => shell.onTargetChange(() => listener()),
+    [shell],
+  )
+  const snapshot = useCallback(() => shell.targetNodeId, [shell])
+  const target = useSyncExternalStore(subscribe, snapshot, snapshot)
+  return useMemo(() => (target === undefined ? null : Path.parse(target)), [target])
 }

package/src/window/hooks/views-for.hook.ts

@@ -1,6 +1,8 @@
-import type { PathLike } from '@astrale-os/kernel-client/graph'
-import type { Shell } from '@astrale-os/shell'
+import type { Node } from '@astrale-os/sdk/graph/node'
+import type { NodePath, PathLike } from '@astrale-os/sdk/graph/path'
+import type { ResolvedView } from '@astrale-os/shell'
 
+import { Path } from '@astrale-os/sdk/graph/path'
 /**
  * useViewsFor (API §10) — "what Views can render this node", as mountable
  * `ViewDescriptor`s for the open-with menu. Backed one-shot (`live:false`) by the
@@ -10,23 +12,22 @@ import type { Shell } from '@astrale-os/shell'
 import { useMemo } from 'react'
 
 import type { ReadState } from '../../graph/memory/read/envelope.js'
-import type { Node, ViewDescriptor } from '../lifecycle/mount.js'
 
 import { useAsyncResource } from '../../graph/async.js'
 import { useShell } from '../../session/shell.hook.js'
 
 export interface ViewsForResult extends ReadState {
-  readonly views: readonly ViewDescriptor[]
+  readonly views: readonly ResolvedView[]
 }
 
-const NO_VIEWS: readonly ViewDescriptor[] = Object.freeze([])
+const NO_VIEWS: readonly ResolvedView[] = Object.freeze([])
 
 export function useViewsFor(node: Node | PathLike | null | undefined): ViewsForResult {
   const shell = useShell()
   const target = resolvePath(node)
 
-  const res = useAsyncResource<readonly ViewDescriptor[]>(
-    target === null ? null : () => resolveViews(shell, target),
+  const res = useAsyncResource<readonly ResolvedView[]>(
+    target === null ? null : () => shell.views.resolve(target),
     NO_VIEWS,
     [shell, target],
   )
@@ -44,23 +45,9 @@ export function useViewsFor(node: Node | PathLike | null | undefined): ViewsForR
   )
 }
 
-/** Dispatch `View.resolve` and project its rows to mountable `ViewDescriptor`s. */
-async function resolveViews(shell: Shell, node: string): Promise<readonly ViewDescriptor[]> {
-  const rows = await shell.views.resolve(node)
-  if (rows.length === 0) return NO_VIEWS
-  return rows.map((r) => ({ id: r.id, path: r.path, url: r.url, handshake: r.handshake }))
-}
-
-/** A path/`@id` the kernel read surface accepts, or `null` for an idle subject. */
-function resolvePath(node: Node | PathLike | null | undefined): string | null {
+/** One canonical target, or `null` for an idle subject. */
+function resolvePath(node: Node | PathLike | null | undefined): NodePath | null {
   if (node === null || node === undefined) return null
-  if (typeof node === 'string') {
-    if (node.length === 0) return null
-    return node.startsWith('/') || node.startsWith('@') ? node : `@${node}`
-  }
-  const obj = node as { path?: { raw?: unknown }; id?: unknown; raw?: unknown }
-  if (typeof obj.path?.raw === 'string') return obj.path.raw
-  if (typeof obj.id === 'string') return `@${obj.id}`
-  if (typeof obj.raw === 'string') return obj.raw
-  return null
+  if ('id' in node) return Path.id(node.id).raw
+  return Path.from(node).raw
 }

package/src/window/hooks/windows.hook.ts

@@ -2,10 +2,9 @@ import type { Window } from '@astrale-os/shell'
 
 /**
  * useWindows / useWindowList (API §10) — reactive views over the windows a
- * `ViewHost`/`AppHost` mounts through the per-shell hub. The shell exposes no
- * window-change feed, so the hub registry (fed by the hosts) is the reactive
- * source; windows mounted imperatively via `shell.mount` outside React are not
- * tracked here — flagged in the module report as a shell foundation gap.
+ * `ViewHost`/`AppHost` or the framework-neutral Shell mounts. The hub mirrors
+ * Shell's immutable window-change feed, so credential, location, lifecycle,
+ * and imperative mounts remain reactive through one snapshot authority.
  */
 import { useMemo, useSyncExternalStore } from 'react'