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

package/dist/sdk/src/interactions/visibility.ts

@@ -0,0 +1,13 @@
+/** Visibility across light and Shadow DOM, without relying on layout (virtual rows may have no rect). */
+export function isInteractionElementVisible(element: HTMLElement | null): boolean {
+  if (!element?.isConnected) return false;
+  let current: Element | null = element;
+  while (current) {
+    if (current.hasAttribute('hidden') || current.hasAttribute('inert') || current.getAttribute('aria-hidden') === 'true') return false;
+    const style = current.ownerDocument.defaultView?.getComputedStyle(current);
+    if (style?.display === 'none' || style?.visibility === 'hidden') return false;
+    const root: Node = current.getRootNode();
+    current = current.parentElement ?? ('host' in root ? (root as ShadowRoot).host : null);
+  }
+  return true;
+}

package/dist/sdk/src/interactions.ts

@@ -0,0 +1,45 @@
+export {
+  ShortcutProvider,
+  SHORTCUT_SCOPE_PRIORITY,
+  isEditableShortcutEvent,
+  shortcutDisplay,
+  useShortcuts,
+} from './interactions/shortcuts';
+export type {
+  ShortcutDefinition,
+  ShortcutHelpEntry,
+  ShortcutScope,
+  UseShortcutsOptions,
+} from './interactions/shortcuts';
+export { collectionActionDefaults } from './interactions/actions';
+export type {
+  CollectionAction,
+  CollectionActionContext,
+  CollectionActionIntent,
+  ResolvedCollectionAction,
+} from './interactions/actions';
+export { useCollectionInteractions, COLLECTION_ITEM_ATTRIBUTE } from './hooks/useCollectionInteractions';
+export type {
+  CollectionInteractionController,
+  CollectionInteractionReason,
+  CollectionKeyboardShortcuts,
+  CollectionNavigationContext,
+  CollectionNavigationDirection,
+  CollectionSelectionChange,
+  SelectionMarqueeRect,
+  UseCollectionInteractionsOptions,
+} from './hooks/useCollectionInteractions';
+export { MultiSelectActionBar, BULK_ACTION_LAYOUT_EVENT } from './components/MultiSelectActionBar';
+export type { BulkActionLayoutDetail } from './components/MultiSelectActionBar';
+export { MultiSelectCheckbox, MultiSelectCheckbox as SelectionCheckbox } from './components/MultiSelectCheckbox';
+export { MultiSelectDragOverlay, MultiSelectDragOverlay as SelectionMarquee } from './components/MultiSelectDragOverlay';
+export { ShortcutHints } from './components/ShortcutHints';
+export type { MultiSelectAction, MultiSelectActionBarProps } from './components/MultiSelectActionBar';
+export type { MultiSelectCheckboxProps } from './components/MultiSelectCheckbox';
+export type { MultiSelectDragOverlayProps } from './components/MultiSelectDragOverlay';
+export type { MultiSelectCheckboxProps as SelectionCheckboxProps } from './components/MultiSelectCheckbox';
+export type { MultiSelectDragOverlayProps as SelectionMarqueeProps } from './components/MultiSelectDragOverlay';
+export type { ShortcutHint, ShortcutHintsProps } from './components/ShortcutHints';
+
+export { useLongPressSelection } from './hooks/useLongPressSelection';
+export { isInteractionElementVisible } from './interactions/visibility';

package/dist/sdk/src/nativeData.ts

@@ -0,0 +1,39 @@
+/** The native row contract, shared by direct tools and scoped Space actions. */
+export type NativeField = { property_id: string } | { property: string } | {
+  column: 'record_key' | 'id' | 'title' | 'created_at' | 'updated_at' | 'last_edited_time' | 'content_type' | 'file_type';
+};
+export type NativeFilter = { and: NativeFilter[] } | { or: NativeFilter[] } | {
+  field: NativeField;
+  op: 'equals' | 'not_equals' | 'in' | 'contains' | 'not_contains' | 'does_not_contain'
+    | 'starts_with' | 'ends_with' | 'is_empty' | 'is_not_empty' | 'greater_than' | 'less_than'
+    | 'greater_than_or_equal_to' | 'less_than_or_equal_to' | 'before' | 'after' | 'on_or_before' | 'on_or_after';
+  value?: unknown;
+};
+export interface NativeQuery {
+  include_content?: boolean;
+  include_archived?: boolean;
+  mode?: 'rows' | 'search' | 'count' | 'aggregate';
+  filter?: NativeFilter;
+  sorts?: Array<{ field: NativeField; direction: 'asc' | 'desc' }>;
+  search?: { text: string; fields: NativeField[] };
+  aggregate?: { op: 'sum' | 'avg' | 'min' | 'max'; field: NativeField };
+  page_size?: number;
+  offset?: number;
+}
+export interface NativeInsert {
+  columns?: { title?: string | null; icon?: string | null; cover?: string | null };
+  properties?: Record<string, unknown>;
+  body?: { blocks: Array<Record<string, unknown>> };
+}
+export interface NativeUpdate extends NativeInsert { record_key: string; expected_revision: number; }
+export interface NativeDelete { record_key: string; expected_revision: number; }
+export interface NativeMutationReceipt {
+  record_key: string;
+  id: string;
+  database_id: string;
+  revision: number;
+  schema_revision: number;
+  receipt_id: string;
+  operation: 'insert' | 'update' | 'delete';
+  replayed?: boolean;
+}

package/dist/sdk/src/presentation.tsx

@@ -0,0 +1,82 @@
+'use client';
+
+import React, { useCallback, useLayoutEffect, type CSSProperties, type ErrorInfo, type ReactNode } from 'react';
+import { createPortal } from 'react-dom';
+import { NotisProvider } from './provider';
+import type { NotisRuntime } from './runtime';
+
+type BoundaryProps = {
+  children: ReactNode;
+  resetKey: string;
+  fallback: (error: Error) => ReactNode;
+  onError: (error: Error, info: ErrorInfo) => void;
+};
+
+/** A navigation can recover a crashed view without remounting healthy drafts. */
+export class PresentationErrorBoundary extends React.Component<BoundaryProps, { error: Error | null; resetKey: string }> {
+  constructor(props: BoundaryProps) { super(props); this.state = { error: null, resetKey: props.resetKey }; }
+  static getDerivedStateFromError(error: Error) { return { error }; }
+  static getDerivedStateFromProps(props: BoundaryProps, state: { resetKey: string }) {
+    return props.resetKey !== state.resetKey ? { error: null, resetKey: props.resetKey } : null;
+  }
+  componentDidCatch(error: Error, info: ErrorInfo) { this.props.onError(error, info); }
+  render() { return this.state.error ? this.props.fallback(this.state.error) : this.props.children; }
+}
+
+function CommittedPresentation({ mount, onCommit, children }: { mount: HTMLElement; onCommit?: (hasContent: boolean) => void; children: ReactNode }) {
+  useLayoutEffect(() => {
+    if (!onCommit) return;
+    const publish = () => onCommit?.(Boolean(mount.querySelector('[data-notis-app-root]')?.childNodes.length));
+    publish();
+    // A source may render null while its first query resolves. Observe the
+    // committed source DOM, not only commits of the unchanged host component.
+    const Observer = mount.ownerDocument.defaultView?.MutationObserver;
+    const observer = Observer ? new Observer(publish) : null;
+    observer?.observe(mount, { childList: true, subtree: true, characterData: true });
+    return () => observer?.disconnect();
+  }, [mount, onCommit]);
+  return children;
+}
+
+/** Portal and offline verification share this exact React/Shadow presentation.
+ * Source is trusted code in the host JS realm; Shadow DOM only isolates CSS.
+ * Loading, credentials and action authority belong to the respective host.
+ */
+export function SdkPresentation({ mount, runtime, component: Component, shell: Shell, theme, resetKey, active = true,
+  fallback, onError, onCommit, boundsCss, onProtocolError }: {
+  mount: HTMLElement | null;
+  runtime: NotisRuntime | null;
+  component: React.ComponentType | null;
+  shell?: React.ComponentType<{ children: ReactNode }>;
+  theme: { mode: 'light' | 'dark'; style: CSSProperties };
+  resetKey: string;
+  fallback: BoundaryProps['fallback'];
+  onError: BoundaryProps['onError'];
+  onCommit?: (hasContent: boolean) => void;
+  boundsCss?: string;
+  active?: boolean;
+  onProtocolError?: (error: Error) => void;
+}) {
+  const shortcutsAvailable = useCallback(() => {
+    if (!active || !mount?.isConnected) return false;
+    let element: HTMLElement | null = mount;
+    while (element) {
+      const style = element.ownerDocument.defaultView?.getComputedStyle(element);
+      if (element.hidden || element.hasAttribute('inert') || element.getAttribute('aria-hidden') === 'true'
+          || style?.display === 'none' || style?.visibility === 'hidden') return false;
+      const root = element.getRootNode();
+      element = element.parentElement || ('host' in root ? (root as ShadowRoot).host as HTMLElement : null);
+    }
+    return true;
+  }, [active, mount]);
+  return <PresentationErrorBoundary resetKey={resetKey} fallback={fallback} onError={onError}>
+    {mount && runtime && Component ? createPortal(<CommittedPresentation mount={mount} onCommit={onCommit}>
+      {boundsCss ? <style data-notis-runtime-bounds>{boundsCss}</style> : null}
+      <NotisProvider runtime={runtime} onProtocolError={onProtocolError} shortcutsAvailable={shortcutsAvailable}>
+        <div data-notis-app-root data-notis-theme={theme.mode} style={theme.style}>
+          {Shell ? <Shell><Component /></Shell> : <Component />}
+        </div>
+      </NotisProvider>
+    </CommittedPresentation>, mount) : null}
+  </PresentationErrorBoundary>;
+}

package/dist/sdk/src/provider.tsx

@@ -0,0 +1,49 @@
+'use client';
+
+import React, { createContext, useContext, useMemo, type Context, type ReactNode } from 'react';
+import type { NotisRuntime } from './runtime';
+import { ShortcutProvider } from './interactions/shortcuts';
+import { guardSpaceRuntime } from './space';
+
+const NOTIS_CONTEXT_SYMBOL = Symbol.for('notis.sdk.runtime_context');
+
+type NotisContextGlobal = typeof globalThis & {
+  [NOTIS_CONTEXT_SYMBOL]?: Context<NotisRuntime | null>;
+};
+
+function getNotisContext(): Context<NotisRuntime | null> {
+  const scope = globalThis as NotisContextGlobal;
+  if (!scope[NOTIS_CONTEXT_SYMBOL]) {
+    scope[NOTIS_CONTEXT_SYMBOL] = createContext<NotisRuntime | null>(null);
+  }
+  return scope[NOTIS_CONTEXT_SYMBOL]!;
+}
+
+const NotisContext = getNotisContext();
+
+/**
+ * Provides the Notis runtime context to all child components. The portal owns
+ * the runtime and injects it into the rendered app tree.
+ */
+export function NotisProvider({ children, runtime, onProtocolError, shortcutsAvailable }: {
+  children: ReactNode; runtime: NotisRuntime | null; onProtocolError?: (error: Error) => void;
+  shortcutsAvailable?: () => boolean;
+}) {
+  const scopedRuntime = useMemo(() => guardSpaceRuntime(runtime, onProtocolError), [runtime, onProtocolError]);
+  if (runtime === undefined) {
+    throw new Error('NotisProvider requires an explicit runtime prop.');
+  }
+  return (
+    <NotisContext.Provider value={scopedRuntime}>
+      <ShortcutProvider isAvailable={shortcutsAvailable}>{children}</ShortcutProvider>
+    </NotisContext.Provider>
+  );
+}
+
+/**
+ * Returns the raw NotisRuntime or null if not yet available.
+ * Prefer the typed hooks (useTool, useNotis, etc.) over this.
+ */
+export function useNotisRuntime(): NotisRuntime | null {
+  return useContext(NotisContext);
+}

package/dist/sdk/src/queryCache.ts

@@ -0,0 +1,172 @@
+import { SdkQueryError } from './queryErrors';
+
+/** In-memory read snapshots. The host owns the lifetime and authorization scope. */
+export interface QuerySnapshot<T = unknown> {
+  data: T | undefined;
+  hasData: boolean;
+  isFetching: boolean;
+  error: Error | null;
+  updatedAt: number;
+  invalidation: number;
+}
+
+export interface QueryFetchOptions {
+  staleTimeMs?: number;
+  force?: boolean;
+}
+
+export interface NotisQueryClient {
+  getSnapshot<T>(key: string): QuerySnapshot<T>;
+  subscribe(key: string, listener: () => void): () => void;
+  fetch<T>(key: string, read: () => Promise<T>, options?: QueryFetchOptions): Promise<T>;
+  prefetch<T>(key: string, read: () => Promise<T>, options?: QueryFetchOptions): Promise<T>;
+  invalidate(key?: string): void;
+  clear(): void;
+  /** Host-only: permanently retire a revoked security scope. */
+  dispose?(): void;
+  getRevision?(): number;
+}
+
+const EMPTY: QuerySnapshot = Object.freeze({
+  data: undefined, hasData: false, isFetching: false, error: null, updatedAt: 0, invalidation: 0,
+});
+
+/** Stable keys distinguish filters, pagination, and resource identities. */
+export function queryKey(value: unknown): string {
+  if (value instanceof Date) return JSON.stringify(value.toISOString());
+  if (Array.isArray(value)) return `[${value.map(queryKey).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record).filter((key) => record[key] !== undefined).sort()
+      .map((key) => `${JSON.stringify(key)}:${queryKey(record[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+/** One shared queue can bound descriptor and data speculation together. */
+export function createPrefetchQueue(concurrency = 2) {
+  let active = 0;
+  const waiting: Array<() => void> = [];
+  function drain() {
+    while (active < concurrency && waiting.length) waiting.shift()!();
+  }
+  return <T>(read: () => Promise<T>): Promise<T> => new Promise<T>((resolve, reject) => {
+    waiting.push(() => {
+      active += 1;
+      Promise.resolve().then(read).then(resolve, reject).finally(() => { active -= 1; drain(); });
+    });
+    drain();
+  });
+}
+
+type Entry = {
+  snapshot: QuerySnapshot;
+  listeners: Set<() => void>;
+  generation: number;
+  pending?: Promise<unknown>;
+};
+
+export function createQueryClient(options: {
+  maxEntries?: number;
+  now?: () => number;
+  schedule?: ReturnType<typeof createPrefetchQueue>;
+  /** Bounds idempotent reads only; never retries the underlying callback. */
+  readTimeoutMs?: number;
+} = {}): NotisQueryClient {
+  const entries = new Map<string, Entry>();
+  const now = options.now ?? Date.now;
+  const maxEntries = options.maxEntries ?? 100;
+  const schedule = options.schedule ?? createPrefetchQueue(2);
+  let epoch = 0;
+  let disposed = false;
+  let revision = 0;
+
+  function prune(keep?: string) {
+    for (const [oldKey, old] of entries) {
+      if (entries.size <= maxEntries) break;
+      if (oldKey !== keep && !old.listeners.size && !old.pending) entries.delete(oldKey);
+    }
+  }
+  function entry(key: string): Entry {
+    let value = entries.get(key);
+    if (!value) {
+      value = { snapshot: EMPTY, listeners: new Set(), generation: 0 };
+      entries.set(key, value);
+    }
+    // Only operations, not getSnapshot during render, update the LRU.
+    entries.delete(key);
+    entries.set(key, value);
+    prune(key);
+    return value;
+  }
+  function publish(value: Entry, snapshot: QuerySnapshot) {
+    value.snapshot = snapshot;
+    for (const listener of value.listeners) listener();
+  }
+  const client: NotisQueryClient = {
+    getSnapshot<T>(key: string) { return (entries.get(key)?.snapshot ?? EMPTY) as QuerySnapshot<T>; },
+    subscribe(key, listener) {
+      const value = entry(key);
+      value.listeners.add(listener);
+      return () => { value.listeners.delete(listener); prune(); };
+    },
+    fetch<T>(key: string, read: () => Promise<T>, fetchOptions: QueryFetchOptions = {}) {
+      if (disposed) return Promise.reject(new SdkQueryError('scopeUnavailable'));
+      const value = entry(key);
+      if (value.pending) return value.pending as Promise<T>;
+      if (!fetchOptions.force && value.snapshot.hasData && value.snapshot.updatedAt > 0
+        && now() - value.snapshot.updatedAt < (fetchOptions.staleTimeMs ?? 30_000)) {
+        return Promise.resolve(value.snapshot.data as T);
+      }
+      const generation = ++value.generation;
+      const requestEpoch = epoch;
+      const canCommit = () => epoch === requestEpoch && value.generation === generation && entries.get(key) === value;
+      let timeout: ReturnType<typeof setTimeout>;
+      const deadline = new Promise<never>((_, reject) => {
+        timeout = setTimeout(() => reject(new SdkQueryError('timedOut')), options.readTimeoutMs ?? 30_000);
+        // Node-based verification must not stay alive for a retired browser read.
+        if (typeof timeout === 'object' && 'unref' in timeout) timeout.unref();
+      });
+      const request = Promise.race([Promise.resolve().then(read), deadline]).then((data) => {
+        if (canCommit()) publish(value, { ...value.snapshot, data, hasData: true, isFetching: false, error: null, updatedAt: now() });
+        return data;
+      }, (reason) => {
+        const error = reason instanceof Error ? reason : new Error(String(reason));
+        if (canCommit()) publish(value, { ...value.snapshot, isFetching: false, error });
+        throw error;
+      }).finally(() => { clearTimeout(timeout); if (value.pending === request) value.pending = undefined; prune(); });
+      value.pending = request;
+      publish(value, { ...value.snapshot, isFetching: true, error: null });
+      return request;
+    },
+    prefetch<T>(key: string, read: () => Promise<T>, fetchOptions?: QueryFetchOptions) {
+      const requestEpoch = epoch;
+      return schedule(() => {
+        if (epoch !== requestEpoch) throw new SdkQueryError('scopeCleared');
+        return client.fetch(key, read, fetchOptions);
+      });
+    },
+    getRevision: () => revision,
+    invalidate(key) {
+      revision += 1;
+      for (const [entryKey, value] of entries) {
+        if (key !== undefined && entryKey !== key) continue;
+        value.generation += 1;
+        value.pending = undefined;
+        publish(value, { ...value.snapshot, updatedAt: 0, isFetching: false, invalidation: value.snapshot.invalidation + 1 });
+      }
+    },
+    dispose() { disposed = true; client.clear(); },
+    clear() {
+      revision += 1;
+      epoch += 1;
+      for (const value of entries.values()) {
+        value.generation += 1;
+        value.pending = undefined;
+        publish(value, { ...EMPTY, invalidation: value.snapshot.invalidation + 1 });
+      }
+      for (const [key, value] of entries) if (!value.listeners.size) entries.delete(key);
+    },
+  };
+  return client;
+}

package/dist/sdk/src/queryErrors.ts

@@ -0,0 +1,51 @@
+/** SDK-owned read failures. The host still owns messages for server/action refusals. */
+const copy = {
+  en: {
+    bindingUnavailable: 'This Space cannot read this database yet.',
+    actionUnavailable: 'This action is unavailable in this Space.',
+    readUnavailable: 'These data cannot be read in this Space.',
+    schemaChanged: 'This database changed. Refresh the page and try again.',
+    responseIncomplete: 'This database could not be loaded. Refresh the page and try again.',
+    listUnavailable: 'This list is unavailable in this view.',
+    timedOut: 'This read took too long. Please retry.',
+    scopeUnavailable: 'App query scope is no longer available.',
+    scopeCleared: 'App query scope was cleared.',
+  },
+  fr: {
+    bindingUnavailable: 'Ce Space ne peut pas encore lire cette base de données.',
+    actionUnavailable: 'Cette action n’est pas disponible dans ce Space.',
+    readUnavailable: 'Ces données ne sont pas accessibles dans ce Space.',
+    schemaChanged: 'Cette base de données a changé. Actualise la page et réessaie.',
+    responseIncomplete: 'Cette base de données n’a pas pu être chargée. Actualise la page et réessaie.',
+    listUnavailable: 'Cette liste n’est pas disponible dans cette vue.',
+    timedOut: 'Cette lecture a pris trop de temps. Réessaie.',
+    scopeUnavailable: 'Les données de cette vue ne sont plus accessibles.',
+    scopeCleared: 'Les données de cette vue ont été réinitialisées.',
+  },
+} as const;
+
+export type QueryErrorKey = keyof typeof copy.en;
+const PREFIX = 'notis_sdk_query:';
+
+/** Code and diagnostic survive localisation; only SDK-owned messages are translated. */
+export class SdkQueryError extends Error {
+  readonly code: string;
+  readonly diagnostic?: string;
+  constructor(key: QueryErrorKey, diagnostic?: string, locale?: string, cause?: Error) {
+    super(copy[locale === 'fr' ? 'fr' : 'en'][key], cause ? { cause } : undefined);
+    this.name = 'SdkQueryError';
+    this.code = PREFIX + key;
+    this.diagnostic = diagnostic;
+  }
+}
+
+/** Called at render time, so a cached failure changes language without replaying its read. */
+export function localizeQueryError(error: Error | null, locale?: string): Error | null {
+  const failure = error as (Error & { code?: unknown; diagnostic?: unknown }) | null;
+  if (!failure || typeof failure.code !== 'string' || !failure.code.startsWith(PREFIX)) return error;
+  const key = failure.code.slice(PREFIX.length);
+  if (!Object.hasOwn(copy.en, key)) return error;
+  const message = copy[locale === 'fr' ? 'fr' : 'en'][key as QueryErrorKey];
+  if (failure.message === message) return error;
+  return new SdkQueryError(key as QueryErrorKey, typeof failure.diagnostic === 'string' ? failure.diagnostic : undefined, locale, failure);
+}