@ai-composer/core 0.1.0

package/src/errors.ts

@@ -0,0 +1,25 @@
+/** Typed error codes so adapters and plugins can branch on failures. */
+export const ErrorCode = {
+  EDITOR_DESTROYED: 'EDITOR_DESTROYED',
+  UNKNOWN_COMMAND: 'UNKNOWN_COMMAND',
+  UNKNOWN_FORMAT: 'UNKNOWN_FORMAT',
+  UNKNOWN_TRIGGER: 'UNKNOWN_TRIGGER',
+  PLUGIN_SETUP_FAILED: 'PLUGIN_SETUP_FAILED',
+} as const;
+
+export type AIComposerErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+export class AIComposerError extends Error {
+  readonly code: AIComposerErrorCode;
+
+  constructor(code: AIComposerErrorCode, message: string) {
+    super(`[${code}] ${message}`);
+    this.name = 'AIComposerError';
+    this.code = code;
+  }
+}
+
+export function toError(value: unknown): Error {
+  if (value instanceof Error) return value;
+  return new Error(typeof value === 'string' ? value : JSON.stringify(value));
+}

package/src/events/event-bus.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createEventBus } from './event-bus';
+
+describe('event bus', () => {
+  it('subscribes and emits typed payloads', () => {
+    const bus = createEventBus<{ change: { value: number }; focus: { focused: boolean } }>();
+    const handler = vi.fn();
+    bus.on('change', handler);
+    bus.emit('change', { value: 42 });
+    expect(handler).toHaveBeenCalledWith({ value: 42 });
+  });
+
+  it('unsubscribe stops delivery', () => {
+    const bus = createEventBus<{ ping: { n: number } }>();
+    const handler = vi.fn();
+    const off = bus.on('ping', handler);
+    off();
+    bus.emit('ping', { n: 1 });
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('once fires a single time', () => {
+    const bus = createEventBus<{ ping: { n: number } }>();
+    const handler = vi.fn();
+    bus.once('ping', handler);
+    bus.emit('ping', { n: 1 });
+    bus.emit('ping', { n: 2 });
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('off removes a specific handler', () => {
+    const bus = createEventBus<{ ping: { n: number } }>();
+    const a = vi.fn();
+    const b = vi.fn();
+    bus.on('ping', a);
+    bus.on('ping', b);
+    bus.off('ping', a);
+    bus.emit('ping', { n: 1 });
+    expect(a).not.toHaveBeenCalled();
+    expect(b).toHaveBeenCalled();
+  });
+
+  it('a throwing listener does not break other listeners', () => {
+    const bus = createEventBus<{ ping: { n: number } }>();
+    const good = vi.fn();
+    bus.on('ping', () => {
+      throw new Error('boom');
+    });
+    bus.on('ping', good);
+    bus.emit('ping', { n: 1 });
+    expect(good).toHaveBeenCalled();
+  });
+
+  it('counts listeners and clears', () => {
+    const bus = createEventBus<{ ping: { n: number } }>();
+    bus.on('ping', () => undefined);
+    bus.on('ping', () => undefined);
+    expect(bus.listenerCount('ping')).toBe(2);
+    bus.clear();
+    expect(bus.listenerCount('ping')).toBe(0);
+  });
+});

package/src/events/event-bus.ts

@@ -0,0 +1,72 @@
+/**
+ * Minimal typed event bus. No framework emitters in core — adapters map this
+ * to synthetic events, RxJS, component events, etc.
+ */
+
+export type Unsubscribe = () => void;
+export type EventHandler<TPayload> = (payload: TPayload) => void;
+
+export interface EventMapBase {
+  [eventType: string]: unknown;
+}
+
+export interface EventBus<TEvents extends EventMapBase> {
+  on<K extends keyof TEvents & string>(type: K, handler: EventHandler<TEvents[K]>): Unsubscribe;
+  once<K extends keyof TEvents & string>(type: K, handler: EventHandler<TEvents[K]>): Unsubscribe;
+  off<K extends keyof TEvents & string>(type: K, handler: EventHandler<TEvents[K]>): void;
+  emit<K extends keyof TEvents & string>(type: K, payload: TEvents[K]): void;
+  listenerCount<K extends keyof TEvents & string>(type: K): number;
+  clear(): void;
+}
+
+export function createEventBus<TEvents extends EventMapBase>(): EventBus<TEvents> {
+  const handlers = new Map<string, Set<EventHandler<unknown>>>();
+
+  const bus: EventBus<TEvents> = {
+    on(type, handler) {
+      let set = handlers.get(type);
+      if (!set) {
+        set = new Set();
+        handlers.set(type, set);
+      }
+      set.add(handler as EventHandler<unknown>);
+      return () => bus.off(type, handler);
+    },
+
+    once(type, handler) {
+      const wrapped: EventHandler<unknown> = (payload) => {
+        off();
+        (handler as EventHandler<unknown>)(payload);
+      };
+      const off = bus.on(type, wrapped as never);
+      return off;
+    },
+
+    off(type, handler) {
+      handlers.get(type)?.delete(handler as EventHandler<unknown>);
+    },
+
+    emit(type, payload) {
+      const set = handlers.get(type);
+      if (!set || set.size === 0) return;
+      for (const handler of [...set]) {
+        try {
+          handler(payload);
+        } catch (error) {
+          // A broken listener must never break the editor loop.
+          console.error(`[ai-composer] unhandled error in "${type}" listener`, error);
+        }
+      }
+    },
+
+    listenerCount(type) {
+      return handlers.get(type)?.size ?? 0;
+    },
+
+    clear() {
+      handlers.clear();
+    },
+  };
+
+  return bus;
+}

package/src/events/events.ts

@@ -0,0 +1,120 @@
+/**
+ * The editor event contract. Every adapter emits exactly these semantics, so
+ * behavior can be contract-tested across frameworks.
+ */
+
+import type { EventBus } from './event-bus';
+import type { AIComposerDocument } from '../model/document';
+import type { AttachmentNode, AIComposerNode } from '../model/nodes';
+import type { SelectionState } from '../model/selection';
+import type { SuggestionItem } from '../state/state';
+
+/** What caused a document change. */
+export type ChangeSource = 'init' | 'user' | 'api' | 'plugin' | 'undo' | 'redo';
+
+export interface ChangeEvent {
+  value: AIComposerDocument;
+  source: ChangeSource;
+}
+
+export interface FocusChangeEvent {
+  focused: boolean;
+}
+
+export interface BeforeSubmitEvent {
+  value: AIComposerDocument;
+  defaultPrevented: boolean;
+  preventDefault(): void;
+}
+
+export interface SubmitEvent {
+  value: AIComposerDocument;
+}
+
+export interface SelectionChangeEvent {
+  selection: SelectionState;
+}
+
+export interface TriggerOpenEvent {
+  triggerId: string;
+  query: string;
+}
+
+export type TriggerCloseReason =
+  | 'select'
+  | 'escape'
+  | 'blur'
+  | 'input'
+  | 'manual'
+  | 'editor-destroy';
+
+export interface TriggerCloseEvent {
+  triggerId: string;
+  reason: TriggerCloseReason;
+}
+
+export interface SuggestionsChangeEvent {
+  triggerId: string | null;
+  suggestions: SuggestionItem[];
+  activeIndex: number;
+}
+
+export interface NodeInsertEvent {
+  node: AIComposerNode;
+  index: number;
+}
+
+export interface NodeRemoveEvent {
+  node: AIComposerNode;
+  index: number;
+}
+
+export interface AttachmentEvent {
+  attachment: AttachmentNode;
+}
+
+export interface CommandExecuteEvent {
+  id: string;
+  payload?: unknown;
+}
+
+export interface ModeChangeEvent {
+  mode: string;
+}
+
+export interface ErrorEvent {
+  error: Error;
+  /** Where it happened, e.g. `trigger:mention:search`, `submit`. */
+  phase?: string;
+}
+
+export interface DestroyEvent {
+  target: 'editor';
+}
+
+export type AIComposerEventMap = {
+  /** Any value change, from any source. */
+  change: ChangeEvent;
+  /** Value change caused by user input (typing, paste, chip insert). */
+  input: ChangeEvent;
+  focus: FocusChangeEvent;
+  blur: FocusChangeEvent;
+  beforeSubmit: BeforeSubmitEvent;
+  submit: SubmitEvent;
+  selectionChange: SelectionChangeEvent;
+  triggerOpen: TriggerOpenEvent;
+  triggerClose: TriggerCloseEvent;
+  suggestionsChange: SuggestionsChangeEvent;
+  nodeInsert: NodeInsertEvent;
+  nodeRemove: NodeRemoveEvent;
+  attachmentAdd: AttachmentEvent;
+  attachmentRemove: AttachmentEvent;
+  commandExecute: CommandExecuteEvent;
+  modeChange: ModeChangeEvent;
+  error: ErrorEvent;
+  destroy: DestroyEvent;
+};
+
+export type AIComposerEventType = keyof AIComposerEventMap & string;
+
+export type AIComposerBus = EventBus<AIComposerEventMap>;

package/src/factory.ts

@@ -0,0 +1,21 @@
+/** Factory + version. */
+
+import { AIComposerImpl, type AIComposer } from './editor';
+import type { AIComposerOptions } from './types';
+
+/**
+ * Create a framework-independent AI Composer editor instance.
+ *
+ * @example
+ * ```ts
+ * const editor = createAIComposer({
+ *   placeholder: 'Ask anything…',
+ *   plugins: [mentionPlugin({ trigger: '@', items })],
+ * });
+ * ```
+ */
+export function createAIComposer(options: AIComposerOptions = {}): AIComposer {
+  return new AIComposerImpl(options);
+}
+
+export const CORE_VERSION = '0.1.0';

package/src/history/history.ts

@@ -0,0 +1,108 @@
+/**
+ * Undo/redo — snapshot-based history (ADR-0003). Composer documents are small,
+ * so storing immutable document references beats operational transforms in
+ * simplicity and debuggability. Rapid consecutive user edits (typing) within
+ * `mergeWindowMs` collapse into a single undo step.
+ */
+
+import type { AIComposerDocument } from '../model/document';
+import type { SelectionState } from '../model/selection';
+
+export interface HistorySnapshot {
+  document: AIComposerDocument;
+  selection: SelectionState;
+}
+
+interface HistoryEntry extends HistorySnapshot {
+  label: string;
+  timestamp: number;
+}
+
+export interface HistoryOptions {
+  /** Max undo steps kept (default 200). */
+  limit?: number;
+  /** Window in ms within which same-label user edits merge (default 500). */
+  mergeWindowMs?: number;
+}
+
+export const DEFAULT_HISTORY_OPTIONS: Required<HistoryOptions> = {
+  limit: 200,
+  mergeWindowMs: 500,
+};
+
+export interface RecordOptions {
+  /** Change label — merges only happen between identical labels. */
+  label?: string;
+  /** Only same-label merges; requires the caller to opt in (user typing). */
+  merge?: boolean;
+}
+
+export class EditorHistory {
+  private options: Required<HistoryOptions>;
+  /** States we can go back TO. */
+  private undoStack: HistoryEntry[] = [];
+  /** States we can go forward TO. */
+  private redoStack: HistoryEntry[] = [];
+
+  constructor(options: HistoryOptions = {}) {
+    this.options = { ...DEFAULT_HISTORY_OPTIONS, ...options };
+  }
+
+  get canUndo(): boolean {
+    return this.undoStack.length > 0;
+  }
+
+  get canRedo(): boolean {
+    return this.redoStack.length > 0;
+  }
+
+  /**
+   * Record a change. `previous` is the state BEFORE the change; documents are
+   * immutable so no cloning is needed.
+   */
+  record(previous: HistorySnapshot, options: RecordOptions = {}): void {
+    const label = options.label ?? 'edit';
+    this.redoStack = [];
+
+    const top = this.undoStack[this.undoStack.length - 1];
+    const shouldMerge =
+      options.merge === true &&
+      top !== undefined &&
+      top.label === label &&
+      Date.now() - top.timestamp <= this.options.mergeWindowMs;
+
+    if (!shouldMerge) {
+      this.undoStack.push({ ...previous, label, timestamp: Date.now() });
+      if (this.undoStack.length > this.options.limit) this.undoStack.shift();
+    }
+  }
+
+  /** Return the state to restore, or null when nothing to undo. */
+  undo(current: HistorySnapshot): HistorySnapshot | null {
+    const entry = this.undoStack.pop();
+    if (!entry) return null;
+    this.redoStack.push({ ...current, label: entry.label, timestamp: Date.now() });
+    return { document: entry.document, selection: entry.selection };
+  }
+
+  /** Return the state to restore, or null when nothing to redo. */
+  redo(current: HistorySnapshot): HistorySnapshot | null {
+    const entry = this.redoStack.pop();
+    if (!entry) return null;
+    this.undoStack.push({ ...current, label: entry.label, timestamp: Date.now() });
+    return { document: entry.document, selection: entry.selection };
+  }
+
+  setOptions(options: HistoryOptions): void {
+    this.options = { ...this.options, ...options };
+  }
+
+  getOptions(): Required<HistoryOptions> {
+    return { ...this.options };
+  }
+
+  reset(): void {
+    this.undoStack = [];
+    this.redoStack = [];
+  }
+}

package/src/index.ts

@@ -0,0 +1,201 @@
+/**
+ * @ai-composer/core — the framework-independent AI composer engine.
+ *
+ * Layers:
+ *   model/         document, nodes, selection (pure data + edit primitives)
+ *   state/         observable editor state
+ *   events/        typed event bus + editor event map
+ *   commands/      command registry + built-ins
+ *   triggers/      trigger registry + suggestion engine
+ *   history/       snapshot undo/redo with merge window
+ *   plugins/       plugin contract + registry
+ *   serialization/ json / text / markdown / html / ai serializers
+ */
+
+// model
+export type { AIComposerDocument } from './model/document';
+export {
+  coerceDocument,
+  createDocument,
+  deleteDocumentRange,
+  documentLength,
+  documentsEqual,
+  findNode,
+  findNodeIndex,
+  getNodesOfType,
+  insertNodesAt,
+  isEmptyDocument,
+  nodeLength,
+  normalizeNodes,
+  sanitizeDocument,
+} from './model/document';
+export type {
+  AttachmentNode,
+  AtomicNode,
+  BaseNode,
+  CommandNode,
+  CustomNode,
+  MentionNode,
+  NodeKey,
+  AIComposerNode,
+  AIComposerNodeType,
+  TextNode,
+  VariableNode,
+} from './model/nodes';
+export {
+  createAttachmentNode,
+  createCommandNode,
+  createCustomNode,
+  createMentionNode,
+  createNodeKey,
+  createTextNode,
+  createVariableNode,
+  ensureNodeKey,
+  getNodeType,
+  isAtomicNode,
+  isAIComposerNode,
+  isTextNode,
+} from './model/nodes';
+export type { DocumentRange, Position, SelectionState } from './model/selection';
+export {
+  clampPosition,
+  clampSelection,
+  comparePositions,
+  createPosition,
+  createSelection,
+  equalsPosition,
+  equalsSelection,
+  fromGlobalOffset,
+  getEnd,
+  getRange,
+  getStart,
+  globalRange,
+  isCollapsed,
+  toGlobalOffset,
+} from './model/selection';
+
+// state
+export type { AIComposerState, SuggestionItem, TriggerState } from './state/state';
+
+// events
+export type {
+  AttachmentEvent,
+  BeforeSubmitEvent,
+  ChangeEvent,
+  ChangeSource,
+  CommandExecuteEvent,
+  DestroyEvent,
+  ErrorEvent,
+  FocusChangeEvent,
+  ModeChangeEvent,
+  NodeInsertEvent,
+  NodeRemoveEvent,
+  AIComposerBus,
+  AIComposerEventMap,
+  AIComposerEventType,
+  SelectionChangeEvent,
+  SubmitEvent,
+  SuggestionsChangeEvent,
+  TriggerCloseEvent,
+  TriggerCloseReason,
+  TriggerOpenEvent,
+} from './events/events';
+export type {
+  EventBus,
+  EventHandler,
+  EventMapBase,
+  Unsubscribe,
+} from './events/event-bus';
+export { createEventBus } from './events/event-bus';
+
+// commands
+export type { CommandContext, CommandRegistry, AIComposerCommand } from './commands/registry';
+export { createCommandRegistry } from './commands/registry';
+export {
+  BUILTIN_COMMANDS,
+  createBuiltinCommands,
+  type AcceptSuggestionPayload,
+  type InsertNodePayload,
+  type InsertTextPayload,
+  type OpenTriggerPayload,
+  type RemoveNodePayload,
+} from './commands/builtins';
+
+// triggers
+export type {
+  AIComposerTrigger,
+  TriggerHost,
+  TriggerRegistry,
+  TriggerSearchContext,
+  TriggerSelectContext,
+} from './triggers/engine';
+export {
+  TriggerEngine,
+  createNodeFromSuggestion,
+  createTriggerRegistry,
+  defineTrigger,
+} from './triggers/engine';
+
+// history
+export type { HistoryOptions, HistorySnapshot, RecordOptions } from './history/history';
+export { DEFAULT_HISTORY_OPTIONS, EditorHistory } from './history/history';
+
+// plugins
+export type { PluginContext, AIComposerPlugin, PluginRegistry } from './plugins/registry';
+export { createPluginRegistry } from './plugins/registry';
+
+// serialization
+export type {
+  AIComposerPayload,
+  SerializationFormat,
+  Serializer,
+  SerializerContext,
+  SerializerRegistry,
+} from './serialization';
+export {
+  createAiSerializer,
+  createDefaultSerializers,
+  createHtmlSerializer,
+  createJsonSerializer,
+  createMarkdownSerializer,
+  createSerializerRegistry,
+  createTextSerializer,
+  documentToText,
+  nodeToText,
+} from './serialization';
+
+// node registry
+export type { NodeDefinition, NodeRegistry } from './nodes/registry';
+export {
+  ATTACHMENT_NODE_DEFINITION,
+  COMMAND_NODE_DEFINITION,
+  CUSTOM_NODE_DEFINITION,
+  MENTION_NODE_DEFINITION,
+  TEXT_NODE_DEFINITION,
+  VARIABLE_NODE_DEFINITION,
+  createDefaultNodeRegistry,
+  createNodeRegistry,
+} from './nodes/registry';
+
+// editor + factory + config
+export type {
+  AIComposer,
+  EditorView,
+  InsertNodeOptions,
+  SetValueOptions,
+  StateListener,
+  TransactionOptions,
+} from './editor';
+export { AIComposerImpl, isAIComposer } from './editor';
+export { createAIComposer, CORE_VERSION } from './factory';
+export type {
+  AIComposerConfig,
+  AIComposerOptions,
+  SubmitConfig,
+  SubmitKey,
+} from './types';
+
+// errors
+export { ErrorCode, AIComposerError, toError, type AIComposerErrorCode } from './errors';
+
+export { escapeHtml } from './utils/html';