@notis_ai/cli 0.2.13 → 0.2.15

package/template/packages/sdk/src/components/MultiSelectActionBar.tsx

@@ -1,25 +1,16 @@
 'use client';
 
-import {
-  useEffect,
+import React, {
   useMemo,
-  useRef,
   useState,
   type CSSProperties,
   type ReactElement,
-  type ReactNode,
 } from 'react';
+import type { ResolvedCollectionAction } from '../interactions/actions';
+import { shortcutDisplay, useShortcuts, type ShortcutDefinition } from '../interactions/shortcuts';
+import type { ShortcutScope } from '../interactions/shortcuts';
 
-export interface MultiSelectAction {
-  id: string;
-  label: string;
-  icon: ReactNode;
-  /** Single-key (e.g. "E", "#") or "Mod+K" shortcut. Bound while the bar is mounted with count > 0. */
-  shortcut?: string;
-  onRun: () => void | Promise<void>;
-  /** Hint for future destructive styling. Currently unused visually. */
-  destructive?: boolean;
-}
+export type MultiSelectAction = ResolvedCollectionAction;
 
 export interface MultiSelectActionBarProps {
   selectedCount: number;
@@ -30,73 +21,10 @@ export interface MultiSelectActionBarProps {
   className?: string;
   /** Optional override for the bar's positioning style. Defaults to bottom-center floating. */
   style?: CSSProperties;
-}
-
-interface ParsedShortcut {
-  key: string;
-  needsMod: boolean;
-  needsShift: boolean;
-}
-
-function parseShortcut(raw: string): ParsedShortcut | null {
-  const parts = raw.split('+').map((p) => p.trim()).filter(Boolean);
-  if (parts.length === 0) return null;
-  let needsMod = false;
-  let needsShift = false;
-  let key = '';
-  for (const part of parts) {
-    const lower = part.toLowerCase();
-    if (lower === 'mod' || lower === 'cmd' || lower === 'ctrl' || lower === 'meta') {
-      needsMod = true;
-    } else if (lower === 'shift') {
-      needsShift = true;
-    } else {
-      key = lower;
-    }
-  }
-  if (!key) return null;
-  return { key, needsMod, needsShift };
-}
-
-function shortcutMatches(shortcut: ParsedShortcut, event: KeyboardEvent): boolean {
-  const eventKey = event.key.toLowerCase();
-  // Special-case "#" so Shift+3 matches without the consumer specifying Shift.
-  if (shortcut.key === '#') {
-    if (eventKey === '#') return true;
-    if (event.shiftKey && eventKey === '3') return true;
-    return false;
-  }
-  if (eventKey !== shortcut.key) return false;
-  if (shortcut.needsMod !== Boolean(event.metaKey || event.ctrlKey)) return false;
-  if (shortcut.needsShift !== event.shiftKey) return false;
-  if (event.altKey) return false;
-  return true;
-}
-
-function isEditableEvent(event: Event): boolean {
-  // Notis apps mount inside a Shadow DOM, so a document-level listener sees
-  // `event.target` retargeted to the shadow host. `composedPath()[0]` pierces
-  // the shadow boundary to the real focused element, so action-bar shortcuts
-  // don't fire while the user is typing in an app input.
-  const target = event.composedPath?.()[0] ?? event.target;
-  if (!(target instanceof HTMLElement)) return false;
-  if (target.isContentEditable) return true;
-  const tag = target.tagName;
-  return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT';
-}
-
-function shortcutDisplay(raw: string): string {
-  const parts = raw.split('+').map((p) => p.trim()).filter(Boolean);
-  return parts
-    .map((part) => {
-      const lower = part.toLowerCase();
-      if (lower === 'mod' || lower === 'cmd' || lower === 'meta') return '⌘';
-      if (lower === 'ctrl') return '⌃';
-      if (lower === 'shift') return '⇧';
-      if (lower === 'alt' || lower === 'option') return '⌥';
-      return part.length === 1 ? part.toUpperCase() : part;
-    })
-    .join('');
+  /** Disable action key bindings while leaving the visible toolbar mounted. */
+  shortcutsEnabled?: boolean;
+  /** Override the default collection shortcut scope. */
+  shortcutScope?: ShortcutScope;
 }
 
 const containerBaseStyle: CSSProperties = {
@@ -180,43 +108,25 @@ export function MultiSelectActionBar({
   itemLabel,
   className,
   style,
+  shortcutsEnabled = true,
+  shortcutScope = 'collection',
 }: MultiSelectActionBarProps): ReactElement | null {
-  const actionsRef = useRef(actions);
-  actionsRef.current = actions;
-
-  const parsedShortcuts = useMemo(() => {
-    return actions
-      .map((action) => {
-        if (!action.shortcut) return null;
-        const parsed = parseShortcut(action.shortcut);
-        return parsed ? { action, parsed } : null;
-      })
-      .filter((entry): entry is { action: MultiSelectAction; parsed: ParsedShortcut } => entry !== null);
+  const actionShortcuts = useMemo<ShortcutDefinition[]>(() => {
+    return actions.flatMap((action): ShortcutDefinition[] => {
+        if (!action.shortcut || action.disabled || action.pending) return [];
+        return [{
+          id: `collection.action.${action.id}`,
+          keys: action.shortcut,
+          label: action.label,
+          onTrigger: () => action.onRun(),
+        }];
+      });
   }, [actions]);
-
-  useEffect(() => {
-    if (selectedCount === 0 || parsedShortcuts.length === 0) return;
-
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (isEditableEvent(event)) return;
-      for (const { action, parsed } of parsedShortcuts) {
-        if (shortcutMatches(parsed, event)) {
-          event.preventDefault();
-          event.stopPropagation();
-          if (typeof event.stopImmediatePropagation === 'function') {
-            event.stopImmediatePropagation();
-          }
-          void action.onRun();
-          return;
-        }
-      }
-    };
-
-    document.addEventListener('keydown', handleKeyDown, true);
-    return () => {
-      document.removeEventListener('keydown', handleKeyDown, true);
-    };
-  }, [parsedShortcuts, selectedCount]);
+  useShortcuts(actionShortcuts, {
+    enabled: shortcutsEnabled && selectedCount > 0,
+    scope: shortcutScope,
+    priority: 25,
+  });
 
   if (selectedCount === 0) return null;
 
@@ -258,21 +168,29 @@ function ActionButton({ action }: { action: MultiSelectAction }) {
     color: hover
       ? 'hsl(var(--background))'
       : baseButtonStyle.color,
+    opacity: action.disabled ? 0.45 : 1,
+    cursor: action.disabled || action.pending ? 'not-allowed' : 'pointer',
   };
 
   return (
     <button
       type="button"
-      onClick={() => void action.onRun()}
+      onClick={() => {
+        if (!action.disabled && !action.pending) void action.onRun();
+      }}
+      disabled={action.disabled || action.pending}
+      aria-busy={action.pending || undefined}
+      aria-keyshortcuts={action.shortcut || undefined}
+      data-destructive={action.destructive ? 'true' : 'false'}
       onMouseEnter={() => setHover(true)}
       onMouseLeave={() => setHover(false)}
       onFocus={() => setHover(true)}
       onBlur={() => setHover(false)}
       style={buttonStyle}
     >
-      <span aria-hidden style={iconSlotStyle}>{action.icon}</span>
+      {action.icon ? <span aria-hidden style={iconSlotStyle}>{action.icon}</span> : null}
       {display ? <kbd aria-hidden style={keycapStyle}>{display}</kbd> : null}
-      <span>{action.label}</span>
+      <span>{action.pending ? `${action.label}…` : action.label}</span>
     </button>
   );
 }

package/template/packages/sdk/src/components/MultiSelectCheckbox.tsx

@@ -1,10 +1,11 @@
 'use client';
 
-import { type CSSProperties, type MouseEvent as ReactMouseEvent, type ReactElement } from 'react';
+import React, { type CSSProperties, type MouseEvent as ReactMouseEvent, type ReactElement } from 'react';
 
 export interface MultiSelectCheckboxProps {
   isSelected: boolean;
   onClick: (event: ReactMouseEvent) => void;
+  disabled?: boolean;
   /** When true, the checkbox is always visible. Default false (hover/focus reveal via the parent's :hover state). */
   alwaysVisible?: boolean;
   /** Optional aria-label override. Defaults to "Select item" / "Deselect item". */
@@ -40,6 +41,7 @@ const checkPath = 'M3.5 7.5l2.5 2.5 6.5-6.5';
 export function MultiSelectCheckbox({
   isSelected,
   onClick,
+  disabled = false,
   alwaysVisible = false,
   ariaLabel,
   className,
@@ -49,6 +51,7 @@ export function MultiSelectCheckbox({
     ...baseStyle,
     ...(isSelected ? selectedStyle : null),
     ...(alwaysVisible || isSelected ? { opacity: 1 } : null),
+    ...(disabled ? { opacity: 0.45, cursor: 'not-allowed' } : null),
     ...(style || null),
   };
 
@@ -62,6 +65,7 @@ export function MultiSelectCheckbox({
       type="button"
       role="checkbox"
       aria-checked={isSelected}
+      disabled={disabled}
       aria-label={ariaLabel ?? (isSelected ? 'Deselect item' : 'Select item')}
       onClick={onClick}
       onMouseDown={(e) => e.stopPropagation()}

package/template/packages/sdk/src/components/MultiSelectDragOverlay.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { type CSSProperties, type ReactElement } from 'react';
+import React, { type CSSProperties, type ReactElement } from 'react';
 import type { DragRect } from '../hooks/useMultiSelect';
 
 export interface MultiSelectDragOverlayProps {

package/template/packages/sdk/src/components/NotisSelectionBoundary.tsx

@@ -0,0 +1,55 @@
+import type { CSSProperties, ClipboardEvent, ReactNode } from 'react';
+import { useCallback } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { ContextResource, ContextSelection } from '../runtime';
+
+export const NOTIS_CONTEXT_CLIPBOARD_TYPE = 'application/x-notis-context+json';
+
+export interface NotisSelectionBoundaryProps {
+  resource?: ContextResource | null;
+  children: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+}
+
+function selectionId(): string {
+  return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+    ? crypto.randomUUID()
+    : `selection-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+/**
+ * Adds structured provenance to ordinary copied text. Pasting still works in
+ * every app because `text/plain` is preserved; Notis chat additionally reads
+ * the custom MIME payload and renders a separate quote pill.
+ */
+export function NotisSelectionBoundary({
+  resource,
+  children,
+  className,
+  style,
+}: NotisSelectionBoundaryProps) {
+  const runtime = useNotisRuntime();
+  const onCopy = useCallback((event: ClipboardEvent<HTMLDivElement>) => {
+    const selection = window.getSelection();
+    const text = selection?.toString().trim() ?? '';
+    if (
+      !text
+      || !selection
+      || !event.currentTarget.contains(selection.anchorNode)
+      || !event.currentTarget.contains(selection.focusNode)
+    ) return;
+
+    const payload: ContextSelection = {
+      id: selectionId(),
+      text: text.slice(0, 12_000),
+      ...(resource ? { resource: { ...resource, snapshot: undefined } } : {}),
+    };
+    event.clipboardData.setData('text/plain', text);
+    event.clipboardData.setData(NOTIS_CONTEXT_CLIPBOARD_TYPE, JSON.stringify(payload));
+    event.preventDefault();
+    runtime?.captureContextSelection?.(payload);
+  }, [resource, runtime]);
+
+  return <div className={className} style={style} onCopy={onCopy}>{children}</div>;
+}

package/template/packages/sdk/src/components/ShortcutHints.tsx

@@ -0,0 +1,56 @@
+'use client';
+
+import React, { type CSSProperties, type ReactElement } from 'react';
+import { shortcutDisplay } from '../interactions/shortcuts';
+
+export interface ShortcutHint {
+  id: string;
+  keys: string;
+  label: string;
+}
+
+export interface ShortcutHintsProps {
+  shortcuts: ShortcutHint[];
+  className?: string;
+  style?: CSSProperties;
+}
+
+const listStyle: CSSProperties = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'center',
+  gap: '0.75rem',
+  color: 'hsl(var(--muted-foreground))',
+  fontSize: '12px',
+};
+
+const hintStyle: CSSProperties = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: '0.35rem',
+};
+
+const keyStyle: CSSProperties = {
+  minWidth: '20px',
+  border: '1px solid hsl(var(--border))',
+  borderRadius: '4px',
+  background: 'hsl(var(--muted))',
+  color: 'hsl(var(--foreground))',
+  padding: '1px 5px',
+  textAlign: 'center',
+  font: 'inherit',
+};
+
+export function ShortcutHints({ shortcuts, className, style }: ShortcutHintsProps): ReactElement | null {
+  if (shortcuts.length === 0) return null;
+  return (
+    <div aria-label="Keyboard shortcuts" className={className} style={{ ...listStyle, ...style }}>
+      {shortcuts.map((shortcut) => (
+        <span key={shortcut.id} style={hintStyle}>
+          <kbd style={keyStyle}>{shortcutDisplay(shortcut.keys)}</kbd>
+          <span>{shortcut.label}</span>
+        </span>
+      ))}
+    </div>
+  );
+}

package/template/packages/sdk/src/config.ts

@@ -83,23 +83,45 @@ export interface NotisAppAuthor {
 }
 
 export interface NotisAppSkillConfig {
+  /** Stable source-owned key used by other app declarations. */
   key: string;
+  /**
+   * Path to the skill, relative to notis.config.ts. Either a Markdown file
+   * (`./skills/onboarding.md`) or a directory holding SKILL.md plus its
+   * supporting files (`./skills/onboarding/`), which are packaged on deploy
+   * and materialized next to SKILL.md in the sandbox.
+   */
   path: string;
+  /** User-facing name used for the installed skill. */
   name: string;
   description?: string;
 }
 
 export interface NotisAppOnboardingConfig {
+  /** Key of a skill declared in `skills`. */
   skill: string;
+  /** Editable message placed in Notis when onboarding is opened. */
   prompt: string;
 }
 
 export interface NotisAppScreenshotConfig {
+  /** Conventional metadata/screenshot-N.png source path. */
   path: string;
+  /** Meaningful description used by the Store gallery and assistive technology. */
   alt: string;
+  /** Route slug captured by `notis apps screenshot`. */
   route?: string;
+  /**
+   * Named scenario from metadata/screenshot-fixtures.json. Its `tools` and
+   * `requests` override the file-level ones key by key for this capture, and
+   * its `actions` run once the route has mounted -- so one route can be shown
+   * in several states (populated, empty, a panel opened) without the states
+   * leaking into each other.
+   */
   scenario?: string;
+  /** Optional CSS selector captured as the truthful focal region for this Store image. */
   focus?: string;
+  /** Portal color scheme used while rendering this screenshot. Defaults to light. */
   theme?: 'light' | 'dark';
 }
 
@@ -131,11 +153,47 @@ export interface NotisAppCapabilities {
    * bound to the app's own databases.
    */
   workspaceDatabases?: 'read';
+
+  /**
+   * Read a few facts about the user's cloud computer: whether a sandbox exists
+   * and is running, and whether the GitHub CLI is signed in there.
+   *
+   * Without this an app has to infer them — the Workspaces app treated a
+   * configured repository as proof that `gh auth login` had happened, which
+   * cannot show an account name and cannot notice a revoked credential.
+   * `'read'` never creates, resumes or commands a sandbox. Read it with
+   * `useCloudComputer()`.
+   *
+   * `'shell'` additionally asks to command the cloud computer: it unlocks
+   * `LOCAL_NOTIS_RUN_SANDBOX_SHELL` and the sandbox file tools from this app's
+   * views (they are denied to every view otherwise), and implies the read
+   * facts. This is the same authority the user's own agent has on the sandbox,
+   * so the user is asked for it explicitly at install or in the Store grant
+   * step; declare it only when the app's core actions genuinely run there.
+   */
+  cloudComputer?: 'read' | 'shell';
+}
+
+/**
+ * Execution hint for a tool whose public name is generated by a provider.
+ *
+ * MCP public names may be truncated or deduplicated, so the upstream action
+ * cannot always be reconstructed from the final `LOCAL_MCP_*` name. Binding
+ * the two lets the host skip provider schema discovery on direct calls while
+ * the public name remains the user-approved permission boundary.
+ */
+export interface NotisAppToolBinding {
+  /** Exact final name also present in `tools`. */
+  name: string;
+  /** Exact upstream MCP action name, for example `execute_sql`. */
+  providerToolName: string;
 }
 
 export interface NotisAppConfig {
   /** URL-safe app slug. Existing apps may still use a display name here. */
   name: string;
+  /** Stable local-development slug. Defaults to a slug derived from `name`. */
+  devSlug?: string;
   /** Human display title, Raycast-style. Falls back to `name`. */
   title?: string;
   description?: string;
@@ -154,6 +212,7 @@ export interface NotisAppConfig {
   tagline?: string;
   /** @deprecated Add release entries to the root CHANGELOG.md instead. */
   versionNotes?: string;
+  /** Editorial screenshot order and capture scenarios for the Store listing. */
   screenshots?: NotisAppScreenshotConfig[];
   /**
    * Databases this app owns. A bare string publishes structure only; use the
@@ -167,8 +226,20 @@ export interface NotisAppConfig {
    */
   capabilities?: NotisAppCapabilities;
   routes?: NotisRouteConfig[];
+  /**
+   * Final tool names this app can call at runtime, enforced server-side. Use
+   * names returned by shared discovery, including native `LOCAL_NOTIS_*`,
+   * connected-service names such as `GMAIL_SEND_EMAIL`,
+   * `LOCAL_POSTFORME_*`, and `LOCAL_MCP_<SERVER>_<TOOL>`. App code calls
+   * each declared name directly with `useTool`; metered calls use the shared
+   * credit-cap and usage-billing path.
+   */
   tools?: string[];
+  /** Optional execution bindings for provider-generated tool names. */
+  toolBindings?: NotisAppToolBinding[];
+  /** Skills shipped from this app's source tree. */
   skills?: NotisAppSkillConfig[];
+  /** Optional onboarding entrypoint exposed from the app sidebar. */
   onboarding?: NotisAppOnboardingConfig;
 }
 

package/template/packages/sdk/src/documents.ts

@@ -12,6 +12,7 @@ import type {
   DatabasePropertyType,
   DocumentContentType,
   DocumentRecord,
+  SecretPropertyValue,
 } from './runtime';
 
 // ---------------------------------------------------------------------------
@@ -45,6 +46,23 @@ export function extractRichText(value: unknown): string {
     .join('');
 }
 
+/**
+ * Reads a `secret` property value. The platform only ever sends the pointer
+ * ({present, reference, status, metadata}), so this rebuilds it field by field
+ * rather than passing the payload through — an app can never surface secret
+ * material through this helper, whatever the server sent.
+ */
+export function getSecretValue(value: unknown): SecretPropertyValue {
+  const record = asRecord(value);
+  const metadata = asRecord(record?.metadata);
+  return {
+    present: record?.present === true,
+    reference: optionalString(record?.reference),
+    status: optionalString(record?.status),
+    metadata,
+  };
+}
+
 /** Extracts the ids of a normalized relation property value. */
 export function getRelationIds(value: unknown): string[] {
   if (!Array.isArray(value)) return [];
@@ -81,12 +99,15 @@ export function normalizePropertyValue(value: unknown): unknown {
     return items.map((item) => optionalString(asRecord(item)?.id) ?? item).filter(Boolean);
   }
   if (type === 'date') return optionalString(asRecord(record.date)?.start) ?? record.date ?? null;
+  // Before the `type in record` fallthrough: a secret value has no `secret`
+  // key, so passing it through would hand the caller the raw payload.
+  if (type === 'secret') return getSecretValue(record);
   if (type in record) return record[type];
   return value;
 }
 
 function normalizeContentType(value: unknown): DocumentContentType | null {
-  return value === 'markdown' || value === 'file' ? value : null;
+  return value === 'markdown' || value === 'file' || value === 'view' ? value : null;
 }
 
 /**
@@ -119,6 +140,12 @@ export function normalizeDocumentRecord(value: unknown): DocumentRecord {
         : null,
     contentMarkdown: optionalString(record.contentMarkdown) ?? optionalString(record.content_markdown),
     plainText: optionalString(record.plainText) ?? optionalString(record.plain_text),
+    viewType: optionalString(record.viewType) ?? optionalString(record.view_type),
+    viewState: asRecord(record.viewState) ?? asRecord(record.view_state),
+    viewRevision:
+      typeof (record.viewRevision ?? record.view_revision) === 'number'
+        ? Number(record.viewRevision ?? record.view_revision)
+        : null,
     createdAt:
       optionalString(record.createdAt)
       ?? optionalString(record.created_at)

package/template/packages/sdk/src/hooks/useActiveResource.ts

@@ -0,0 +1,19 @@
+import { useEffect, useMemo } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { ContextResource } from '../runtime';
+
+function stableResource(resource: ContextResource | null): string {
+  return JSON.stringify(resource);
+}
+
+/** Keep Notis aware of the resource currently open inside an app view. */
+export function useActiveResource(resource: ContextResource | null): void {
+  const runtime = useNotisRuntime();
+  const signature = stableResource(resource);
+  const stable = useMemo(() => resource, [signature]);
+
+  useEffect(() => {
+    runtime?.publishActiveResource?.(stable);
+    return () => runtime?.publishActiveResource?.(null);
+  }, [runtime, stable]);
+}

package/template/packages/sdk/src/hooks/useCloudComputer.ts

@@ -0,0 +1,97 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { CloudComputerFacts } from '../runtime';
+
+export interface UseCloudComputerResult {
+  /**
+   * The facts, or null while the first read is in flight. `facts.available`
+   * is false when this host cannot answer — render the app's own fallback.
+   */
+  facts: CloudComputerFacts | null;
+  loading: boolean;
+  error: Error | null;
+  /** Re-read the facts. The platform caches them for a few minutes. */
+  refresh: () => Promise<void>;
+}
+
+const UNAVAILABLE: CloudComputerFacts = {
+  available: false,
+  reason: 'unsupported_host',
+  sandbox: null,
+  cli_auth: {
+    gh: { authenticated: null, account: null, checked_at: null, reason: 'unsupported_host' },
+  },
+};
+
+/**
+ * Read-only facts about the user's cloud computer.
+ *
+ * ```tsx
+ * const { facts } = useCloudComputer();
+ * const gh = facts?.available ? facts.cli_auth.gh : null;
+ *
+ * return gh?.authenticated
+ *   ? <p>Signed in as {gh.account}</p>
+ *   : <GithubConnect />;
+ * ```
+ *
+ * Requires `capabilities.cloudComputer: 'read'` in `notis.config.ts` and the
+ * user's approval at install time. It answers with state the platform already
+ * holds: reading it never creates, resumes or commands a sandbox, and the GitHub
+ * probe only runs when the sandbox is already awake. `authenticated: null`
+ * therefore means *unknown*, not *signed out* — keep the app's own fallback for
+ * that case and for hosts that answer `{ available: false }` (the dev harness,
+ * the vite preview).
+ */
+export function useCloudComputer(): UseCloudComputerResult {
+  const runtime = useNotisRuntime();
+  const [facts, setFacts] = useState<CloudComputerFacts | null>(null);
+  // True from the first committed render: the initial read is already queued
+  // in an effect, and `{ loading: false, facts: null }` would flash a
+  // consumer's fallback branch before the answer arrives.
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  const mounted = useRef(true);
+
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+
+  const read = useCallback(async (options?: { refresh?: boolean }) => {
+    if (!runtime?.cloudComputerFacts) {
+      setFacts(UNAVAILABLE);
+      setLoading(false);
+      return;
+    }
+
+    setLoading(true);
+    setError(null);
+    try {
+      const next = await runtime.cloudComputerFacts(options);
+      if (mounted.current) setFacts(next);
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      if (mounted.current) {
+        setError(e);
+        // A refused or failed read is the same product state as a host that
+        // cannot answer: the app shows its fallback instead of an error.
+        setFacts(UNAVAILABLE);
+      }
+    } finally {
+      if (mounted.current) setLoading(false);
+    }
+  }, [runtime]);
+
+  useEffect(() => {
+    void read();
+  }, [read]);
+
+  const refresh = useCallback(() => read({ refresh: true }), [read]);
+
+  return { facts, loading, error, refresh };
+}