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

package/dist/schema/relation.hook.d.ts

@@ -0,0 +1,46 @@
+import type { BoundInstanceOf, Definition, EdgeEndpointAcceptedDefinitionsOf } from '@astrale-os/sdk/domain';
+import type { LinkedCountOf } from '@astrale-os/sdk/query';
+import type { GraphResource } from '../graph/resource.js';
+type DefinitionCoordinates = Pick<Definition<'class' | 'interface'>, 'kind' | 'origin' | 'name' | 'key' | 'schemaRef' | 'definition'>;
+type NodeDefinition = DefinitionCoordinates & {
+    readonly family: 'node';
+};
+type EdgeDefinition = DefinitionCoordinates & {
+    readonly family: 'edge';
+};
+type EndpointRole = 'source' | 'target';
+type Opposite<Role extends EndpointRole> = Role extends 'source' ? 'target' : 'source';
+type Accepted<Definition extends EdgeDefinition, Role extends EndpointRole> = EdgeEndpointAcceptedDefinitionsOf<Definition, Opposite<Role>>;
+type StartingDefinition<Relation extends EdgeDefinition, Role extends EndpointRole> = EdgeEndpointAcceptedDefinitionsOf<Relation, Role> & NodeDefinition;
+type RelatedDefinition<Relation extends EdgeDefinition, Role extends EndpointRole> = Accepted<Relation, Role> & NodeDefinition;
+type EffectiveCardinality<Relation extends EdgeDefinition, Role extends EndpointRole, To extends RelatedDefinition<Relation, Role>> = LinkedCountOf<Relation, Role, To>;
+export interface RelationUnavailable {
+    readonly kind: 'required-hidden-or-invalid';
+    readonly cardinality: '1' | '1..*';
+}
+export declare class RelationUnavailableError extends Error {
+    readonly unavailable: RelationUnavailable;
+    readonly code: 'SHELL_REACT_RELATION_UNAVAILABLE';
+    constructor(unavailable: RelationUnavailable);
+}
+export type RelationResource<T, C extends string> = C extends '1' | '0..1' ? GraphResource<T | null> & {
+    readonly cardinality: C;
+    readonly unavailable?: RelationUnavailable;
+    require(): T;
+} : GraphResource<readonly T[]> & {
+    readonly cardinality: C;
+    readonly unavailable?: RelationUnavailable;
+    require(): readonly T[];
+};
+export interface RelationOptions<Role extends EndpointRole, To> {
+    readonly from: Role;
+    /** Exact rich opposite-endpoint definition used to admit and brand returned nodes. */
+    readonly to: To;
+    readonly page?: {
+        readonly size: number;
+    };
+}
+/** Traverse one exact rich Edge definition with endpoint and cardinality inference. */
+export declare function useRelation<Definition extends EdgeDefinition, Role extends EndpointRole, To extends RelatedDefinition<Definition, Role>>(definition: Definition, source: BoundInstanceOf<StartingDefinition<Definition, Role>> | null | undefined, options: RelationOptions<Role, To>): RelationResource<BoundInstanceOf<To>, EffectiveCardinality<Definition, Role, To>>;
+export {};
+//# sourceMappingURL=relation.hook.d.ts.map

package/dist/schema/relation.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation.hook.d.ts","sourceRoot":"","sources":["../../src/schema/relation.hook.ts"],"names":[],"mappings":"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"}

package/dist/schema/relation.hook.js

@@ -0,0 +1,136 @@
+import { NodeId } from '@astrale-os/sdk/graph/node';
+import { Path } from '@astrale-os/sdk/graph/path';
+import { Query } from '@astrale-os/sdk/query';
+import { useCallback, useMemo } from 'react';
+import { useStoreResource } from '../graph/resource.js';
+import { bindingFor } from './domain.hook.js';
+export class RelationUnavailableError extends Error {
+    unavailable;
+    code = 'SHELL_REACT_RELATION_UNAVAILABLE';
+    constructor(unavailable) {
+        super(`Required relation (${unavailable.cardinality}) is hidden or violates the installed schema.`);
+        this.unavailable = unavailable;
+        this.name = 'RelationUnavailableError';
+    }
+}
+/** Traverse one exact rich Edge definition with endpoint and cardinality inference. */
+export function useRelation(definition, source, options) {
+    const binding = bindingFor(definition);
+    if (source !== null && source !== undefined) {
+        admitSource(binding, definition, options.from, source);
+    }
+    admitRelatedDefinition(binding, definition, options.from, options.to);
+    const path = source === null || source === undefined ? null : Path.id(NodeId(source.id));
+    const query = useMemo(() => {
+        if (path === null)
+            return null;
+        const root = Query.from({ kind: 'node', paths: [path], binding: 'relation_source' });
+        const admitted = root.filter({ satisfies: source.$.definition.schemaRef });
+        const expanded = admitted.expand({
+            via: [definition.schemaRef],
+            direction: options.from === 'source' ? 'outgoing' : 'incoming',
+        });
+        return expanded
+            .filter({ satisfies: options.to.schemaRef })
+            .select({ kind: 'graph', binding: expanded.node });
+    }, [definition, options.from, options.to, path?.raw, source]);
+    const cardinality = effectiveCardinality(binding, definition, options.from, options.to);
+    const project = useCallback((response) => {
+        const result = response.result;
+        if (result.kind !== 'graph' || result.selection.kind !== 'node') {
+            return cardinality === '0..1'
+                ? null
+                : cardinality === '0..*'
+                    ? Object.freeze([])
+                    : undefined;
+        }
+        const byId = new Map(result.graph.nodes.map((node) => [node.id, node]));
+        const values = result.selection.ids.flatMap((id) => {
+            const node = byId.get(id);
+            if (node === undefined)
+                return [];
+            const bind = binding.$.bind;
+            return [bind(options.to, node)];
+        });
+        if (cardinality === '0..1')
+            return values[0] ?? null;
+        if (cardinality === '1')
+            return values[0];
+        if (cardinality === '1..*' && values.length === 0)
+            return undefined;
+        return Object.freeze(values);
+    }, [binding, cardinality, options.to, query]);
+    const resource = useStoreResource(query, options.page?.size ?? 50, project);
+    const unavailable = (cardinality === '1' &&
+        resource.data === undefined &&
+        resource.state !== 'idle' &&
+        resource.state !== 'loading') ||
+        (cardinality === '1..*' &&
+            resource.data === undefined &&
+            resource.state !== 'idle' &&
+            resource.state !== 'loading')
+        ? Object.freeze({ kind: 'required-hidden-or-invalid', cardinality })
+        : undefined;
+    const require = () => {
+        if (unavailable !== undefined)
+            throw new RelationUnavailableError(unavailable);
+        if (resource.data === undefined || resource.data === null) {
+            throw new Error('Relation resource is not settled with an available value.');
+        }
+        return resource.data;
+    };
+    return Object.freeze({
+        ...resource,
+        cardinality,
+        ...(unavailable === undefined ? {} : { unavailable }),
+        require,
+    });
+}
+function admitSource(binding, relation, from, source) {
+    const accepted = edgeEndpoints(relation)[from].accepts;
+    const matches = accepted.some((ref) => {
+        const candidate = binding.$.inspect(ref);
+        return source.$.definition.satisfies(candidate);
+    });
+    if (!matches)
+        throw new TypeError('Relation source does not satisfy the selected endpoint.');
+}
+function endpointCardinality(definition, side) {
+    const endpoint = edgeEndpoints(definition)[side];
+    const cardinality = side === 'source' ? endpoint.outgoing : endpoint.incoming;
+    if (cardinality === undefined) {
+        throw new TypeError(`Relation ${side} endpoint does not expose its traversal cardinality.`);
+    }
+    return cardinality;
+}
+function effectiveCardinality(binding, relation, from, to) {
+    const base = endpointCardinality(relation, from);
+    if (base !== '1' && base !== '1..*') {
+        return base;
+    }
+    const opposite = from === 'source' ? 'target' : 'source';
+    const coversEndpoint = edgeEndpoints(relation)[opposite].accepts.every((ref) => {
+        const candidate = binding.$.inspect(ref);
+        return candidate.satisfies(to);
+    });
+    return (coversEndpoint ? base : base === '1' ? '0..1' : '0..*');
+}
+function admitRelatedDefinition(binding, relation, from, to) {
+    const opposite = from === 'source' ? 'target' : 'source';
+    const accepted = edgeEndpoints(relation)[opposite].accepts;
+    const matches = accepted.some((ref) => {
+        const candidate = binding.$.inspect(ref);
+        return to.satisfies(candidate);
+    });
+    if (!matches)
+        throw new TypeError('Relation target definition is not admitted by the opposite endpoint.');
+}
+function edgeEndpoints(relation) {
+    const declaration = relation.definition;
+    const source = declaration.endpoints?.source;
+    const target = declaration.endpoints?.target;
+    if (declaration.family !== 'edge' || source === undefined || target === undefined) {
+        throw new TypeError('Relation definition does not expose admitted Edge endpoints.');
+    }
+    return Object.freeze({ source, target });
+}

package/dist/selection/live.d.ts

@@ -1,21 +1,13 @@
-import type { GraphMemory } from '@astrale-os/kernel-client/store';
-/** A live memory node — the non-null projection of a point read. */
-export type SelectionNode = NonNullable<ReturnType<GraphMemory['getSnapshot']>['node']>;
-export type NodeId = SelectionNode['id'];
-/**
- * The in-scope graph memory, structurally narrowed. Reads the base memory the
- * provider seats in `GraphContext`, defensively so selection also works under a
- * bare/fake context (tests) or before one is mounted.
- */
-export declare function useMemory(): GraphMemory | null;
-export interface LiveSnapshot {
+import type { Node, NodeId } from '@astrale-os/sdk/graph/node';
+export type SelectionNode = Node;
+export type { NodeId };
+export interface ResolvedSelection {
     readonly aliveIds: readonly NodeId[];
     readonly nodes: readonly SelectionNode[];
+    readonly pending: boolean;
+    readonly error: unknown;
+    refetch(): Promise<void>;
 }
-/**
- * Subscribe to each id's node shape and project the surviving nodes. The result
- * keeps a stable reference across renders when membership and node identities
- * are unchanged (useSyncExternalStore contract).
- */
-export declare function useLiveNodes(orderedIds: readonly NodeId[], memory: GraphMemory | null): LiveSnapshot;
+/** Resolve selected identities through the authenticated GraphApi; no fake live subscription. */
+export declare function useResolvedNodes(orderedIds: readonly NodeId[]): ResolvedSelection;
 //# sourceMappingURL=live.d.ts.map

package/dist/selection/live.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"live.d.ts","sourceRoot":"","sources":["../../src/selection/live.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAA2B,MAAM,iCAAiC,CAAA;AAc3F,oEAAoE;AACpE,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAA;AACvF,MAAM,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAA;AAyBxC;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,WAAW,GAAG,IAAI,CAO9C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;CACzC;AAeD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,MAAM,EAAE,WAAW,GAAG,IAAI,GACzB,YAAY,CA4Dd"}
+{"version":3,"file":"live.d.ts","sourceRoot":"","sources":["../../src/selection/live.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAA;AAO9D,MAAM,MAAM,aAAa,GAAG,IAAI,CAAA;AAChC,YAAY,EAAE,MAAM,EAAE,CAAA;AAEtB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;IACxC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAUD,iGAAiG;AACjG,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,iBAAiB,CAgEjF"}

package/dist/selection/live.js

@@ -1,116 +1,69 @@
-/**
- * Selection liveness (API §9) — resolve the scope's ids to LIVE memory nodes, and
- * the node types the selection speaks. Each id is subscribed as an independent
- * point-read shape; an id drops ONLY once its shape has SETTLED to absence (the
- * fixed latch) — a cold shape whose point-read has not landed is kept alive with
- * no node, so a selection made from a children row is never self-cleared before
- * its fetch resolves. Degrades to no nodes (ids kept) when no memory is in scope.
- */
-import { useCallback, useContext, useRef, useSyncExternalStore } from 'react';
-import { GraphContext } from '../graph/graph.context.js';
-const LIVE_OPTS = { live: true };
-const EMPTY_NODES = [];
-const NOOP = () => { };
-/** Point-read shape addressing a node by its graph id. */
-function nodeShape(id) {
-    return `@${id}`;
-}
-/**
- * A null-node id is a CONFIRMED absence (drop it) only when the shape settled
- * there: it was seen warm and is now gone (deletion), or a live subscription has
- * finished fetching and found nothing (mask/never-existed). A never-warm, not-
- * yet-fetched (cold/pending) shape is NOT absence — the id stays alive, no node.
- */
-function isConfirmedAbsent(snap, id, everWarm) {
-    if (everWarm.has(id))
-        return true;
-    return snap.live === true && snap.pending === false;
-}
-/**
- * The in-scope graph memory, structurally narrowed. Reads the base memory the
- * provider seats in `GraphContext`, defensively so selection also works under a
- * bare/fake context (tests) or before one is mounted.
- */
-export function useMemory() {
-    const ctx = useContext(GraphContext);
-    return ctx !== null &&
-        typeof ctx.subscribe === 'function' &&
-        typeof ctx.getSnapshot === 'function'
-        ? ctx
-        : null;
-}
-function unchanged(prev, aliveIds, nodes) {
-    // `aliveIds` and `nodes` can differ in length (a cold id is alive with no node
-    // yet), so compare the two lists independently.
-    if (prev.aliveIds.length !== aliveIds.length || prev.nodes.length !== nodes.length)
-        return false;
-    for (let i = 0; i < aliveIds.length; i += 1)
-        if (prev.aliveIds[i] !== aliveIds[i])
-            return false;
-    for (let i = 0; i < nodes.length; i += 1)
-        if (prev.nodes[i] !== nodes[i])
-            return false;
-    return true;
-}
-/**
- * Subscribe to each id's node shape and project the surviving nodes. The result
- * keeps a stable reference across renders when membership and node identities
- * are unchanged (useSyncExternalStore contract).
- */
-export function useLiveNodes(orderedIds, memory) {
-    // Stands in for `orderedIds` in the callback deps (a fresh array each render).
-    const idsKey = orderedIds.join(' ');
-    const cache = useRef(null);
-    // Ids whose shape has been seen warm at least once — a later null is a deletion
-    // (confirmed absence), whereas a never-warm null is merely cold. Monotonic, so
-    // re-reading getSnapshot within a render is idempotent (useSyncExternalStore-safe).
-    const everWarm = useRef(new Set());
-    const getSnapshot = useCallback(() => {
-        let aliveIds;
-        let nodes;
-        if (memory === null) {
-            // No liveness source: keep the ids, resolve no nodes.
-            aliveIds = orderedIds;
-            nodes = EMPTY_NODES;
-        }
-        else {
-            const seen = everWarm.current;
-            const a = [];
-            const n = [];
-            for (const id of orderedIds) {
-                const snap = memory.getSnapshot(nodeShape(id), LIVE_OPTS);
-                const node = snap.node;
-                if (node !== null) {
-                    seen.add(id);
-                    a.push(id);
-                    n.push(node);
-                }
-                else if (!isConfirmedAbsent(snap, id, seen)) {
-                    // Cold / not-yet-fetched: keep the id alive, no node yet — never a
-                    // premature drop (the critical self-clear this guards against).
-                    a.push(id);
-                }
-                // else: settled absence (deleted/masked) → drops from ids and nodes.
+import { Path } from '@astrale-os/sdk/graph/path';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useSessionKernel } from '../auth/session-kernel.js';
+/** Resolve selected identities through the authenticated GraphApi; no fake live subscription. */
+export function useResolvedNodes(orderedIds) {
+    const graph = useSessionKernel().graph;
+    const key = orderedIds.join('\u0000');
+    const idsRef = useRef(orderedIds);
+    idsRef.current = orderedIds;
+    const generation = useRef(0);
+    const alive = useRef(true);
+    const [state, setState] = useState({
+        key,
+        aliveIds: orderedIds,
+        nodes: [],
+        pending: orderedIds.length > 0,
+        error: undefined,
+    });
+    useEffect(() => {
+        alive.current = true;
+        return () => {
+            alive.current = false;
+        };
+    }, []);
+    const load = useCallback(async () => {
+        const ids = idsRef.current;
+        const currentKey = ids.join('\u0000');
+        const id = ++generation.current;
+        if (ids.length === 0) {
+            if (alive.current) {
+                setState({ key: currentKey, aliveIds: [], nodes: [], pending: false, error: undefined });
             }
-            aliveIds = a;
-            nodes = n;
+            return;
         }
-        const prev = cache.current;
-        if (prev !== null && prev.memory === memory && unchanged(prev.snap, aliveIds, nodes)) {
-            return prev.snap;
+        setState({ key: currentKey, aliveIds: ids, nodes: [], pending: true, error: undefined });
+        try {
+            const values = await Promise.all(ids.map((nodeId) => graph.get(Path.id(nodeId))));
+            if (!alive.current || id !== generation.current)
+                return;
+            const aliveIds = [];
+            const nodes = [];
+            values.forEach((node, index) => {
+                if (node === null)
+                    return;
+                aliveIds.push(ids[index]);
+                nodes.push(node);
+            });
+            setState({
+                key: currentKey,
+                aliveIds: Object.freeze(aliveIds),
+                nodes: Object.freeze(nodes),
+                pending: false,
+                error: undefined,
+            });
         }
-        const snap = { aliveIds, nodes };
-        cache.current = { memory, snap };
-        return snap;
-    }, [memory, idsKey]);
-    const subscribe = useCallback((onStoreChange) => {
-        if (memory === null || orderedIds.length === 0)
-            return NOOP;
-        const unsubs = orderedIds.map((id) => memory.subscribe(nodeShape(id), onStoreChange, LIVE_OPTS));
-        return () => {
-            for (const unsub of unsubs)
-                unsub();
-        };
-    }, [memory, idsKey]);
-    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+        catch (error) {
+            if (alive.current && id === generation.current) {
+                setState({ key: currentKey, aliveIds: ids, nodes: [], pending: false, error });
+            }
+        }
+    }, [graph]);
+    useEffect(() => {
+        void load();
+    }, [key, load]);
+    if (state.key !== key) {
+        return { aliveIds: orderedIds, nodes: [], pending: true, error: undefined, refetch: load };
+    }
+    return { ...state, refetch: load };
 }

package/dist/selection/scope.context.js

@@ -6,7 +6,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * math stays caller-side (read `anchor`). Seats the selection context.
  */
 import { createContext, useCallback, useEffect, useMemo, useReducer, useRef } from 'react';
-import { useLiveNodes, useMemory } from './live.js';
+import { useResolvedNodes } from './live.js';
 export const SelectionContext = createContext(null);
 SelectionContext.displayName = 'AstraleSelectionContext';
 function dedupe(ids) {
@@ -67,14 +67,15 @@ function initState(initial) {
 export function SelectionScope(props) {
     const { initial, onChange, children } = props;
     const [state, dispatch] = useReducer(reducer, initial, initState);
-    const memory = useMemory();
-    const { aliveIds, nodes } = useLiveNodes(state.ids, memory);
+    const { aliveIds, nodes, pending, error } = useResolvedNodes(state.ids);
     // Re-canonicalize stored state when liveness drops a node (or its anchor).
     useEffect(() => {
         const anchorDead = state.anchor !== null && !aliveIds.includes(state.anchor);
+        if (pending || error !== undefined)
+            return;
         if (!sameIds(state.ids, aliveIds) || anchorDead)
             dispatch({ t: 'prune', alive: aliveIds });
-    }, [aliveIds, state.ids, state.anchor]);
+    }, [aliveIds, pending, error, state.ids, state.anchor]);
     // Report changes (explicit ops AND liveness drops), skipping the initial mount.
     const onChangeRef = useRef(onChange);
     onChangeRef.current = onChange;

package/dist/session/boot/boot.d.ts

@@ -1,19 +1,7 @@
-/**
- * The boot machine inputs (API §2): config identity (what triggers a reboot) and
- * whoami resolution (`createShell → init → whoami → OS-user preresolve`). Kept
- * pure of React so the provider's boot effect composes them.
- */
 import type { Shell, ShellConfig } from '@astrale-os/shell';
 import type { SelfNode } from '../session.context.js';
 export declare function isShellConfig(config: ShellConfig | Shell): config is ShellConfig;
-/**
- * Identity of a config — primitive fields only, so re-passing an inline `fetch`,
- * `adapter`, `getCredential`, or `parentWindow` each render does not reboot;
- * changing the kernel/credential does. A principal switch driven by a NEW
- * `getCredential` closure (rather than a new `credential` string) is therefore
- * NOT observed here — remount the provider (React `key`) to rebind it.
- */
+/** Stable ownership key. Capability objects intentionally use reference identity. */
 export declare function configIdentity(config: ShellConfig | Shell): string;
-/** Resolve whoami when the bound kernel exposes an auth surface; else null. */
 export declare function resolveSelf(shell: Shell): Promise<SelfNode | null>;
 //# sourceMappingURL=boot.d.ts.map

package/dist/session/boot/boot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"boot.d.ts","sourceRoot":"","sources":["../../../src/session/boot/boot.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAErD,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,GAAG,MAAM,IAAI,WAAW,CAEhF;AAeD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,GAAG,MAAM,CAYlE;AAED,+EAA+E;AAC/E,wBAAsB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAQxE"}
+{"version":3,"file":"boot.d.ts","sourceRoot":"","sources":["../../../src/session/boot/boot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAErD,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,GAAG,MAAM,IAAI,WAAW,CAEhF;AAcD,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,GAAG,MAAM,CAKlE;AAED,wBAAsB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAGxE"}

package/dist/session/boot/boot.js

@@ -3,43 +3,25 @@ export function isShellConfig(config) {
 }
 let prebuiltCounter = 0;
 const prebuiltIds = new WeakMap();
-/** Stable id per prebuilt-Shell object reference (a new object reboots). */
 function prebuiltId(shell) {
     let id = prebuiltIds.get(shell);
     if (id === undefined) {
-        prebuiltCounter += 1;
-        id = `prebuilt#${prebuiltCounter}`;
+        id = `prebuilt#${++prebuiltCounter}`;
         prebuiltIds.set(shell, id);
     }
     return id;
 }
-/**
- * Identity of a config — primitive fields only, so re-passing an inline `fetch`,
- * `adapter`, `getCredential`, or `parentWindow` each render does not reboot;
- * changing the kernel/credential does. A principal switch driven by a NEW
- * `getCredential` closure (rather than a new `credential` string) is therefore
- * NOT observed here — remount the provider (React `key`) to rebind it.
- */
+/** Stable ownership key. Capability objects intentionally use reference identity. */
 export function configIdentity(config) {
     if (!isShellConfig(config))
         return prebuiltId(config);
-    if (config.mode === 'standalone') {
-        return [
-            'standalone',
-            config.kernelUrl,
-            config.credential ?? '',
-            config.mintIdentity ?? '',
-            config.windowId ?? '',
-        ].join('|');
-    }
-    return `sandboxed|${config.initTimeoutMs ?? ''}`;
+    if (config.mode === 'sandboxed')
+        return prebuiltId(config);
+    if (config.client !== undefined)
+        return `standalone-client|${prebuiltId(config.client)}`;
+    return `standalone-session|${prebuiltId(config.session)}`;
 }
-/** Resolve whoami when the bound kernel exposes an auth surface; else null. */
 export async function resolveSelf(shell) {
-    const kernel = shell.kernel;
-    const auth = kernel.auth;
-    const whoami = auth?.whoami;
-    if (typeof whoami !== 'function')
-        return null;
-    return whoami.call(auth);
+    const auth = shell.kernel.auth;
+    return typeof auth.whoami === 'function' ? auth.whoami() : null;
 }

package/dist/session/index.d.ts

@@ -5,4 +5,5 @@ export { useKernelClient } from './kernel-client.hook.js';
 export { useKernelInstance } from './kernel-instance.hook.js';
 export type { KernelInstance } from './kernel-instance.hook.js';
 export { useConnection } from './connection/connection.hook.js';
+export type { ConnectionStatus, ConnectionValue } from './connection/connection.store.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/session/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAC7D,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAC7D,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAA;AAC/D,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAA"}

package/dist/session/kernel-instance.hook.d.ts

@@ -1,9 +1,6 @@
+/** Public, non-secret identity of the connected source Kernel. */
 export interface KernelInstance {
-    /** Kernel envelope endpoint this shell is bound to. */
     readonly url: string;
-    /** Current kernel credential. Never cache; read per request. */
-    token(): string;
 }
-/** Low-level access for direct kernel-envelope calls and token exchange code. */
 export declare function useKernelInstance(): KernelInstance;
 //# sourceMappingURL=kernel-instance.hook.d.ts.map

package/dist/session/kernel-instance.hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kernel-instance.hook.d.ts","sourceRoot":"","sources":["../../src/session/kernel-instance.hook.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,KAAK,IAAI,MAAM,CAAA;CAChB;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,IAAI,cAAc,CASlD"}
+{"version":3,"file":"kernel-instance.hook.d.ts","sourceRoot":"","sources":["../../src/session/kernel-instance.hook.ts"],"names":[],"mappings":"AAIA,kEAAkE;AAClE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAGlD"}

package/dist/session/kernel-instance.hook.js

@@ -1,10 +1,6 @@
 import { useMemo } from 'react';
 import { useKernelClient } from './kernel-client.hook.js';
-/** Low-level access for direct kernel-envelope calls and token exchange code. */
 export function useKernelInstance() {
     const kernel = useKernelClient();
-    return useMemo(() => ({
-        url: kernel.url,
-        token: () => kernel.authToken(),
-    }), [kernel]);
+    return useMemo(() => Object.freeze({ url: kernel.url }), [kernel]);
 }

package/dist/session/provider.d.ts

@@ -1,31 +1,17 @@
 import type { Shell, ShellConfig } from '@astrale-os/shell';
 import type { ReactElement, ReactNode } from 'react';
-/** 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;
+    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;
+    /** 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 declare function ShellProvider(props: ShellProviderProps): ReactElement | null;
 //# sourceMappingURL=provider.d.ts.map

package/dist/session/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/session/provider.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AA0BpD,6CAA6C;AAC7C,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAE1C,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,MAAM,EAAE,WAAW,GAAG,KAAK,CAAA;IAC3B,wDAAwD;IACxD,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,gGAAgG;IAChG,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,KAAK,SAAS,CAAA;IAChE,4FAA4F;IAC5F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;IACrC,QAAQ,EAAE,SAAS,CAAA;CACpB;AAmBD,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,YAAY,GAAG,IAAI,CA0I5E"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/session/provider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAiBpD,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAEjF,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAAA;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,KAAK,SAAS,CAAA;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;IAC9C,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;CAC7B;AAED,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,YAAY,GAAG,IAAI,CAyG5E"}