@notis_ai/cli 0.2.0-beta.191.1 → 0.2.0-beta.196.1

package/dist/sdk/src/components/DocumentEditor.tsx

@@ -4,6 +4,7 @@ import type { CSSProperties, ReactElement } from 'react';
 import { useNotisRuntime } from '../provider';
 import { useDocument } from '../hooks/useDocument';
 import { Markdown } from './Markdown';
+import { RecordComponentUnavailable } from './RecordComponents';
 import type { NotisDocumentEditorProps } from '../runtime';
 
 const fallbackNoticeStyle: CSSProperties = {
@@ -35,7 +36,7 @@ const fallbackTitleStyle: CSSProperties = {
  */
 function DocumentEditorFallback({ documentId, variant = 'full', className }: NotisDocumentEditorProps) {
   const runtime = useNotisRuntime();
-  const { document, loading, error } = useDocument(documentId);
+  const { document, loading, error } = useDocument(documentId ?? null);
   // Listing screenshots should show the app as it looks in the portal, so the
   // harness-only editing notice stays out of scenario captures.
   const isScreenshot = Boolean(runtime?.context?.screenshotScenario);
@@ -68,7 +69,7 @@ function DocumentEditorFallback({ documentId, variant = 'full', className }: Not
             ? 'Interactive report'
             : document.viewType === 'html'
               ? 'Interactive HTML document'
-              : 'View document'} — open it in Notis Documents for
+              : 'View document'} — open it in its Notis Space for
           the full native experience.
         </div>
       ) : (
@@ -87,7 +88,7 @@ function DocumentEditorFallback({ documentId, variant = 'full', className }: Not
  * dispatches on the document's content type (markdown -> rich text editor,
  * files -> matching viewer, views -> their trusted native Documents surface).
  * Outside the portal this falls back to a read-only preview or an explicit
- * open-in-Documents notice for native views.
+ * open-in-Space notice for native views.
  *
  * ```tsx
  * <DocumentEditor documentId={entry.id} variant="body" className="min-h-[320px]" />
@@ -99,5 +100,7 @@ export function DocumentEditor(props: NotisDocumentEditorProps): ReactElement {
   if (HostEditor) {
     return <HostEditor {...props} />;
   }
+  // A Space must never fall back to the legacy account-wide document reader.
+  if (runtime?.resource?.kind === 'space' || props.recordKey) return <RecordComponentUnavailable className={props.className} />;
   return <DocumentEditorFallback {...props} />;
 }

package/dist/sdk/src/components/DocumentPage.tsx

@@ -0,0 +1,141 @@
+'use client';
+
+import { useCallback, useRef, type CSSProperties, type ReactElement } from 'react';
+import { useNotisRuntime } from '../provider';
+import { DocumentEditor } from './DocumentEditor';
+import { ShareControl } from './RecordComponents';
+import { Skeleton } from './Skeleton';
+import type { NotisDocumentPageProps } from '../runtime';
+
+const copy = {
+  en: { loading: 'Loading document', breadcrumb: 'Breadcrumb' },
+  fr: { loading: 'Chargement du document', breadcrumb: "Fil d'Ariane" },
+};
+
+/** Column widths shared by the host page, its skeleton and the fallback, so nothing moves when the page arrives. */
+export const DOCUMENT_PAGE_WIDTHS = { standard: 900, wide: 1200, full: undefined } as const;
+/**
+ * The page's horizontal gutter: 16px, then 48px from 640px wide (the host page's px-4 sm:px-12), and its
+ * toolbar height (56px plus its 1px border, Beta's py-3 toolbar). The skeleton uses the same values.
+ */
+export const DOCUMENT_PAGE_GUTTER = { narrow: 16, wide: 48, breakpoint: 640, toolbar: 57 } as const;
+
+const SKELETON = 'notis-document-page-skeleton';
+// Inline styles cannot change with the width; this sheet (rendered with the skeleton, so it reaches a
+// Space's ShadowRoot) gives the skeleton the page's own gutter and icon row at every width.
+const skeletonCss = `.${SKELETON}__column{padding:8px ${DOCUMENT_PAGE_GUTTER.narrow}px 0}`
+  + `.${SKELETON}__icon{width:44px;height:44px;margin-bottom:4px}`
+  + `@media (min-width:${DOCUMENT_PAGE_GUTTER.breakpoint}px){.${SKELETON}__column{padding:8px ${DOCUMENT_PAGE_GUTTER.wide}px 0}`
+  + `.${SKELETON}__icon{width:56px;height:56px}}`;
+
+function useCopy() {
+  return copy[useNotisRuntime()?.context?.locale === 'fr' ? 'fr' : 'en'];
+}
+
+function columnStyle(width: NotisDocumentPageProps['width'] = 'standard'): CSSProperties {
+  const max = DOCUMENT_PAGE_WIDTHS[width];
+  return { width: '100%', maxWidth: max ? `${max}px` : undefined, margin: '0 auto', boxSizing: 'border-box' };
+}
+
+/**
+ * Placeholder shaped like the document page (toolbar, icon row, title, meta strip, body lines) at the
+ * same column width and gutter, so the page replaces it without a layout shift. Hosts show it while the
+ * record and the editor load; a Space can show it while its own data decides which record opens.
+ */
+export function DocumentPageSkeleton({ width = 'standard', className, label }: {
+  width?: NotisDocumentPageProps['width']; className?: string; label?: string;
+}): ReactElement {
+  const t = useCopy();
+  return <div role="status" aria-busy="true" aria-label={label || t.loading} data-notis-skeleton="document-page" className={className}
+    style={{ width: '100%', display: 'flex', flexDirection: 'column' }}>
+    <style>{skeletonCss}</style>
+    <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', height: DOCUMENT_PAGE_GUTTER.toolbar,
+      padding: `0 ${DOCUMENT_PAGE_GUTTER.narrow}px`, boxSizing: 'border-box' }}>
+      <Skeleton style={{ width: 180, height: 14 }} />
+      <Skeleton style={{ width: 48, height: 12 }} />
+    </div>
+    <div className={`${SKELETON}__column`} style={{ ...columnStyle(width), display: 'flex', flexDirection: 'column' }}>
+      <Skeleton className={`${SKELETON}__icon`} style={{ borderRadius: 12, height: undefined }} />
+      <Skeleton style={{ width: '58%', height: 36, margin: '2px 0 10px' }} />
+      <Skeleton style={{ width: '72%', height: 14, margin: '15px 0' }} />
+      <div style={{ display: 'grid', gap: 12, marginTop: 24 }}>
+        {[100, 96, 88, 100, 64].map((size, index) => <Skeleton key={index} style={{ width: `${size}%`, height: 16 }} />)}
+      </div>
+    </div>
+  </div>;
+}
+
+/**
+ * Shown by hosts that predate DocumentPage: the same record, with the editor these hosts already have.
+ * menuItems show as plain toolbar buttons and onSaved is called when a save finishes (title null);
+ * layout, header parts, meta and width options other than the column are not available there.
+ */
+function DocumentPageFallback(props: NotisDocumentPageProps) {
+  const t = useCopy();
+  const { recordKey, breadcrumb, actions, share = false, aboveBody, belowBody, width, readOnly, className, menuItems = [], onSaved, onSavingChange } = props;
+  const crumbs = breadcrumb === false ? [] : breadcrumb || [];
+  const showToolbar = crumbs.length > 0 || Boolean(actions) || share || menuItems.length > 0;
+  // DocumentEditor reports saving, not what it saved: a finished save tells the Space to refresh its lists.
+  const saving = useRef(false);
+  const savingChange = useCallback((value: boolean) => {
+    if (saving.current && !value) onSaved?.({ recordKey, title: null });
+    saving.current = value;
+    onSavingChange?.(value);
+  }, [onSaved, onSavingChange, recordKey]);
+  return <div className={className} style={{ width: '100%', display: 'flex', flexDirection: 'column' }}>
+    {showToolbar ? <div style={{ display: 'flex', alignItems: 'center', gap: 8, minHeight: 48, padding: '0 16px' }}>
+      <nav aria-label={t.breadcrumb} style={{ display: 'flex', alignItems: 'center', gap: 4, flex: 1, minWidth: 0, fontSize: 14 }}>
+        {crumbs.map((crumb, index) => <span key={`${crumb.label}-${index}`} style={{ display: 'inline-flex', alignItems: 'center', gap: 4 }}>
+          {crumb.onSelect ? <button type="button" onClick={crumb.onSelect}
+            style={{ background: 'none', border: 0, padding: '4px 6px', borderRadius: 6, cursor: 'pointer', color: 'hsl(var(--muted-foreground))', font: 'inherit' }}>
+            {crumb.label}</button> : <span style={{ color: 'hsl(var(--muted-foreground))' }}>{crumb.label}</span>}
+          <span aria-hidden="true" style={{ color: 'hsl(var(--muted-foreground))' }}>/</span>
+        </span>)}
+      </nav>
+      {actions}
+      {share ? <ShareControl recordKey={recordKey} /> : null}
+      {/* The host's '...' menu is not available here: its entries show as plain buttons. */}
+      {menuItems.map((item, index) => <button key={`${item.label}-${index}`} type="button" onClick={item.onSelect} disabled={item.disabled}
+        style={{ background: 'none', border: 0, padding: '4px 8px', borderRadius: 6, cursor: item.disabled ? 'default' : 'pointer', font: 'inherit', fontSize: 13,
+          color: item.destructive ? 'hsl(var(--destructive))' : 'hsl(var(--muted-foreground))', opacity: item.disabled ? 0.5 : 1 }}>{item.label}</button>)}
+    </div> : null}
+    <div style={{ ...columnStyle(width), padding: '24px 16px 96px', display: 'flex', flexDirection: 'column', gap: 20 }}>
+      {aboveBody}
+      <DocumentEditor recordKey={recordKey} variant={props.header === false ? 'body' : 'full'} showProperties={props.properties !== 'hidden'}
+        readOnly={readOnly} onDirtyChange={props.onDirtyChange} onSavingChange={savingChange} />
+      {belowBody}
+    </div>
+  </div>;
+}
+
+/**
+ * The full page of one record that is the main content of a Space view, such as a note: breadcrumb,
+ * Saving or Saved status, '...' menu, cover, icon, title, meta strip, properties that save
+ * automatically, and the collaborative body with presence. The host (Portal) draws it and keeps one
+ * save queue for the whole record. Files open in their viewer under the header; HTML and reports show
+ * only the toolbar (breadcrumb, actions, Share, '...' menu) above their frame, with no header, meta,
+ * properties, aboveBody or belowBody.
+ *
+ * ```tsx
+ * if (params.note) return <DocumentPage recordKey={params.note}
+ *   breadcrumb={[{ label: 'All notes', onSelect: () => setParams({ note: null }) }]}
+ *   actions={<TrashButton />} onSaved={() => notes.refetch()} />;
+ * ```
+ *
+ * Slots (`breadcrumb`, `actions`, `menuItems`, `aboveBody`, `belowBody`) and toggles (`share`,
+ * `header`, `meta`, `properties`, `width`) adjust it; `layout` rearranges its parts. Hosts without
+ * this component show the record with `DocumentEditor` instead.
+ */
+export function DocumentPage(props: NotisDocumentPageProps): ReactElement {
+  const Host = useNotisRuntime()?.ui?.DocumentPage;
+  return Host ? <Host {...props} /> : <DocumentPageFallback {...props} />;
+}
+
+/**
+ * Starts reading a record before it opens (for example on a list row's hover or focus), so its
+ * DocumentPage shows at once. Does nothing outside a host that supports it.
+ */
+export function usePrefetchRecord(): (recordKey: string) => void {
+  const prefetch = useNotisRuntime()?.ui?.prefetchRecord;
+  return useCallback((recordKey: string) => { if (recordKey) prefetch?.(recordKey); }, [prefetch]);
+}

package/dist/sdk/src/components/RecordComponents.tsx

@@ -0,0 +1,33 @@
+"use client";
+
+import type { ReactElement } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { NotisHtmlFrameProps, NotisRecordPropertiesProps, NotisReportFrameProps, NotisShareControlProps } from '../runtime';
+
+const copy = {
+  en: { unavailable: 'Open this record in Notis to use this component.' },
+  fr: { unavailable: 'Ouvre cet enregistrement dans Notis pour utiliser ce composant.' },
+};
+export function RecordComponentUnavailable({ className }: { className?: string }): ReactElement {
+  const runtime = useNotisRuntime();
+  const locale = runtime?.context?.locale === 'fr' ? 'fr' : 'en';
+  return <div role="status" className={className}>{copy[locale].unavailable}</div>;
+}
+export function RecordProperties(props: NotisRecordPropertiesProps): ReactElement {
+  const Host = useNotisRuntime()?.ui?.RecordProperties;
+  return Host ? <Host {...props} /> : <RecordComponentUnavailable className={props.className} />;
+}
+/** The host applies its viewer CSP and an opaque-origin sandbox; source cannot relax either. */
+export function HtmlFrame(props: NotisHtmlFrameProps): ReactElement {
+  const Host = useNotisRuntime()?.ui?.HtmlFrame;
+  return Host ? <Host {...props} /> : <RecordComponentUnavailable className={props.className} />;
+}
+export function ReportFrame(props: NotisReportFrameProps): ReactElement {
+  const Host = useNotisRuntime()?.ui?.ReportFrame;
+  return Host ? <Host {...props} /> : <RecordComponentUnavailable className={props.className} />;
+}
+/** Private/shared state, copy link and revoke, backed by this record's Site. */
+export function ShareControl(props: NotisShareControlProps): ReactElement {
+  const Host = useNotisRuntime()?.ui?.ShareControl;
+  return Host ? <Host {...props} /> : <RecordComponentUnavailable className={props.className} />;
+}

package/dist/sdk/src/components/RenderChartData.tsx

@@ -0,0 +1,19 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+/** A chart's data, available to view Markdown without adding a second visible table.
+ * Keep labels/values identical to the chart. The renderer recognizes this semantic
+ * table inside Shadow DOM; snapshots never infer numbers from SVG geometry.
+ */
+export function RenderChartData({ title, columns, rows, children }: {
+  title: string;
+  columns: readonly string[];
+  rows: readonly (readonly (string | number | boolean | null)[])[];
+  children?: ReactNode;
+}) {
+  return <>{children}<table hidden data-notis-render="chart-data" aria-label={title}>
+    <thead><tr>{columns.map((column, index) => <th key={index}>{column}</th>)}</tr></thead>
+    <tbody>{rows.map((row, index) => <tr key={index}>{columns.map((_, column) => <td key={column}>{row[column] == null ? '' : String(row[column])}</td>)}</tr>)}</tbody>
+  </table></>;
+}

package/dist/sdk/src/config.ts

@@ -1,3 +1,7 @@
+export { defineSpace, defineSpaces } from './space';
+export type { SpaceDefinition, SpacesWorkspace, SpaceActionTemplate, SpaceResourceReference, SpaceDatabaseCreate } from './space';
+export type { SpaceViewParam, SpaceViewParamType, SpaceShows, SpaceMemoryPolicy, SpaceMemorySnapshot, SpaceChrome, SpaceMarkdownInput } from './space';
+
 /**
  * Configuration utilities for notis.config.ts.
  *
@@ -88,28 +92,6 @@ export interface NotisAppAuthor {
   url?: string;
 }
 
-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;
@@ -245,10 +227,6 @@ export interface NotisAppConfig {
   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/dist/sdk/src/documents.ts

@@ -125,6 +125,8 @@ export function normalizeDocumentRecord(value: unknown): DocumentRecord {
 
   return {
     id: optionalString(record.id) ?? '',
+    recordKey: optionalString(record.recordKey) ?? optionalString(record.record_key) ?? undefined,
+    revision: typeof record.revision === 'number' ? record.revision : undefined,
     title: optionalString(record.title) ?? 'Untitled',
     url: optionalString(record.url),
     properties,

package/dist/sdk/src/hooks/useAction.ts

@@ -0,0 +1,28 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { useQuery, type UseQueryOptions, type UseQueryResult } from './useQuery';
+import type { SpaceActionOptions } from '../space';
+
+export function useAction<TInput extends Record<string, unknown> = Record<string, unknown>, TResult = unknown>(actionId: string): {
+  call: (inputs: TInput, options?: SpaceActionOptions) => Promise<TResult>; loading: boolean; error: Error | null;
+} {
+  const runtime = useNotisRuntime();
+  const [pending, setPending] = useState(0);
+  const [error, setError] = useState<Error | null>(null);
+  const call = useCallback(async (inputs: TInput, options?: SpaceActionOptions) => {
+    if (runtime?.resource?.kind !== 'space' || !runtime.callAction) throw new Error('A Space action runtime is required.');
+    setPending((value) => value + 1); setError(null);
+    try { return await runtime.callAction<TResult>(actionId, inputs, options); }
+    catch (cause) { const failure = cause instanceof Error ? cause : new Error(String(cause)); setError(failure); throw failure; }
+    finally { setPending((value) => value - 1); }
+  }, [runtime, actionId]);
+  return { call, loading: pending > 0, error };
+}
+
+export function useActionQuery<TResult = unknown>(actionId: string, inputs: Record<string, unknown>,
+  options: UseQueryOptions = { readOnly: true }): UseQueryResult<TResult> {
+  const { call } = useAction<Record<string, unknown>, TResult>(actionId);
+  return useQuery(['action', actionId, inputs], () => call(inputs, { readOnly: true, dedupe: true }), options);
+}

package/dist/sdk/src/hooks/useCloudComputer.ts

@@ -3,7 +3,21 @@
 import { useCallback, useRef } from 'react';
 import { useQuery } from './useQuery';
 import { useNotisRuntime } from '../provider';
-import type { CloudComputerFacts } from '../runtime';
+import { queryKey } from '../queryCache';
+import { spaceQueryKey } from '../space';
+import type { CloudComputerFacts, NotisRuntime } from '../runtime';
+
+/** Cache key of the facts read; re-read once the viewer allows a Space to use the cloud computer. */
+export const CLOUD_COMPUTER_FACTS_KEY = ['cloud-computer-facts'] as const;
+
+/** Marks the facts stale in the host cache so every mounted `useCloudComputer()` reads them again. */
+export function invalidateCloudComputerFacts(runtime: NotisRuntime | null): void {
+  try {
+    runtime?.queryClient?.invalidate(queryKey(spaceQueryKey(runtime, CLOUD_COMPUTER_FACTS_KEY)));
+  } catch {
+    // A host without a Space access context has no shared facts cache to refresh.
+  }
+}
 
 export interface UseCloudComputerResult {
   /**
@@ -16,6 +30,12 @@ export interface UseCloudComputerResult {
   error: Error | null;
   /** Re-read the facts. The platform caches them for a few minutes. */
   refresh: () => Promise<void>;
+  /**
+   * Space only (`cloudComputer: 'read'` or `'shell'`): ask the host to show its approval prompt.
+   * Resolves true once the viewer allowed it (the facts are then read again), false when they did
+   * not, and null on hosts without the prompt (Beta Apps, Sites, previews offline).
+   */
+  requestApproval: () => Promise<boolean | null>;
 }
 
 const UNAVAILABLE: CloudComputerFacts = {
@@ -40,7 +60,9 @@ const UNAVAILABLE: CloudComputerFacts = {
  * ```
  *
  * Requires `capabilities.cloudComputer: 'read'` in `notis.config.ts` and the
- * user's approval at install time. It answers with state the platform already
+ * user's approval at install time. In a Space, declare `cloudComputer: 'read'`
+ * (or `'shell'`) in `defineSpace`; until the viewer allows it the facts answer
+ * unavailable, so offer `requestApproval()`. 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
@@ -50,7 +72,7 @@ const UNAVAILABLE: CloudComputerFacts = {
 export function useCloudComputer(): UseCloudComputerResult {
   const runtime = useNotisRuntime();
   const explicitRefresh = useRef(false);
-  const query = useQuery<CloudComputerFacts>(['cloud-computer-facts'], async () => {
+  const query = useQuery<CloudComputerFacts>(CLOUD_COMPUTER_FACTS_KEY, async () => {
     const refresh = explicitRefresh.current;
     explicitRefresh.current = false;
     return runtime?.cloudComputerFacts ? runtime.cloudComputerFacts(refresh ? { refresh: true } : undefined) : UNAVAILABLE;
@@ -59,6 +81,15 @@ export function useCloudComputer(): UseCloudComputerResult {
     explicitRefresh.current = true;
     await query.refetch();
   }, [query.refetch]);
+  const transport = runtime?.spaceCloudComputer;
+  const requestApproval = useCallback(async () => {
+    if (!transport) return null;
+    const status = await transport.requestApproval();
+    if (status?.approved !== true) return false;
+    invalidateCloudComputerFacts(runtime);
+    await query.refetch();
+    return true;
+  }, [query.refetch, runtime, transport]);
   return { facts: query.data ?? (query.error ? UNAVAILABLE : null), loading: query.loading,
-    isFetching: query.isFetching, error: query.error, refresh };
+    isFetching: query.isFetching, error: query.error, refresh, requestApproval };
 }

package/dist/sdk/src/hooks/useCloudComputerShell.ts

@@ -0,0 +1,114 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { invalidateCloudComputerFacts } from './useCloudComputer';
+import type {
+  SpaceCloudComputerLevel,
+  SpaceCloudComputerRunResult,
+  SpaceCloudComputerStatus,
+  SpaceCloudComputerUploadInput,
+  SpaceCloudComputerUploadResult,
+} from '../space';
+
+export interface UseCloudComputerShellResult {
+  /**
+   * The level this Space declares (`'read'` or `'shell'`) when this host offers the cloud computer,
+   * else null (Sites, links, verification harnesses, older hosts): keep the page's own fallback.
+   */
+  level: SpaceCloudComputerLevel | null;
+  /** True when `run` and `upload` are offered: the host offers the cloud computer and the Space declares `'shell'`. */
+  available: boolean;
+  /** The viewer's approval for this Space's current code (either level), or null while it is read. */
+  status: SpaceCloudComputerStatus | null;
+  approved: boolean;
+  loading: boolean;
+  /**
+   * Run one non-interactive command on the viewer's own cloud computer. Same result as the shell tool.
+   * Pass the same `requestId` when the page retries this run itself: a run is never repeated for one key.
+   */
+  run(command: string, options?: RunOptions): Promise<SpaceCloudComputerRunResult>;
+  /** Write one file (at most 1 MiB) straight to the cloud computer; it never travels by URL or chat. */
+  upload(file: SpaceCloudComputerUploadInput): Promise<SpaceCloudComputerUploadResult>;
+  /**
+   * Ask the host to show its approval prompt, for either declared level. Only the person's click in
+   * that prompt approves; once allowed, every `useCloudComputer()` reads the facts again.
+   */
+  requestApproval(): Promise<SpaceCloudComputerStatus | null>;
+  refresh(): Promise<void>;
+}
+
+type RunOptions = { cwd?: string; timeoutMs?: number; maxOutputLength?: number; requestId?: string };
+
+const unavailable = async (): Promise<never> => {
+  throw new Error('The cloud computer is not available in this Space.');
+};
+
+/**
+ * The viewer's approval and, for `cloudComputer: 'shell'`, commands and file writes on the signed-in
+ * viewer's own cloud computer, from a Space page.
+ *
+ * ```tsx
+ * const shell = useCloudComputerShell();
+ * if (!shell.level) return <AskNotisFallback />;
+ * if (!shell.approved) return <Button onClick={() => shell.requestApproval()}>Allow</Button>;
+ * const result = await shell.run(`bash ${SCRIPTS}/workspace.sh sync ${quote(repo)} ${quote(name)}`);
+ * ```
+ *
+ * Requires `cloudComputer` in `defineSpace` and the viewer's approval, which the Portal asks for in
+ * its own prompt and which covers only the exact code the viewer allowed: any new release asks again.
+ */
+export function useCloudComputerShell(): UseCloudComputerShellResult {
+  const runtime = useNotisRuntime();
+  const transport = runtime?.spaceCloudComputer;
+  const declared = runtime?.space?.cloudComputer;
+  const level: SpaceCloudComputerLevel | null = transport && (declared === 'read' || declared === 'shell') ? declared : null;
+  const available = level === 'shell';
+  const [status, setStatus] = useState<SpaceCloudComputerStatus | null>(null);
+  const [loading, setLoading] = useState(Boolean(level));
+  const mounted = useRef(true);
+  useEffect(() => () => { mounted.current = false; }, []);
+
+  const refresh = useCallback(async () => {
+    if (!level || !transport) return;
+    setLoading(true);
+    try {
+      const next = await transport.status();
+      if (mounted.current) setStatus(next);
+    } catch {
+      if (mounted.current) setStatus(null);
+    } finally {
+      if (mounted.current) setLoading(false);
+    }
+  }, [level, transport]);
+
+  useEffect(() => {
+    mounted.current = true;
+    void refresh();
+  }, [refresh]);
+
+  const run = useCallback(async (command: string, options: RunOptions = {}) => {
+    if (!available || !transport) return unavailable();
+    return transport.run({ command, ...(options.cwd ? { cwd: options.cwd } : {}),
+      ...(options.timeoutMs ? { timeout_ms: options.timeoutMs } : {}),
+      ...(options.maxOutputLength ? { max_output_length: options.maxOutputLength } : {}),
+      ...(options.requestId ? { request_id: options.requestId } : {}) });
+  }, [available, transport]);
+
+  const upload = useCallback(async (file: SpaceCloudComputerUploadInput) => {
+    if (!available || !transport) return unavailable();
+    return transport.upload(file);
+  }, [available, transport]);
+
+  const requestApproval = useCallback(async () => {
+    if (!level || !transport) return null;
+    const next = await transport.requestApproval();
+    if (mounted.current) setStatus(next);
+    // A facts read refused before the approval must not keep showing "unavailable".
+    if (next?.approved === true) invalidateCloudComputerFacts(runtime);
+    return next;
+  }, [level, runtime, transport]);
+
+  return { level, available, status, approved: status?.approved === true, loading: Boolean(level) && loading,
+    run, upload, requestApproval, refresh };
+}

package/dist/sdk/src/hooks/useHandover.ts

@@ -48,12 +48,13 @@ export interface UseHandoverResult {
  */
 export function useHandover(): UseHandoverResult {
   const runtime = useNotisRuntime();
+  const dispatch = runtime?.resource?.kind === 'space' ? runtime.draftHandover : runtime?.handover;
   const [pending, setPending] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
   const handover = useCallback(
     async (payload: HandoverPayload): Promise<HandoverResult> => {
-      if (!runtime?.handover) {
+      if (!dispatch) {
         throw new Error('This Notis host cannot hand work to the manager chat.');
       }
 
@@ -61,7 +62,7 @@ export function useHandover(): UseHandoverResult {
       setError(null);
 
       try {
-        return await runtime.handover(payload);
+        return await dispatch(payload);
       } catch (err) {
         const e = err instanceof Error ? err : new Error(String(err));
         setError(e);
@@ -70,8 +71,8 @@ export function useHandover(): UseHandoverResult {
         setPending(false);
       }
     },
-    [runtime],
+    [dispatch],
   );
 
-  return { handover, pending, error, available: Boolean(runtime?.handover) };
+  return { handover, pending, error, available: Boolean(dispatch) };
 }

package/dist/sdk/src/hooks/useNativeDocumentBody.ts

@@ -0,0 +1,50 @@
+'use client';
+
+import { useCallback, useLayoutEffect, useRef, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { useQuery } from './useQuery';
+import { SpaceActionError, spaceQueryKey, type SpaceDocumentBodyRead, type SpaceDocumentBodySave } from '../space';
+
+/** Explicit textarea Save. The source owns the draft and retains its request ID
+ * until a receipt or unchanged result; background reads never replace that draft. */
+export function useNativeDocumentBody(binding: string, recordKey: string | null, options: {
+  readAction: string; writeAction?: string; enabled?: boolean;
+}) {
+  const runtime = useNotisRuntime();
+  const scope = JSON.stringify(spaceQueryKey(runtime, ['native-body', binding, recordKey, options.readAction, options.writeAction]));
+  const currentScope = useRef<string | null>(scope);
+  useLayoutEffect(() => {
+    currentScope.current = scope;
+    return () => { currentScope.current = null; };
+  }, [scope]);
+  const [state, setState] = useState<{ scope: string; pending: number; error: Error | null }>({ scope, pending: 0, error: null });
+  const query = useQuery<SpaceDocumentBodyRead>(['native-body', binding, recordKey, options.readAction], async () => {
+    if (!recordKey || runtime?.resource?.kind !== 'space' || !runtime.documentBody) throw new Error('Open a Space document first.');
+    const result = await runtime.documentBody({ operation: 'read', binding, recordKey, readAction: options.readAction });
+    if (!('content_markdown' in result)) throw new Error('The document response is incomplete.');
+    return result;
+  }, { readOnly: true, enabled: Boolean(recordKey) && options.enabled !== false });
+  const save = useCallback(async (draft: {
+    contentMarkdown: string; expectedRevision: number; schemaRevision: number; requestId: string;
+  }): Promise<SpaceDocumentBodySave> => {
+    if (!recordKey || !options.writeAction || runtime?.resource?.kind !== 'space' || !runtime.documentBody) {
+      throw new Error('This Space does not expose a body-edit action.');
+    }
+    setState(previous => ({ scope, pending: (previous.scope === scope ? previous.pending : 0) + 1, error: null }));
+    try {
+      const result = await runtime.documentBody({ operation: 'save', binding, recordKey,
+        readAction: options.readAction, writeAction: options.writeAction, ...draft });
+      if (currentScope.current !== scope) throw new SpaceActionError('This document view changed. Keep the original save request.', draft.requestId);
+      if (!('status' in result)) throw new Error('The document save receipt is incomplete.');
+      return result;
+    } catch (cause) {
+      const error = cause instanceof Error ? cause : new Error(String(cause));
+      if (currentScope.current === scope) setState(previous => ({ ...previous, error }));
+      throw error;
+    } finally {
+      if (currentScope.current === scope) setState(previous => ({ ...previous, pending: Math.max(0, previous.pending - 1) }));
+    }
+  }, [runtime, binding, recordKey, options.readAction, options.writeAction, scope]);
+  return { ...query, body: query.data, save, saving: state.scope === scope && state.pending > 0,
+    saveError: state.scope === scope ? state.error : null };
+}