@notis_ai/cli 0.2.18 → 0.2.20

package/dist/sdk/src/ui/util.ts

@@ -0,0 +1,83 @@
+/** Small shared helpers of the toolkit pieces (not exported from `@notis/sdk/ui`). */
+
+import { useCallback, useEffect, useLayoutEffect, useRef } from 'react';
+import { labelValue, pick, type Words } from '../words/types';
+import { useToolkitLocale } from './engine/hooks';
+
+/** Joins class names, skipping empty ones. */
+export function cx(...names: Array<string | false | null | undefined>): string {
+  return names.filter(Boolean).join(' ');
+}
+
+/** `(words) => string` in the toolkit locale. Plain strings pass through (Space code may pass its own words). */
+export function useT(): (words: Words | string) => string {
+  const locale = useToolkitLocale();
+  return useCallback((words: Words | string) => pick(words, locale), [locale]);
+}
+
+/** `(label, value) => "Label: value"` in the toolkit locale (French: a narrow no-break space before the colon). */
+export function useLabelValue(): (label: string, value: string) => string {
+  const locale = useToolkitLocale();
+  return useCallback((label: string, value: string) => labelValue(label, value, locale), [locale]);
+}
+
+/** A data attribute that is present (empty string) or absent, never "false". */
+export function flag(on: boolean | undefined): '' | undefined {
+  return on ? '' : undefined;
+}
+
+export const useIsoLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+
+/** The latest value, readable from callbacks registered once. */
+export function useLatest<V>(value: V): { readonly current: V } {
+  const ref = useRef(value);
+  ref.current = value;
+  return ref;
+}
+
+let idCounter = 0;
+/** A stable id for aria wiring (React 18 has useId, but the SDK supports any React the host ships). */
+export function useStableId(prefix: string): string {
+  const ref = useRef<string | null>(null);
+  if (ref.current === null) {
+    idCounter += 1;
+    ref.current = `${prefix}-${idCounter}`;
+  }
+  return ref.current;
+}
+
+/** True when the event path (shadow roots included) passes through one of the elements. */
+export function eventWithin(event: Event, elements: Array<Element | null | undefined>): boolean {
+  const path = typeof event.composedPath === 'function' ? event.composedPath() : [];
+  for (const element of elements) {
+    if (!element) continue;
+    if (path.includes(element)) return true;
+    if (event.target instanceof Node && element.contains(event.target)) return true;
+  }
+  return false;
+}
+
+/** The element that has focus, looking through open shadow roots. */
+export function deepActiveElement(root: Document | ShadowRoot = document): Element | null {
+  let active = root.activeElement;
+  while (active && active.shadowRoot && active.shadowRoot.activeElement) active = active.shadowRoot.activeElement;
+  return active;
+}
+
+/**
+ * Scrolls the nearest sideways-scrolling ancestor so `el` is fully in view (a tab strip or toolbar on a phone).
+ * Unlike scrollIntoView it never scrolls the page up or down.
+ */
+export function revealInline(el: HTMLElement | null | undefined): void {
+  if (!el || typeof window === 'undefined') return;
+  for (let box = el.parentElement; box; box = box.parentElement) {
+    if (box.scrollWidth <= box.clientWidth) continue;
+    const overflow = window.getComputedStyle(box).overflowX;
+    if (overflow !== 'auto' && overflow !== 'scroll') continue;
+    const boxRect = box.getBoundingClientRect();
+    const rect = el.getBoundingClientRect();
+    if (rect.left < boxRect.left) box.scrollLeft -= boxRect.left - rect.left;
+    else if (rect.right > boxRect.right) box.scrollLeft += rect.right - boxRect.right;
+    return;
+  }
+}

package/dist/sdk/src/viewPeriod.ts

@@ -0,0 +1,26 @@
+/** Inclusive calendar ranges; Monday starts a week. Matches the server's shown reader. */
+export const VIEW_PERIODS = ['today', 'tomorrow', 'this_week', 'last_week', 'this_month', 'last_month'] as const;
+export function isViewDate(value: string): boolean {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || value.startsWith('0000-')) return false;
+  const parsed = new Date(`${value}T00:00:00Z`);
+  return Number.isFinite(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+}
+export function isViewPeriod(value: string): boolean {
+  if ((VIEW_PERIODS as readonly string[]).includes(value)) return true;
+  const parts = value.split('/');
+  return parts.length === 2 && parts.every(isViewDate) && parts[0] <= parts[1];
+}
+export function resolveViewPeriod(value: string, timeZone = 'UTC', now = new Date()): { start: string; end: string } {
+  if (!isViewPeriod(value)) throw new Error('Invalid view period');
+  if (value.includes('/')) { const [start, end] = value.split('/'); return { start, end }; }
+  const parts = new Intl.DateTimeFormat('en-US', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' }).formatToParts(now);
+  const get = (type: string) => parts.find(part => part.type === type)!.value;
+  const start = new Date(`${get('year')}-${get('month')}-${get('day')}T00:00:00Z`);
+  if (value === 'tomorrow') start.setUTCDate(start.getUTCDate() + 1);
+  if (value.endsWith('week')) start.setUTCDate(start.getUTCDate() - (start.getUTCDay() + 6) % 7 - (value === 'last_week' ? 7 : 0));
+  if (value.endsWith('month')) { start.setUTCDate(1); if (value === 'last_month') start.setUTCMonth(start.getUTCMonth() - 1); }
+  const end = new Date(start);
+  if (value.endsWith('week')) end.setUTCDate(end.getUTCDate() + 6);
+  if (value.endsWith('month')) { end.setUTCMonth(end.getUTCMonth() + 1); end.setUTCDate(0); }
+  return { start: start.toISOString().slice(0, 10), end: end.toISOString().slice(0, 10) };
+}

package/dist/sdk/src/vite.ts

@@ -0,0 +1,92 @@
+/**
+ * Vite config builder for Notis Space views.
+ *
+ * Usage:
+ * ```ts
+ * // vite.config.ts
+ * import { notisViteConfig } from '@notis/sdk/vite';
+ * import workspace from './notis.config';
+ * export default notisViteConfig(workspace);
+ * ```
+ *
+ * Produces a library-mode ES module bundle with React externalized, and for
+ * Spaces the host-provided SDK too.
+ * Output: .notis/output/bundle/app.js + app.css
+ */
+
+import * as vite from 'vite';
+import type { SpacesWorkspace } from './space';
+import { notisTailwindContent } from './tailwind';
+import { NOTIS_SDK_HOST_MODULES, REACT_HOST_MODULES } from './runtimeModules';
+
+const externalReact: string[] = [...REACT_HOST_MODULES];
+
+// The oldest browsers that support CSS light-dark() natively. With Vite's
+// default CSS target, Lightning CSS (Vite 8) rewrites light-dark(a, b) into
+// var(--lightningcss-light, a) var(--lightningcss-dark, b), and those
+// variables are only set by a stylesheet color-scheme rule. The Notis host
+// sets color-scheme inline, so the lowered colours resolve to nothing and
+// render transparent. Targeting these versions keeps light-dark() as written.
+export const NOTIS_CSS_TARGET = ['chrome123', 'edge123', 'firefox120', 'safari17.5'];
+
+/**
+ * Every selected Space builds with the same library config; the CLI writes the
+ * selected entry to `.notis/_entry.tsx`. The workspace index is accepted so
+ * vite.config.ts can pass its notis.config default export.
+ */
+export function notisViteConfig(_workspace: SpacesWorkspace): vite.UserConfig {
+  // A Space bundle never contains the SDK: the host provides `@notis/sdk` and
+  // `@notis/sdk/ui` like React (runtimeModules.ts).
+  const external = [...externalReact, ...Object.keys(NOTIS_SDK_HOST_MODULES)];
+  // Vite 8 preserves external require() calls. App bundles run in a browser
+  // with an ESM import map, so bundled CommonJS dependencies must import React.
+  // Older pulled apps also receive this SDK; their Vite already does this.
+  const externalRequirePlugin = 'esmExternalRequirePlugin' in vite
+    && typeof vite.esmExternalRequirePlugin === 'function'
+    ? vite.esmExternalRequirePlugin({ external })
+    : null;
+  return {
+    plugins: [
+      notisTailwindContent(),
+      ...(externalRequirePlugin ? [externalRequirePlugin] : []),
+      // @vitejs/plugin-react is added by the consumer's vite.config.ts
+      // or auto-detected. We provide the config shape only.
+    ],
+    build: {
+      lib: {
+        entry: '.notis/_entry.tsx',
+        formats: ['es'],
+        fileName: () => 'app.js',
+      },
+      // Keep Vite's compatibility alias: SDK refresh also serves historical
+      // Vite 5/6/7 apps, which do not understand rolldownOptions.
+      rollupOptions: {
+        // On Vite 8 the plugin must own externalization as well as conversion:
+        // a top-level external match bypasses its require-to-import transform.
+        external: externalRequirePlugin ? [] : external,
+        output: {
+          globals: {
+            react: 'window.React',
+            'react-dom': 'window.ReactDOM',
+            'react-dom/client': 'window.ReactDOMClient',
+            'react/jsx-runtime': 'window.React',
+          },
+          assetFileNames: 'app[extname]',
+          inlineDynamicImports: true,
+        },
+      },
+      outDir: '.notis/output/bundle',
+      emptyOutDir: true,
+      cssCodeSplit: false,
+      cssTarget: NOTIS_CSS_TARGET,
+    },
+    resolve: {
+      alias: {
+        '@': process.cwd(),
+      },
+    },
+    define: {
+      'process.env.NODE_ENV': JSON.stringify('production'),
+    },
+  };
+}

package/dist/sdk/src/words/actions.ts

@@ -0,0 +1,295 @@
+/**
+ * The standard action catalogue (toolkit spec 2.7). Notis owns these words and keys; a Space supplies only `run`.
+ * Pure: the React binding (`useActions`) lives in `ui/actions/`.
+ */
+
+import { canonicalKey, keyList } from './keys';
+import { fillWords, isWords, type KeySpec, type Words } from './types';
+
+/** Phosphor icon name ('archive', 'trash', ...). The toolkit's Icon resolves it. */
+export type IconName = string;
+
+/**
+ * An icon name, or an icon element (`<Archive size={16} />`). The element is typed structurally so the words stay
+ * free of React; menus and the selection bar draw either.
+ */
+export type ActionIcon = IconName | { readonly type: unknown; readonly props: unknown; readonly key?: unknown };
+
+export type ActionTone = 'default' | 'danger';
+
+export type UndoFn = () => void | Promise<void>;
+
+/** One choice of a picker action (Move to, Assign). */
+export interface ActionOption {
+  value: string;
+  label: Words | string;
+  icon?: ActionIcon;
+  /** A muted second line or right-hand hint. */
+  hint?: Words | string;
+}
+
+/**
+ * What a run may return besides nothing or an UndoFn.
+ * - `cancelled`: the user backed out (a confirm said no): no toast, the selection stays.
+ * - `undo`: the toast offers Undo (and binds Z).
+ * - `failed`: the items that did not change; they stay selected and the toast says how many.
+ * - `toast`: words for this run only (null: no toast).
+ * - `reason`: a muted second line under the toast's words: why items failed, or a note on what happened (it shows
+ *   alone when the run has no toast words).
+ */
+export interface ActionResult<T = unknown> {
+  cancelled?: boolean;
+  undo?: UndoFn;
+  failed?: readonly T[];
+  toast?: Words | string | null;
+  reason?: Words | string | null;
+}
+
+export type ActionRunResult<T = unknown> = void | undefined | UndoFn | ActionResult<T>;
+
+/**
+ * Throw it from an action's `run`, or from any UndoFn a toast offers, to say why it failed: the failure toast ("That
+ * did not work. Try again.", "Could not undo that.") shows `reason` as its second line. Any other throw shows the
+ * failure words alone.
+ */
+export class ActionError extends Error {
+  readonly reason: Words | string;
+  readonly code = 'notis_action_error';
+
+  constructor(reason: Words | string, options?: { cause?: unknown }) {
+    super(typeof reason === 'string' ? reason : reason.en);
+    this.name = 'ActionError';
+    this.reason = reason;
+    if (options && 'cause' in options) (this as { cause?: unknown }).cause = options.cause;
+  }
+}
+
+/** The reason an ActionError carries, else null. A Space bundles its own copy of the words, so this reads the shape. */
+export function actionErrorReason(error: unknown): Words | string | null {
+  if (!error || typeof error !== 'object') return null;
+  const { name, code, reason } = error as { name?: unknown; code?: unknown; reason?: unknown };
+  if (name !== 'ActionError' || code !== 'notis_action_error') return null;
+  return typeof reason === 'string' || isWords(reason) ? reason : null;
+}
+
+export interface ActionDef<T = unknown> {
+  id: string;
+  /** Words, or one string for both languages. */
+  label: Words | string;
+  icon?: ActionIcon;
+  key?: KeySpec;
+  tone?: ActionTone;
+  /** Shown in the selection bar and run on every selected item. Default true. */
+  bulk?: boolean;
+  appliesTo?: (item: T) => boolean;
+  /**
+   * Return an UndoFn to make the toast offer Undo (and bind Z), or an ActionResult. A picker action receives the
+   * chosen option as `choice`.
+   */
+  run: (items: T[], choice?: ActionOption) => Promise<ActionRunResult<T>> | ActionRunResult<T>;
+  /**
+   * Words after a run; default from the catalogue. `null`, `false` or an explicit `toast: undefined` turns the
+   * toast off; the function may return null for no toast on that run.
+   */
+  toast?: ((n: number) => Words | string | null) | null | false;
+  /** The other half of a toggle (one key, one button): a mixed selection shows the first listed half. */
+  toggle?: string;
+  /** Picker choices (Move to, Assign): the list opens a menu of them and passes the pick to `run`. */
+  options?: readonly ActionOption[] | ((items: T[]) => readonly ActionOption[]);
+  /** The current value of the items (checked in the picker), when they all share one. */
+  value?: (items: T[]) => string | null | undefined;
+}
+
+export const STANDARD_ACTION_IDS = [
+  'complete', 'archive', 'unarchive', 'star', 'unstar', 'later', 'move', 'assign', 'read', 'unread', 'delete',
+  'progress', 'pause', 'resume', 'enable', 'disable', 'waiting',
+] as const;
+
+export type StandardActionId = typeof STANDARD_ACTION_IDS[number];
+
+export type ActionRef<T = unknown> = StandardActionId | (Partial<ActionDef<T>> & { id: string });
+
+/** A toast with one and many forms; `{n}` in `other` is the count. */
+export interface CountedWords {
+  one: Words;
+  other: Words;
+}
+
+export interface StandardAction {
+  id: StandardActionId;
+  label: Words;
+  icon: IconName;
+  key: KeySpec | null;
+  tone: ActionTone;
+  toast: CountedWords | null;
+  /** The other half of a toggle on the same key (star/unstar, read/unread). */
+  toggle?: StandardActionId;
+  /** Opens a picker instead of acting at once. */
+  picker?: boolean;
+  /** Not offered to Spaces yet (spec 6.10). */
+  managerOnly?: boolean;
+}
+
+const counted = (oneEn: string, otherEn: string, oneFr: string, otherFr: string): CountedWords => ({
+  one: { en: oneEn, fr: oneFr },
+  other: { en: otherEn, fr: otherFr },
+});
+
+const same = (en: string, fr: string): CountedWords => ({ one: { en, fr }, other: { en, fr } });
+
+export const STANDARD_ACTIONS: Readonly<Record<StandardActionId, StandardAction>> = Object.freeze({
+  complete: {
+    id: 'complete', label: { en: 'Complete', fr: 'Terminer' }, icon: 'check', key: 'e', tone: 'default',
+    toast: counted('1 item completed.', '{n} items completed.', '1 élément terminé.', '{n} éléments terminés.'),
+  },
+  archive: {
+    id: 'archive', label: { en: 'Archive', fr: 'Archiver' }, icon: 'archive', key: 'e', tone: 'default',
+    toast: counted('1 item archived.', '{n} items archived.', '1 élément archivé.', '{n} éléments archivés.'),
+  },
+  unarchive: {
+    // Back out of the archive. A Space names its own first stop: `{ id: 'unarchive', label: { en: 'Move to Inbox', ... } }`.
+    id: 'unarchive', label: { en: 'Move to triage', fr: 'Déplacer vers le tri' }, icon: 'tray-arrow-up', key: 'shift+e',
+    tone: 'default',
+    toast: counted('1 item restored.', '{n} items restored.', '1 élément restauré.', '{n} éléments restaurés.'),
+  },
+  star: {
+    id: 'star', label: { en: 'Star', fr: 'Mettre en favori' }, icon: 'star', key: 's', tone: 'default', toggle: 'unstar',
+    toast: counted('1 item starred.', '{n} items starred.', '1 élément ajouté aux favoris.',
+      '{n} éléments ajoutés aux favoris.'),
+  },
+  unstar: {
+    id: 'unstar', label: { en: 'Unstar', fr: 'Retirer des favoris' }, icon: 'star', key: 's', tone: 'default',
+    toggle: 'star', toast: null,
+  },
+  later: {
+    id: 'later', label: { en: 'Later', fr: 'Plus tard' }, icon: 'clock', key: 'h', tone: 'default',
+    toast: same('Snoozed until tomorrow.', 'Reporté à demain.'),
+  },
+  move: {
+    id: 'move', label: { en: 'Move to…', fr: 'Déplacer vers…' }, icon: 'arrow-bend-up-right', key: 'm', tone: 'default',
+    toast: null, picker: true,
+  },
+  assign: {
+    id: 'assign', label: { en: 'Assign…', fr: 'Attribuer…' }, icon: 'user-plus', key: 'a', tone: 'default',
+    toast: null, picker: true,
+  },
+  read: {
+    id: 'read', label: { en: 'Mark as read', fr: 'Marquer comme lu' }, icon: 'envelope-open', key: 'u', tone: 'default',
+    toggle: 'unread', toast: null,
+  },
+  unread: {
+    id: 'unread', label: { en: 'Mark as unread', fr: 'Marquer comme non lu' }, icon: 'envelope-simple', key: 'u',
+    tone: 'default', toggle: 'read', toast: null,
+  },
+  delete: {
+    id: 'delete', label: { en: 'Delete', fr: 'Supprimer' }, icon: 'trash', key: '#', tone: 'danger',
+    toast: counted('1 item deleted.', '{n} items deleted.', '1 élément supprimé.', '{n} éléments supprimés.'),
+  },
+  progress: {
+    id: 'progress', label: { en: 'Start progress', fr: 'Passer en cours' }, icon: 'circle-half', key: null,
+    tone: 'default', toast: null,
+  },
+  pause: {
+    id: 'pause', label: { en: 'Pause', fr: 'Mettre en pause' }, icon: 'pause', key: null, tone: 'default',
+    toggle: 'resume', toast: null,
+  },
+  resume: {
+    id: 'resume', label: { en: 'Resume', fr: 'Reprendre' }, icon: 'play', key: null, tone: 'default',
+    toggle: 'pause', toast: null,
+  },
+  enable: {
+    id: 'enable', label: { en: 'Enable', fr: 'Activer' }, icon: 'toggle-right', key: null, tone: 'default',
+    toggle: 'disable', toast: null,
+  },
+  disable: {
+    id: 'disable', label: { en: 'Disable', fr: 'Désactiver' }, icon: 'toggle-left', key: null, tone: 'default',
+    toggle: 'enable', toast: null,
+  },
+  waiting: {
+    id: 'waiting', label: { en: 'Waiting', fr: 'En attente' }, icon: 'hourglass', key: 'w', tone: 'default', toast: null,
+    managerOnly: true,
+  },
+});
+
+export function isStandardActionId(id: unknown): id is StandardActionId {
+  return typeof id === 'string' && Object.prototype.hasOwnProperty.call(STANDARD_ACTIONS, id);
+}
+
+/** The toast after `n` items, count filled in; null when the action has none. */
+export function actionToast(id: StandardActionId, n: number): Words | null {
+  const toast = STANDARD_ACTIONS[id].toast;
+  if (!toast) return null;
+  return fillWords(n === 1 ? toast.one : toast.other, { n });
+}
+
+/**
+ * The catalogue defaults for a ref, with the Space's overrides on top. `run` comes from the Space. An own `toast`
+ * key set to undefined, null or false turns the default toast off (the result then carries `toast: null`).
+ */
+export function resolveActionRef<T>(ref: ActionRef<T>): Partial<ActionDef<T>> & { id: string } {
+  if (typeof ref === 'string') return standardDefaults<T>(ref);
+  const toastOff = Object.prototype.hasOwnProperty.call(ref, 'toast') && !ref.toast;
+  const merged: Partial<ActionDef<T>> & { id: string } = isStandardActionId(ref.id)
+    ? { ...standardDefaults<T>(ref.id), ...stripUndefined(ref) }
+    : { ...ref };
+  if (toastOff) merged.toast = null;
+  return merged;
+}
+
+/** One string for both languages, or the words as given. */
+export function toWords(value: Words | string): Words {
+  return typeof value === 'string' ? { en: value, fr: value } : value;
+}
+
+function standardDefaults<T>(id: StandardActionId): Partial<ActionDef<T>> & { id: string } {
+  const action = STANDARD_ACTIONS[id];
+  return {
+    id,
+    label: action.label,
+    icon: action.icon,
+    key: action.key ?? undefined,
+    tone: action.tone,
+    toast: action.toast ? (n: number) => actionToast(id, n)! : undefined,
+    ...(action.toggle ? { toggle: action.toggle } : {}),
+  };
+}
+
+function stripUndefined<V extends object>(value: V): Partial<V> {
+  const out: Partial<V> = {};
+  for (const [k, v] of Object.entries(value)) if (v !== undefined) (out as Record<string, unknown>)[k] = v;
+  return out;
+}
+
+export interface ActionKeyClash {
+  key: string;
+  ids: string[];
+}
+
+/**
+ * Actions of one list that share a key. Toggle pairs (star/unstar, read/unread) are one key by design and do not
+ * clash. complete and archive both take E, so a list may list only one.
+ */
+export function actionKeyClashes(refs: readonly ActionRef<unknown>[]): ActionKeyClash[] {
+  const byKey = new Map<string, string[]>();
+  const toggles = new Map<string, string>();
+  for (const ref of refs) {
+    const resolved = resolveActionRef(ref);
+    if (resolved.toggle) toggles.set(resolved.id, resolved.toggle);
+    for (const spec of keyList(resolved.key)) {
+      const canonical = canonicalKey(spec);
+      const ids = byKey.get(canonical) ?? [];
+      if (!ids.includes(resolved.id)) ids.push(resolved.id);
+      byKey.set(canonical, ids);
+    }
+  }
+  const clashes: ActionKeyClash[] = [];
+  for (const [key, ids] of byKey) {
+    const left = ids.filter((id, index) => {
+      const partner = toggles.get(id);
+      // Keep one member of each toggle pair.
+      return !(partner && ids.indexOf(partner) !== -1 && ids.indexOf(partner) < index);
+    });
+    if (left.length > 1) clashes.push({ key, ids: left });
+  }
+  return clashes;
+}

package/dist/sdk/src/words/clashes.ts

@@ -0,0 +1,158 @@
+/**
+ * Key clash rules (toolkit spec 2.1). The engine runs them at registration; the design check (stream C) runs
+ * `checkClashes` on a Space's declared shortcuts at build time. Pure.
+ */
+
+import { canonicalKey, isHostReserved, keyList, parseKeySpec } from './keys';
+import { SCOPE_ORDER, type KeySpec, type Scope } from './types';
+
+export type ClashKind =
+  /** A Space binds a key the Notis host owns. Error. */
+  | 'reserved'
+  /** A Space registers at app scope, which is host only (spec 6.7). Error. */
+  | 'app-scope'
+  /** Same key, same scope, same owner, both available. Error. */
+  | 'duplicate'
+  /** Same key at different scopes: legal, the higher scope wins. Info. */
+  | 'shadowed'
+  /** A single key that also starts a sequence in the same scope and owner ('g' and 'g i'): the single key wins. Info. */
+  | 'prefix'
+  /** The spec does not parse. Error. */
+  | 'invalid';
+
+export interface ClashCandidate {
+  id: string;
+  keys: KeySpec | readonly KeySpec[];
+  scope: Scope;
+  /** Who registered it: a Space id, a retained view, or 'notis'. Default 'notis'. */
+  owner?: string;
+  /** 'space' defs may not use reserved keys or the app scope. Default 'space' when owner is set and not 'notis'. */
+  ownerKind?: 'space' | 'host';
+  /** Default true. Unavailable defs (hidden retained views) never clash. */
+  available?: boolean;
+}
+
+export interface Clash {
+  kind: ClashKind;
+  severity: 'error' | 'info';
+  /** Canonical key ('shift+e', 'g i'). */
+  key: string;
+  ids: string[];
+  scope?: Scope;
+  scopes?: Scope[];
+  owner?: string;
+  message: string;
+}
+
+const PLATFORMS = ['mac', 'other'] as const;
+
+/** Canonical forms of a def's keys on both platforms ('ctrl+a' equals 'mod+a' off a Mac). */
+export function keyFingerprints(keys: KeySpec | readonly KeySpec[]): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const spec of keyList(keys)) {
+    for (const platform of PLATFORMS) out.set(`${platform}:${canonicalKey(spec, platform)}`, canonicalKey(spec, 'mac'));
+  }
+  return out;
+}
+
+export function ownerOf(candidate: ClashCandidate): string {
+  return candidate.owner ?? 'notis';
+}
+
+export function ownerKindOf(candidate: ClashCandidate): 'space' | 'host' {
+  if (candidate.ownerKind) return candidate.ownerKind;
+  return ownerOf(candidate) === 'notis' ? 'host' : 'space';
+}
+
+/** Errors a single def has on its own (invalid, reserved, app scope). */
+export function selfClashes(candidate: ClashCandidate): Clash[] {
+  const clashes: Clash[] = [];
+  const space = ownerKindOf(candidate) === 'space';
+  for (const spec of keyList(candidate.keys)) {
+    try { parseKeySpec(spec); } catch (error) {
+      clashes.push({
+        kind: 'invalid', severity: 'error', key: spec, ids: [candidate.id], scope: candidate.scope,
+        owner: ownerOf(candidate), message: (error as Error).message,
+      });
+      continue;
+    }
+    if (space && isHostReserved(spec)) {
+      clashes.push({
+        kind: 'reserved', severity: 'error', key: canonicalKey(spec), ids: [candidate.id], scope: candidate.scope,
+        owner: ownerOf(candidate),
+        message: `"${candidate.id}" uses ${canonicalKey(spec)}, which Notis keeps for itself. Pick another key.`,
+      });
+    }
+  }
+  if (space && candidate.scope === 'app') {
+    clashes.push({
+      kind: 'app-scope', severity: 'error', key: keyList(candidate.keys).join(', '), ids: [candidate.id],
+      scope: 'app', owner: ownerOf(candidate),
+      message: `"${candidate.id}" registers at app scope, which only Notis uses. Use route or a lower scope.`,
+    });
+  }
+  return clashes;
+}
+
+function safeFingerprints(keys: KeySpec | readonly KeySpec[]): Map<string, string> {
+  try { return keyFingerprints(keys); } catch { return new Map(); }
+}
+
+/** Errors and infos between two defs, `later` registered after `earlier`. */
+export function pairClashes(earlier: ClashCandidate, later: ClashCandidate): Clash[] {
+  if (earlier.available === false || later.available === false) return [];
+  const a = safeFingerprints(earlier.keys);
+  const b = safeFingerprints(later.keys);
+  const shared = new Set<string>();
+  for (const [fingerprint, key] of b) if (a.has(fingerprint)) shared.add(key);
+  const clashes: Clash[] = [];
+  const sameOwner = ownerOf(earlier) === ownerOf(later);
+  for (const key of shared) {
+    if (earlier.scope === later.scope && sameOwner) {
+      clashes.push({
+        kind: 'duplicate', severity: 'error', key, ids: [earlier.id, later.id], scope: later.scope,
+        owner: ownerOf(later),
+        message: `NotisKeyClash: "${earlier.id}" and "${later.id}" both use ${key} in the ${later.scope} scope.`,
+      });
+    } else if (earlier.scope !== later.scope) {
+      const [low, high] = SCOPE_ORDER[earlier.scope] < SCOPE_ORDER[later.scope] ? [earlier, later] : [later, earlier];
+      clashes.push({
+        kind: 'shadowed', severity: 'info', key, ids: [high.id, low.id], scopes: [high.scope, low.scope],
+        message: `${key}: "${high.id}" (${high.scope}) is asked before "${low.id}" (${low.scope}).`,
+      });
+    }
+  }
+  if (earlier.scope === later.scope && sameOwner) {
+    for (const [single, sequence] of [[earlier, later], [later, earlier]] as const) {
+      for (const one of keyList(single.keys)) {
+        for (const seq of keyList(sequence.keys)) {
+          let s: ReturnType<typeof parseKeySpec>; let q: ReturnType<typeof parseKeySpec>;
+          try { s = parseKeySpec(one); q = parseKeySpec(seq); } catch { continue; }
+          if (s.length !== 1 || q.length < 2) continue;
+          if (canonicalKey(one) !== canonicalKey(seq).split(' ')[0]) continue;
+          clashes.push({
+            kind: 'prefix', severity: 'info', key: canonicalKey(one), ids: [single.id, sequence.id],
+            scope: single.scope, owner: ownerOf(single),
+            message: `${canonicalKey(one)} runs "${single.id}" at once, so "${sequence.id}" (${canonicalKey(seq)}) never starts.`,
+          });
+        }
+      }
+    }
+  }
+  return clashes;
+}
+
+/** Every clash in a list of defs, in registration order. */
+export function checkClashes(defs: readonly ClashCandidate[]): Clash[] {
+  const clashes: Clash[] = [];
+  defs.forEach((def, index) => {
+    clashes.push(...selfClashes(def));
+    for (let i = 0; i < index; i += 1) clashes.push(...pairClashes(defs[i]!, def));
+  });
+  return clashes;
+}
+
+/** Only the clashes that must stop a build or throw in dev. */
+export function clashErrors(defs: readonly ClashCandidate[]): Clash[] {
+  return checkClashes(defs).filter((clash) => clash.severity === 'error');
+}