@notis_ai/cli 0.2.17 → 0.2.19

package/dist/space-sdk/src/ui/timeline/timelineMath.d.ts

@@ -0,0 +1,123 @@
+/**
+ * TimelineView math (toolkit spec 2.11, deck round 5 "timeline"). Pure: date-fns only, no React.
+ *
+ * Days are counted from today (0 is today). Each zoom shows a fixed window around today and a fixed number of pixels
+ * per day, so the roadmap scrolls sideways instead of squeezing titles. Bars of a lane are packed in rows: a bar takes
+ * the first row whose last bar ended before it starts.
+ */
+import type { Locale } from '../../words/types';
+import { type DateInput } from '../calendar/calendarMath';
+export type TimelineZoom = 'week' | 'month' | 'quarter';
+export declare const TIMELINE_ZOOMS: readonly TimelineZoom[];
+/** Window of each zoom: first day (from today), days shown, pixels per day. */
+export declare const TIMELINE_ZOOM: Readonly<Record<TimelineZoom, {
+    from: number;
+    span: number;
+    px: number;
+}>>;
+/** How far `[` and `]` move the window, in days. */
+export declare const TIMELINE_STEP: Readonly<Record<TimelineZoom, number>>;
+export declare const TIMELINE_ROW_H = 36;
+export declare const TIMELINE_BAR_TOP = 6;
+export declare const TIMELINE_TRACK_PAD = 12;
+/** A bar cut by the window edge needs this many visible days to carry its title; thinner slivers are left out. */
+export declare const TIMELINE_MIN_VISIBLE_DAYS = 4;
+/** A tick label this close to today (share of the window) hides behind the Today chip. */
+export declare const TIMELINE_TODAY_GAP = 0.045;
+export interface TimelineWindow {
+    zoom: TimelineZoom;
+    /** First day shown, in days from today. */
+    from: number;
+    span: number;
+    px: number;
+}
+export declare function timelineWindow(zoom: TimelineZoom, offset?: number): TimelineWindow;
+/** `min-width` of the timeline: the lane labels (9rem) plus the days. */
+export declare function timelineMinWidth(win: TimelineWindow): string;
+/** Days from today to a day. */
+export declare function dayIndex(date: Date, today: Date): number;
+/** Start day and end day (exclusive) from today. No end, or an end before the start, gives one day. */
+export interface DaySpan {
+    s: number;
+    e: number;
+}
+export declare function itemSpan(start: DateInput, end: DateInput, today: Date): DaySpan | null;
+export declare function barVisibleDays(span: DaySpan, win: TimelineWindow): number;
+/**
+ * The bar shows when it is wholly inside the window, or when its visible part is at least four days (the deck's
+ * rule for slivers at the edges).
+ */
+export declare function inView(span: DaySpan, win: TimelineWindow): boolean;
+/** Packs bars into rows, sorted by start (stable). */
+export declare function packRows<B extends {
+    span: DaySpan;
+}>(bars: readonly B[]): {
+    bars: Array<B & {
+        row: number;
+    }>;
+    rows: number;
+};
+export interface BarGeometry {
+    /** Percent of the track. */
+    left: number;
+    width: number;
+    top: number;
+    cutLeft: boolean;
+    cutRight: boolean;
+}
+export declare function barGeometry(span: DaySpan, win: TimelineWindow, row: number): BarGeometry;
+export declare function trackHeight(rows: number): number;
+/** Percent of the track for a day from today. */
+export declare function dayPercent(day: number, win: TimelineWindow): number;
+export declare function todayInWindow(win: TimelineWindow): boolean;
+export interface TimelineTick {
+    /** Days from today. */
+    day: number;
+    date: Date;
+    label: string;
+    percent: number;
+    /** False when the label would sit under the Today chip (the grid line still draws). */
+    showLabel: boolean;
+}
+/** Quarter: the first of each month ("Nov" / "Nov."). Week and month: every Monday ("Oct 19" / "19 oct."). */
+export declare function timelineTicks(win: TimelineWindow, today: Date, locale: Locale): TimelineTick[];
+export interface TimelineLaneInfo {
+    id: string;
+    label: string;
+}
+export interface LaidBar<T> {
+    item: T;
+    id: string;
+    span: DaySpan;
+    row: number;
+    geometry: BarGeometry;
+}
+export interface LaidLane<T> extends TimelineLaneInfo {
+    bars: Array<LaidBar<T>>;
+    rows: number;
+    height: number;
+    /** Items of the lane in the window. */
+    count: number;
+}
+export interface TimelineLayoutInput<T> {
+    items: readonly T[];
+    getId: (item: T) => string;
+    getStart: (item: T) => DateInput;
+    getEnd: (item: T) => DateInput;
+    lane: (item: T) => TimelineLaneInfo;
+    /** Lane order; lanes not listed follow in the order they first appear. Lanes listed here show even when empty. */
+    lanes?: readonly TimelineLaneInfo[];
+    win: TimelineWindow;
+    today: Date;
+}
+/** Lanes with packed bars, plus `order`: the bar ids lane by lane, by start (what J and K walk). */
+export declare function layoutTimeline<T>(input: TimelineLayoutInput<T>): {
+    lanes: Array<LaidLane<T>>;
+    order: string[];
+    undated: T[];
+};
+/**
+ * Where T puts the cursor once the window is back on today: the first bar (in reading order) running today, else the
+ * bar starting soonest after today, else the last bar.
+ */
+export declare function timelineTodayCursor<T>(lanes: ReadonlyArray<LaidLane<T>>): string | null;

package/dist/space-sdk/src/viewPeriod.d.ts

@@ -0,0 +1,8 @@
+/** Inclusive calendar ranges; Monday starts a week. Matches the server's shown reader. */
+export declare const VIEW_PERIODS: readonly ['today', 'tomorrow', 'this_week', 'last_week', 'this_month', 'last_month'];
+export declare function isViewDate(value: string): boolean;
+export declare function isViewPeriod(value: string): boolean;
+export declare function resolveViewPeriod(value: string, timeZone?: string, now?: Date): {
+    start: string;
+    end: string;
+};

package/dist/space-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/space-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/space-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');
+}