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

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

@@ -0,0 +1,39 @@
+'use client';
+
+import React, { type CSSProperties, type ReactElement } from 'react';
+import type { DragRect } from '../hooks/useMultiSelect';
+
+export interface MultiSelectDragOverlayProps {
+  rect: DragRect | null;
+  className?: string;
+  style?: CSSProperties;
+}
+
+const overlayBaseStyle: CSSProperties = {
+  position: 'fixed',
+  borderRadius: '3px',
+  border: '1px solid rgba(35, 131, 226, 0.3)',
+  background: 'rgba(35, 131, 226, 0.08)',
+  pointerEvents: 'none',
+  zIndex: 50,
+};
+
+export function MultiSelectDragOverlay({
+  rect,
+  className,
+  style,
+}: MultiSelectDragOverlayProps): ReactElement | null {
+  if (!rect) return null;
+  if (rect.width === 0 && rect.height === 0) return null;
+
+  const merged: CSSProperties = {
+    ...overlayBaseStyle,
+    left: rect.left,
+    top: rect.top,
+    width: rect.width,
+    height: rect.height,
+    ...(style || null),
+  };
+
+  return <div aria-hidden className={className} style={merged} />;
+}

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

@@ -0,0 +1,172 @@
+'use client';
+import React, { useEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react';
+import type { ContextResource } from '../runtime';
+import { NotisSelectionBoundary } from './NotisSelectionBoundary';
+import { useAgentContext } from '../hooks/useAgentContext';
+
+export interface NotisCommentBoxProps {
+  quote?: string;
+  value: string;
+  onChange(value: string): void;
+  onSubmit(): void;
+  onCancel(): void;
+  pending?: boolean;
+  error?: string;
+  className?: string;
+}
+
+/** Compact, chrome-themed presentation. Apps retain ownership of comment state. */
+export function NotisCommentBox({ quote, value, onChange, onSubmit, onCancel, pending, error, className = '' }: NotisCommentBoxProps) {
+  return <div data-notis-comment-ui role="dialog" aria-label="Comment on selection"
+    style={{ colorScheme: 'dark', background: 'hsl(var(--sidebar-background, 0 0% 7.5%))', color: 'hsl(var(--sidebar-foreground, 240 4.8% 95.9%))', borderColor: 'hsl(var(--sidebar-border, 0 0% 23.5%))' }}
+    className={`flex min-w-0 flex-col gap-2 rounded-xl border p-2.5 text-sm shadow-lg ${className}`}>
+    <div className="flex min-w-0 items-center gap-2">
+      {quote && <blockquote title={quote} className="min-w-0 flex-1 truncate border-l-2 border-current/40 pl-2 opacity-70">{quote}</blockquote>}
+      <button type="button" aria-label="Cancel comment" onClick={onCancel} disabled={pending} className="ml-auto flex size-7 shrink-0 items-center justify-center rounded-lg opacity-70 hover:bg-white/10 hover:opacity-100 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-current disabled:opacity-40 [@media(pointer:coarse)]:size-9">
+        <svg aria-hidden="true" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round"><path d="m6 6 12 12M18 6 6 18" /></svg>
+      </button>
+    </div>
+    <textarea autoFocus rows={2} name="selection-comment" aria-label="Your comment" placeholder="Add a comment…" value={value} onChange={event => onChange(event.target.value)} disabled={pending}
+      onKeyDown={event => { if (event.nativeEvent.isComposing || pending) return; if (event.key === 'Escape') { event.preventDefault(); onCancel(); } if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) { event.preventDefault(); if (value.trim()) onSubmit(); } }}
+      className="w-full min-w-0 resize-none rounded bg-transparent px-0.5 py-1 text-base text-inherit outline-none placeholder:text-current placeholder:opacity-60 sm:text-sm" />
+    {error && <p role="alert" className="text-sm text-red-300">{error}</p>}
+    <div className="flex items-center justify-between gap-3">
+      <span className="text-xs opacity-60">⌘ / Ctrl ↵ to add</span>
+      <button type="button" disabled={pending || !value.trim()} onClick={onSubmit}
+        style={{ background: 'hsl(var(--sidebar-foreground, 240 4.8% 95.9%))', color: 'hsl(var(--sidebar-background, 0 0% 7.5%))' }}
+        className="min-h-8 shrink-0 rounded-lg px-2.5 text-sm font-medium hover:opacity-90 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-current disabled:opacity-40 [@media(pointer:coarse)]:min-h-9">{pending ? 'Adding…' : 'Add to chat'}</button>
+    </div>
+  </div>;
+}
+
+export interface NotisCommentBoundaryProps {
+  resource?: ContextResource | null;
+  children: ReactNode;
+  className?: string;
+  commentClassName?: string;
+  /** Replace the optional standard editor while retaining selection/context behavior. */
+  renderComment?: (props: NotisCommentBoxProps) => ReactNode;
+}
+
+type SelectionRect = Pick<DOMRect, 'left' | 'right' | 'top' | 'bottom'>;
+
+/** Place the tile after the final selected line, otherwise below (or above near the viewport bottom). */
+export function getCommentActionPosition(rects: SelectionRect[], viewport: { width: number; height: number }, rightBoundary = viewport.width, trailing: SelectionRect[] = []) {
+  const last = rects[rects.length - 1];
+  const size = 32, gap = 8;
+  const clampX = (x: number) => Math.max(gap, Math.min(viewport.width - size - gap, x));
+  const clampY = (y: number) => Math.max(gap, Math.min(viewport.height - size - gap, y));
+  const beside = { left: last.right + gap, top: clampY((last.top + last.bottom - size) / 2) };
+  const overlapsText = trailing.some(rect => rect.left < beside.left + size && rect.right > beside.left && rect.top < beside.top + size && rect.bottom > beside.top);
+  if (beside.left + size <= Math.min(viewport.width, rightBoundary) - gap && !overlapsText) return beside;
+  return { left: clampX(last.right - size), top: clampY(last.bottom + gap + size <= viewport.height - gap ? last.bottom + gap : last.top - size - gap) };
+}
+
+/** Browser paragraph selection may include an adjacent block's empty starting boundary. */
+export function getOwnedCommentRange(selected: Range, content: Element): Range | null {
+  const owned = content.ownerDocument.createRange();
+  owned.selectNodeContents(content);
+  const range = selected.cloneRange();
+  // Only clip whitespace outside the resource; actual neighboring content must
+  // never be silently attached to this resource's comment.
+  if (range.compareBoundaryPoints(Range.START_TO_START, owned) < 0) {
+    const before = range.cloneRange();
+    before.setEnd(owned.startContainer, owned.startOffset);
+    if (before.toString().trim()) return null;
+    range.setStart(owned.startContainer, owned.startOffset);
+  }
+  if (range.compareBoundaryPoints(Range.END_TO_END, owned) > 0) {
+    const after = range.cloneRange();
+    after.setStart(owned.endContainer, owned.endOffset);
+    if (after.toString().trim()) return null;
+    range.setEnd(owned.endContainer, owned.endOffset);
+  }
+  if (range.collapsed || !content.contains(range.startContainer) || !content.contains(range.endContainer)) return null;
+  return range;
+}
+
+/** Selection-to-chat convenience. No annotation database, polling or background attachment. */
+export function NotisCommentBoundary({ resource, children, className, commentClassName, renderComment }: NotisCommentBoundaryProps) {
+  const context = useAgentContext();
+  const root = useRef<HTMLDivElement>(null);
+  const [selection, setSelection] = useState<{ id: string; text: string; resource?: ContextResource | null; top: number; left: number } | null>(null);
+  const [editing, setEditing] = useState(false);
+  const editingRef = useRef(false);
+  const [comment, setComment] = useState('');
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState('');
+  useEffect(() => {
+    const node = root.current;
+    if (!node) return;
+    const document = node.ownerDocument;
+    const scope = node.getRootNode() as ShadowRoot & { getSelection?: () => Selection | null };
+    const clearInvalidSelection = () => {
+      // Opening the editor focuses its input and collapses the browser range.
+      // Keep the captured quote/editor; only the unopened action follows live selection.
+      if (editingRef.current) return;
+      const selected = scope.getSelection?.() || document.defaultView?.getSelection();
+      const content = node.firstElementChild;
+      if (!selected?.rangeCount || selected.isCollapsed || !selected.toString().trim()
+        || !content || !getOwnedCommentRange(selected.getRangeAt(0), content)) setSelection(null);
+    };
+    document.addEventListener('selectionchange', clearInvalidSelection);
+    if (scope !== (document as unknown as ShadowRoot)) scope.addEventListener('selectionchange', clearInvalidSelection);
+    return () => {
+      document.removeEventListener('selectionchange', clearInvalidSelection);
+      if (scope !== (document as unknown as ShadowRoot)) scope.removeEventListener('selectionchange', clearInvalidSelection);
+    };
+  }, []);
+  const open = () => { editingRef.current = true; setEditing(true); };
+  const capture = (target: EventTarget | null) => {
+    // Clicking the action/editor must not unmount it before its click runs.
+    if (editing || (target instanceof Element && target.closest('[data-notis-comment-ui]'))) return;
+    const node = root.current;
+    const scope = node?.getRootNode() as ShadowRoot & { getSelection?: () => Selection | null };
+    const selected = scope?.getSelection?.() || window.getSelection();
+    if (!node || !selected?.rangeCount || selected.isCollapsed) { setSelection(null); return; }
+    const content = node.firstElementChild;
+    const range = content ? getOwnedCommentRange(selected.getRangeAt(0), content) : null;
+    if (!range) { setSelection(null); return; }
+    const start = range.startContainer.nodeType === Node.ELEMENT_NODE ? range.startContainer as Element : range.startContainer.parentElement;
+    const end = range.endContainer.nodeType === Node.ELEMENT_NODE ? range.endContainer as Element : range.endContainer.parentElement;
+    if (!node.contains(range.startContainer) || !node.contains(range.endContainer)
+      || start?.closest('input,textarea,button,[contenteditable],[data-notis-comment-ui]')
+      || end?.closest('input,textarea,button,[contenteditable],[data-notis-comment-ui]')) { setSelection(null); return; }
+    const rect = range.getBoundingClientRect();
+    const lines = Array.from(range.getClientRects?.() || []).filter(line => line.width > 0 && line.height > 0);
+    const boundary = node.firstElementChild?.getBoundingClientRect();
+    const trailing: DOMRect[] = [];
+    const endBlock = end?.closest('p,li,h1,h2,h3,h4,h5,h6,td,th,div');
+    if (endBlock && node.contains(endBlock)) {
+      const remainder = range.cloneRange();
+      remainder.selectNodeContents(endBlock);
+      remainder.setStart(range.endContainer, range.endOffset);
+      trailing.push(...Array.from(remainder.getClientRects?.() || []).filter(line => line.width > 0 && line.height > 0));
+    }
+    const position = getCommentActionPosition(lines.length ? lines : [rect], { width: window.innerWidth, height: window.innerHeight }, boundary?.width ? boundary.right : window.innerWidth, trailing);
+    setSelection({ id: crypto.randomUUID(), text: selected.toString().trim(), resource: resource ? JSON.parse(JSON.stringify(resource)) : null, ...position });
+  };
+  const close = () => { editingRef.current = false; setEditing(false); setSelection(null); setComment(''); setError(''); };
+  const submit = async () => {
+    if (!selection || !comment.trim() || pending) return;
+    setPending(true); setError('');
+    try {
+      const added = await context.add({ id: selection.id, kind: 'comment', title: selection.resource?.label || 'Comment', icon: 'phosphor:chat-text', text: selection.text, comment, resource: selection.resource });
+      if (!added) throw new Error('The comment could not be added to chat.');
+      close();
+    } catch (reason) { setError(reason instanceof Error ? reason.message : 'Could not add this comment.'); }
+    finally { setPending(false); }
+  };
+  const editorProps: NotisCommentBoxProps = { quote: selection?.text, value: comment, onChange: setComment, onSubmit: () => void submit(), onCancel: close, pending, error, className: commentClassName };
+  return <div ref={root} className="contents" onMouseUp={event => capture(event.target)} onDoubleClick={event => capture(event.target)} onKeyUp={event => { if (!editing && (event.shiftKey || event.key === 'Shift' || ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'a'))) capture(event.target); }}>
+    <NotisSelectionBoundary resource={resource} className={className} style={className ? undefined : { display: 'contents' }}>{children}</NotisSelectionBoundary>
+    {selection && <div data-notis-comment-ui className="fixed z-50 max-h-[calc(100dvh-1rem)]" style={{ overflow: editing ? 'auto' : 'visible', top: editing ? Math.min(selection.top, Math.max(8, window.innerHeight - 320)) : selection.top, left: `clamp(8px, ${selection.left}px, calc(100vw - ${editing ? 'min(20rem, calc(100vw - 1rem))' : '2rem'} - 8px))`, width: editing ? 'min(20rem, calc(100vw - 1rem))' : undefined } as CSSProperties}>
+      {editing ? (renderComment ? renderComment(editorProps) : <NotisCommentBox {...editorProps} />) : <button type="button" aria-label="Comment" title="Comment" onMouseDown={event => event.preventDefault()} onClick={open}
+        style={{ background: 'hsl(var(--sidebar-background, 0 0% 7.5%))', color: 'hsl(var(--sidebar-foreground, 240 4.8% 95.9%))' }}
+        className="relative flex size-8 items-center justify-center rounded-lg ring-1 ring-white/15 hover:opacity-90 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-current">
+        <svg aria-hidden="true" width="18" height="18" viewBox="0 0 256 256" fill="currentColor"><path d="M216,48H40A16,16,0,0,0,24,64V224a15.85,15.85,0,0,0,9.24,14.5A16.13,16.13,0,0,0,40,240a15.89,15.89,0,0,0,10.25-3.78l.09-.07L83,208H216a16,16,0,0,0,16-16V64A16,16,0,0,0,216,48ZM40,224h0ZM216,192H80a8,8,0,0,0-5.23,1.95L40,224V64H216ZM88,112a8,8,0,0,1,8-8h64a8,8,0,0,1,0,16H96A8,8,0,0,1,88,112Zm0,32a8,8,0,0,1,8-8h64a8,8,0,1,1,0,16H96A8,8,0,0,1,88,144Z" /></svg>
+        <span aria-hidden="true" className="absolute left-1/2 top-1/2 hidden size-12 -translate-x-1/2 -translate-y-1/2 [@media(pointer:coarse)]:block" />
+      </button>}
+    </div>}
+  </div>;
+}

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

@@ -0,0 +1,59 @@
+import type { CSSProperties, ClipboardEvent, ReactNode } from 'react';
+import React, { 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 target = event.target as Element | null;
+    if (target?.closest?.('input,textarea,[contenteditable="true"]')) return;
+    const scope = event.currentTarget.getRootNode() as ShadowRoot & { getSelection?: () => Selection | null };
+    const selection = scope?.getSelection?.() || window.getSelection();
+    const text = selection?.toString() ?? '';
+    if (
+      !text.trim()
+      || !selection
+      || !event.currentTarget.contains(selection.anchorNode)
+      || !event.currentTarget.contains(selection.focusNode)
+    ) return;
+
+    const payload: ContextSelection = {
+      id: selectionId(),
+      text,
+      ...(runtime?.contextSource ? { source: runtime.contextSource } : {}),
+      ...(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/dist/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/dist/sdk/src/components/Skeleton.tsx

@@ -0,0 +1,24 @@
+import type { CSSProperties } from 'react';
+
+/** Content-shaped placeholder. Never use it to replace a successful cached result. */
+export function Skeleton({ className, style }: { className?: string; style?: CSSProperties }) {
+  return <span aria-hidden="true" className={className} style={{ display: 'block', height: 16,
+    // Apps may define --muted as HSL channels or a complete CSS color. A
+    // neutral default remains visible with either token format and no theme.
+    borderRadius: 6, background: 'rgba(128,128,128,.18)', ...style }} />;
+}
+
+export function ViewSkeleton({ variant = 'table', rows = 5 }: {
+  variant?: 'table' | 'cards' | 'graph' | 'detail'; rows?: number;
+}) {
+  return <div role="status" aria-label="Loading content" aria-busy="true" data-notis-content-skeleton
+    style={{ width: '100%', display: 'grid', gap: 16, padding: 24 }}>
+    <Skeleton style={{ width: '32%', height: 28 }} />
+    {variant === 'graph' ? <Skeleton style={{ height: 420 }} /> :
+      <div style={{ display: 'grid', gap: 12, gridTemplateColumns: variant === 'cards' ? 'repeat(auto-fit,minmax(180px,1fr))' : '1fr' }}>
+        {Array.from({ length: rows }, (_, index) => <Skeleton key={index}
+          style={{ height: variant === 'cards' ? 112 : variant === 'detail' ? 20 : 44,
+            width: variant === 'detail' && index === rows - 1 ? '65%' : '100%' }} />)}
+      </div>}
+  </div>;
+}

package/dist/sdk/src/config.ts

@@ -0,0 +1,261 @@
+/**
+ * Configuration utilities for notis.config.ts.
+ *
+ * Usage:
+ * ```ts
+ * // notis.config.ts
+ * import { defineNotisApp } from '@notis/sdk/config';
+ *
+ * export default defineNotisApp({
+ *   name: 'My App',
+ *   description: 'Does things',
+ *   icon: 'phosphor:squares-four',
+ *   databases: ['tasks'],
+ *   routes: [
+ *     {
+ *       path: '/',
+ *       slug: 'notes',
+ *       name: 'Notes',
+ *       default: true,
+ *       collection: {
+ *         database: 'notes',
+ *         titleProperty: 'Name',
+ *         parentProperty: 'Parent',
+ *         sidebar: {
+ *           mode: 'tree',
+ *           allowCreate: true,
+ *         },
+ *       },
+ *     },
+ *   ],
+ *   tools: [...],
+ * });
+ * ```
+ */
+
+export interface NotisRouteConfig {
+  path: string;
+  slug: string;
+  name: string;
+  icon?: string;
+  parentSlug?: string | null;
+  default?: boolean;
+  /**
+   * Allow the host to address an app-owned resource on this route through the
+   * canonical `?resource=<id>` deep link. Read the incoming id with
+   * `useNotis().resourceId`.
+   */
+  resourceDeepLinks?: boolean;
+  exportName?: string;
+  collection?: {
+    database: string;
+    titleProperty: string;
+    parentProperty?: string | null;
+    sidebar?: {
+      mode: 'flat-list' | 'tree';
+      allowCreate: boolean;
+    };
+  };
+}
+
+export const NOTIS_APP_CATEGORIES = [
+  'Productivity',
+  'Sales & Marketing',
+  'Operations',
+  'Product & Engineering',
+  'Personal',
+] as const;
+
+export type NotisAppCategory = typeof NOTIS_APP_CATEGORIES[number];
+
+export interface NotisAppDatabaseConfig {
+  /** Database slug, as declared by the app. */
+  slug: string;
+  /**
+   * Ship this database's rows to everyone who installs the app.
+   *
+   * Off by default: declaring a database publishes its STRUCTURE, never its
+   * content. Turn it on only for starter content that every installer should
+   * receive - a default folder tree, a set of templates - and never for a
+   * database that accumulates the author's own data.
+   */
+  seedDocuments?: boolean;
+}
+
+export interface NotisAppAuthor {
+  name: string;
+  handle?: string;
+  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;
+  /** 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';
+}
+
+/**
+ * Named accent tokens for an app's avatar. Keep in sync with the portal
+ * `ACCENT_NAMES` and the server `ACCENT_TOKENS`.
+ */
+export const NOTIS_APP_ACCENTS = [
+  'blue',
+  'violet',
+  'emerald',
+  'amber',
+  'rose',
+  'sky',
+  'fuchsia',
+  'teal',
+] as const;
+
+export type NotisAppAccent = typeof NOTIS_APP_ACCENTS[number];
+
+export interface NotisAppCapabilities {
+  /**
+   * Read every database in the workspace, not only the ones this app declares
+   * in `databases` or created itself.
+   *
+   * An app runtime is otherwise sandboxed to its own databases, so a catalog or
+   * explorer app sees an empty list without this. `'read'` is the only accepted
+   * value and it never grants writes: `LOCAL_NOTIS_DATABASE_UPSERT_*` stays
+   * 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 {
+  /** Standalone reports share the view engine without app installation. */
+  kind?: 'app' | 'report';
+  /** Existing data sources, never owned or materialized by a report. */
+  databaseAccess?: Array<{ id: string; access: 'read' | 'write' }>;
+  /** URL-safe app slug. Existing apps may still use a display name here. */
+  name: string;
+  /** Human display title, Raycast-style. Falls back to `name`. */
+  title?: string;
+  description?: string;
+  /**
+   * App icon. A `phosphor:<name>` value (e.g. `phosphor:dice-five`) or
+   * `metadata/icon.png`. When unset, the app shows its two-letter initials.
+   */
+  icon?: string;
+  /**
+   * Optional accent color for the app avatar. One of {@link NOTIS_APP_ACCENTS}.
+   * When unset, a stable accent is derived automatically from the app id.
+   */
+  accent?: NotisAppAccent;
+  author?: NotisAppAuthor;
+  categories?: NotisAppCategory[];
+  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
+   * object form to opt a database into shipping its rows to installers.
+   */
+  databases?: (string | NotisAppDatabaseConfig)[];
+  /**
+   * Extra permissions the app asks for at install time. Everything here widens
+   * what the app can reach beyond its own data, so each one is surfaced to the
+   * user before they install.
+   */
+  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;
+}
+
+/**
+ * Identity function that provides type checking and autocomplete for the
+ * Notis app configuration. The returned object is read at build time by
+ * `notis apps build` to generate the manifest.
+ */
+export function defineNotisApp(config: NotisAppConfig): NotisAppConfig {
+  return config;
+}