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

package/src/graph/store.ts

@@ -0,0 +1,97 @@
+import type { GraphApi } from '@astrale-os/kernel-client/graph'
+import type { GraphStore as GraphStoreValue } from '@astrale-os/kernel-client/store'
+import type { Shell } from '@astrale-os/shell'
+
+import { GraphStore } from '@astrale-os/kernel-client/store'
+import { useContext } from 'react'
+
+import { GraphContext } from './graph.context.js'
+
+interface StoreEntry {
+  readonly shell: Shell
+  readonly graph: GraphApi
+  readonly scope: string
+  readonly store: GraphStoreValue
+  readonly owned: boolean
+  retained: number
+  generation: number
+}
+
+const entries = new WeakMap<Shell, StoreEntry>()
+
+/** Authority/schema identity. Session ids and Publication ETags are deliberately absent. */
+export interface GraphStoreScope {
+  readonly authority: string
+  readonly schemaRevision: string
+}
+
+type StoreIdentity = Awaited<ReturnType<Shell['kernel']['auth']['whoami']>>
+
+export async function resolveGraphStoreScope(
+  shell: Shell,
+  knownIdentity?: StoreIdentity | null,
+): Promise<GraphStoreScope> {
+  const [identity, snapshot] = await Promise.all([
+    knownIdentity === undefined
+      ? shell.kernel.auth.whoami().catch(() => null)
+      : Promise.resolve(knownIdentity),
+    shell.kernel.snapshot(),
+  ])
+  return Object.freeze({
+    authority:
+      identity === null
+        ? 'anonymous'
+        : `${identity.issuer}\u0000${identity.subject}\u0000${identity.id}`,
+    schemaRevision: snapshot.publication.schema.revision,
+  })
+}
+
+export function storeFor(shell: Shell, scope: GraphStoreScope): StoreEntry {
+  const current = entries.get(shell)
+  const scopeKey = `${scope.authority}\u0000${scope.schemaRevision}`
+  if (current !== undefined && current.graph === shell.kernel.graph && current.scope === scopeKey) {
+    return current
+  }
+  const supplied = shell.kernel.store
+  const created: StoreEntry = {
+    shell,
+    graph: shell.kernel.graph,
+    scope: scopeKey,
+    // A supplied Store is trusted only for the KernelClient's first declared scope. A later
+    // authority/revision/GraphApi replacement gets a new Store and cannot inherit old memory.
+    store:
+      current === undefined && supplied !== undefined
+        ? supplied
+        : new GraphStore({ graph: shell.kernel.graph }),
+    owned: current !== undefined || supplied === undefined,
+    retained: 0,
+    generation: 0,
+  }
+  entries.set(shell, created)
+  if (current !== undefined && current.retained === 0 && current.owned) current.store.close()
+  return created
+}
+
+export function retainStore(entry: StoreEntry): () => void {
+  entry.generation += 1
+  entry.retained += 1
+  let released = false
+  return () => {
+    if (released) return
+    released = true
+    entry.retained -= 1
+    const generation = ++entry.generation
+    queueMicrotask(() => {
+      if (entry.retained !== 0 || entry.generation !== generation || !entry.owned) return
+      if (entries.get(entry.shell) === entry) entries.delete(entry.shell)
+      entry.store.close()
+    })
+  }
+}
+
+/** The exact caller/schema-scoped GraphStore for the current View subtree. */
+export function useGraphStore(): GraphStoreValue {
+  const store = useContext(GraphContext)
+  if (store === null) throw new Error('useGraphStore must be used within a <ShellProvider>')
+  return store
+}

package/src/host/actions.hook.ts

@@ -0,0 +1,165 @@
+import type {
+  AccessRequest,
+  AccessResult,
+  ExternalOpenRequest,
+  ExternalOpenResult,
+  HostCapabilities,
+  ModalRequest,
+  ModalResult,
+  NotificationRequest,
+  NotificationResult,
+  OpenViewRequest,
+  OpenViewResult,
+} from '@astrale-os/shell'
+
+import { useMemo } from 'react'
+
+import { useSendIntent } from '../intents/send-intent.hook.js'
+import { useShell } from '../session/shell.hook.js'
+
+export function useHostCapabilities(): HostCapabilities {
+  return useShell().hostCapabilities
+}
+
+export class HostCapabilityUnavailableError extends Error {
+  readonly code = 'SHELL_REACT_HOST_CAPABILITY_UNAVAILABLE' as const
+  constructor(readonly capability: string) {
+    super(`Host capability '${capability}' is unavailable.`)
+    this.name = 'HostCapabilityUnavailableError'
+  }
+}
+
+export interface HostDialogApi {
+  readonly supported: boolean
+  open(request: ModalRequest): Promise<ModalResult>
+  confirm(request: Omit<ModalRequest, 'nested'>): Promise<boolean>
+}
+
+export function useHostDialog(): HostDialogApi {
+  const capabilities = useHostCapabilities()
+  const send = useSendIntent()
+  return useMemo(
+    () => ({
+      supported: capabilities.actions.modal !== undefined,
+      open: (request: ModalRequest) => {
+        if (capabilities.actions.modal === undefined) return unsupported('actions.modal')
+        portable(request)
+        return send('actions.modal', request)
+      },
+      confirm: async (request: Omit<ModalRequest, 'nested'>) => {
+        if (capabilities.actions.modal === undefined) return unsupported('actions.modal')
+        portable(request)
+        return (await send('actions.modal', request)).outcome === 'confirmed'
+      },
+    }),
+    [capabilities, send],
+  )
+}
+
+export interface NotifyApi {
+  (request: NotificationRequest): Promise<NotificationResult>
+  readonly supported: boolean
+}
+
+export function useNotify(): NotifyApi {
+  const capabilities = useHostCapabilities()
+  const send = useSendIntent()
+  return useMemo(() => {
+    const notify = ((request: NotificationRequest) => {
+      if (capabilities.actions.notify === undefined) return unsupported('actions.notify')
+      portable(request)
+      return send('actions.notify', request)
+    }) as NotifyApi
+    Object.defineProperty(notify, 'supported', {
+      enumerable: true,
+      value: capabilities.actions.notify !== undefined,
+    })
+    return notify
+  }, [capabilities, send])
+}
+
+export interface OpenViewApi {
+  (request: OpenViewRequest): Promise<OpenViewResult>
+  readonly supported: boolean
+}
+
+export function useOpenView(): OpenViewApi {
+  const capabilities = useHostCapabilities()
+  const send = useSendIntent()
+  return useMemo(() => {
+    const open = ((request: OpenViewRequest) => {
+      if (capabilities.navigation.openView === undefined) return unsupported('view.open')
+      portable(request)
+      return send('view.open', request)
+    }) as OpenViewApi
+    Object.defineProperty(open, 'supported', {
+      enumerable: true,
+      value: capabilities.navigation.openView !== undefined,
+    })
+    return open
+  }, [capabilities, send])
+}
+
+export interface ExternalOpenApi {
+  (request: ExternalOpenRequest): Promise<ExternalOpenResult>
+  readonly supported: boolean
+}
+
+export function useExternalOpen(): ExternalOpenApi {
+  const capabilities = useHostCapabilities()
+  const send = useSendIntent()
+  return useMemo(() => {
+    const open = ((request: ExternalOpenRequest) => {
+      if (capabilities.navigation.external === undefined) return unsupported('browser.openExternal')
+      portable(request)
+      return send('browser.openExternal', request)
+    }) as ExternalOpenApi
+    Object.defineProperty(open, 'supported', {
+      enumerable: true,
+      value: capabilities.navigation.external !== undefined,
+    })
+    return open
+  }, [capabilities, send])
+}
+
+export interface RequestAccessApi {
+  (request: AccessRequest): Promise<AccessResult>
+  readonly supported: boolean
+}
+
+export function useRequestAccess(): RequestAccessApi {
+  const capabilities = useHostCapabilities()
+  const send = useSendIntent()
+  return useMemo(() => {
+    const request = ((input: AccessRequest) => {
+      if (capabilities.access.request === undefined) return unsupported('access.request')
+      portable(input)
+      return send('access.request', input)
+    }) as RequestAccessApi
+    Object.defineProperty(request, 'supported', {
+      enumerable: true,
+      value: capabilities.access.request !== undefined,
+    })
+    return request
+  }, [capabilities, send])
+}
+
+function unsupported<Result>(capability: string): Promise<Result> {
+  return Promise.reject(new HostCapabilityUnavailableError(capability))
+}
+
+function portable(input: unknown): void {
+  const seen = new WeakSet<object>()
+  const visit = (value: unknown): void => {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') return
+    if (typeof value === 'number' && Number.isFinite(value)) return
+    if (typeof value !== 'object' || ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+      throw new TypeError('Host action payload must be serializable data.')
+    }
+    if (seen.has(value)) throw new TypeError('Host action payload cannot contain cycles.')
+    seen.add(value)
+    if (Array.isArray(value)) value.forEach(visit)
+    else Object.values(value).forEach(visit)
+  }
+  visit(input)
+}

package/src/host/components.tsx

@@ -0,0 +1,29 @@
+import type { ReactElement, ReactNode } from 'react'
+
+import type { HostDialogApi, NotifyApi, OpenViewApi, RequestAccessApi } from './actions.hook.js'
+
+import { useHostDialog, useNotify, useOpenView, useRequestAccess } from './actions.hook.js'
+
+export function HostDialog(props: {
+  readonly children: (dialog: HostDialogApi) => ReactNode
+}): ReactElement {
+  return <>{props.children(useHostDialog())}</>
+}
+
+export function Notify(props: {
+  readonly children: (notify: NotifyApi) => ReactNode
+}): ReactElement {
+  return <>{props.children(useNotify())}</>
+}
+
+export function NestedView(props: {
+  readonly children: (open: OpenViewApi) => ReactNode
+}): ReactElement {
+  return <>{props.children(useOpenView())}</>
+}
+
+export function RequestAccess(props: {
+  readonly children: (request: RequestAccessApi) => ReactNode
+}): ReactElement {
+  return <>{props.children(useRequestAccess())}</>
+}

package/src/host/index.ts

@@ -0,0 +1,17 @@
+export {
+  useExternalOpen,
+  useHostCapabilities,
+  useHostDialog,
+  useNotify,
+  useOpenView,
+  useRequestAccess,
+} from './actions.hook.js'
+export type {
+  ExternalOpenApi,
+  HostDialogApi,
+  NotifyApi,
+  OpenViewApi,
+  RequestAccessApi,
+} from './actions.hook.js'
+export { HostDialog, NestedView, Notify, RequestAccess } from './components.js'
+export { HostCapabilityUnavailableError } from './actions.hook.js'

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,33 @@ export type {
   SendIntent,
 } from './intents/index.js'
 
-// ─── application — the OS plane (§12) ────────────────────────────────────────
+// Headless composition kit.
+export {
+  Can,
+  ConnectionBoundary,
+  CredentialBoundary,
+  defaultViewError,
+  defaultViewLoading,
+  GraphBoundary,
+  mountDomainFrontend,
+  ViewApp,
+  ViewBoundary,
+  ViewErrorBoundary,
+} from './components/index.js'
+export type {
+  MountedDomainFrontend,
+  MountDomainFrontendOptions,
+  ViewErrorBoundaryProps,
+} from './components/index.js'
+
+// Shell application conveniences.
 export {
   AppHost,
   AppLogo,
   useApps,
   useCurrentSpace,
+  useInstalledDomains,
   useOpenApp,
-  useRoles,
-  useDomains,
   useSpace,
   useSpaces,
   useUser,
@@ -147,73 +195,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'