@astrale-os/shell-react 0.1.0

package/dist/application/spaces/current-space.store.js

@@ -0,0 +1,79 @@
+// Stable idles for when the OS plane is unavailable (§12.2) — a fixed snapshot
+// and a no-op subscription keep `useSyncExternalStore` tear-free without touching
+// (and re-triggering a fetch on) the real current-space store.
+export const IDLE_SNAPSHOT = { space: null, pending: false, error: undefined };
+export const idleSnapshot = () => IDLE_SNAPSHOT;
+export const noopSubscribe = () => () => { };
+function createStore(load) {
+    let confirmed = null;
+    let loaded = false;
+    let pending = false;
+    let error = undefined;
+    let override = null;
+    let seq = 0;
+    let snap = { space: null, pending: false, error: undefined };
+    const listeners = new Set();
+    /** Recompute the projection (override wins) and notify only on a real change. */
+    function rebuild() {
+        const space = override !== null ? override.space : confirmed;
+        if (space === snap.space && pending === snap.pending && error === snap.error)
+            return;
+        snap = { space, pending, error };
+        for (const l of listeners)
+            l();
+    }
+    function fetch() {
+        const my = ++seq;
+        pending = true;
+        rebuild();
+        return load().then((space) => {
+            if (my !== seq)
+                return;
+            confirmed = space;
+            loaded = true;
+            pending = false;
+            error = undefined;
+            rebuild();
+        }, (e) => {
+            if (my !== seq)
+                return;
+            pending = false;
+            error = e;
+            rebuild();
+        });
+    }
+    return {
+        subscribe(cb) {
+            listeners.add(cb);
+            if (!loaded && !pending)
+                void fetch();
+            return () => listeners.delete(cb);
+        },
+        getSnapshot: () => snap,
+        ensure() {
+            if (!loaded && !pending)
+                void fetch();
+        },
+        refresh: () => fetch(),
+        setOptimistic(space) {
+            override = { space };
+            rebuild();
+        },
+        clearOptimistic() {
+            if (override === null)
+                return;
+            override = null;
+            rebuild();
+        },
+    };
+}
+const stores = new WeakMap();
+/** The one current-space store for a Shell (created on first touch). */
+export function currentSpaceStore(shell) {
+    let s = stores.get(shell);
+    if (s === undefined) {
+        s = createStore(() => shell.user.currentSpace());
+        stores.set(shell, s);
+    }
+    return s;
+}

package/dist/application/spaces/space.hook.d.ts

@@ -0,0 +1,5 @@
+import type { NodeRefInput } from '@astrale-os/kernel-client';
+import type { CurrentSpaceResult } from './current-space.hook';
+export type SpaceResult = CurrentSpaceResult;
+export declare function useSpace(ref: NodeRefInput | null | undefined): SpaceResult;
+//# sourceMappingURL=space.hook.d.ts.map

package/dist/application/spaces/space.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"space.hook.d.ts","sourceRoot":"","sources":["../../../src/application/spaces/space.hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAU7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAO9D,MAAM,MAAM,WAAW,GAAG,kBAAkB,CAAA;AAE5C,wBAAgB,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,CAqB1E"}

package/dist/application/spaces/space.hook.js

@@ -0,0 +1,25 @@
+import { normalizeRef } from '@astrale-os/kernel-client';
+/**
+ * useSpace(ref) (API §12.2) — a single space by ref; `null`/`undefined` (or an
+ * unavailable OS plane) is idle (§1.3). One-shot today (§12 flag).
+ */
+import { useMemo } from 'react';
+import { useAsyncResource } from '../../graph/async';
+import { isIdleInput } from '../../graph/memory/read/idle';
+import { useShell } from '../../session/shell.hook';
+import { isOsPlaneAvailable } from '../user/user.store';
+export function useSpace(ref) {
+    const shell = useShell();
+    const idle = isIdleInput(ref) || !isOsPlaneAvailable(shell);
+    // The inline guard (not the stored `idle`) narrows `ref` to non-null below.
+    const key = idle ? null : normalizeRef(ref);
+    const res = useAsyncResource(idle ? null : () => shell.spaces.get(ref), null, [shell, key]);
+    return useMemo(() => ({
+        space: idle ? null : res.data,
+        pending: idle ? false : res.pending,
+        error: idle ? undefined : res.error,
+        live: false,
+        seq: 0,
+        refetch: res.refetch,
+    }), [idle, res]);
+}

package/dist/application/spaces/spaces.hook.d.ts

@@ -0,0 +1,14 @@
+import type { NodeRefInput } from '@astrale-os/kernel-client';
+import type { SpaceNode } from '@astrale-os/shell';
+import type { Action } from '../../graph/action';
+import type { ReadState } from '../../graph/memory/read/envelope';
+export interface SpacesResult extends ReadState {
+    /** Spaces-dir children, live (one-shot today), the caller's readable set. */
+    readonly spaces: readonly SpaceNode[];
+    /** The `selected_space` target — optimistically ahead during a `switch`. */
+    readonly selected: SpaceNode | null;
+    /** `user::switchSpace` with a manual optimistic overlay (§1.6). */
+    readonly switch: Action<[NodeRefInput], void>;
+}
+export declare function useSpaces(): SpacesResult;
+//# sourceMappingURL=spaces.hook.d.ts.map

package/dist/application/spaces/spaces.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spaces.hook.d.ts","sourceRoot":"","sources":["../../../src/application/spaces/spaces.hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAYlD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAA;AAUjE,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC7C,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;IACrC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI,CAAA;IACnC,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,CAAA;CAC9C;AAED,wBAAgB,SAAS,IAAI,YAAY,CA4DxC"}

package/dist/application/spaces/spaces.hook.js

@@ -0,0 +1,82 @@
+import { normalizeRef } from '@astrale-os/kernel-client';
+/**
+ * useSpaces (API §12.2) — the spaces list, the selected space, and a `switch`
+ * Action that repoints the `selected_space` edge. Reads the SAME per-Shell
+ * current-space store as useCurrentSpace/useApps, so a switch re-themes every
+ * consumer in the window at once — optimistically ahead of the round-trip (§1.6),
+ * commit reconciles, failure rolls back. Reads are one-shot today (§12 flag).
+ */
+import { useEffect, useMemo, useSyncExternalStore } from 'react';
+import { useAction } from '../../graph/action';
+import { useAsyncResource } from '../../graph/async';
+import { useShell } from '../../session/shell.hook';
+import { isOsPlaneAvailable } from '../user/user.store';
+import { currentSpaceStore, idleSnapshot, noopSubscribe } from './current-space.store';
+const NO_SPACES = [];
+export function useSpaces() {
+    const shell = useShell();
+    const available = isOsPlaneAvailable(shell);
+    const store = currentSpaceStore(shell);
+    const spacesRes = useAsyncResource(available ? () => shell.spaces.list() : null, NO_SPACES, [shell, available]);
+    useEffect(() => {
+        if (available)
+            store.ensure();
+    }, [store, available]);
+    const selectedSnap = useSyncExternalStore(available ? store.subscribe : noopSubscribe, available ? store.getSnapshot : idleSnapshot, available ? store.getSnapshot : idleSnapshot);
+    const spaces = spacesRes.data;
+    const switchAction = useAction(async (ref) => {
+        // Optimistic override on the SHARED store, so useCurrentSpace / useApps ahead
+        // of the round-trip too (§12.2). Only overlay a known target (a path ref that
+        // matches nothing in the list simply skips the preview).
+        const target = findSpace(spaces, ref);
+        if (target !== null)
+            store.setOptimistic(target);
+        try {
+            await shell.user.switchSpace(ref);
+            await store.refresh(); // reconcile confirmed truth BEFORE dropping the preview
+            store.clearOptimistic();
+        }
+        catch (error) {
+            store.clearOptimistic(); // rollback: reveal the confirmed (previous) space
+            throw error;
+        }
+    });
+    return useMemo(() => ({
+        spaces,
+        selected: selectedSnap.space,
+        switch: switchAction,
+        pending: spacesRes.pending || selectedSnap.pending,
+        error: spacesRes.error ?? selectedSnap.error,
+        live: false,
+        seq: 0,
+        refetch: async () => {
+            await Promise.all([spacesRes.refetch(), store.refresh()]);
+        },
+    }), [
+        spaces,
+        selectedSnap,
+        switchAction,
+        spacesRes.pending,
+        spacesRes.error,
+        spacesRes.refetch,
+        store,
+    ]);
+}
+/** The space in `spaces` denoted by `ref`, or `null` (path refs don't match by id). */
+function findSpace(spaces, ref) {
+    const id = refIdOf(ref);
+    if (id === null)
+        return null;
+    return spaces.find((s) => s.id === id) ?? null;
+}
+/** A bound-node-ish subject carries a graph id. */
+function hasId(x) {
+    return typeof x === 'object' && x !== null && 'id' in x;
+}
+/** The graph id a subject denotes, or `null` when it is a path (no id to match). */
+function refIdOf(x) {
+    if (hasId(x))
+        return x.id;
+    const raw = normalizeRef(x);
+    return raw.startsWith('@') ? raw.slice(1) : null;
+}

package/dist/application/user/user.hook.d.ts

@@ -0,0 +1,10 @@
+/**
+ * useUser (API §12.2) — self as the shell-domain `User` (typed
+ * firstName/lastName/email). The provider PRE-RESOLVES it at boot (`primeUser`),
+ * so `useUser` is synchronous below the provider (API §2). OS-plane absent → throws
+ * descriptively to the nearest boundary; a never-primed shell suspends on first use
+ * (§1.4). FLAG: not yet re-rendered on rename — becomes live via a memory shape.
+ */
+import type { UserNode } from '@astrale-os/shell';
+export declare function useUser(): UserNode;
+//# sourceMappingURL=user.hook.d.ts.map

package/dist/application/user/user.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.hook.d.ts","sourceRoot":"","sources":["../../../src/application/user/user.hook.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAKjD,wBAAgB,OAAO,IAAI,QAAQ,CAclC"}

package/dist/application/user/user.hook.js

@@ -0,0 +1,19 @@
+import { useShell } from '../../session/shell.hook';
+import { loadUser, userCache } from './user.store';
+export function useUser() {
+    const shell = useShell();
+    const entry = userCache.get(shell) ?? loadUser(shell);
+    if (entry.status === 'pending')
+        throw entry.promise;
+    // OS plane resolved absent at boot — throw to the nearest boundary; do NOT
+    // re-load (the plane is not coming back this session).
+    if (entry.status === 'unavailable')
+        throw entry.error;
+    if (entry.status === 'rejected') {
+        // Retryable transient: drop the poisoned cell so an error-boundary retry
+        // re-loads `me()` instead of re-throwing the same failure forever.
+        userCache.delete(shell);
+        throw entry.error;
+    }
+    return entry.value;
+}

package/dist/application/user/user.store.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The OS-plane user store (API §2/§12.2). Provider-boot priming (`primeUser`) seeds
+ * the per-Shell user cache so `useUser` is synchronous, and tracks OS-plane
+ * availability: a missing/rejecting `shell.user.me` marks the plane down (the other
+ * OS hooks then read idle) without failing boot. A never-primed shell falls back to
+ * a lazy cold read that SUSPENDS on first use (§1.4).
+ */
+import type { Shell, UserNode } from '@astrale-os/shell';
+export type UserEntry = {
+    status: 'pending';
+    promise: Promise<void>;
+} | {
+    status: 'resolved';
+    value: UserNode;
+} | {
+    status: 'rejected';
+    error: unknown;
+}
+/** OS plane absent — throw descriptively, do NOT re-load (a reload just refails). */
+ | {
+    status: 'unavailable';
+    error: unknown;
+};
+export declare const userCache: WeakMap<Shell, UserEntry>;
+/** Is the OS plane (shell.user/spaces/apps) usable for this shell? */
+export declare function isOsPlaneAvailable(shell: Shell): boolean;
+/**
+ * Provider-boot priming (API §2). Best-effort: seed the user cache so `useUser`
+ * is synchronous, or mark the OS plane down. NEVER throws — boot must not fail on
+ * a missing OS plane.
+ */
+export declare function primeUser(shell: Shell): Promise<void>;
+/** Kick off `me()` lazily (a shell that was never primed) and cache a suspense cell. */
+export declare function loadUser(shell: Shell): UserEntry;
+//# sourceMappingURL=user.store.d.ts.map

package/dist/application/user/user.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.store.d.ts","sourceRoot":"","sources":["../../../src/application/user/user.store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAExD,MAAM,MAAM,SAAS,GACjB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,GAC7C;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,GACvC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE;AACxC,qFAAqF;GACnF;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAE7C,eAAO,MAAM,SAAS,2BAAkC,CAAA;AAKxD,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAExD;AAcD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB3D;AAED,wFAAwF;AACxF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAoBhD"}

package/dist/application/user/user.store.js

@@ -0,0 +1,51 @@
+export const userCache = new WeakMap();
+/** Shells whose OS plane could not be resolved at boot — OS hooks read idle. */
+const osPlaneDown = new WeakSet();
+/** Is the OS plane (shell.user/spaces/apps) usable for this shell? */
+export function isOsPlaneAvailable(shell) {
+    return !osPlaneDown.has(shell);
+}
+function osPlaneError(cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    return new Error(`The OS plane is unavailable (useUser/useSpaces/useApps): shell.user.me() could not resolve ` +
+        `— the workspace/shell domain may not be installed for this identity. (${detail})`);
+}
+/**
+ * Provider-boot priming (API §2). Best-effort: seed the user cache so `useUser`
+ * is synchronous, or mark the OS plane down. NEVER throws — boot must not fail on
+ * a missing OS plane.
+ */
+export async function primeUser(shell) {
+    const me = shell.user?.me;
+    if (typeof me !== 'function') {
+        osPlaneDown.add(shell);
+        userCache.set(shell, {
+            status: 'unavailable',
+            error: osPlaneError('shell.user.me is not a function'),
+        });
+        return;
+    }
+    try {
+        const value = await me.call(shell.user);
+        osPlaneDown.delete(shell);
+        userCache.set(shell, { status: 'resolved', value });
+    }
+    catch (error) {
+        osPlaneDown.add(shell);
+        userCache.set(shell, { status: 'unavailable', error: osPlaneError(error) });
+    }
+}
+/** Kick off `me()` lazily (a shell that was never primed) and cache a suspense cell. */
+export function loadUser(shell) {
+    const cell = { status: 'pending' };
+    cell.promise = shell.user.me().then((value) => {
+        cell.status = 'resolved';
+        cell.value = value;
+    }, (error) => {
+        cell.status = 'rejected';
+        cell.error = error;
+    });
+    const entry = cell;
+    userCache.set(shell, entry);
+    return entry;
+}

package/dist/auth/act-as.context.d.ts

@@ -0,0 +1,40 @@
+import type { CredentialInput, FnMap } from '@astrale-os/kernel-client';
+import type { BoundClientSessionView } from '@astrale-os/kernel-client/session';
+import type { ReactElement, ReactNode } from 'react';
+import type { SelfNode } from '../session/session.context';
+/** A bound session view — the kernel surface `session.as(cred)` yields. */
+export type SessionView = BoundClientSessionView<FnMap>;
+/** A whoami-shaped identity/graph node (kernel-client does not yet re-export `Node` — G8). */
+export type NodeValue = SelfNode;
+/** The root scope key — the memory's own default scope (`createMemory` default). */
+export declare const ROOT_SCOPE = "default";
+/**
+ * The principal a subtree acts as (API §4). `scope` is the memory isolation key
+ * (§5.4): the graph plane scopes its memory by `memory.forScope(scope)` so an
+ * <ActAs> subtree never shares cached results with another principal.
+ */
+export interface IdentityBinding {
+    readonly kernel: SessionView;
+    readonly self: SelfNode;
+    readonly scope: string;
+}
+export declare const IdentityContext: import("react").Context<IdentityBinding | null>;
+/**
+ * The principal this subtree dispatches as. An <ActAs> value wins; otherwise the
+ * root binding off ShellContext. Throws outside a provider, or when the bound
+ * kernel resolved no identity (a bare prebuilt Shell with no auth surface).
+ */
+export declare function useIdentityBinding(): IdentityBinding;
+export interface ActAsProps {
+    /** The principal to act as. A thunk is resolved by the kernel per dispatch. */
+    credential: CredentialInput | (() => CredentialInput);
+    children: ReactNode;
+}
+/**
+ * A subtree that dispatches as another principal: rebinds the kernel (session.as),
+ * resolves whoami, and provides a fresh identity binding with a DISTINCT memory
+ * scope (`as:<id>`). Nestable — it rebinds from the current effective principal. A
+ * brief nested boot holds the subtree (renders null) until whoami resolves.
+ */
+export declare function ActAs({ credential, children }: ActAsProps): ReactElement | null;
+//# sourceMappingURL=act-as.context.d.ts.map

package/dist/auth/act-as.context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"act-as.context.d.ts","sourceRoot":"","sources":["../../src/auth/act-as.context.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAA;AACvE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAA;AAC/E,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAWpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAA;AAI1D,2EAA2E;AAC3E,MAAM,MAAM,WAAW,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAA;AAEvD,8FAA8F;AAC9F,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAA;AAEhC,oFAAoF;AACpF,eAAO,MAAM,UAAU,YAAY,CAAA;AAEnC;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AACD,eAAO,MAAM,eAAe,iDAA8C,CAAA;AAG1E;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAiBpD;AAED,MAAM,WAAW,UAAU;IACzB,+EAA+E;IAC/E,UAAU,EAAE,eAAe,GAAG,CAAC,MAAM,eAAe,CAAC,CAAA;IACrD,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,UAAU,GAAG,YAAY,GAAG,IAAI,CAkC/E"}

package/dist/auth/act-as.context.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The acting-principal binding (API §4). `IdentityContext` seats the effective
+ * principal a subtree dispatches as — its bound kernel view + whoami + memory
+ * scope; `useIdentityBinding` resolves it (an `<ActAs>` override, else the root
+ * off ShellContext). `<ActAs>` rebinds a subtree to another principal with a
+ * DISTINCT memory scope so results never leak across principals (§5.4).
+ */
+import { createContext, useContext, useEffect, useMemo, useState } from 'react';
+import { ShellContext } from '../session/session.context';
+/** The root scope key — the memory's own default scope (`createMemory` default). */
+export const ROOT_SCOPE = 'default';
+export const IdentityContext = createContext(null);
+IdentityContext.displayName = 'AstraleIdentityContext';
+/**
+ * The principal this subtree dispatches as. An <ActAs> value wins; otherwise the
+ * root binding off ShellContext. Throws outside a provider, or when the bound
+ * kernel resolved no identity (a bare prebuilt Shell with no auth surface).
+ */
+export function useIdentityBinding() {
+    const override = useContext(IdentityContext);
+    if (override !== null)
+        return override;
+    const runtime = useContext(ShellContext);
+    if (runtime === null) {
+        throw new Error('identity hooks must be used within a <ShellProvider>');
+    }
+    if (runtime.self === null) {
+        throw new Error('identity hooks require an identity: this shell exposed no auth surface, so whoami ' +
+            'resolved nothing at boot');
+    }
+    // The root binding reads stable fields (self, shell.kernel), so a fresh object
+    // per render is inert — consumers key off `kernel`/`self`, both stable.
+    return { kernel: runtime.shell.kernel, self: runtime.self, scope: ROOT_SCOPE };
+}
+/**
+ * A subtree that dispatches as another principal: rebinds the kernel (session.as),
+ * resolves whoami, and provides a fresh identity binding with a DISTINCT memory
+ * scope (`as:<id>`). Nestable — it rebinds from the current effective principal. A
+ * brief nested boot holds the subtree (renders null) until whoami resolves.
+ */
+export function ActAs({ credential, children }) {
+    const parent = useIdentityBinding();
+    // Key the rebind on a STABLE credential identity (like `configIdentity` does),
+    // so an inline object credential (`credential={{ … }}`) does not re-mint the
+    // session view — and re-run whoami, unmounting the subtree — every parent
+    // render. A thunk still keys by reference: pass a stable thunk to avoid churn.
+    const credKey = credentialIdentity(credential);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const kernel = useMemo(() => parent.kernel.as(credential), [parent.kernel, credKey]);
+    const [self, setSelf] = useState(null);
+    useEffect(() => {
+        let alive = true;
+        setSelf(null);
+        void kernel.auth.whoami().then((node) => {
+            if (alive)
+                setSelf(node);
+        }, () => {
+            /* held (null) subtree on resolve failure — transport errors surface via the provider */
+        });
+        return () => {
+            alive = false;
+        };
+    }, [kernel]);
+    const value = useMemo(() => (self === null ? null : { kernel, self, scope: `as:${self.id}` }), [kernel, self]);
+    if (value === null)
+        return null;
+    return _jsx(IdentityContext.Provider, { value: value, children: children });
+}
+/**
+ * A stable identity for a credential: the thunk by reference, a string as itself,
+ * and an object by a serialized form — so an equal inline object does not churn
+ * the memo (worst case a serialize failure falls back to reference identity).
+ */
+function credentialIdentity(credential) {
+    if (typeof credential === 'function' || typeof credential === 'string')
+        return credential;
+    try {
+        return `cred:${JSON.stringify(credential)}`;
+    }
+    catch {
+        return credential;
+    }
+}

package/dist/auth/auth.hook.d.ts

@@ -0,0 +1,3 @@
+import type { AuthApi } from '@astrale-os/kernel-client/auth';
+export declare function useAuth(): AuthApi;
+//# sourceMappingURL=auth.hook.d.ts.map

package/dist/auth/auth.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.hook.d.ts","sourceRoot":"","sources":["../../src/auth/auth.hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAA;AAkB7D,wBAAgB,OAAO,IAAI,OAAO,CAGjC"}

package/dist/auth/auth.hook.js

@@ -0,0 +1,25 @@
+/**
+ * useAuth (API §4) — the imperative AuthApi of the effective principal
+ * (whoami/credential/mint/delegate/check/grant/revoke/bind/unbind). Grant and
+ * revoke additionally nudge the principal's useCan ledger on success, delivering
+ * the Tier-0 local re-check (SPEC §11.3). DEVIATION: API §4 describes a pure
+ * passthrough; the wrap is the only way to surface a local grant/revoke today,
+ * since permissions dispatch as identity methods rather than graph patches.
+ * Cross-client liveness still awaits the watch tiers (G7).
+ */
+import { useMemo } from 'react';
+import { useIdentityBinding } from './act-as.context';
+import { ledgerFor } from './can.hook';
+export function useAuth() {
+    const { kernel } = useIdentityBinding();
+    return useMemo(() => withLedgerNudge(kernel), [kernel]);
+}
+/** Wrap grant/revoke so a successful local change re-checks the principal's cells. */
+function withLedgerNudge(kernel) {
+    const auth = kernel.auth;
+    const ledger = ledgerFor(kernel);
+    const invalidate = () => ledger.invalidateAll();
+    const grant = ((arg) => Promise.resolve(auth.grant(arg)).then(invalidate));
+    const revoke = ((arg) => Promise.resolve(auth.revoke(arg)).then(invalidate));
+    return { ...auth, grant, revoke };
+}

package/dist/auth/can.hook.d.ts

@@ -0,0 +1,40 @@
+import type { AuthApi, Perms } from '@astrale-os/kernel-client/auth';
+import type { PathLike, Ref } from '@astrale-os/kernel-client/graph';
+import type { NodeValue, SessionView } from './act-as.context';
+/** A node value carries the id/class/path triple (mirrors the memory's `isNodeValue`). */
+export declare function isNodeValue(x: unknown): x is NodeValue;
+/** Normalize a `useCan` subject to a dispatchable `Ref` plus a stable dedup key. */
+export declare function toRef(on: NodeValue | PathLike): {
+    ref: Ref;
+    key: string;
+};
+/** One deduped check — its last-known value plus the subscribers watching it. */
+declare class CheckCell {
+    private readonly auth;
+    private readonly perms;
+    private readonly on;
+    value: boolean | undefined;
+    private inFlight;
+    private readonly listeners;
+    constructor(auth: AuthApi, perms: Perms, on: Ref);
+    subscribe: (onChange: () => void) => (() => void);
+    getSnapshot: () => boolean | undefined;
+    /** Run the check once when the value is unknown and nothing is in flight. */
+    ensure(): void;
+    /** Force a re-check (local grant/revoke on this principal). */
+    invalidate(): void;
+    private run;
+}
+/** Per-principal cell registry — dedup across the whole tree for one kernel handle. */
+export declare class CheckLedger {
+    private readonly auth;
+    private readonly cells;
+    constructor(auth: AuthApi);
+    cell(key: string, perms: Perms, on: Ref): CheckCell;
+    /** Re-check every observed cell — conservative Tier-0 sweep after a local grant/revoke. */
+    invalidateAll(): void;
+}
+export declare function ledgerFor(kernel: SessionView): CheckLedger;
+export declare function useCan(perms: Perms, on: NodeValue | PathLike | null | undefined): boolean | undefined;
+export {};
+//# sourceMappingURL=can.hook.d.ts.map

package/dist/auth/can.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"can.hook.d.ts","sourceRoot":"","sources":["../../src/auth/can.hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,gCAAgC,CAAA;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,iCAAiC,CAAA;AAapE,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAO9D,0FAA0F;AAC1F,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,SAAS,CAEtD;AAED,oFAAoF;AACpF,wBAAgB,KAAK,CAAC,EAAE,EAAE,SAAS,GAAG,QAAQ,GAAG;IAAE,GAAG,EAAE,GAAG,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAGzE;AAID,iFAAiF;AACjF,cAAM,SAAS;IAMX,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,EAAE;IAPrB,KAAK,EAAE,OAAO,GAAG,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAElD,YACmB,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,KAAK,EACZ,EAAE,EAAE,GAAG,EACtB;IAEJ,SAAS,aAAc,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CAI/C;IAED,WAAW,QAAO,OAAO,GAAG,SAAS,CAAc;IAEnD,6EAA6E;IAC7E,MAAM,IAAI,IAAI,CAGb;IAED,+DAA+D;IAC/D,UAAU,IAAI,IAAI,CAMjB;IAED,OAAO,CAAC,GAAG;CAkBZ;AAED,uFAAuF;AACvF,qBAAa,WAAW;IAGV,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IAErD,YAA6B,IAAI,EAAE,OAAO,EAAI;IAE9C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,GAAG,SAAS,CAOlD;IAED,2FAA2F;IAC3F,aAAa,IAAI,IAAI,CAEpB;CACF;AAMD,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAO1D;AAID,wBAAgB,MAAM,CACpB,KAAK,EAAE,KAAK,EACZ,EAAE,EAAE,SAAS,GAAG,QAAQ,GAAG,IAAI,GAAG,SAAS,GAC1C,OAAO,GAAG,SAAS,CAoBrB"}