@notis_ai/cli 0.2.17 → 0.2.19

package/{template/packages → dist}/sdk/package.json

@@ -8,30 +8,29 @@
     "./interactions": "./src/interactions.ts",
     "./config": "./src/config.ts",
     "./vite": "./src/vite.ts",
-    "./ui": "./src/ui.ts",
-    "./styles.css": "./src/styles.css"
+    "./styles.css": "./src/styles.css",
+    "./ui": "./src/ui.ts"
   },
   "files": [
-    "src",
-    "template"
+    "src"
   ],
   "scripts": {
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit && tsc --noEmit -p design-system"
   },
   "dependencies": {
     "react-markdown": "^10.1.0",
     "remark-gfm": "^4.0.1"
   },
   "peerDependencies": {
+    "@vitejs/plugin-react": ">=4.0.0",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
-    "vite": ">=5.0.0",
-    "@vitejs/plugin-react": ">=4.0.0"
+    "vite": ">=5.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "typescript": "^5.0.0"
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
+    "typescript": "^7.0.2"
   }
 }

package/dist/sdk/src/agentContext.ts

@@ -0,0 +1,36 @@
+/** Serializable context shared with the agent. Apps own annotation storage. */
+export interface ContextAttachment {
+  /** Durable HTTPS URL supplied by the app. Sent through the host media pipeline. */
+  url: string;
+  name: string;
+  mimeType: string;
+}
+
+export interface AgentContextContent {
+  title?: string;
+  /** Emoji, Phosphor icon name, or HTTPS image URL. Never executable markup. */
+  icon?: string;
+  /** An app-defined kind, not a closed list of annotation types. */
+  kind?: string;
+  text?: string;
+  comment?: string;
+  preview?: { format: 'text' | 'markdown'; content: string };
+  /** Any JSON-serializable value: coordinates, chart state, loaded records, etc. */
+  data?: unknown;
+  attachments?: ContextAttachment[];
+}
+
+export interface AgentContextItem extends AgentContextContent {
+  /** Stable within this app. The host scopes IDs to the originating app. */
+  id: string;
+  resource?: import('./runtime').ContextResource | null;
+}
+
+/** Host-stamped origin. Apps describe resources; the host identifies the app/view. */
+export interface AgentContextSource {
+  appId: string;
+  appName: string;
+  viewSlug: string;
+  viewName: string;
+  viewUrl?: string | null;
+}

package/dist/sdk/src/bundleModule.ts

@@ -0,0 +1,175 @@
+/** Framework-neutral ESM loading shared by Portal and credentialless verification. */
+import type React from 'react';
+import { NOTIS_SDK_HOST_MODULES } from './runtimeModules';
+
+const SDK_SPECIFIER = String.raw`@notis\/sdk(?:\/[^"'\s]*)?`;
+// `from "x"`, `import("x")` and the side-effect `import "x"`.
+const SDK_REFERENCE = new RegExp(String.raw`(\bfrom\s*|\bimport\s*\(\s*|\bimport(?![\w$])\s*)(["'])(${SDK_SPECIFIER})\2`, 'g');
+// The clause of a static `import ... from "x"` or `export ... from "x"`; quotes never appear in it.
+const SDK_CLAUSE = new RegExp(String.raw`\b(?:import|export)(?![\w$])\s*([^;"'\x60()]*?)\s*from\s*(["'])(${SDK_SPECIFIER})\2`, 'g');
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+type HostGlobals = Record<string, unknown>;
+
+function sdkError(code: string, message: string, extra: Record<string, unknown> = {}) {
+  return Object.assign(new Error(message), { code, ...extra });
+}
+
+/** The names a static import or re-export clause takes from its module ('default' for a default import). */
+function importedNames(clause: string): string[] {
+  const names: string[] = [];
+  let rest = clause.trim();
+  const braces = rest.match(/\{([^}]*)\}/);
+  if (braces) {
+    for (const part of braces[1].split(',')) {
+      const name = part.trim().split(/\s+as\s+/)[0]?.trim();
+      if (name) names.push(name);
+    }
+    rest = rest.replace(braces[0], '');
+  }
+  for (const part of rest.split(',')) {
+    const name = part.trim();
+    // `* as N` and `export *` take the whole namespace; nothing to check by name.
+    if (name && !name.startsWith('*')) names.push('default');
+  }
+  return names;
+}
+
+function hostNamespace(specifier: string, globals: HostGlobals): Record<string, unknown> {
+  if (!Object.hasOwn(NOTIS_SDK_HOST_MODULES, specifier)) {
+    throw sdkError('client_update_required', `This Space needs ${specifier}, which this version of Notis does not provide.`,
+      { missing: [specifier] });
+  }
+  const globalName = NOTIS_SDK_HOST_MODULES[specifier as keyof typeof NOTIS_SDK_HOST_MODULES];
+  const namespace = globals[globalName];
+  if (!namespace || typeof namespace !== 'object') {
+    throw sdkError('notis_sdk_host_unavailable', `The host did not provide ${specifier} (window.${globalName}).`);
+  }
+  return namespace as Record<string, unknown>;
+}
+
+/** A module that re-exports every member of one host-provided SDK namespace, read when it evaluates. */
+function sdkShim(globalName: string, namespace: Record<string, unknown>): string {
+  const names = Object.keys(namespace);
+  const body = [`const M = globalThis[${JSON.stringify(globalName)}];`];
+  const exported: string[] = [];
+  names.forEach((name, index) => {
+    body.push(`const e${index} = M[${JSON.stringify(name)}];`);
+    exported.push(`e${index} as ${IDENTIFIER.test(name) ? name : JSON.stringify(name)}`);
+  });
+  if (exported.length) body.push(`export { ${exported.join(', ')} };`);
+  return `data:text/javascript,${encodeURIComponent(body.join(' '))}`;
+}
+
+/**
+ * Points every `@notis/sdk` import of a Space bundle at the host's own SDK
+ * (`window.__NotisSDK`, `window.__NotisSDKUI`). A bundle that needs a module or
+ * a name this host does not have is refused with `client_update_required`
+ * before it loads, instead of failing to link.
+ */
+export function rewriteSdkImports(source: string, globals: HostGlobals = globalThis as unknown as HostGlobals): string {
+  if (!source.includes('@notis/sdk')) return source;
+  const missing = new Set<string>();
+  for (const [, clause, , specifier] of source.matchAll(SDK_CLAUSE)) {
+    const namespace = hostNamespace(specifier, globals);
+    for (const name of importedNames(clause)) {
+      if (!Object.hasOwn(namespace, name)) missing.add(`${specifier}:${name}`);
+    }
+  }
+  if (missing.size) {
+    throw sdkError('client_update_required', `This Space needs a newer version of Notis (missing ${[...missing].join(', ')}).`,
+      { missing: [...missing] });
+  }
+  const shims = new Map<string, string>();
+  return source.replace(SDK_REFERENCE, (_match, lead: string, quote: string, specifier: string) => {
+    let shim = shims.get(specifier);
+    if (!shim) {
+      const namespace = hostNamespace(specifier, globals);
+      shim = sdkShim(NOTIS_SDK_HOST_MODULES[specifier as keyof typeof NOTIS_SDK_HOST_MODULES], namespace);
+      shims.set(specifier, shim);
+    }
+    return `${lead}${quote}${shim}${quote}`;
+  });
+}
+
+/** Every host-provided import of a bundle (React and the SDK) pointed at the host's globals. */
+export function rewriteBundleImports(source: string, globals?: HostGlobals): string {
+  return rewriteSdkImports(rewriteReactImports(source), globals);
+}
+
+export function rewriteReactImports(source: string): string {
+  // Create inline data URLs that re-export from window globals.
+  // This avoids the "Cannot find module" error with blob URL imports.
+  const reactShim = `data:text/javascript,${encodeURIComponent(
+    'const R = window.React; export default R; export const { createContext, createRef, useState, useEffect, useContext, useCallback, useMemo, useRef, useReducer, useLayoutEffect, useId, memo, forwardRef, createElement, Fragment, Children, cloneElement, isValidElement, lazy, Suspense, startTransition, useTransition, useDeferredValue, useSyncExternalStore, useInsertionEffect, useDebugValue, useImperativeHandle, Component, PureComponent } = R;'
+  )}`;
+  const jsxShim = `data:text/javascript,${encodeURIComponent(
+    'const J = window.__ReactJSXRuntime || {}; const R = window.React; export const jsx = J.jsx || R.createElement; export const jsxs = J.jsxs || R.createElement; export const jsxDEV = J.jsxDEV || R.createElement; export const Fragment = J.Fragment || R.Fragment;'
+  )}`;
+  const reactDomShim = `data:text/javascript,${encodeURIComponent(
+    'const RD = window.ReactDOM; export default RD; export const { createPortal, flushSync, unstable_batchedUpdates } = RD;'
+  )}`;
+  const reactDomClientShim = `data:text/javascript,${encodeURIComponent(
+    'const RDC = window.ReactDOMClient; export default RDC; export const { createRoot, hydrateRoot } = RDC;'
+  )}`;
+
+  let result = source;
+  // Replace bare side-effect imports
+  result = result.replace(/import\s*["']react-dom\/client["'];?/g, `import "${reactDomClientShim}";`);
+  result = result.replace(/import\s*["']react-dom["'];?/g, `import "${reactDomShim}";`);
+  result = result.replace(/import\s*["']react\/jsx-runtime["'];?/g, `import "${jsxShim}";`);
+  result = result.replace(/import\s*["']react\/jsx-dev-runtime["'];?/g, `import "${jsxShim}";`);
+  result = result.replace(/import\s*["']react["'];?/g, `import "${reactShim}";`);
+
+  // Replace import statements with data URL shims
+  // Handle: import { ... } from "react/jsx-runtime"
+  result = result.replace(/from\s*["']react\/jsx-runtime["']/g, `from "${jsxShim}"`);
+  result = result.replace(/from\s*["']react\/jsx-dev-runtime["']/g, `from "${jsxShim}"`);
+  // Handle react-dom/client before react-dom
+  result = result.replace(/from\s*["']react-dom\/client["']/g, `from "${reactDomClientShim}"`);
+  // Handle: import ... from "react-dom"
+  result = result.replace(/from\s*["']react-dom["']/g, `from "${reactDomShim}"`);
+  // Handle: import ... from "react" (must come after react-dom and react/jsx-runtime)
+  result = result.replace(/from\s*["']react["']/g, `from "${reactShim}"`);
+
+  return result;
+}
+
+export function resolveBundleRouteExport(
+  moduleExports: Record<string, React.ComponentType>,
+  exportCandidates: string[],
+  strict = false,
+): { name: string; component: React.ComponentType } | null {
+  const namedExport = exportCandidates.find((name) => Boolean(moduleExports[name]));
+  if (namedExport) {
+    return { name: namedExport, component: moduleExports[namedExport] };
+  }
+  if (strict) return null;
+  if (moduleExports.default) {
+    return { name: 'default', component: moduleExports.default };
+  }
+
+  // Vite may minify an entry export even though the manifest still carries
+  // its source name. A bundle with one non-shell component is unambiguous, so
+  // keep Dev usable instead of showing "View not available" for that route.
+  const componentExports = Object.entries(moduleExports).filter(
+    ([name, value]) => name !== '__AppShell' && Boolean(value),
+  );
+  if (componentExports.length !== 1) {
+    return null;
+  }
+  const [name, component] = componentExports[0];
+  return { name, component };
+}
+
+export async function importRewrittenBundleSource(source: string): Promise<Record<string, React.ComponentType>> {
+  const blob = new Blob([source], { type: 'text/javascript' });
+  const url = URL.createObjectURL(blob);
+  try {
+    return await import(/* webpackIgnore: true */ url) as Record<string, React.ComponentType>;
+  } finally { URL.revokeObjectURL(url); }
+}
+
+export function importBundleSource(source: string) {
+  return importRewrittenBundleSource(rewriteBundleImports(source));
+}

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

@@ -0,0 +1,103 @@
+'use client';
+
+import React, { useEffect, useId, useRef, useState, type ReactNode } from 'react';
+import { useIsoLayoutEffect } from '../ui/util';
+
+export interface DialogProps {
+  open: boolean;
+  /** Request dismissal. Keep open unchanged to prevent dismissal while saving. */
+  onClose: () => void;
+  title: ReactNode;
+  description?: ReactNode;
+  role?: 'dialog' | 'alertdialog';
+  /**
+   * A confirmation: on phones and tablets the operating system's own dialog asks instead of the card. OK clicks the
+   * button marked `data-dialog-confirm`; Cancel clicks the one marked `data-dialog-cancel`, else calls `onClose`.
+   * Desktop browsers and the Desktop app keep the card.
+   */
+  nativeOnTouch?: boolean;
+  children: ReactNode;
+}
+
+/** How long the card stays hidden after OK while the work runs; a slow or failed action shows it again. */
+const NATIVE_CONFIRM_REVEAL_MS = 1500;
+/** A Cancel faster than this came from a browser with no OS dialog (an embedded view): show the card instead. */
+const NATIVE_CONFIRM_MISSING_MS = 30;
+
+/** Touch-first devices confirm with the operating system's dialog, as the Portal's AlertDialog does. */
+export function prefersNativeConfirm(): boolean {
+  if (typeof window === 'undefined' || typeof window.confirm !== 'function') return false;
+  if ((window as Window & { electronAPI?: { isElectron?: boolean } }).electronAPI?.isElectron) return false;
+  return window.matchMedia?.('(hover: none) and (pointer: coarse)').matches === true;
+}
+
+/** One OS dialog: the question first, then each line of the explanation as its own paragraph. */
+function nativeConfirmMessage(title: string, description: string): string {
+  return [title, ...description.split(/\n+/)].map((part) => part.trim()).filter(Boolean).join('\n\n');
+}
+
+/** Native top-layer dialog; content and actions remain app-owned. */
+export function Dialog({ open, onClose, title, description, role = 'dialog', nativeOnTouch = false, children }: DialogProps) {
+  const ref = useRef<HTMLDialogElement>(null);
+  const titleId = useId();
+  const descriptionId = useId();
+  const onCloseRef = useRef(onClose);
+  onCloseRef.current = onClose;
+  // Each opening asks the OS again.
+  const [native, setNative] = useState(false);
+
+  // Before paint, so a touch confirmation never flashes the card first.
+  useIsoLayoutEffect(() => {
+    if (!open) return;
+    const dialog = ref.current!;
+    dialog.showModal();
+    setNative(nativeOnTouch && prefersNativeConfirm());
+    return () => { if (dialog.open) dialog.close(); };
+  }, [open, nativeOnTouch]);
+
+  useEffect(() => {
+    if (!open || !native) return;
+    const dialog = ref.current!;
+    let reveal: ReturnType<typeof setTimeout> | undefined;
+    // Let the dialog finish opening (title, buttons) before the OS takes over.
+    const ask = setTimeout(() => {
+      const asked = performance.now();
+      const describedBy = dialog.querySelector('.notis-dialog-description') as HTMLElement | null;
+      const confirmed = window.confirm(nativeConfirmMessage(
+        dialog.querySelector('.notis-dialog-title')?.textContent ?? '',
+        describedBy ? (typeof describedBy.innerText === 'string' ? describedBy.innerText : describedBy.textContent ?? '') : '',
+      ));
+      if (!confirmed && performance.now() - asked < NATIVE_CONFIRM_MISSING_MS) {
+        setNative(false);
+        return;
+      }
+      if (confirmed) dialog.querySelector<HTMLButtonElement>('[data-dialog-confirm]')?.click();
+      else {
+        const cancel = dialog.querySelector<HTMLButtonElement>('[data-dialog-cancel]');
+        if (cancel) cancel.click(); else onCloseRef.current();
+      }
+      reveal = setTimeout(() => setNative(false), confirmed ? NATIVE_CONFIRM_REVEAL_MS : 0);
+    }, 0);
+    return () => {
+      clearTimeout(ask);
+      if (reveal !== undefined) clearTimeout(reveal);
+    };
+  }, [open, native]);
+
+  return (
+    <dialog
+      ref={ref}
+      className="notis-dialog"
+      role={role}
+      aria-labelledby={titleId}
+      aria-describedby={description == null ? undefined : descriptionId}
+      data-native-confirm={native ? '' : undefined}
+      onCancel={(event) => { event.preventDefault(); onClose(); }}
+      onKeyDown={(event) => event.stopPropagation()}
+    >
+      <h2 id={titleId} className="notis-dialog-title">{title}</h2>
+      {description != null && <p id={descriptionId} className="notis-dialog-description">{description}</p>}
+      {children}
+    </dialog>
+  );
+}

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

@@ -0,0 +1,113 @@
+'use client';
+
+import type { CSSProperties, ReactElement } from 'react';
+import { useNotisRuntime } from '../provider';
+import { DOCUMENT_HOOK_WORDS, useDocument } from '../hooks/useDocument';
+import { fillWords, pick, type Locale, type Words } from '../words/types';
+import { Markdown } from './Markdown';
+import { RecordComponentUnavailable } from './RecordComponents';
+import type { NotisDocumentEditorProps } from '../runtime';
+
+/** The words of the read-only document preview, in English and French (C7). */
+export const DOCUMENT_EDITOR_WORDS = Object.freeze({
+  loading: { en: 'Loading document', fr: 'Chargement du document' },
+  readOnly: { en: 'Read-only preview. Edit it in Notis.', fr: 'Aperçu en lecture seule. Modifie-le dans Notis.' },
+  report: { en: 'Interactive report. Open it in its Space to use it.', fr: 'Rapport interactif. Ouvre-le dans son Space pour l’utiliser.' },
+  html: { en: 'Interactive page. Open it in its Space to use it.', fr: 'Page interactive. Ouvre-la dans son Space pour l’utiliser.' },
+  view: { en: 'View. Open it in its Space to see it.', fr: 'Vue. Ouvre-la dans son Space pour la voir.' },
+  file: { en: '{type} file. Open it in Notis to see it.', fr: 'Fichier {type}. Ouvre-le dans Notis pour le voir.' },
+  anyFile: { en: 'File. Open it in Notis to see it.', fr: 'Fichier. Ouvre-le dans Notis pour le voir.' },
+}) satisfies Readonly<Record<string, Words>>;
+
+const fallbackNoticeStyle: CSSProperties = {
+  marginTop: '0.75rem',
+  fontSize: '12px',
+  color: 'hsl(var(--muted-foreground))',
+};
+
+// Flat, like a callout: a tinted block, no border (C7).
+const fallbackFrameStyle: CSSProperties = {
+  borderRadius: '0.5rem',
+  background: 'hsl(var(--muted) / .5)',
+  padding: '12px 16px',
+  fontSize: '13px',
+  lineHeight: '20px',
+  color: 'hsl(var(--muted-foreground))',
+};
+
+const fallbackTitleStyle: CSSProperties = {
+  margin: '0 0 0.75rem',
+  fontSize: '1.5rem',
+  fontWeight: 700,
+  letterSpacing: '-0.01em',
+  color: 'hsl(var(--foreground))',
+};
+
+/**
+ * Read-only stand-in used when no host editor is available (standalone dev
+ * harness, snapshots). Markdown content renders via `Markdown`; other content
+ * types get a typed placeholder.
+ */
+function DocumentEditorFallback({ documentId, variant = 'full', className }: NotisDocumentEditorProps) {
+  const { document, loading, error } = useDocument(documentId ?? null);
+  const locale: Locale = useNotisRuntime()?.context?.locale === 'fr' ? 'fr' : 'en';
+  const t = (words: Words) => pick(words, locale);
+
+  if (loading) {
+    return <div role="status" aria-busy="true" className={className} style={fallbackFrameStyle}>{t(DOCUMENT_EDITOR_WORDS.loading)}</div>;
+  }
+  if (error || !document) {
+    return (
+      <div role="status" className={className} style={fallbackFrameStyle}>
+        {error?.message ?? t(DOCUMENT_HOOK_WORDS.notFound)}
+      </div>
+    );
+  }
+
+  const isMarkdown = document.contentType === 'markdown' || !document.contentType;
+  return (
+    <div className={className}>
+      {variant === 'full' ? <h1 style={fallbackTitleStyle}>{document.title}</h1> : null}
+      {isMarkdown ? (
+        <>
+          <Markdown value={document.contentMarkdown ?? ''} />
+          <p style={fallbackNoticeStyle}>{t(DOCUMENT_EDITOR_WORDS.readOnly)}</p>
+        </>
+      ) : document.contentType === 'view' ? (
+        <div style={fallbackFrameStyle}>
+          {t(document.viewType === 'report' ? DOCUMENT_EDITOR_WORDS.report
+            : document.viewType === 'html' ? DOCUMENT_EDITOR_WORDS.html : DOCUMENT_EDITOR_WORDS.view)}
+        </div>
+      ) : (
+        <div style={fallbackFrameStyle}>
+          {document.fileType
+            ? t(fillWords(DOCUMENT_EDITOR_WORDS.file, { type: document.fileType.toUpperCase() }))
+            : t(DOCUMENT_EDITOR_WORDS.anyFile)}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Embeds the document editor for a document anywhere in an app view. The host
+ * (portal) provides the implementation through `runtime.ui.DocumentEditor` and
+ * 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-Space notice for native views.
+ *
+ * ```tsx
+ * <DocumentEditor documentId={entry.id} variant="body" className="min-h-[320px]" />
+ * ```
+ */
+export function DocumentEditor(props: NotisDocumentEditorProps): ReactElement {
+  const runtime = useNotisRuntime();
+  const HostEditor = runtime?.ui?.DocumentEditor;
+  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,184 @@
+'use client';
+
+import { useCallback, useRef, useState, type CSSProperties, type ReactElement } from 'react';
+import { useNotisRuntime } from '../provider';
+import { useTopBarTitleLeaf } from '../hooks/useTopBarTitleLeaf';
+import { DocumentEditor } from './DocumentEditor';
+import { HtmlFrame, ShareControl } from './RecordComponents';
+import { Skeleton } from './Skeleton';
+import { renderIcon } from '../ui/icons';
+import type { NotisDocumentPageProps } from '../runtime';
+
+const copy = {
+  en: { loading: 'Loading document', breadcrumb: 'Breadcrumb', untitled: 'Untitled' },
+  fr: { loading: 'Chargement du document', breadcrumb: "Fil d'Ariane", untitled: 'Sans titre' },
+};
+
+/** 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;
+
+/** The widest a crumb before the last one gets; past it the words end in an ellipsis (C10). */
+const CRUMB_MAX = 160;
+// The room the fallback crumb keeps beside its buttons, and the one padding every crumb part has.
+const CRUMB_MIN = 72;
+const CRUMB_PADDING = '4px 6px';
+
+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 toolbar buttons (icon only when they carry one) 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.
+ * With viewer 'html' the host's HtmlFrame replaces the editor.
+ */
+// A 16px box for a menu item's icon, sized here because a host without the toolkit stylesheet gives the svg no size.
+const ICON_BOX: CSSProperties = { display: 'inline-flex', width: 16, height: 16, overflow: 'hidden' };
+
+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' }}>
+      {/* C10: the crumb shrinks (each part ends in an ellipsis, a slash only between parts) and never runs under the
+        buttons, which never wrap. The last part gets the room the others leave; every part has the same padding. When
+        the buttons alone outgrow the bar (longer French labels), their labels shorten too, down to CRUMB_MIN of crumb. */}
+      <nav aria-label={t.breadcrumb} style={{ display: 'flex', alignItems: 'center', gap: 4, flex: 1, minWidth: CRUMB_MIN, overflow: 'hidden', fontSize: 14 }}>
+        {crumbs.map((crumb, index) => {
+          const last = index === crumbs.length - 1;
+          const text: CSSProperties = { display: 'block', minWidth: 0, maxWidth: last ? '100%' : CRUMB_MAX, overflow: 'hidden',
+            textOverflow: 'ellipsis', whiteSpace: 'nowrap', color: 'hsl(var(--muted-foreground))' };
+          return <span key={`${crumb.label}-${index}`} style={{ display: 'inline-flex', alignItems: 'center', gap: 4, minWidth: 0, flex: '0 1 auto' }}>
+            {crumb.onSelect ? <button type="button" onClick={crumb.onSelect} title={crumb.label}
+              style={{ ...text, background: 'none', border: 0, padding: CRUMB_PADDING, borderRadius: 6, cursor: 'pointer', font: 'inherit' }}>
+              {crumb.label}</button>
+              : <span title={crumb.label} style={{ ...text, padding: CRUMB_PADDING }}>{crumb.label}</span>}
+            {last ? null : <span aria-hidden="true" style={{ flex: 'none', color: 'hsl(var(--muted-foreground))' }}>/</span>}
+          </span>;
+        })}
+      </nav>
+      <div data-notis-document-page-actions="" style={{ display: 'flex', alignItems: 'center', gap: 4, flex: '0 1 auto', minWidth: 0, whiteSpace: 'nowrap' }}>
+        {actions}
+        {share ? <ShareControl recordKey={recordKey} /> : null}
+        {/* The host's '...' menu is not available here: its entries show as buttons, icon only when they carry one. */}
+        {menuItems.map((item, index) => <button key={`${item.label}-${index}`} type="button" onClick={item.onSelect} disabled={item.disabled} title={item.label}
+          aria-label={item.icon ? item.label : undefined}
+          style={{ display: 'inline-flex', alignItems: 'center', background: 'none', border: 0, padding: item.icon ? 6 : '4px 8px', borderRadius: 6, cursor: item.disabled ? 'default' : 'pointer', font: 'inherit', fontSize: 13,
+            flex: '0 1 auto', minWidth: 0, maxWidth: CRUMB_MAX, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', color: item.destructive ? 'hsl(var(--destructive))' : 'hsl(var(--muted-foreground))', opacity: item.disabled ? 0.5 : 1 }}>{item.icon ? <span style={ICON_BOX}>{renderIcon(item.icon)}</span> : item.label}</button>)}
+      </div>
+    </div> : null}
+    {props.viewer === 'html' ? <HtmlFrame recordKey={recordKey} /> :
+    <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. `viewer: 'html'` opens a record whose one stored `.html` file is
+ * the page (for example a note that keeps a saved HTML report) the same way.
+ *
+ * ```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 runtime = useNotisRuntime();
+  const Host = runtime?.ui?.DocumentPage;
+  const t = useCopy();
+  const { recordKey, onTitle } = props;
+  // A record opened from the view (it draws a way back) names the top bar leaf with its title, so the view's page
+  // becomes a parent crumb. The host reports the title; until it does, and on hosts that never do, there is no leaf.
+  const leaf = props.topBarTitle ?? (Array.isArray(props.breadcrumb) && props.breadcrumb.length > 0);
+  // The top bar is then the page's crumb: its view crumb goes back as the page's last crumb did, and the host draws
+  // its own breadcrumb only where the top bar shows none.
+  const inTopBar = Boolean(leaf && Host && runtime?.setTopBarTitleLeaf);
+  const back = Array.isArray(props.breadcrumb) ? [...props.breadcrumb].reverse().find(crumb => crumb.onSelect)?.onSelect : undefined;
+  const [reported, setReported] = useState<{ recordKey: string; title: string } | null>(null);
+  const reportTitle = useCallback((title: string) => {
+    setReported(current => current?.recordKey === recordKey && current.title === title ? current : { recordKey, title });
+    onTitle?.(title);
+  }, [recordKey, onTitle]);
+  const title = reported?.recordKey === recordKey ? reported.title : null;
+  useTopBarTitleLeaf(leaf && title !== null ? title.trim() || t.untitled : null, back, { recordKey });
+  return Host ? <Host {...props} topBarTitle={inTopBar} onTitle={reportTitle} /> : <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]);
+}