@astrale-os/shell-react 0.1.0

package/dist/window/lifecycle/mount.js

@@ -0,0 +1,92 @@
+function isViewDescriptor(view) {
+    return typeof view === 'object' && view !== null && 'id' in view && 'path' in view;
+}
+/** Last path segment or host, alnum-only — a stable-ish functionId from a url. */
+function slugOfUrl(url) {
+    const trimmed = url.replace(/[#?].*$/, '').replace(/\/+$/, '');
+    const tail = trimmed.split('/').filter(Boolean).pop() ?? 'view';
+    return tail.replace(/[^a-z0-9]/gi, '').slice(-32) || 'view';
+}
+/** A ref addressable by the kernel read surface (`get`). `@<id>` for bare ids. */
+function toPath(ref) {
+    if (typeof ref === 'string') {
+        return ref.startsWith('/') || ref.startsWith('@') ? ref : `@${ref}`;
+    }
+    const obj = ref;
+    if (obj.path?.raw !== undefined)
+        return obj.path.raw;
+    if (obj.id !== undefined)
+        return `@${obj.id}`;
+    throw new Error('ViewHost: unresolvable view ref');
+}
+async function resolveViewRef(kernel, ref, handshakeHint) {
+    const node = await kernel.get(toPath(ref));
+    if (node === null)
+        throw new Error(`ViewHost: view not found (${toPath(ref)})`);
+    const props = node.props ?? {};
+    const url = props.url;
+    if (typeof url !== 'string' || url.length === 0) {
+        throw new Error('ViewHost: resolved view has no url');
+    }
+    const handshake = normalizeHandshake(handshakeHint ?? props.handshake);
+    const id = node.id ?? slugOfUrl(url);
+    return { url, handshake, functionId: id };
+}
+function normalizeHandshake(value) {
+    return value === 'none' ? 'none' : 'shell';
+}
+/** Resolve a source; may hit the kernel for a bare/urless View ref (G5). */
+export async function resolveSource(kernel, source) {
+    if ('url' in source) {
+        return { url: source.url, handshake: 'none', functionId: slugOfUrl(source.url) };
+    }
+    const view = source.view;
+    if (isViewDescriptor(view)) {
+        if (view.url !== undefined && view.url.length > 0) {
+            return {
+                url: view.url,
+                handshake: normalizeHandshake(view.handshake),
+                functionId: view.id,
+            };
+        }
+        return resolveViewRef(kernel, view.id, view.handshake);
+    }
+    return resolveViewRef(kernel, view);
+}
+/** A stable remount key: the same source identity must not remount. */
+export function sourceKey(source) {
+    if ('url' in source)
+        return `url:${source.url}`;
+    const view = source.view;
+    if (isViewDescriptor(view))
+        return `view:${view.id}:${view.url ?? ''}:${view.handshake ?? ''}`;
+    if (typeof view === 'string')
+        return `ref:${view}`;
+    const obj = view;
+    return `ref:${obj.id ?? obj.path?.raw ?? '?'}`;
+}
+/** The bare node id delivered as `targetNodeId` at mount / retarget. */
+export function refToId(ref) {
+    if (ref === undefined)
+        return undefined;
+    if (typeof ref === 'string')
+        return ref.startsWith('@') ? ref.slice(1) : ref;
+    const obj = ref;
+    return obj.id;
+}
+/**
+ * Fallbackable = the view didn't speak the shell protocol (timeout/failed), not a
+ * security refusal (origin mismatch) — only the former downgrades to plain.
+ */
+export function isFallbackableHandshakeError(err) {
+    const code = err?.code;
+    return code === 'HANDSHAKE_TIMEOUT' || code === 'HANDSHAKE_FAILED';
+}
+/** Parent → child hot-swap of the target node (no remount) — API §10 setTarget. */
+export function sendSetTarget(shell, windowId, nodeId) {
+    shell.children.send(windowId, {
+        type: 'intent',
+        version: 1,
+        envelope: { name: 'setTarget', payload: { nodeId }, sender: { windowId: '<parent>' } },
+    });
+}

package/dist/window/lifecycle/states.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The WindowState phase machine (API §10) — the lifecycle of a hosted view as the
+ * React face observes it. Distinct from the shell's own `WindowState`
+ * (`active|hidden|closing|closed`): this is the phase a `ViewHost`/`AppHost`
+ * renders around.
+ */
+/**
+ * Lifecycle of a hosted view as the React face observes it (API §10).
+ *
+ * `ready.downgraded` marks a mount that fell back to a plain iframe after a
+ * fallbackable handshake error. It rides here (not on the shell `Window`) until
+ * the shell `Window` grows a first-class flag — flagged in the module report.
+ *
+ * `crashed.windowId` is OPTIONAL: a crash before a window exists (a session-open
+ * failure, a pre-mount source-resolution failure) has no id to report — the type
+ * says so rather than carrying a placeholder `''`.
+ */
+export type WindowState = {
+    readonly phase: 'mounting';
+} | {
+    readonly phase: 'ready';
+    readonly windowId: string;
+    readonly downgraded?: boolean;
+} | {
+    readonly phase: 'crashed';
+    readonly windowId?: string;
+    readonly error?: unknown;
+} | {
+    readonly phase: 'closed';
+    readonly windowId: string;
+    readonly refusal?: string;
+};
+//# sourceMappingURL=states.d.ts.map

package/dist/window/lifecycle/states.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"states.d.ts","sourceRoot":"","sources":["../../../src/window/lifecycle/states.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GACrF;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACnF;IAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA"}

package/dist/window/lifecycle/states.js

@@ -0,0 +1,7 @@
+/**
+ * The WindowState phase machine (API §10) — the lifecycle of a hosted view as the
+ * React face observes it. Distinct from the shell's own `WindowState`
+ * (`active|hidden|closing|closed`): this is the phase a `ViewHost`/`AppHost`
+ * renders around.
+ */
+export {};

package/dist/window/placement.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Slot geometry (API §10) — the physical iframe-slot layer over a stage container
+ * (measure + project). Slots live in the stage (imperative DOM), insulated from
+ * React reconciliation of the hosts; only a slot's box is repositioned, so a
+ * healthy iframe never reloads on reorder/re-key/re-parent.
+ */
+/** Viewport-space box a host projects onto its stage slot. */
+export interface SlotRect {
+    readonly top: number;
+    readonly left: number;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * One persistent slot inside the stage. Its `element` is the mount host handed
+ * to `shell.mount`; the element NEVER moves in the DOM while the owning host
+ * reorders/re-keys/re-parents — only its box is repositioned via `place`.
+ */
+export interface StageSlot {
+    readonly element: HTMLElement;
+    place(rect: SlotRect): void;
+    release(): void;
+}
+export interface StageController {
+    acquire(): StageSlot;
+    dispose(): void;
+}
+/** Build the slot layer over a stage container element (imperative, no React). */
+export declare function createStageController(container: HTMLElement): StageController;
+/** Measure an anchor element's viewport box. */
+export declare function rectOf(el: HTMLElement): SlotRect;
+export declare function sameRect(a: SlotRect, b: SlotRect): boolean;
+//# sourceMappingURL=placement.d.ts.map

package/dist/window/placement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.d.ts","sourceRoot":"","sources":["../../src/window/placement.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8DAA8D;AAC9D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAC7B,KAAK,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAA;IAC3B,OAAO,IAAI,IAAI,CAAA;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,IAAI,SAAS,CAAA;IACpB,OAAO,IAAI,IAAI,CAAA;CAChB;AAED,kFAAkF;AAClF,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,WAAW,GAAG,eAAe,CAyC7E;AAED,gDAAgD;AAChD,wBAAgB,MAAM,CAAC,EAAE,EAAE,WAAW,GAAG,QAAQ,CAGhD;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,OAAO,CAE1D"}

package/dist/window/placement.js

@@ -0,0 +1,57 @@
+/**
+ * Slot geometry (API §10) — the physical iframe-slot layer over a stage container
+ * (measure + project). Slots live in the stage (imperative DOM), insulated from
+ * React reconciliation of the hosts; only a slot's box is repositioned, so a
+ * healthy iframe never reloads on reorder/re-key/re-parent.
+ */
+/** Build the slot layer over a stage container element (imperative, no React). */
+export function createStageController(container) {
+    const slots = new Set();
+    let disposed = false;
+    return {
+        acquire() {
+            const element = container.ownerDocument.createElement('div');
+            element.dataset.astraleViewSlot = '';
+            element.style.position = 'absolute';
+            element.style.top = '0';
+            element.style.left = '0';
+            element.style.pointerEvents = 'auto';
+            container.appendChild(element);
+            slots.add(element);
+            let released = false;
+            return {
+                element,
+                place(rect) {
+                    // translate + explicit box, so a reflow of the container never drifts
+                    // the slot off its anchor.
+                    element.style.transform = `translate(${rect.left}px, ${rect.top}px)`;
+                    element.style.width = `${rect.width}px`;
+                    element.style.height = `${rect.height}px`;
+                },
+                release() {
+                    if (released)
+                        return;
+                    released = true;
+                    slots.delete(element);
+                    element.remove();
+                },
+            };
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const el of slots)
+                el.remove();
+            slots.clear();
+        },
+    };
+}
+/** Measure an anchor element's viewport box. */
+export function rectOf(el) {
+    const r = el.getBoundingClientRect();
+    return { top: r.top, left: r.left, width: r.width, height: r.height };
+}
+export function sameRect(a, b) {
+    return a.top === b.top && a.left === b.left && a.width === b.width && a.height === b.height;
+}

package/dist/window/stage.d.ts

@@ -0,0 +1,3 @@
+import type { ReactElement } from 'react';
+export declare function ViewStage(): ReactElement;
+//# sourceMappingURL=stage.d.ts.map

package/dist/window/stage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../../src/window/stage.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,YAAY,EAAE,MAAM,OAAO,CAAA;AA4BxD,wBAAgB,SAAS,IAAI,YAAY,CAiBxC"}

package/dist/window/stage.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * ViewStage (API §10) — the fixed-positioning layer that physically owns every
+ * iframe for the `ViewHost`/`AppHost`s in the tree. Mount it ONCE near the root.
+ * Reordering / re-parenting / re-keying hosts never reloads a healthy iframe:
+ * each iframe lives in a stage slot (imperative DOM), insulated from React
+ * reconciliation of the hosts; only the slot's box is repositioned.
+ */
+import { useEffect, useMemo, useRef } from 'react';
+import { useShell } from '../session/shell.hook';
+import { getStageHub } from './hub';
+import { createStageController } from './placement';
+/**
+ * A full-viewport overlay that does not intercept pointer events — individual
+ * slots re-enable them, so only the iframes are interactive, not the gaps.
+ */
+const STAGE_STYLE = {
+    position: 'fixed',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    pointerEvents: 'none',
+};
+export function ViewStage() {
+    const shell = useShell();
+    const hub = useMemo(() => getStageHub(shell), [shell]);
+    const containerRef = useRef(null);
+    useEffect(() => {
+        const container = containerRef.current;
+        if (container === null)
+            return;
+        const controller = createStageController(container);
+        hub.setController(controller);
+        return () => {
+            hub.setController(null);
+            controller.dispose();
+        };
+    }, [hub]);
+    return _jsx("div", { ref: containerRef, "data-astrale-view-stage": "", style: STAGE_STYLE });
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@astrale-os/shell-react",
+  "version": "0.1.0",
+  "description": "Astrale shell-react — the React face of the shell (provider, hooks, view components)",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/astrale-os/shell.git",
+    "directory": "packages/shell-react"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@astrale-domains/workspace-schema": ">=0.2.0 <1.0.0",
+    "@astrale-os/kernel-client": ">=0.3.0 <1.0.0",
+    "@astrale-os/kernel-core": ">=0.6.0 <1.0.0",
+    "@astrale-os/kernel-dsl": ">=0.1.0 <1.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@typescript/native-preview": "latest",
+    "@vitejs/plugin-react": "^5.0.4",
+    "happy-dom": "^20.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "~6.0.1-rc",
+    "vitest": "^3.2.4",
+    "@astrale-os/shell": "0.2.0"
+  },
+  "peerDependencies": {
+    "@astrale-os/shell": ">=0.2.0 <1.0.0",
+    "react": ">=18"
+  },
+  "scripts": {
+    "build": "tsgo",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "typecheck": "tsgo --noEmit && tsgo --noEmit -p tsconfig.test.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "preinstall": "node .check-workspace.cjs"
+  }
+}

package/src/application/apps/app-host.tsx

@@ -0,0 +1,113 @@
+import type { NodeRefInput } from '@astrale-os/kernel-client'
+import type { ApplicationNode, AppSession, IntentRegistry, SandboxProfile } from '@astrale-os/shell'
+import type { CSSProperties, ReactElement, ReactNode } from 'react'
+
+/**
+ * AppHost (API §12.2) = useOpenApp + ViewHost. Opens the app's `AppSession`,
+ * mounts its entry view with the session credential, and DISPOSES the session
+ * with the window (unmount, or an app change). `opening` renders while the
+ * session opens; `no-view` when the app pins no entrypoint; every mounted-frame
+ * phase is the window module's `WindowState`.
+ */
+import { forwardRef, useEffect, useRef, useState } from 'react'
+
+import type { ViewHostHandle } from '../../window/host'
+import type { ViewDescriptor } from '../../window/lifecycle/mount'
+import type { WindowState } from '../../window/lifecycle/states'
+
+import { ViewHost } from '../../window/host'
+import { toRef } from './apps.hook'
+import { useOpenApp } from './open-app.hook'
+
+/** The states `AppHost`'s fallback answers — the frame's, plus the two OS phases. */
+export type AppHostFallbackState =
+  | WindowState
+  | { readonly phase: 'opening' }
+  | { readonly phase: 'no-view' }
+
+export interface AppHostProps {
+  app: ApplicationNode | NodeRefInput
+  /**
+   * Default target node delivered to the app's view as `targetNodeId` (API §12.2).
+   * Container-anchored apps need one — the dock passes the current space. A deeper
+   * fix (an install-time app data container + `app::open` returning a default
+   * target) is a tracked domain-modeling question; until then the host supplies it.
+   */
+  node?: NodeRefInput
+  capabilities?: { intents: readonly (keyof IntentRegistry)[] }
+  sandbox?: SandboxProfile | null
+  fallback?: (state: AppHostFallbackState) => ReactNode
+  onSession?: (session: AppSession) => void
+  className?: string
+  style?: CSSProperties
+}
+
+export const AppHost = forwardRef<ViewHostHandle, AppHostProps>(
+  function AppHost(props, ref): ReactElement {
+    const open = useOpenApp()
+    const [session, setSession] = useState<AppSession | null>(null)
+    const [error, setError] = useState<unknown>(undefined)
+
+    const appKey = toRef(props.app)
+    const openRef = useRef(open)
+    openRef.current = open
+    const appRef = useRef(props.app)
+    appRef.current = props.app
+    const onSessionRef = useRef(props.onSession)
+    onSessionRef.current = props.onSession
+
+    // Open (re)opens the session per app; the cleanup disposes it — so the session
+    // is torn down with the window (unmount) and swapped on an app change.
+    useEffect(() => {
+      let cancelled = false
+      let opened: AppSession | null = null
+      setSession(null)
+      setError(undefined)
+      void openRef.current(appRef.current).then(
+        (s) => {
+          if (cancelled) {
+            s.dispose()
+            return
+          }
+          opened = s
+          setSession(s)
+          onSessionRef.current?.(s)
+        },
+        (e: unknown) => {
+          if (!cancelled) setError(e)
+        },
+      )
+      return () => {
+        cancelled = true
+        opened?.dispose()
+      }
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [appKey])
+
+    const { fallback, className, style } = props
+    const box = (children: ReactNode): ReactElement => (
+      <div className={className} style={style}>
+        {children}
+      </div>
+    )
+
+    // A session-open failure has no window yet — `windowId` is honestly absent (§10).
+    if (error !== undefined) return box(fallback?.({ phase: 'crashed', error }) ?? null)
+    if (session === null) return box(fallback?.({ phase: 'opening' }) ?? null)
+    if (session.view === null) return box(fallback?.({ phase: 'no-view' }) ?? null)
+
+    return (
+      <ViewHost
+        ref={ref}
+        view={session.view as ViewDescriptor}
+        node={props.node}
+        credential={session.credential}
+        capabilities={props.capabilities ?? { intents: [] }}
+        sandbox={props.sandbox}
+        fallback={fallback ? (s: WindowState) => fallback(s) : undefined}
+        className={className}
+        style={style}
+      />
+    )
+  },
+)

package/src/application/apps/app-logo.tsx

@@ -0,0 +1,56 @@
+/**
+ * AppLogo (API §12.2) — render a node's logo prop: a url/`data:` URI as `<img>`,
+ * or an inline SVG string (sanitized + inlined), else `fallback`. The SVG path is
+ * a MINIMAL dependency-free strip (drops `<script>`/`<foreignObject>`, `on*`
+ * handlers, `javascript:` URLs); pass pre-sanitized markup for a hardened guard.
+ */
+import type { CSSProperties, ReactElement, ReactNode } from 'react'
+
+const URL_LOGO = /^(?:data:|https?:|\/)/i
+
+export interface AppLogoProps {
+  /** The logo string — a url/`data:` URI or an inline `<svg>` string. */
+  logo?: string
+  /** `<img>` alt text (url logos only). Default: `''` (decorative). */
+  alt?: string
+  className?: string
+  style?: CSSProperties
+  /** Rendered when `logo` is absent or unusable (e.g. a letter avatar). */
+  fallback?: ReactNode
+}
+
+export function AppLogo({ logo, alt, className, style, fallback }: AppLogoProps): ReactElement {
+  if (logo !== undefined && URL_LOGO.test(logo)) {
+    return <img src={logo} alt={alt ?? ''} className={className} style={style} />
+  }
+  const svg = logo !== undefined ? sanitizeInlineSvg(logo) : null
+  if (svg !== null) {
+    return (
+      <span
+        aria-hidden
+        className={className}
+        style={style}
+        // Minimally sanitized inline SVG — see the module header for the trust boundary.
+        dangerouslySetInnerHTML={{ __html: svg }}
+      />
+    )
+  }
+  return <>{fallback ?? null}</>
+}
+
+/**
+ * Accept only a string that opens with `<svg`, and strip the obvious script
+ * vectors: `<script>`/`<foreignObject>` blocks, `on*=` handlers, `javascript:`
+ * URLs. Intentionally minimal (no heavy dep) — not a general HTML sanitizer.
+ */
+function sanitizeInlineSvg(raw: string): string | null {
+  const s = raw.trimStart()
+  if (!s.toLowerCase().startsWith('<svg')) return null
+  return s
+    .replace(/<\s*script[\s\S]*?<\s*\/\s*script\s*>/gi, '')
+    .replace(/<\s*foreignObject[\s\S]*?<\s*\/\s*foreignObject\s*>/gi, '')
+    .replace(/\son[a-z0-9_-]+\s*=\s*"[^"]*"/gi, '')
+    .replace(/\son[a-z0-9_-]+\s*=\s*'[^']*'/gi, '')
+    .replace(/\son[a-z0-9_-]+\s*=\s*[^\s>]+/gi, '')
+    .replace(/(href|xlink:href|src)\s*=\s*(["'])\s*javascript:[^"']*\2/gi, '')
+}

package/src/application/apps/apps.hook.ts

@@ -0,0 +1,81 @@
+import type { NodeRefInput } from '@astrale-os/kernel-client'
+import type { ApplicationNode, SpaceNode } from '@astrale-os/shell'
+
+import { normalizeRef } from '@astrale-os/kernel-client'
+/**
+ * useApps(space?) (API §12.2) — the apps installed in a space (`installed_in`
+ * in-edges). No arg targets the CURRENT space (shared store, so a switch anywhere
+ * swaps the dock) and is IDLE while none is selected (§1.3); an explicit `null`
+ * stays idle; OS plane unavailable → fully idle. Also `toRef`, the app/space
+ * subject normalizer the apps hooks share.
+ */
+import { useCallback, useEffect, useMemo, useSyncExternalStore } from 'react'
+
+import type { ReadState } from '../../graph/memory/read/envelope'
+import type { CurrentSpaceSnapshot } from '../spaces/current-space.store'
+
+import { useAsyncResource } from '../../graph/async'
+import { useShell } from '../../session/shell.hook'
+import { currentSpaceStore } from '../spaces/current-space.store'
+import { isOsPlaneAvailable } from '../user/user.store'
+
+const NO_APPS: readonly ApplicationNode[] = []
+const IDLE_CURRENT: CurrentSpaceSnapshot = { space: null, pending: false, error: undefined }
+
+export interface AppsResult extends ReadState {
+  readonly apps: readonly ApplicationNode[]
+}
+
+export function useApps(space?: SpaceNode | NodeRefInput | null): AppsResult {
+  const shell = useShell()
+  const available = isOsPlaneAvailable(shell)
+
+  // No arg → the CURRENT space, read through the shared store so a switch in any
+  // window swaps the dock here (§12.2). An explicit `null` stays idle; an explicit
+  // space bypasses the store entirely (no needless currentSpace fetch). OS plane
+  // unavailable (§12.2) → fully idle.
+  const useCurrent = space === undefined
+  const store = currentSpaceStore(shell)
+  useEffect(() => {
+    if (useCurrent && available) store.ensure()
+  }, [store, useCurrent, available])
+  const subscribe = useCallback(
+    (cb: () => void) => (useCurrent && available ? store.subscribe(cb) : () => {}),
+    [store, useCurrent, available],
+  )
+  const getSnapshot = useCallback(
+    (): CurrentSpaceSnapshot => (useCurrent && available ? store.getSnapshot() : IDLE_CURRENT),
+    [store, useCurrent, available],
+  )
+  const currentSnap = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+
+  const effective = useCurrent ? currentSnap.space : (space ?? null)
+  const effRef = effective === null ? null : toRef(effective)
+  const appsRes = useAsyncResource<readonly ApplicationNode[]>(
+    !available || effRef === null ? null : () => shell.apps.in(effRef),
+    NO_APPS,
+    [shell, effRef, available],
+  )
+
+  return useMemo<AppsResult>(
+    () => ({
+      apps: appsRes.data,
+      pending: (useCurrent && currentSnap.pending) || appsRes.pending,
+      error: (useCurrent ? currentSnap.error : undefined) ?? appsRes.error,
+      live: false,
+      seq: 0,
+      refetch: appsRes.refetch,
+    }),
+    [appsRes.data, appsRes.pending, appsRes.error, appsRes.refetch, useCurrent, currentSnap],
+  )
+}
+
+/** A bound-node-ish subject carries a graph id. */
+function hasId(x: unknown): x is { readonly id: string } {
+  return typeof x === 'object' && x !== null && 'id' in x
+}
+
+/** An `@id` ref for a bound node, else the normalized ref of a raw subject. */
+export function toRef(x: NodeRefInput | { readonly id: string }): string {
+  return hasId(x) ? `@${x.id}` : normalizeRef(x)
+}

package/src/application/apps/open-app.hook.ts

@@ -0,0 +1,18 @@
+/**
+ * useOpenApp (API §12.2) — the Action that opens an `AppSession` (the three-call
+ * app-open protocol lives in the shell package). Resolves to the session; disposal
+ * is the caller's (AppHost disposes it with the window).
+ */
+import type { NodeRefInput } from '@astrale-os/kernel-client'
+import type { ApplicationNode, AppSession } from '@astrale-os/shell'
+
+import type { Action } from '../../graph/action'
+
+import { useAction } from '../../graph/action'
+import { useShell } from '../../session/shell.hook'
+import { toRef } from './apps.hook'
+
+export function useOpenApp(): Action<[ApplicationNode | NodeRefInput], AppSession> {
+  const shell = useShell()
+  return useAction((app: ApplicationNode | NodeRefInput) => shell.apps.open(toRef(app)))
+}

package/src/application/index.ts

@@ -0,0 +1,22 @@
+// application — API §12.2. The OS-plane hooks over the shell package's
+// `shell.user/spaces/apps` namespaces + the window module: useUser, useSpaces,
+// useCurrentSpace, useSpace, useApps, useRoles, useOpenApp, AppHost, AppLogo.
+export { useUser } from './user/user.hook'
+export { useSpaces } from './spaces/spaces.hook'
+export type { SpacesResult } from './spaces/spaces.hook'
+export { useCurrentSpace } from './spaces/current-space.hook'
+export type { CurrentSpaceResult } from './spaces/current-space.hook'
+export { useSpace } from './spaces/space.hook'
+export type { SpaceResult } from './spaces/space.hook'
+export { useApps } from './apps/apps.hook'
+export type { AppsResult } from './apps/apps.hook'
+export { useOpenApp } from './apps/open-app.hook'
+export { AppHost } from './apps/app-host'
+export type { AppHostFallbackState, AppHostProps } from './apps/app-host'
+export { AppLogo } from './apps/app-logo'
+export type { AppLogoProps } from './apps/app-logo'
+export { useRoles } from './roles.hook'
+export type { RolesResult } from './roles.hook'
+
+// The OS node/session types (from the shell package, single import surface).
+export type { ApplicationNode, AppSession, RoleNode, SpaceNode, UserNode } from '@astrale-os/shell'