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

package/src/index.ts

@@ -1,82 +1,90 @@
-/**
- * @astrale-os/shell-react — the React face of the shell (SHELL_REACT_API.md §0).
- * One package, one import surface (SPEC §4.2); the bounded-context directories are
- * the module structure, not subpaths. This public barrel composes the context
- * barrels. Settled naming (§0): useKernelClient = the raw handle (session);
- * useKernel() = the TYPED kernel (schema, no arg); useDomain(schema) = a typed
- * domain binding. `useNode`/`useChildren` are single overloaded symbols (untyped
- * floor + typed overloads) exported from the graph plane.
- */
+/** @astrale-os/shell-react — curated React runtime over Shell and Kernel Client Store. */
 
-// ─── session (§2 provider + §3) ──────────────────────────────────────────────
-export { ShellProvider } from './session/index.js'
-export type { ShellError, ShellProviderProps } from './session/index.js'
-export { useConnection, useKernelClient, useKernelInstance, useShell } from './session/index.js'
-export type { KernelInstance } from './session/index.js'
-
-// ─── auth (§4) ───────────────────────────────────────────────────────────────
+// Root/provider and authenticated caller.
+export {
+  ShellProvider,
+  useConnection,
+  useKernelClient,
+  useKernelInstance,
+  useShell,
+} from './session/index.js'
+export type { KernelInstance, ShellError, ShellProviderProps } from './session/index.js'
 export { ActAs, useAuth, useCan, useSelf } from './auth/index.js'
-export type { ActAsProps } from './auth/index.js'
+export type { ActAsProps, PolicyObject } from './auth/index.js'
 
-// ─── graph — the untyped floor + writes + dispatch (§5, §7) ──────────────────
-// `useNode`/`useChildren` are single symbols merging the untyped floor + typed
-// overloads.
+// One Store path and named SDK definitions. Raw Query/Mutation builders are intentionally absent.
 export {
+  ClientError,
+  NodeUnavailableError,
+  ProtocolError,
+  ResponseError,
+  StaleRouteError,
+  TransportError,
+  isClientError,
+  isNodeUnavailableError,
   useCall,
-  useChildren,
-  useGraph,
-  useMove,
-  useMutate,
-  useNode,
+  useGraphStore,
   useQuery,
   useStream,
 } from './graph/index.js'
 export type {
-  ChildrenOptions,
-  ChildrenResult,
-  GraphMemory,
-  MoveAction,
-  Node,
-  NodeResult,
-  QueryResult,
-  ShapeInput,
-  UseMutateOptions,
+  CallOptions,
+  GraphResource,
+  GraphResourceState,
+  GraphStore,
+  QueryResourceOptions,
+  StreamHandle,
+  StreamOptions,
 } from './graph/index.js'
-export type { CallOptions, StreamHandle, StreamOptions } from './graph/index.js'
 
-// ─── schema — the typed substrate (§6) ───────────────────────────────────────
-export { useDomain, useFunction, useIn, useKernel, useMethod, useOut } from './schema/index.js'
-export type { FunctionOptions } from './schema/index.js'
-export type { MethodOptions } from './schema/index.js'
+// Rich exact Domain bindings.
+export {
+  RelationUnavailableError,
+  queryRefresh,
+  useAction,
+  useDomain,
+  useDomains,
+  useDynamicDomain,
+  useDynamicObject,
+  useKernel,
+  useMutation,
+  useObject,
+  useRelation,
+} from './schema/index.js'
 export type {
-  AutoMethodAction,
-  BoundMethodAction,
-  EndpointResult,
-  FunctionNames,
-  FunctionParams,
-  FunctionResult,
-  MethodIsStatic,
-  MethodNames,
-  MethodParams,
-  MethodResult,
-  TargetedMethodAction,
-  TypedChildrenResult,
-  TypedNodeResult,
+  ActionOptions,
+  ActionRefresh,
+  DomainAction,
+  MutationOptions,
+  QueryRefresh,
+  RelationOptions,
+  RelationResource,
+  RelationUnavailable,
+  RichReadOptions,
 } from './schema/index.js'
 
-// ─── navigation (§8) ─────────────────────────────────────────────────────────
+// Typed navigation and selection.
 export {
   Link,
+  NavigationScope,
   NavScope,
+  NodeLink,
+  pathParam,
+  ViewLink,
+  defineNavigation,
+  enumParam,
+  location,
   memoryAdapter,
   urlAdapter,
   useAncestors,
   useLocation,
-  useNavScope,
   useNavigate,
+  useNavigation,
+  useNavScope,
 } from './navigation/index.js'
 export type {
   LinkProps,
+  LocationDefinition,
   MissingPolicy,
   NavAdapter,
   NavLocation,
@@ -84,41 +92,63 @@ export type {
   NavScopeProps,
   NavSnapshot,
   NavTarget,
+  NavigationDefinition,
+  NavigationParam,
+  NavigationParams,
+  NavigationRoutes,
+  NavigationTarget,
+  NodeLinkProps,
   Navigate,
   SerializedLocation,
+  ViewLinkProps,
 } from './navigation/index.js'
-
-// ─── selection (§9) ──────────────────────────────────────────────────────────
 export { SelectionScope, useSelection } from './selection/index.js'
 export type { Selection, SelectionScopeProps } from './selection/index.js'
 
-// ─── window (§10) ────────────────────────────────────────────────────────────
+// View/window lifecycle and host effects.
 export {
+  ViewHost,
+  ViewStage,
   useCloseGuard,
   useTargetNode,
+  useTargetPath,
   useViewsFor,
   useWindow,
   useWindowList,
   useWindows,
-  ViewHost,
-  ViewStage,
 } from './window/index.js'
 export type {
   CloseGuard,
   CloseVerdict,
-  ResolvedSource,
+  ResolvedView,
   SandboxPolicy,
-  ViewDescriptor,
-  ViewHostProps,
-  ViewSource,
   ViewHostHandle,
+  ViewHostProps,
   ViewsForResult,
   WindowListEntry,
   WindowState,
   WindowView,
 } from './window/index.js'
-
-// ─── intents (§11) ───────────────────────────────────────────────────────────
+export {
+  HostDialog,
+  NestedView,
+  Notify,
+  RequestAccess,
+  useExternalOpen,
+  useHostCapabilities,
+  useHostDialog,
+  useNotify,
+  useOpenView,
+  useRequestAccess,
+} from './host/index.js'
+export type {
+  ExternalOpenApi,
+  HostDialogApi,
+  NotifyApi,
+  OpenViewApi,
+  RequestAccessApi,
+} from './host/index.js'
+export { HostCapabilityUnavailableError } from './host/index.js'
 export { useEmitIntent, useIntent, useSendIntent } from './intents/index.js'
 export type {
   EmitIntent,
@@ -128,15 +158,28 @@ export type {
   SendIntent,
 } from './intents/index.js'
 
-// ─── application — the OS plane (§12) ────────────────────────────────────────
+// Headless composition kit.
+export {
+  Can,
+  ConnectionBoundary,
+  CredentialBoundary,
+  defaultViewError,
+  defaultViewLoading,
+  GraphBoundary,
+  Astrale,
+  ViewBoundary,
+  ViewErrorBoundary,
+} from './components/index.js'
+export type { AstraleProps, ViewErrorBoundaryProps } from './components/index.js'
+
+// Shell application conveniences.
 export {
   AppHost,
   AppLogo,
   useApps,
   useCurrentSpace,
+  useInstalledDomains,
   useOpenApp,
-  useRoles,
-  useDomains,
   useSpace,
   useSpaces,
   useUser,
@@ -147,73 +190,37 @@ export type {
   AppLogoProps,
   AppsResult,
   CurrentSpaceResult,
-  RolesResult,
   DomainsResult,
   SpaceResult,
   SpacesResult,
 } from './application/index.js'
-// OS node/session types (from the shell package, single import surface).
-export type {
-  ApplicationNode,
-  AppSession,
-  DomainSearchResult,
-  RoleNode,
-  SpaceNode,
-  UserNode,
-} from '@astrale-os/shell'
-
-// ─── shared envelopes (§1) ───────────────────────────────────────────────────
-export type { Action, ReadState, ReadOptions, Windowed } from './graph/index.js'
 
-// ─── error taxonomy (§1.4) — guards + classes, re-exported from kernel-client ─
-export * from './graph/guards.error.js'
+// Canonical identity carriers used by View props and rich hooks.
+export { NodeId } from '@astrale-os/sdk/graph/node'
+export { NodePath, Path } from '@astrale-os/sdk/graph/path'
+export type { Node } from '@astrale-os/sdk/graph/node'
+export type { PathLike } from '@astrale-os/sdk/graph/path'
+export type { AuthApi, Identity, PolicyDecisionInput } from '@astrale-os/kernel-client/auth'
+export type { DomainBinding, DomainInvokeOptions } from '@astrale-os/shell'
 
-// ─── re-exported kernel-client types (one import surface, §0 preamble) ───────
-export {
-  DESCRIPTION_KEY,
-  NAME_KEY,
-  STATUS_KEY,
-  descriptionOf,
-  nameOf,
-  normalizeRef,
-  statusOf,
-} from '@astrale-os/kernel-client'
-export type {
-  AnyBoundNode,
-  BoundNode,
-  CreatableClassNames,
-  CreateProps,
-  CredentialInput,
-  DefOf,
-  EdgeNames,
-  EndpointsOf,
-  FnMap,
-  NamedNodeLike,
-  NodeRefInput,
-  SchemaBoundView,
-  TypeNames,
-} from '@astrale-os/kernel-client'
-export type {
-  EdgeIdentity,
-  GatherBuilder,
-  OrderInput,
-  PatchBuilder,
-  PatchInput,
-  PathLike,
-  Properties,
-  QueryASTInput,
-  QuerySource,
-} from '@astrale-os/kernel-client/graph'
-export type { AuthApi, Perms } from '@astrale-os/kernel-client/auth'
-export type { Schema } from '@astrale-os/kernel-dsl'
-
-// ─── re-exported shell types (one import surface, SPEC §4.2) ──────────────────
+// Shell contracts retained at the package root for custom full-app composition.
 export type {
+  ApplicationNode,
+  AppSession,
   CloseResult,
+  CredentialSnapshot,
+  DomainSearchResult,
+  HostCapabilities,
+  IntentRegistry,
   KernelClient,
   MountCredential,
+  NodeTarget,
   Shell,
   ShellConfig,
+  SpaceNode,
+  UserNode,
+  ViewLocation,
+  ViewPresentation,
+  ViewPresentationRequest,
   Window,
 } from '@astrale-os/shell'
-export type { IntentRegistry } from '@astrale-os/shell'

package/src/intents/envelope.ts

@@ -3,28 +3,13 @@
  * a registry entry, the wire constants, and `intentMessage` — the single builder
  * both directions (send + reply) share.
  */
-import type { IntentMessage, IntentRegistry } from '@astrale-os/shell'
+import type { IntentMessage, IntentRegistry, PayloadOf, ReplyOf } from '@astrale-os/shell'
 
-/**
- * Payload of a registry entry: the `{ payload }` field for the wrapped shape,
- * else the whole entry (a legacy bare-payload augmentation). Robust to both, so
- * bare augmentations keep compiling unchanged.
- */
-export type IntentPayload<K extends keyof IntentRegistry> = IntentRegistry[K] extends {
-  payload: infer P
-}
-  ? P
-  : IntentRegistry[K]
+/** Payload declared by the canonical Shell intent registry entry. */
+export type IntentPayload<K extends keyof IntentRegistry> = PayloadOf<K>
 
-/**
- * Reply of a registry entry: the `{ reply }` field when declared, else `void`
- * (bare-payload and today's reply-less entries — forward-compatible with G4).
- */
-export type IntentReply<K extends keyof IntentRegistry> = IntentRegistry[K] extends {
-  reply: infer R
-}
-  ? R
-  : void
+/** Reply declared by the canonical Shell intent registry entry. */
+export type IntentReply<K extends keyof IntentRegistry> = ReplyOf<K>
 
 /** Sentinel `ctx.sender` carries for a parent-delivered intent (the shell stamps it). */
 export const PARENT_SENDER = '<parent>'
@@ -35,9 +20,8 @@ export const INTENT_REPLY = 'intentReply'
 export const NOOP = (): void => {}
 
 /**
- * Build an intent wire message. Bare-vs-wrapped payload variance (§11 pin) is
- * erased on the wire — the receiver reads `envelope.payload` verbatim; the cast
- * bridges the correlated name↔payload the union type cannot express.
+ * Build an intent wire message. The cast bridges the correlated name↔payload
+ * relation that the generic union type cannot express.
  */
 export function intentMessage(
   name: string,

package/src/intents/send-intent.hook.ts

@@ -1,108 +1,53 @@
-import type { IntentMessage, IntentRegistry } from '@astrale-os/shell'
+import type { IntentRegistry, RequestIntentOptions } from '@astrale-os/shell'
 
-/**
- * useSendIntent (API §11) — a stable typed sender. Each call attaches a
- * `correlationId`, subscribes for the matching `intentReply` on the origin channel
- * BEFORE sending, then resolves with the reply's result. The promise also resolves
- * (`void`) if the target window closes or this hook unmounts — a pending reply
- * never strands.
- */
+import { requestChildIntent, requestIntent } from '@astrale-os/shell'
 import { useCallback, useEffect, useRef } from 'react'
 
 import type { IntentPayload, IntentReply } from './envelope.js'
 
 import { useShell } from '../session/shell.hook.js'
-import { INTENT_REPLY, NOOP, intentMessage } from './envelope.js'
 import { resolveIntentTarget } from './resolve-intent-target.js'
 
-/** The typed sender returned by {@link useSendIntent}. */
+/** Typed request sender backed exclusively by Shell's core correlation implementation. */
 export interface SendIntent {
   <K extends keyof IntentRegistry>(
     name: K,
     payload: IntentPayload<K>,
-    /** `to`: `'parent'` (reserved) or a child windowId. Default: the parent, if any. */
-    opts?: { to?: 'parent' | string },
-  ): Promise<IntentReply<K> | void>
+    options?: RequestIntentOptions & { readonly to?: 'parent' | string },
+  ): Promise<IntentReply<K>>
 }
 
 export function useSendIntent(): SendIntent {
   const shell = useShell()
-  // Unmount settlers for in-flight sends, so a pending reply resolves on teardown.
-  const pendingRef = useRef<Set<() => void>>(new Set())
+  const lifetime = useRef(new AbortController())
+
   useEffect(() => {
-    const pending = pendingRef.current
-    return () => {
-      for (const settle of pending) settle()
-      pending.clear()
-    }
+    const controller = lifetime.current.signal.aborted ? new AbortController() : lifetime.current
+    lifetime.current = controller
+    return () => controller.abort(new Error('Intent requester unmounted'))
   }, [])
 
   return useCallback(
     <K extends keyof IntentRegistry>(
       name: K,
       payload: IntentPayload<K>,
-      opts?: { to?: 'parent' | string },
-    ): Promise<IntentReply<K> | void> => {
-      const target = resolveIntentTarget(shell, opts?.to)
+      options?: RequestIntentOptions & { readonly to?: 'parent' | string },
+    ): Promise<IntentReply<K>> => {
+      const target = resolveIntentTarget(shell, options?.to)
       if (target.kind === 'invalid') {
         return Promise.reject(new Error(`useSendIntent: ${target.reason}`))
       }
-      const correlationId = crypto.randomUUID()
-      const message = intentMessage(name, payload, correlationId)
-      const pending = pendingRef.current
-
-      return new Promise<IntentReply<K> | void>((resolve, reject) => {
-        let done = false
-        let offReply = NOOP
-        let offClose = NOOP
-        const onUnmount = (): void => settle(undefined)
-        function settle(value: IntentReply<K> | void): void {
-          if (done) return
-          done = true
-          offReply()
-          offClose()
-          pending.delete(onUnmount)
-          resolve(value)
-        }
-        function fail(error: Error): void {
-          if (done) return
-          done = true
-          offReply()
-          offClose()
-          pending.delete(onUnmount)
-          reject(error)
-        }
-        const onReply = (m: IntentMessage): void => {
-          if (m.envelope.name !== INTENT_REPLY) return
-          const reply = m.envelope.payload as {
-            correlationId: string
-            result?: unknown
-            error?: { message: string }
-          }
-          if (reply.correlationId !== correlationId) return
-          if (reply.error) {
-            fail(new Error(reply.error.message))
-            return
-          }
-          settle(reply.result as IntentReply<K>)
-        }
-
-        pending.add(onUnmount)
-        if (target.kind === 'parent') {
-          const parent = shell.parent!
-          offReply = parent.on('intent', onReply)
-          parent.send(message)
-        } else {
-          const { windowId } = target
-          offReply = shell.children.on('intent', (wid, m) => {
-            if (wid === windowId) onReply(m)
-          })
-          offClose = shell.children.onClose((wid) => {
-            if (wid === windowId) settle(undefined)
-          })
-          shell.children.send(windowId, message)
-        }
-      })
+      const signal =
+        options?.signal === undefined
+          ? lifetime.current.signal
+          : AbortSignal.any([lifetime.current.signal, options.signal])
+      const requestOptions: RequestIntentOptions = {
+        signal,
+        ...(options?.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+      }
+      return target.kind === 'parent'
+        ? requestIntent(shell.parent!, name, payload, requestOptions)
+        : requestChildIntent(shell.children, target.windowId, name, payload, requestOptions)
     },
     [shell],
   )

package/src/navigation/adapters/adapter.ts

@@ -6,8 +6,11 @@
 import type { SerializedLocation } from '../history.js'
 
 export interface NavAdapter {
+  readonly kind: 'memory' | 'browser'
   read(): SerializedLocation | null
   write(loc: SerializedLocation, opts: { replace: boolean }): void
+  /** Remove only this adapter's owned projection when no history entry survives. */
+  clear(opts: { replace: boolean }): void
   subscribe(onExternalChange: () => void): () => void
   href?(loc: SerializedLocation): string
 }

package/src/navigation/adapters/memory.adapter.ts

@@ -10,10 +10,14 @@ export function memoryAdapter(initial?: SerializedLocation): NavAdapter {
   let current: SerializedLocation | null = initial ?? null
   const listeners = new Set<() => void>()
   return {
+    kind: 'memory',
     read: () => current,
     write: (loc) => {
       current = loc
     },
+    clear: () => {
+      current = null
+    },
     subscribe: (cb) => {
       listeners.add(cb)
       return () => listeners.delete(cb)

package/src/navigation/adapters/url.adapter.ts

@@ -1,3 +1,6 @@
+import { NodePath } from '@astrale-os/sdk/graph/path'
+import { Key } from '@astrale-os/sdk/schema'
+
 /**
  * urlAdapter (API §8.1) — the History-API adapter: mirrors the location into the
  * query string (URL form → `<a href>`), owning the nav query keys (`param`,
@@ -6,35 +9,62 @@
 import type { SerializedLocation } from '../history.js'
 import type { NavAdapter } from './adapter.js'
 
-const VIEW_KEY = 'view'
+const VIEW_KEY = 'astrale.view'
+const PARAM_PREFIX = 'astrale.param.'
 
 /** History-API adapter — the location lives in the query string. */
 export function urlAdapter(opts?: { param?: string }): NavAdapter {
-  const param = opts?.param ?? 'node'
+  const param = opts?.param ?? 'astrale.node'
   const hasWindow = (): boolean => typeof window !== 'undefined'
 
   const build = (loc: SerializedLocation): string => {
     const url = new URL(window.location.href)
-    const sp = new URLSearchParams()
+    const sp = url.searchParams
     sp.set(param, loc.node)
     if (loc.view !== undefined) sp.set(VIEW_KEY, loc.view)
+    else sp.delete(VIEW_KEY)
+    for (const key of sp.keys()) if (key.startsWith(PARAM_PREFIX)) sp.delete(key)
     for (const [k, v] of Object.entries(loc.params ?? {})) {
-      if (k !== param && k !== VIEW_KEY) sp.set(k, v)
+      if (isSensitive(k)) throw new TypeError(`Navigation param '${k}' is sensitive.`)
+      sp.set(`${PARAM_PREFIX}${k}`, v)
     }
     url.search = sp.toString()
     return `${url.pathname}${url.search}${url.hash}`
   }
 
+  const clear = (): string => {
+    const url = new URL(window.location.href)
+    const sp = url.searchParams
+    sp.delete(param)
+    sp.delete(VIEW_KEY)
+    for (const key of sp.keys()) if (key.startsWith(PARAM_PREFIX)) sp.delete(key)
+    url.search = sp.toString()
+    return `${url.pathname}${url.search}${url.hash}`
+  }
+
   return {
+    kind: 'browser',
     read() {
       if (!hasWindow()) return null
       const sp = new URL(window.location.href).searchParams
-      const node = sp.get(param)
-      if (node === null) return null
-      const view = sp.get(VIEW_KEY) ?? undefined
+      const rawNode = sp.get(param)
+      if (rawNode === null) return null
+      let node
+      let view
+      try {
+        node = NodePath(rawNode)
+        const rawView = sp.get(VIEW_KEY)
+        if (rawView !== null) {
+          const admitted = Key(rawView)
+          if (!Key.ref(admitted).startsWith('view.')) throw new TypeError('Invalid View key.')
+          view = admitted as Key.View
+        }
+      } catch {
+        return null
+      }
       const params: Record<string, string> = {}
       for (const [k, v] of sp) {
-        if (k !== param && k !== VIEW_KEY) params[k] = v
+        if (k.startsWith(PARAM_PREFIX)) params[k.slice(PARAM_PREFIX.length)] = v
       }
       return {
         node,
@@ -48,6 +78,12 @@ export function urlAdapter(opts?: { param?: string }): NavAdapter {
       if (replace) window.history.replaceState(null, '', href)
       else window.history.pushState(null, '', href)
     },
+    clear({ replace }) {
+      if (!hasWindow()) return
+      const href = clear()
+      if (replace) window.history.replaceState(null, '', href)
+      else window.history.pushState(null, '', href)
+    },
     subscribe(cb) {
       if (!hasWindow()) return () => undefined
       const handler = (): void => cb()
@@ -59,3 +95,7 @@ export function urlAdapter(opts?: { param?: string }): NavAdapter {
     },
   }
 }
+
+function isSensitive(key: string): boolean {
+  return /token|credential|authorization|secret/i.test(key)
+}