@ai-composer/core 0.1.0

package/src/model/document.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'vitest';
+import { createMentionNode, createTextNode } from './nodes';
+import {
+  createDocument,
+  documentLength,
+  deleteDocumentRange,
+  documentsEqual,
+  findNodeIndex,
+  insertNodesAt,
+  isEmptyDocument,
+  nodeLength,
+  normalizeNodes,
+} from './document';
+import { createPosition, createSelection, fromGlobalOffset, toGlobalOffset } from './selection';
+
+describe('document model', () => {
+  it('creates an empty document', () => {
+    const doc = createDocument();
+    expect(doc.nodes).toEqual([]);
+    expect(isEmptyDocument(doc)).toBe(true);
+    expect(documentLength(doc)).toBe(0);
+  });
+
+  it('coerces metadata and keeps node order', () => {
+    const doc = createDocument([createTextNode('hi'), createMentionNode({ id: 'u1', label: 'Ada' })], {
+      sessionId: 's1',
+    });
+    expect(doc.metadata).toEqual({ sessionId: 's1' });
+    expect(doc.nodes.map((n) => n.type)).toEqual(['text', 'mention']);
+  });
+
+  it('measures node length (atomic nodes are length 1)', () => {
+    expect(nodeLength(createTextNode('hello'))).toBe(5);
+    expect(nodeLength(createMentionNode({ id: 'u1', label: 'Ada Lovelace' }))).toBe(1);
+  });
+
+  it('merges adjacent text nodes and drops empty ones', () => {
+    const merged = normalizeNodes([
+      createTextNode('ab'),
+      createTextNode(''),
+      createTextNode('cd'),
+      createMentionNode({ id: 'u1', label: 'Ada' }),
+      createTextNode('ef'),
+    ]);
+    expect(merged).toHaveLength(3);
+    expect(merged[0]).toMatchObject({ type: 'text', text: 'abcd' });
+  });
+
+  it('round-trips global offsets', () => {
+    const doc = createDocument([
+      createTextNode('ab'),
+      createMentionNode({ id: 'u1', label: 'Ada' }),
+      createTextNode('cd'),
+    ]);
+    // 0:a 1:b 2:|chip| 3:c 4:d
+    expect(toGlobalOffset(doc, createPosition(0, 2))).toBe(2);
+    expect(toGlobalOffset(doc, createPosition(1, 1))).toBe(3);
+    expect(toGlobalOffset(doc, createPosition(2, 0))).toBe(3);
+    expect(fromGlobalOffset(doc, 3)).toEqual(createPosition(2, 0));
+    expect(fromGlobalOffset(doc, 5)).toEqual(createPosition(2, 2));
+  });
+
+  it('deletes a range spanning nodes and reports the caret', () => {
+    const doc = createDocument([
+      createTextNode('hello '),
+      createMentionNode({ id: 'u1', label: 'Ada' }),
+      createTextNode(' world'),
+    ]);
+    // (0,5)=global 5 ("hello|"), (2,1)=global 8 (inside " world" after its space)
+    const result = deleteDocumentRange(doc, {
+      start: createPosition(0, 5),
+      end: createPosition(2, 1),
+    });
+    // chip + the leading space of " world" are gone; text runs merge
+    expect(result.document.nodes.map((n) => (n.type === 'text' ? n.text : n.type))).toEqual([
+      'helloworld',
+    ]);
+    // caret sits where the deleted range began (global offset 5)
+    expect(toGlobalOffset(result.document, result.caret)).toBe(5);
+  });
+
+  it('deletes an atomic node fully when the range covers it', () => {
+    const doc = createDocument([
+      createTextNode('a'),
+      createMentionNode({ id: 'u1', label: 'Ada' }),
+      createTextNode('b'),
+    ]);
+    const result = deleteDocumentRange(doc, {
+      start: createPosition(1, 0),
+      end: createPosition(1, 1),
+    });
+    // adjacent text runs merge once the chip between them disappears
+    expect(result.document.nodes.map((n) => (n.type === 'text' ? n.text : n.type))).toEqual(['ab']);
+  });
+
+  it('inserts nodes at a position, splitting text nodes', () => {
+    const doc = createDocument([createTextNode('hello')]);
+    const mention = createMentionNode({ id: 'u1', label: 'Ada' });
+    const result = insertNodesAt(doc, createPosition(0, 2), [mention]);
+    expect(result.document.nodes).toHaveLength(3);
+    expect(result.document.nodes[0]).toMatchObject({ type: 'text', text: 'he' });
+    expect(result.document.nodes[1]).toBe(mention);
+    expect(toGlobalOffset(result.document, result.caret)).toBe(3);
+  });
+
+  it('finds nodes by key', () => {
+    const mention = createMentionNode({ id: 'u1', label: 'Ada' });
+    const doc = createDocument([createTextNode('hi '), mention]);
+    expect(findNodeIndex(doc, mention.key)).toBe(1);
+    expect(findNodeIndex(doc, 'missing')).toBe(-1);
+  });
+
+  it('compares documents structurally (keys matter)', () => {
+    const text = createTextNode('x');
+    const a = createDocument([text]);
+    // same node instances → equal
+    expect(documentsEqual(a, createDocument([text]))).toBe(true);
+    expect(documentsEqual(a, a)).toBe(true);
+    // different keys, same text → not equal (node identity is part of the value)
+    expect(documentsEqual(a, createDocument([createTextNode('x')]))).toBe(false);
+    expect(documentsEqual(a, createDocument([createTextNode('y')]))).toBe(false);
+  });
+
+  it('keeps selection usable on empty documents', () => {
+    const doc = createDocument();
+    expect(fromGlobalOffset(doc, 0)).toEqual(createPosition(0, 0));
+    expect(toGlobalOffset(doc, createPosition(0, 0))).toBe(0);
+    expect(createSelection(createPosition(0, 0)).anchor).toEqual(createPosition(0, 0));
+  });
+});

package/src/model/document.ts

@@ -0,0 +1,207 @@
+/**
+ * Composer document — the authoritative, framework-neutral value of an editor
+ * (model-first architecture, ADR-0001). Documents are treated as immutable:
+ * edit helpers return new documents and never mutate node objects.
+ */
+
+import {
+  createNodeKey,
+  createTextNode,
+  isAIComposerNode,
+  type AIComposerNode,
+} from './nodes';
+import { fromGlobalOffset, toGlobalOffset, type Position, type DocumentRange } from './selection';
+
+export interface AIComposerDocument {
+  nodes: AIComposerNode[];
+  metadata?: Record<string, unknown>;
+}
+
+export function createDocument(nodes: AIComposerNode[] = [], metadata?: Record<string, unknown>): AIComposerDocument {
+  const document: AIComposerDocument = { nodes: normalizeNodes(nodes) };
+  if (metadata !== undefined) document.metadata = metadata;
+  return document;
+}
+
+/** Coerce common inputs into a document. */
+export function coerceDocument(value: AIComposerDocument | AIComposerNode[] | string | null | undefined): AIComposerDocument {
+  if (value === null || value === undefined) return createDocument([]);
+  if (typeof value === 'string') return createDocument(value ? [createTextNode(value)] : []);
+  if (Array.isArray(value)) return createDocument(value);
+  return createDocument(value.nodes ?? [], value.metadata);
+}
+
+/**
+ * Merge adjacent text nodes and drop empty text runs. Returns a new array;
+ * input nodes are never mutated.
+ */
+export function normalizeNodes(nodes: AIComposerNode[]): AIComposerNode[] {
+  const result: AIComposerNode[] = [];
+  for (const node of nodes) {
+    if (node.type === 'text') {
+      if (node.text === '') continue;
+      const last = result[result.length - 1];
+      if (last && last.type === 'text') {
+        result[result.length - 1] = { ...last, text: last.text + node.text };
+        continue;
+      }
+    }
+    result.push(node);
+  }
+  return result;
+}
+
+export function nodeLength(node: AIComposerNode): number {
+  return node.type === 'text' ? node.text.length : 1;
+}
+
+export function totalLength(nodes: AIComposerNode[]): number {
+  return nodes.reduce((sum, node) => sum + nodeLength(node), 0);
+}
+
+export function documentLength(document: AIComposerDocument): number {
+  return totalLength(document.nodes);
+}
+
+/**
+ * True when there is nothing meaningful to show or submit: no chips and no
+ * text beyond whitespace. ContentEditable hosts keep a layout `<br>` after
+ * the user deletes everything — that artifact must read as empty or the
+ * placeholder never comes back.
+ */
+export function isEmptyDocument(document: AIComposerDocument): boolean {
+  let sawChip = false;
+  let sawText = false;
+  for (const node of document.nodes) {
+    if (node.type !== 'text') sawChip = true;
+    else if (node.text.trim().length > 0) sawText = true;
+  }
+  return !sawChip && !sawText;
+}
+
+export function findNodeIndex(document: AIComposerDocument, key: string): number {
+  return document.nodes.findIndex((node) => node.key === key);
+}
+
+export function findNode(document: AIComposerDocument, key: string): { node: AIComposerNode; index: number } | null {
+  const index = findNodeIndex(document, key);
+  return index >= 0 ? { node: document.nodes[index], index } : null;
+}
+
+export function getNodesOfType<T extends AIComposerNode>(document: AIComposerDocument, type: T['type']): T[] {
+  return document.nodes.filter((node): node is T => node.type === type);
+}
+
+export function cloneDocument(document: AIComposerDocument): AIComposerDocument {
+  return {
+    nodes: document.nodes.map((node) => ({ ...node })),
+    ...(document.metadata ? { metadata: { ...document.metadata } } : {}),
+  };
+}
+
+export function documentsEqual(a: AIComposerDocument, b: AIComposerDocument): boolean {
+  if (a === b) return true;
+  return JSON.stringify(a.nodes) === JSON.stringify(b.nodes);
+}
+
+/**
+ * Replace unknown/unregistered node types with a readable text node so that
+ * documents from external sources (paste, storage, setValue) can never inject
+ * unrenderable nodes.
+ */
+export function sanitizeDocument(
+  document: AIComposerDocument,
+  isKnownType: (type: string) => boolean,
+): AIComposerDocument {
+  const nodes = document.nodes.map((node) => {
+    if (isKnownType(node.type) && isAIComposerNode(node)) return node;
+    if (node.type === 'text' && typeof (node as { text?: unknown }).text === 'string') {
+      return createTextNode((node as { text: string }).text);
+    }
+    return createTextNode(JSON.stringify(node));
+  });
+  return createDocument(nodes, document.metadata);
+}
+
+// ---------------------------------------------------------------------------
+// Edit primitives (pure)
+// ---------------------------------------------------------------------------
+
+/** Delete `range` (inclusive) and report the caret position after deletion. */
+export function deleteDocumentRange(
+  document: AIComposerDocument,
+  range: DocumentRange,
+): { document: AIComposerDocument; caret: Position } {
+  const startOffset = toGlobalOffset(document, range.start);
+  const endOffset = toGlobalOffset(document, range.end);
+  const low = Math.min(startOffset, endOffset);
+  const high = Math.max(startOffset, endOffset);
+
+  const nodes: AIComposerNode[] = [];
+  let cursor = 0;
+  for (const node of document.nodes) {
+    const length = nodeLength(node);
+    const nodeStart = cursor;
+    const nodeEnd = cursor + length;
+
+    if (nodeEnd <= low || nodeStart >= high) {
+      nodes.push(node);
+      cursor = nodeEnd;
+      continue;
+    }
+
+    if (node.type === 'text') {
+      const keepBefore = Math.max(0, low - nodeStart);
+      const keepAfter = Math.max(0, nodeEnd - high);
+      if (keepBefore > 0) nodes.push({ ...node, text: node.text.slice(0, keepBefore) });
+      if (keepAfter > 0) nodes.push(createTextNode(node.text.slice(node.text.length - keepAfter)));
+    }
+    // atomic nodes overlapping the range are removed entirely
+    cursor = nodeEnd;
+  }
+
+  const next: AIComposerDocument = { nodes, ...(document.metadata ? { metadata: document.metadata } : {}) };
+  const normalized: AIComposerDocument = { ...next, nodes: normalizeNodes(next.nodes) };
+  return { document: normalized, caret: fromGlobalOffset(normalized, low) };
+}
+
+/** Insert `inserted` at `position` (splitting a text node when needed). */
+export function insertNodesAt(
+  document: AIComposerDocument,
+  position: Position,
+  inserted: AIComposerNode[],
+): { document: AIComposerDocument; caret: Position } {
+  if (inserted.length === 0) return { document, caret: position };
+
+  const index = Math.min(Math.max(position.nodeIndex, 0), document.nodes.length);
+  const target = document.nodes[index];
+  const result: AIComposerNode[] = [...document.nodes.slice(0, index)];
+
+  if (target && target.type === 'text') {
+    const offset = Math.min(Math.max(position.offset, 0), target.text.length);
+    if (offset === 0) {
+      result.push(...inserted, target);
+    } else if (offset === target.text.length) {
+      result.push(target, ...inserted);
+    } else {
+      result.push(
+        { ...target, text: target.text.slice(0, offset) },
+        ...inserted,
+        createTextNode(target.text.slice(offset), createNodeKey('text')),
+      );
+    }
+  } else if (target) {
+    // atomic target: offset 0 = before the chip, 1 = after it
+    if (position.offset > 0) result.push(target, ...inserted);
+    else result.push(...inserted, target);
+  } else {
+    result.push(...inserted);
+  }
+
+  result.push(...document.nodes.slice(index + 1));
+
+  const next: AIComposerDocument = { nodes: result, ...(document.metadata ? { metadata: document.metadata } : {}) };
+  const normalized: AIComposerDocument = { ...next, nodes: normalizeNodes(next.nodes) };
+  const caretOffset = toGlobalOffset(document, position) + totalLength(inserted);
+  return { document: normalized, caret: fromGlobalOffset(normalized, caretOffset) };
+}

package/src/model/nodes.ts

@@ -0,0 +1,151 @@
+/**
+ * Node model.
+ *
+ * A composer document is a flat list of nodes (see ADR-0002): text runs and
+ * atomic "chip" nodes (mention, command, variable, attachment, custom).
+ *
+ * Every node carries a stable instance `key`. It is NOT the entity id —
+ * {@link MentionNode}.id identifies the mentioned entity, `key` identifies
+ * this particular node instance and stays stable across clones, undo/redo
+ * and DOM round-trips (React keys, DOM↔model mapping).
+ */
+
+/** Stable node instance key. */
+export type NodeKey = string;
+
+export interface BaseNode {
+  key: NodeKey;
+}
+
+export interface TextNode extends BaseNode {
+  type: 'text';
+  text: string;
+}
+
+export interface MentionNode extends BaseNode {
+  type: 'mention';
+  /** Entity id (user, ticket, …) — not the node instance key. */
+  id: string;
+  label: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CommandNode extends BaseNode {
+  type: 'command';
+  id: string;
+  label: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface VariableNode extends BaseNode {
+  type: 'variable';
+  name: string;
+  value?: unknown;
+}
+
+export interface AttachmentNode extends BaseNode {
+  type: 'attachment';
+  id: string;
+  name: string;
+  mimeType: string;
+  size?: number;
+  metadata?: Record<string, unknown>;
+}
+
+/** Application/plugin-defined node. Rendering & serialization come from the owning NodeDefinition. */
+export interface CustomNode extends BaseNode {
+  type: 'custom';
+  plugin: string;
+  nodeType: string;
+  data: unknown;
+}
+
+export type AIComposerNode = TextNode | MentionNode | CommandNode | VariableNode | AttachmentNode | CustomNode;
+
+/** Anything that is not a text run is indivisible (length 1) for edits and selection. */
+export type AtomicNode = Exclude<AIComposerNode, TextNode>;
+
+export type AIComposerNodeType = AIComposerNode['type'];
+
+let sequence = 0;
+
+/** Generate a unique node key, e.g. `mention_lx3a_07_f2k9q1`. */
+export function createNodeKey(prefix = 'n'): NodeKey {
+  sequence += 1;
+  return `${prefix}_${Date.now().toString(36)}_${sequence.toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+
+export function createTextNode(text: string, key: NodeKey = createNodeKey('text')): TextNode {
+  return { type: 'text', key, text };
+}
+
+export function createMentionNode(
+  input: Omit<MentionNode, 'type' | 'key'>,
+  key: NodeKey = createNodeKey('mention'),
+): MentionNode {
+  return { type: 'mention', key, ...input };
+}
+
+export function createCommandNode(
+  input: Omit<CommandNode, 'type' | 'key'>,
+  key: NodeKey = createNodeKey('command'),
+): CommandNode {
+  return { type: 'command', key, ...input };
+}
+
+export function createVariableNode(
+  input: { name: string; value?: unknown },
+  key: NodeKey = createNodeKey('variable'),
+): VariableNode {
+  return { type: 'variable', key, name: input.name, ...(input.value !== undefined ? { value: input.value } : {}) };
+}
+
+export function createAttachmentNode(
+  input: Omit<AttachmentNode, 'type' | 'key'>,
+  key: NodeKey = createNodeKey('attachment'),
+): AttachmentNode {
+  return { type: 'attachment', key, ...input };
+}
+
+export function createCustomNode(
+  input: { plugin: string; nodeType: string; data: unknown },
+  key: NodeKey = createNodeKey(input.nodeType || 'custom'),
+): CustomNode {
+  return { type: 'custom', key, plugin: input.plugin, nodeType: input.nodeType, data: input.data };
+}
+
+/** Assign a key to a hand-built node that lacks one (e.g. from parsed JSON). */
+export function ensureNodeKey<T extends AIComposerNode>(node: T): T {
+  return node.key ? node : { ...node, key: createNodeKey(node.type) };
+}
+
+// ---------------------------------------------------------------------------
+// Guards
+// ---------------------------------------------------------------------------
+
+export function isTextNode(node: AIComposerNode): node is TextNode {
+  return node.type === 'text';
+}
+
+export function isAtomicNode(node: AIComposerNode): node is AtomicNode {
+  return node.type !== 'text';
+}
+
+export function getNodeType(node: AIComposerNode): AIComposerNodeType {
+  return node.type;
+}
+
+/** Lightweight structural validation for documents coming from views / storage. */
+export function isAIComposerNode(value: unknown): value is AIComposerNode {
+  if (typeof value !== 'object' || value === null) return false;
+  const node = value as Partial<AIComposerNode>;
+  return (
+    typeof node.type === 'string' &&
+    typeof node.key === 'string' &&
+    (node.type !== 'text' || typeof (node as Partial<TextNode>).text === 'string')
+  );
+}

package/src/model/selection.ts

@@ -0,0 +1,107 @@
+/**
+ * Selection model — framework-neutral positions against the document model,
+ * never raw DOM Range objects (see ADR-0001).
+ */
+
+import type { AIComposerDocument } from './document';
+import { nodeLength } from './document';
+
+/** Caret or selection endpoint. For atomic nodes offset is 0 (before) or 1 (after). */
+export interface Position {
+  nodeIndex: number;
+  offset: number;
+}
+
+export interface SelectionState {
+  anchor: Position;
+  focus: Position;
+}
+
+export interface DocumentRange {
+  start: Position;
+  end: Position;
+}
+
+export const createPosition = (nodeIndex: number, offset = 0): Position => ({ nodeIndex, offset });
+
+export const createSelection = (
+  anchor: Position = createPosition(0, 0),
+  focus: Position = anchor,
+): SelectionState => ({ anchor, focus });
+
+export function equalsPosition(a: Position, b: Position): boolean {
+  return a.nodeIndex === b.nodeIndex && a.offset === b.offset;
+}
+
+export function equalsSelection(a: SelectionState, b: SelectionState): boolean {
+  return equalsPosition(a.anchor, b.anchor) && equalsPosition(a.focus, b.focus);
+}
+
+/** Total order over positions: by node index, then offset. */
+export function comparePositions(a: Position, b: Position): number {
+  if (a.nodeIndex !== b.nodeIndex) return a.nodeIndex < b.nodeIndex ? -1 : 1;
+  if (a.offset === b.offset) return 0;
+  return a.offset < b.offset ? -1 : 1;
+}
+
+export const isCollapsed = (selection: SelectionState): boolean =>
+  equalsPosition(selection.anchor, selection.focus);
+
+/** Anchor→focus ordering regardless of selection direction. */
+export function getRange(selection: SelectionState): DocumentRange {
+  return comparePositions(selection.anchor, selection.focus) <= 0
+    ? { start: selection.anchor, end: selection.focus }
+    : { start: selection.focus, end: selection.anchor };
+}
+
+export const getStart = (selection: SelectionState): Position => getRange(selection).start;
+export const getEnd = (selection: SelectionState): Position => getRange(selection).end;
+
+/** Convert a model position into a document-wide character offset. */
+export function toGlobalOffset(document: AIComposerDocument, position: Position): number {
+  let offset = 0;
+  for (let i = 0; i < position.nodeIndex && i < document.nodes.length; i += 1) {
+    offset += nodeLength(document.nodes[i]);
+  }
+  const node = document.nodes[position.nodeIndex];
+  if (!node) return offset;
+  if (node.type === 'text') return offset + Math.min(Math.max(position.offset, 0), node.text.length);
+  return offset + (position.offset > 0 ? 1 : 0);
+}
+
+/** Convert a document-wide offset back into a node-relative position. */
+export function fromGlobalOffset(document: AIComposerDocument, globalOffset: number): Position {
+  let remaining = Math.max(0, globalOffset);
+  for (let i = 0; i < document.nodes.length; i += 1) {
+    const length = nodeLength(document.nodes[i]);
+    if (remaining < length || (remaining === length && i === document.nodes.length - 1)) {
+      return createPosition(i, remaining);
+    }
+    remaining -= length;
+  }
+  return createPosition(document.nodes.length, 0);
+}
+
+export function clampPosition(document: AIComposerDocument, position: Position): Position {
+  const maxIndex = document.nodes.length;
+  const nodeIndex = Math.min(Math.max(position.nodeIndex, 0), maxIndex);
+  if (nodeIndex === maxIndex) {
+    // At (or beyond) the end boundary: clamp onto the last node's end.
+    if (maxIndex === 0) return createPosition(0, 0);
+    const last = document.nodes[maxIndex - 1];
+    return createPosition(maxIndex - 1, nodeLength(last));
+  }
+  const node = document.nodes[nodeIndex];
+  if (!node) return createPosition(nodeIndex, 0);
+  const maxOffset = nodeLength(node);
+  return createPosition(nodeIndex, Math.min(Math.max(position.offset, 0), maxOffset));
+}
+
+export function clampSelection(document: AIComposerDocument, selection: SelectionState): SelectionState {
+  return createSelection(clampPosition(document, selection.anchor), clampPosition(document, selection.focus));
+}
+
+export function globalRange(document: AIComposerDocument, selection: SelectionState): { start: number; end: number } {
+  const { start, end } = getRange(selection);
+  return { start: toGlobalOffset(document, start), end: toGlobalOffset(document, end) };
+}