@astrale-os/shell-react 0.1.0

package/dist/graph/query/neighbors.hook.d.ts

@@ -0,0 +1,7 @@
+import type { AnyBoundNode, EdgeNames } from '@astrale-os/kernel-client';
+import type { Schema } from '@astrale-os/kernel-dsl';
+import type { EndpointResult } from '../../schema/types';
+import type { ReadOptions } from '../memory/read/envelope';
+export declare function useOut<S extends Schema, E extends EdgeNames<S>>(node: AnyBoundNode<S> | null | undefined, edge: E, opts?: ReadOptions): EndpointResult<S, E, 'to'>;
+export declare function useIn<S extends Schema, E extends EdgeNames<S>>(node: AnyBoundNode<S> | null | undefined, edge: E, opts?: ReadOptions): EndpointResult<S, E, 'from'>;
+//# sourceMappingURL=neighbors.hook.d.ts.map

package/dist/graph/query/neighbors.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"neighbors.hook.d.ts","sourceRoot":"","sources":["../../../src/graph/query/neighbors.hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AASpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,KAAK,EAAa,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAKrE,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,EAC7D,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,EACxC,IAAI,EAAE,CAAC,EACP,IAAI,CAAC,EAAE,WAAW,GACjB,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAE5B;AAED,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,EAC5D,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,EACxC,IAAI,EAAE,CAAC,EACP,IAAI,CAAC,EAAE,WAAW,GACjB,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAE9B"}

package/dist/graph/query/neighbors.hook.js

@@ -0,0 +1,79 @@
+/**
+ * useOut / useIn (API §6) — the public typed traversal read hooks. Resolve
+ * endpoints one-shot through `BoundNode.out/in` (`live: false`); become live with
+ * no surface change once edge-endpoint ids land. Deviations tracked in API §6/G6.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { schemaOf, tagSchema } from '../../schema/tag';
+import { isIdleInput } from '../memory/read/idle';
+export function useOut(node, edge, opts) {
+    return useEndpoint(node, edge, 'out', opts);
+}
+export function useIn(node, edge, opts) {
+    return useEndpoint(node, edge, 'in', opts);
+}
+function useEndpoint(node, edge, side, _opts) {
+    const schema = isIdleInput(node) ? undefined : schemaOf(node);
+    const run = useCallback(async () => {
+        if (isIdleInput(node))
+            return null;
+        // AnyBoundNode omits traversal at the type level; the runtime node (bindAny
+        // → createBoundNode) carries out/in. The edge name is typed by the caller.
+        const t = node;
+        const result = await (side === 'out' ? t.out(edge) : t.in(edge));
+        if (schema !== undefined)
+            tagEndpoints(result, schema);
+        return result;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [node?.id, edge, side]);
+    const { data, pending, error, refetch } = useAsyncRead(isIdleInput(node) ? null : run, [
+        node?.id ?? null,
+        edge,
+        side,
+    ]);
+    return useMemo(() => {
+        const live = { pending, error, live: false, seq: 0, refetch };
+        if (isIdleInput(node))
+            return { ...live, node: null, nodes: EMPTY };
+        if (Array.isArray(data))
+            return { ...live, nodes: data };
+        return { ...live, node: (data ?? null) };
+    }, [node, data, pending, error, refetch]);
+}
+// ── helpers ──────────────────────────────────────────────────────────────────
+const EMPTY = Object.freeze([]);
+function tagEndpoints(result, schema) {
+    if (Array.isArray(result))
+        for (const r of result)
+            tagSchema(r, schema);
+    else if (result !== null && result !== undefined)
+        tagSchema(result, schema);
+}
+/** One-shot async read with pending/error/refetch and stale-response guarding. */
+function useAsyncRead(run, deps) {
+    const [state, setState] = useState({ pending: run !== null, error: undefined });
+    const runRef = useRef(run);
+    runRef.current = run;
+    const seq = useRef(0);
+    const refetch = useCallback(() => {
+        const current = runRef.current;
+        if (current === null) {
+            setState({ pending: false, error: undefined, data: undefined });
+            return Promise.resolve();
+        }
+        const my = ++seq.current;
+        setState((s) => ({ ...s, pending: true, error: undefined }));
+        return current().then((data) => {
+            if (my === seq.current)
+                setState({ data, pending: false, error: undefined });
+        }, (error) => {
+            if (my === seq.current)
+                setState((s) => ({ data: s.data, pending: false, error }));
+        });
+    }, []);
+    useEffect(() => {
+        void refetch();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, deps);
+    return { ...state, refetch };
+}

package/dist/graph/query/node.hook.d.ts

@@ -0,0 +1,14 @@
+import type { NodeRefInput, TypeNames } from '@astrale-os/kernel-client';
+import type { PathLike } from '@astrale-os/kernel-client/graph';
+import type { Schema } from '@astrale-os/kernel-dsl';
+import type { TypedNodeResult } from '../../schema/types';
+import type { ReadState, Node, ReadOptions } from '../memory/read/envelope';
+export interface NodeResult extends ReadState {
+    /** The node, or `null` when missing ≡ masked (never throws NOT_FOUND). */
+    readonly node: Node | null;
+}
+/** Typed: one node bound under `schema` as `type`. */
+export declare function useNode<S extends Schema, T extends TypeNames<S>>(schema: S, type: T, ref: NodeRefInput | null | undefined, opts?: ReadOptions): TypedNodeResult<S, T>;
+/** Untyped: one node by ref — `null` ref is idle (§1.3). */
+export declare function useNode(ref: PathLike | null | undefined, opts?: ReadOptions): NodeResult;
+//# sourceMappingURL=node.hook.d.ts.map

package/dist/graph/query/node.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.hook.d.ts","sourceRoot":"","sources":["../../../src/graph/query/node.hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAC/D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAWpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAK3E,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;CAC3B;AAiCD,sDAAsD;AACtD,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,EAC9D,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,CAAC,EACP,GAAG,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,EACpC,IAAI,CAAC,EAAE,WAAW,GACjB,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AACxB,4DAA4D;AAC5D,wBAAgB,OAAO,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,UAAU,CAAA"}

package/dist/graph/query/node.hook.js

@@ -0,0 +1,43 @@
+/**
+ * useNode (API §5 + §6) — ONE public symbol, overloaded: pass a `Schema` (+ type)
+ * for the typed `BoundNode` result, or a bare ref for the untyped `Node` result.
+ * Both forms ride the SAME memory shape — a typed read and its untyped twin are
+ * one cache entry, one liveness, one overlay. The runtime dispatches on the first
+ * argument; a given call site is always one form, so hook order is stable.
+ */
+import { useMemo } from 'react';
+import { useNode as useNodeTyped } from '../../schema/bind-read';
+import { useRead } from '../memory/read/read';
+/**
+ * A `Schema` (from `defineSchema`) — its shape (`domain`/`classes`/`interfaces`)
+ * is disjoint from a `PathLike` (`string | Path`), so this cleanly routes the
+ * typed vs untyped overload at runtime.
+ */
+function isSchema(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'domain' in value &&
+        'classes' in value &&
+        'interfaces' in value);
+}
+/** One node by path — live, suspense-first; `null` ref is idle (§1.3). */
+function useNodeUntyped(ref, opts) {
+    const r = useRead(ref, opts);
+    return useMemo(() => ({
+        pending: r.pending,
+        error: r.error,
+        live: r.live,
+        seq: r.seq,
+        refetch: r.refetch,
+        node: r.first,
+    }), [r]);
+}
+// The implementation signature returns an erased supertype of both result
+// shapes — every overload above is assignable to it regardless of `BoundNode`
+// variance; callers only ever see the precise overload return types.
+export function useNode(a, b, c, d) {
+    if (isSchema(a)) {
+        return useNodeTyped(a, b, c, d);
+    }
+    return useNodeUntyped(a, b);
+}

package/dist/graph/query/query.hook.d.ts

@@ -0,0 +1,14 @@
+import type { GatherBuilder, QueryASTInput, QuerySource } from '@astrale-os/kernel-client/graph';
+import type { ReadState, Node, ReadOptions, Windowed } from '../memory/read/envelope';
+export interface QueryResult extends ReadState, Windowed {
+    readonly nodes: readonly Node[];
+    readonly roots: readonly Node[];
+    readonly first: Node | null;
+    gathered(alias: string): {
+        readonly nodes: readonly Node[];
+        readonly first: Node | null;
+    };
+}
+/** A structured read — builder callback or AST value; `null` is idle (§1.3). */
+export declare function useQuery(build: ((q: QuerySource) => GatherBuilder) | QueryASTInput | null | undefined, opts?: ReadOptions): QueryResult;
+//# sourceMappingURL=query.hook.d.ts.map

package/dist/graph/query/query.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.hook.d.ts","sourceRoot":"","sources":["../../../src/graph/query/query.hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AAShG,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAIrF,MAAM,WAAW,WAAY,SAAQ,SAAS,EAAE,QAAQ;IACtD,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG;QAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,CAAA;KAAE,CAAA;CAC1F;AAED,gFAAgF;AAChF,wBAAgB,QAAQ,CACtB,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,KAAK,aAAa,CAAC,GAAG,aAAa,GAAG,IAAI,GAAG,SAAS,EAC7E,IAAI,CAAC,EAAE,WAAW,GACjB,WAAW,CAiBb"}

package/dist/graph/query/query.hook.js

@@ -0,0 +1,23 @@
+/**
+ * useQuery (API §5) — a structured read: a builder callback or an AST value;
+ * `null` is idle (§1.3). Rides the §1 envelope over the shared memory, projecting
+ * roots/first/nodes and the gathered-alias arms.
+ */
+import { useMemo } from 'react';
+import { useRead } from '../memory/read/read';
+/** A structured read — builder callback or AST value; `null` is idle (§1.3). */
+export function useQuery(build, opts) {
+    const r = useRead(build ?? null, opts);
+    return useMemo(() => ({
+        pending: r.pending,
+        error: r.error,
+        live: r.live,
+        seq: r.seq,
+        refetch: r.refetch,
+        nodes: r.nodes,
+        roots: r.roots,
+        first: r.first,
+        gathered: r.gathered,
+        more: r.more,
+    }), [r]);
+}

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @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.
+ */
+export { ShellProvider } from './session';
+export type { ShellError, ShellProviderProps } from './session';
+export { useConnection, useKernelClient, useKernelInstance, useShell } from './session';
+export type { KernelInstance } from './session';
+export { ActAs, useAuth, useCan, useSelf } from './auth';
+export type { ActAsProps } from './auth';
+export { useCall, useChildren, useGraph, useMove, useMutate, useNode, useQuery, useStream, } from './graph';
+export type { ChildrenOptions, ChildrenResult, GraphMemory, MoveAction, Node, NodeResult, QueryResult, ShapeInput, UseMutateOptions, } from './graph';
+export type { CallOptions, StreamHandle, StreamOptions } from './graph';
+export { useDomain, useFunction, useIn, useKernel, useMethod, useOut } from './schema';
+export type { FunctionOptions } from './schema';
+export type { MethodOptions } from './schema';
+export type { AutoMethodAction, BoundMethodAction, EndpointResult, FunctionNames, FunctionParams, FunctionResult, MethodIsStatic, MethodNames, MethodParams, MethodResult, TargetedMethodAction, TypedChildrenResult, TypedNodeResult, } from './schema';
+export { Link, NavScope, memoryAdapter, urlAdapter, useAncestors, useLocation, useNavScope, useNavigate, } from './navigation';
+export type { LinkProps, MissingPolicy, NavAdapter, NavLocation, NavScopeHandle, NavScopeProps, NavSnapshot, NavTarget, Navigate, SerializedLocation, } from './navigation';
+export { SelectionScope, useSelection } from './selection';
+export type { Selection, SelectionScopeProps } from './selection';
+export { useCloseGuard, useTargetNode, useViewsFor, useWindow, useWindowList, useWindows, ViewHost, ViewStage, } from './window';
+export type { CloseGuard, CloseVerdict, ViewDescriptor, ViewHostProps, ViewSource, ViewHostHandle, ViewsForResult, WindowListEntry, WindowState, WindowView, } from './window';
+export { useIntent, useSendIntent } from './intents';
+export type { IntentCtx, IntentPayload, IntentReply, SendIntent } from './intents';
+export { AppHost, AppLogo, useApps, useCurrentSpace, useOpenApp, useRoles, useSpace, useSpaces, useUser, } from './application';
+export type { AppHostFallbackState, AppHostProps, AppLogoProps, AppsResult, CurrentSpaceResult, RolesResult, SpaceResult, SpacesResult, } from './application';
+export type { ApplicationNode, AppSession, RoleNode, SpaceNode, UserNode } from '@astrale-os/shell';
+export type { Action, ReadState, ReadOptions, Windowed } from './graph';
+export * from './graph/guards.error';
+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';
+export type { CloseResult, KernelClient, MountCredential, Shell, ShellConfig, Window, } from '@astrale-os/shell';
+export type { IntentRegistry } from '@astrale-os/shell';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,34 @@
+/**
+ * @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.
+ */
+// ─── session (§2 provider + §3) ──────────────────────────────────────────────
+export { ShellProvider } from './session';
+export { useConnection, useKernelClient, useKernelInstance, useShell } from './session';
+// ─── auth (§4) ───────────────────────────────────────────────────────────────
+export { ActAs, useAuth, useCan, useSelf } from './auth';
+// ─── graph — the untyped floor + writes + dispatch (§5, §7) ──────────────────
+// `useNode`/`useChildren` are single symbols merging the untyped floor + typed
+// overloads.
+export { useCall, useChildren, useGraph, useMove, useMutate, useNode, useQuery, useStream, } from './graph';
+// ─── schema — the typed substrate (§6) ───────────────────────────────────────
+export { useDomain, useFunction, useIn, useKernel, useMethod, useOut } from './schema';
+// ─── navigation (§8) ─────────────────────────────────────────────────────────
+export { Link, NavScope, memoryAdapter, urlAdapter, useAncestors, useLocation, useNavScope, useNavigate, } from './navigation';
+// ─── selection (§9) ──────────────────────────────────────────────────────────
+export { SelectionScope, useSelection } from './selection';
+// ─── window (§10) ────────────────────────────────────────────────────────────
+export { useCloseGuard, useTargetNode, useViewsFor, useWindow, useWindowList, useWindows, ViewHost, ViewStage, } from './window';
+// ─── intents (§11) ───────────────────────────────────────────────────────────
+export { useIntent, useSendIntent } from './intents';
+// ─── application — the OS plane (§12) ────────────────────────────────────────
+export { AppHost, AppLogo, useApps, useCurrentSpace, useOpenApp, useRoles, useSpace, useSpaces, useUser, } from './application';
+// ─── error taxonomy (§1.4) — guards + classes, re-exported from kernel-client ─
+export * from './graph/guards.error';
+// ─── 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';

package/dist/intents/envelope.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Intent envelope construction (API §11). The typed payload/reply projections of
+ * a registry entry, the wire constants, and `intentMessage` — the single builder
+ * both directions (send + reply) share.
+ */
+import type { IntentMessage, IntentRegistry } 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];
+/**
+ * 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;
+/** Sentinel `ctx.sender` carries for a parent-delivered intent (the shell stamps it). */
+export declare const PARENT_SENDER = "<parent>";
+/** Correlated-reply channel name (the shell's fire-and-forget reply protocol). */
+export declare const INTENT_REPLY = "intentReply";
+export declare 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.
+ */
+export declare function intentMessage(name: string, payload: unknown, correlationId?: string): IntentMessage;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/intents/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/intents/envelope.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEtE;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,MAAM,cAAc,IAAI,cAAc,CAAC,CAAC,CAAC,SAAS;IACpF,OAAO,EAAE,MAAM,CAAC,CAAA;CACjB,GACG,CAAC,GACD,cAAc,CAAC,CAAC,CAAC,CAAA;AAErB;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,cAAc,IAAI,cAAc,CAAC,CAAC,CAAC,SAAS;IAClF,KAAK,EAAE,MAAM,CAAC,CAAA;CACf,GACG,CAAC,GACD,IAAI,CAAA;AAER,yFAAyF;AACzF,eAAO,MAAM,aAAa,aAAa,CAAA;AAGvC,kFAAkF;AAClF,eAAO,MAAM,YAAY,gBAAgB,CAAA;AACzC,eAAO,MAAM,IAAI,QAAO,IAAU,CAAA;AAElC;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,aAAa,CAMf"}

package/dist/intents/envelope.js

@@ -0,0 +1,19 @@
+/** Sentinel `ctx.sender` carries for a parent-delivered intent (the shell stamps it). */
+export const PARENT_SENDER = '<parent>';
+/** Outbound `sender.windowId`; the receiver re-stamps it with the trusted id. */
+const SELF_SENDER = 'self';
+/** Correlated-reply channel name (the shell's fire-and-forget reply protocol). */
+export const INTENT_REPLY = 'intentReply';
+export const NOOP = () => { };
+/**
+ * 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.
+ */
+export function intentMessage(name, payload, correlationId) {
+    return {
+        type: 'intent',
+        version: 1,
+        envelope: { name, payload, sender: { windowId: SELF_SENDER }, correlationId },
+    };
+}

package/dist/intents/index.d.ts

@@ -0,0 +1,6 @@
+export { useIntent } from './listen-intent.hook';
+export type { IntentCtx } from './listen-intent.hook';
+export { useSendIntent } from './send-intent.hook';
+export type { SendIntent } from './send-intent.hook';
+export type { IntentPayload, IntentReply } from './envelope';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/intents/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAChD,YAAY,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}

package/dist/intents/index.js

@@ -0,0 +1,3 @@
+// intents — API §11 (useIntent, useSendIntent). See SHELL_REACT_API.md.
+export { useIntent } from './listen-intent.hook';
+export { useSendIntent } from './send-intent.hook';

package/dist/intents/listen-intent.hook.d.ts

@@ -0,0 +1,16 @@
+import type { IntentRegistry } from '@astrale-os/shell';
+import type { IntentPayload, IntentReply } from './envelope';
+/** Delivery context passed alongside an inbound intent's payload. */
+export interface IntentCtx<K extends keyof IntentRegistry> {
+    /** REAL source windowId; the `'<parent>'` sentinel for a parent-delivered intent. */
+    readonly sender: string;
+    /** Reply to the sender's pending request — exactly-once; dropped if it died. */
+    reply(result: IntentReply<K>): void;
+}
+/**
+ * Subscribe `handler` to inbound `name` intents. `ctx.sender` is the REAL
+ * windowId (the channel-authenticated id, or `'<parent>'` upstream); `ctx.reply`
+ * answers a correlated request once.
+ */
+export declare function useIntent<K extends keyof IntentRegistry>(name: K, handler: (payload: IntentPayload<K>, ctx: IntentCtx<K>) => void | Promise<void>): void;
+//# sourceMappingURL=listen-intent.hook.d.ts.map

package/dist/intents/listen-intent.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listen-intent.hook.d.ts","sourceRoot":"","sources":["../../src/intents/listen-intent.hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAYtE,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAM5D,qEAAqE;AACrE,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,MAAM,cAAc;IACvD,qFAAqF;IACrF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,gFAAgF;IAChF,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;CACpC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,cAAc,EACtD,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC9E,IAAI,CAyDN"}

package/dist/intents/listen-intent.hook.js

@@ -0,0 +1,75 @@
+/**
+ * useIntent (API §11) — subscribe ONE handler to inbound intents (post-middleware,
+ * via shell.onIntent) with the REAL sender windowId and an exactly-once,
+ * unmount-safe `ctx.reply`. The subscription identity is independent of the
+ * handler closure (latest-handler ref), so re-renders never re-register. Reply
+ * obligations are tracked per sender window so a child close drops ours before a
+ * late async handler can aim a reply at a gone counterparty.
+ */
+import { useEffect, useRef } from 'react';
+import { useShell } from '../session/shell.hook';
+import { NOOP } from './envelope';
+import { sendReply } from './reply';
+/**
+ * Subscribe `handler` to inbound `name` intents. `ctx.sender` is the REAL
+ * windowId (the channel-authenticated id, or `'<parent>'` upstream); `ctx.reply`
+ * answers a correlated request once.
+ */
+export function useIntent(name, handler) {
+    const shell = useShell();
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    useEffect(() => {
+        let alive = true;
+        // Open reply obligations by sender window, so a child close drops ours
+        // before a late async handler can aim a reply at a gone counterparty.
+        const bySender = new Map();
+        const track = (sender, drop) => {
+            let set = bySender.get(sender);
+            if (set === undefined) {
+                set = new Set();
+                bySender.set(sender, set);
+            }
+            set.add(drop);
+            return () => set.delete(drop);
+        };
+        const offClose = shell.children.onClose((windowId) => {
+            const set = bySender.get(windowId);
+            if (set === undefined)
+                return;
+            for (const drop of set)
+                drop();
+            bySender.delete(windowId);
+        });
+        const off = shell.onIntent(name, (message) => {
+            const { payload, correlationId } = message.envelope;
+            const sender = message.envelope.sender.windowId;
+            let settled = false;
+            const untrack = correlationId === undefined
+                ? NOOP
+                : track(sender, () => {
+                    settled = true;
+                });
+            const ctx = {
+                sender,
+                reply(result) {
+                    if (settled || !alive)
+                        return;
+                    settled = true;
+                    untrack();
+                    if (correlationId === undefined)
+                        return;
+                    sendReply(shell, sender, correlationId, result);
+                },
+            };
+            void Promise.resolve(handlerRef.current(payload, ctx))
+                .catch(NOOP)
+                .finally(untrack);
+        });
+        return () => {
+            alive = false;
+            off();
+            offClose();
+        };
+    }, [shell, name]);
+}

package/dist/intents/reply.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reply delivery (API §11) — route a correlated reply to whichever channel the
+ * request arrived on (parent vs a child window). Best-effort: a gone counterparty
+ * drops the reply safely (counterparty-death cleanup).
+ */
+import type { Shell } from '@astrale-os/shell';
+/** Deliver a reply to whichever channel the request arrived on. Best-effort. */
+export declare function sendReply(shell: Shell, sender: string, correlationId: string, result: unknown): void;
+//# sourceMappingURL=reply.d.ts.map

package/dist/intents/reply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reply.d.ts","sourceRoot":"","sources":["../../src/intents/reply.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAI9C,gFAAgF;AAChF,wBAAgB,SAAS,CACvB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,OAAO,GACd,IAAI,CAQN"}

package/dist/intents/reply.js

@@ -0,0 +1,14 @@
+import { INTENT_REPLY, PARENT_SENDER, intentMessage } from './envelope';
+/** Deliver a reply to whichever channel the request arrived on. Best-effort. */
+export function sendReply(shell, sender, correlationId, result) {
+    const message = intentMessage(INTENT_REPLY, { correlationId, result });
+    try {
+        if (sender === PARENT_SENDER)
+            shell.parent?.send(message);
+        else
+            shell.children.send(sender, message); // no-op if the child has detached
+    }
+    catch {
+        // Counterparty gone — the reply is safely dropped.
+    }
+}

package/dist/intents/send-intent.hook.d.ts

@@ -0,0 +1,12 @@
+import type { IntentRegistry } from '@astrale-os/shell';
+import type { IntentPayload, IntentReply } from './envelope';
+/** The typed sender returned by {@link useSendIntent}. */
+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>;
+}
+export declare function useSendIntent(): SendIntent;
+//# sourceMappingURL=send-intent.hook.d.ts.map

package/dist/intents/send-intent.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"send-intent.hook.d.ts","sourceRoot":"","sources":["../../src/intents/send-intent.hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,cAAc,EAAS,MAAM,mBAAmB,CAAA;AAW7E,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAK5D,0DAA0D;AAC1D,MAAM,WAAW,UAAU;IACzB,CAAC,CAAC,SAAS,MAAM,cAAc,EAC7B,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC;IACzB,oFAAoF;IACpF,IAAI,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAA;KAAE,GAChC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;CAClC;AAqBD,wBAAgB,aAAa,IAAI,UAAU,CAiE1C"}

package/dist/intents/send-intent.hook.js

@@ -0,0 +1,86 @@
+/**
+ * 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 { useCallback, useEffect, useRef } from 'react';
+import { useShell } from '../session/shell.hook';
+import { INTENT_REPLY, NOOP, intentMessage } from './envelope';
+function resolveTarget(shell, to) {
+    if (to === undefined) {
+        return shell.parent !== null
+            ? { kind: 'parent' }
+            : { kind: 'invalid', reason: 'no target — pass opts.to (a child windowId) from a root shell' };
+    }
+    if (to === 'parent') {
+        return shell.parent !== null
+            ? { kind: 'parent' }
+            : { kind: 'invalid', reason: "opts.to 'parent' but this shell has no parent channel" };
+    }
+    return { kind: 'child', windowId: to };
+}
+export function useSendIntent() {
+    const shell = useShell();
+    // Unmount settlers for in-flight sends, so a pending reply resolves on teardown.
+    const pendingRef = useRef(new Set());
+    useEffect(() => {
+        const pending = pendingRef.current;
+        return () => {
+            for (const settle of pending)
+                settle();
+            pending.clear();
+        };
+    }, []);
+    return useCallback((name, payload, opts) => {
+        const target = resolveTarget(shell, opts?.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((resolve) => {
+            let done = false;
+            let offReply = NOOP;
+            let offClose = NOOP;
+            const onUnmount = () => settle(undefined);
+            function settle(value) {
+                if (done)
+                    return;
+                done = true;
+                offReply();
+                offClose();
+                pending.delete(onUnmount);
+                resolve(value);
+            }
+            const onReply = (m) => {
+                if (m.envelope.name !== INTENT_REPLY)
+                    return;
+                const reply = m.envelope.payload;
+                if (reply.correlationId !== correlationId)
+                    return;
+                settle(reply.result);
+            };
+            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);
+            }
+        });
+    }, [shell]);
+}

package/dist/navigation/adapters/adapter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The nav persistence port (API §8.1). The pluggable seam a `NavScope` mirrors its
+ * location through. `href` is the URL-form probe `<Link>` needs: present → an
+ * `<a href>` (cmd/ctrl-click falls through); absent → `role="link"`.
+ */
+import type { SerializedLocation } from '../history';
+export interface NavAdapter {
+    read(): SerializedLocation | null;
+    write(loc: SerializedLocation, opts: {
+        replace: boolean;
+    }): void;
+    subscribe(onExternalChange: () => void): () => void;
+    href?(loc: SerializedLocation): string;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/navigation/adapters/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/navigation/adapters/adapter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD,MAAM,WAAW,UAAU;IACzB,IAAI,IAAI,kBAAkB,GAAG,IAAI,CAAA;IACjC,KAAK,CAAC,GAAG,EAAE,kBAAkB,EAAE,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAA;IAChE,SAAS,CAAC,gBAAgB,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IACnD,IAAI,CAAC,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAAA;CACvC"}

package/dist/navigation/adapters/adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/navigation/adapters/memory.adapter.d.ts

@@ -0,0 +1,9 @@
+/**
+ * memoryAdapter (API §8.1) — the default scope backing: holds one location in a
+ * closure (per-pane state, no URL form → Link renders `role="link"`).
+ */
+import type { SerializedLocation } from '../history';
+import type { NavAdapter } from './adapter';
+/** In-memory adapter — the default scope backing (per-pane state, no URL). */
+export declare function memoryAdapter(initial?: SerializedLocation): NavAdapter;
+//# sourceMappingURL=memory.adapter.d.ts.map