@ai-composer/core 0.1.0

package/src/nodes/registry.ts

@@ -0,0 +1,142 @@
+/**
+ * Node type registry. Core registers the built-in node types; plugins can add
+ * custom ones or override serialization for built-ins (ADR-0004).
+ */
+
+import type { Unsubscribe } from '../events/event-bus';
+import { escapeHtml } from '../utils/html';
+import type {
+  AttachmentNode,
+  CommandNode,
+  CustomNode,
+  MentionNode,
+  AIComposerNode,
+  TextNode,
+  VariableNode,
+} from '../model/nodes';
+
+export interface NodeDefinition {
+  /** Node type identifier, e.g. 'mention'. `custom` nodes also carry `nodeType`. */
+  type: string;
+  /** Owning plugin id (informational, for custom nodes). */
+  plugin?: string;
+  /** Atomic nodes are indivisible units with model length 1. */
+  isAtomic: boolean;
+  /** Plain-text projection used by the `text` serializer and a11y announcements. */
+  toText?(node: AIComposerNode): string;
+  /** Markdown projection. */
+  toMarkdown?(node: AIComposerNode): string;
+  /** Safe HTML projection — must escape user content (used for copy/export, never for trusting input). */
+  toHtml?(node: AIComposerNode): string;
+  /** Short chip label for DOM rendering. */
+  toDisplay?(node: AIComposerNode): string;
+}
+
+export interface NodeRegistry {
+  register(definition: NodeDefinition): Unsubscribe;
+  get(type: string): NodeDefinition | undefined;
+  has(type: string): boolean;
+  list(): NodeDefinition[];
+  clear(): void;
+}
+
+export function createNodeRegistry(): NodeRegistry {
+  const definitions = new Map<string, NodeDefinition>();
+  return {
+    register(definition) {
+      definitions.set(definition.type, definition);
+      return () => {
+        if (definitions.get(definition.type) === definition) definitions.delete(definition.type);
+      };
+    },
+    get(type) {
+      return definitions.get(type);
+    },
+    has(type) {
+      return definitions.has(type);
+    },
+    list() {
+      return [...definitions.values()];
+    },
+    clear() {
+      definitions.clear();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Built-in definitions
+// ---------------------------------------------------------------------------
+
+const as = <T extends AIComposerNode>(node: AIComposerNode): T => node as T;
+
+export const TEXT_NODE_DEFINITION: NodeDefinition = {
+  type: 'text',
+  isAtomic: false,
+  toText: (node) => as<TextNode>(node).text,
+  toMarkdown: (node) => as<TextNode>(node).text,
+  toHtml: (node) => escapeHtml(as<TextNode>(node).text).replace(/\n/g, '<br>'),
+  toDisplay: (node) => as<TextNode>(node).text,
+};
+
+export const MENTION_NODE_DEFINITION: NodeDefinition = {
+  type: 'mention',
+  isAtomic: true,
+  toText: (node) => `@${as<MentionNode>(node).label}`,
+  toMarkdown: (node) => `[@${as<MentionNode>(node).label}](mention:${as<MentionNode>(node).id})`,
+  toHtml: (node) =>
+    `<span data-aic-node="mention" data-aic-id="${escapeHtml(as<MentionNode>(node).id)}">@${escapeHtml(as<MentionNode>(node).label)}</span>`,
+  toDisplay: (node) => `@${as<MentionNode>(node).label}`,
+};
+
+export const COMMAND_NODE_DEFINITION: NodeDefinition = {
+  type: 'command',
+  isAtomic: true,
+  toText: (node) => `/${as<CommandNode>(node).label}`,
+  toMarkdown: (node) => `[/${as<CommandNode>(node).label}](command:${as<CommandNode>(node).id})`,
+  toHtml: (node) =>
+    `<span data-aic-node="command" data-aic-id="${escapeHtml(as<CommandNode>(node).id)}">/${escapeHtml(as<CommandNode>(node).label)}</span>`,
+  toDisplay: (node) => `/${as<CommandNode>(node).label}`,
+};
+
+export const VARIABLE_NODE_DEFINITION: NodeDefinition = {
+  type: 'variable',
+  isAtomic: true,
+  toText: (node) => `{{${as<VariableNode>(node).name}}}`,
+  toMarkdown: (node) => `{{${as<VariableNode>(node).name}}}`,
+  toHtml: (node) =>
+    `<span data-aic-node="variable" data-aic-name="${escapeHtml(as<VariableNode>(node).name)}">{{${escapeHtml(as<VariableNode>(node).name)}}}</span>`,
+  toDisplay: (node) => `{{${as<VariableNode>(node).name}}}`,
+};
+
+export const ATTACHMENT_NODE_DEFINITION: NodeDefinition = {
+  type: 'attachment',
+  isAtomic: true,
+  toText: (node) => as<AttachmentNode>(node).name,
+  toMarkdown: (node) => `[${as<AttachmentNode>(node).name}](attachment:${as<AttachmentNode>(node).id})`,
+  toHtml: (node) =>
+    `<span data-aic-node="attachment" data-aic-id="${escapeHtml(as<AttachmentNode>(node).id)}" data-aic-mime="${escapeHtml(as<AttachmentNode>(node).mimeType)}">${escapeHtml(as<AttachmentNode>(node).name)}</span>`,
+  toDisplay: (node) => as<AttachmentNode>(node).name,
+};
+
+export const CUSTOM_NODE_DEFINITION: NodeDefinition = {
+  type: 'custom',
+  isAtomic: true,
+  toText: (node) => JSON.stringify(as<CustomNode>(node).data),
+  toMarkdown: (node) => escapeHtml(JSON.stringify(as<CustomNode>(node).data)),
+  toHtml: (node) =>
+    `<span data-aic-node="custom" data-aic-plugin="${escapeHtml(as<CustomNode>(node).plugin)}" data-aic-type="${escapeHtml(as<CustomNode>(node).nodeType)}" data-aic-data="${escapeHtml(JSON.stringify(as<CustomNode>(node).data))}">${escapeHtml(String(as<CustomNode>(node).data ?? ''))}</span>`,
+  toDisplay: (node) => String(as<CustomNode>(node).data ?? ''),
+};
+
+/** Registry pre-loaded with all built-in node types. */
+export function createDefaultNodeRegistry(): NodeRegistry {
+  const registry = createNodeRegistry();
+  registry.register(TEXT_NODE_DEFINITION);
+  registry.register(MENTION_NODE_DEFINITION);
+  registry.register(COMMAND_NODE_DEFINITION);
+  registry.register(VARIABLE_NODE_DEFINITION);
+  registry.register(ATTACHMENT_NODE_DEFINITION);
+  registry.register(CUSTOM_NODE_DEFINITION);
+  return registry;
+}

package/src/plugins/registry.ts

@@ -0,0 +1,163 @@
+/**
+ * Plugin architecture (ADR-0004). Plugins are plain objects with declarative
+ * contributions plus an optional `setup()` for imperative wiring. They receive
+ * a scoped context — never raw editor internals.
+ */
+
+import type { Unsubscribe, EventBus } from '../events/event-bus';
+import type { AIComposerEventMap } from '../events/events';
+import type { AIComposerCommand } from '../commands/registry';
+import type { AIComposerTrigger } from '../triggers/engine';
+import type { NodeDefinition } from '../nodes/registry';
+import type { Serializer } from '../serialization/serializers';
+import type { CommandRegistry } from '../commands/registry';
+import type { TriggerRegistry } from '../triggers/engine';
+import type { NodeRegistry } from '../nodes/registry';
+import type { SerializerRegistry } from '../serialization/registry';
+import type { AIComposer } from '../editor';
+import type { AIComposerConfig } from '../types';
+
+/** Controlled capabilities exposed to plugins. */
+export interface PluginContext {
+  editor: AIComposer;
+  getConfig(): AIComposerConfig;
+  commands: CommandRegistry;
+  triggers: TriggerRegistry;
+  nodes: NodeRegistry;
+  serializers: SerializerRegistry;
+  /** Subscribe to editor events (emit is intentionally not handed out). */
+  events: Pick<EventBus<AIComposerEventMap>, 'on' | 'once' | 'off'>;
+  /** Register cleanup run when the plugin is destroyed. */
+  onCleanup(cleanup: () => void): void;
+}
+
+export interface AIComposerPlugin {
+  /** Unique plugin name. */
+  name: string;
+  version?: string;
+  /** Imperative wiring — called once when the plugin is attached. */
+  setup?(context: PluginContext): void;
+  commands?: AIComposerCommand[];
+  triggers?: AIComposerTrigger[];
+  nodeTypes?: NodeDefinition[];
+  serializers?: Serializer[];
+  /** Called when the plugin is removed or the editor destroyed. */
+  destroy?(): void;
+}
+
+interface InstalledPlugin {
+  plugin: AIComposerPlugin;
+  disposers: Array<() => void>;
+}
+
+export interface PluginRegistry {
+  add(plugin: AIComposerPlugin): Unsubscribe;
+  get(name: string): AIComposerPlugin | undefined;
+  list(): AIComposerPlugin[];
+  /** Set up a plugin immediately with the given context (used by the factory). */
+  install(plugin: AIComposerPlugin, context: PluginContext): Unsubscribe;
+  destroyAll(): void;
+}
+
+export function createPluginRegistry(): PluginRegistry {
+  const installed: InstalledPlugin[] = [];
+
+  const teardown = (entry: InstalledPlugin): void => {
+    for (const dispose of entry.disposers.splice(0)) {
+      try {
+        dispose();
+      } catch (error) {
+        console.error(`[ai-composer] plugin "${entry.plugin.name}" cleanup failed`, error);
+      }
+    }
+    try {
+      entry.plugin.destroy?.();
+    } catch (error) {
+      console.error(`[ai-composer] plugin "${entry.plugin.name}" destroy failed`, error);
+    }
+  };
+
+  const registry: PluginRegistry = {
+    add(plugin) {
+      const entry: InstalledPlugin = { plugin, disposers: [] };
+      installed.push(entry);
+      return () => {
+        const index = installed.indexOf(entry);
+        if (index >= 0) {
+          installed.splice(index, 1);
+          teardown(entry);
+        }
+      };
+    },
+
+    get(name) {
+      return installed.find((entry) => entry.plugin.name === name)?.plugin;
+    },
+
+    list() {
+      return installed.map((entry) => entry.plugin);
+    },
+
+    install(plugin, context) {
+      const entry: InstalledPlugin = { plugin, disposers: [] };
+      installed.push(entry);
+
+      const scoped: PluginContext = {
+        ...context,
+        onCleanup: (cleanup: () => void) => {
+          entry.disposers.push(cleanup);
+        },
+        events: {
+          on: (type, handler) => {
+            const off = context.events.on(type, handler);
+            entry.disposers.push(off);
+            return off;
+          },
+          once: (type, handler) => {
+            const off = context.events.once(type, handler);
+            entry.disposers.push(off);
+            return off;
+          },
+          off: (type, handler) => context.events.off(type, handler),
+        },
+      };
+
+      for (const command of plugin.commands ?? []) {
+        entry.disposers.push(context.commands.register(command));
+      }
+      for (const trigger of plugin.triggers ?? []) {
+        entry.disposers.push(context.triggers.register(trigger));
+      }
+      for (const nodeType of plugin.nodeTypes ?? []) {
+        entry.disposers.push(context.nodes.register(nodeType));
+      }
+      for (const serializer of plugin.serializers ?? []) {
+        entry.disposers.push(context.serializers.register(serializer));
+      }
+
+      try {
+        plugin.setup?.(scoped);
+      } catch (error) {
+        // roll this plugin back; the editor stays alive
+        const index = installed.indexOf(entry);
+        if (index >= 0) installed.splice(index, 1);
+        teardown(entry);
+        throw error;
+      }
+
+      return () => {
+        const index = installed.indexOf(entry);
+        if (index >= 0) {
+          installed.splice(index, 1);
+          teardown(entry);
+        }
+      };
+    },
+
+    destroyAll() {
+      for (const entry of installed.splice(0)) teardown(entry);
+    },
+  };
+
+  return registry;
+}

package/src/serialization/builtins.ts

@@ -0,0 +1,123 @@
+/**
+ * Built-in serializers. Every projection goes through the node registry so
+ * plugins control how their custom nodes serialize.
+ */
+
+import { escapeHtml } from '../utils/html';
+import type { AIComposerDocument } from '../model/document';
+import type { AIComposerNode } from '../model/nodes';
+import type { NodeDefinition } from '../nodes/registry';
+import type { Serializer, SerializerContext } from './serializers';
+
+/** Structured payload handed to AI providers — provider-neutral by design (see docs). */
+export interface AIComposerPayload {
+  text: string;
+  entities: Array<{
+    type: string;
+    key: string;
+    id?: string;
+    label?: string;
+    name?: string;
+    data?: unknown;
+  }>;
+  metadata?: Record<string, unknown>;
+}
+
+function definitionOf(context: SerializerContext, node: AIComposerNode): NodeDefinition | undefined {
+  return context.nodes.get(node.type);
+}
+
+/** Plain-text projection of a single node. */
+export function nodeToText(node: AIComposerNode, context: SerializerContext): string {
+  const def = definitionOf(context, node);
+  if (def?.toText) return def.toText(node);
+  if (node.type === 'text') return node.text;
+  return '';
+}
+
+export function documentToText(document: AIComposerDocument, context: SerializerContext): string {
+  return document.nodes.map((node) => nodeToText(node, context)).join('');
+}
+
+function nodeToMarkdown(node: AIComposerNode, context: SerializerContext): string {
+  const def = definitionOf(context, node);
+  if (def?.toMarkdown) return def.toMarkdown(node);
+  return nodeToText(node, context);
+}
+
+function nodeToHtml(node: AIComposerNode, context: SerializerContext): string {
+  const def = definitionOf(context, node);
+  if (def?.toHtml) return def.toHtml(node);
+  return escapeHtml(nodeToText(node, context));
+}
+
+export function createJsonSerializer(): Serializer {
+  return {
+    format: 'json',
+    serialize(document) {
+      // Round-trip safe: plain JSON structures only.
+      return JSON.parse(JSON.stringify(document)) as AIComposerDocument;
+    },
+  };
+}
+
+export function createTextSerializer(): Serializer {
+  return {
+    format: 'text',
+    serialize(document, context) {
+      return documentToText(document, context);
+    },
+  };
+}
+
+export function createMarkdownSerializer(): Serializer {
+  return {
+    format: 'markdown',
+    serialize(document, context) {
+      return document.nodes.map((node) => nodeToMarkdown(node, context)).join('');
+    },
+  };
+}
+
+export function createHtmlSerializer(): Serializer {
+  return {
+    format: 'html',
+    serialize(document, context) {
+      const body = document.nodes.map((node) => nodeToHtml(node, context)).join('');
+      return `<div data-aic-document>${body}</div>`;
+    },
+  };
+}
+
+export function createAiSerializer(): Serializer {
+  return {
+    format: 'ai',
+    serialize(document, context): AIComposerPayload {
+      return {
+        text: documentToText(document, context),
+        entities: document.nodes
+          .filter((node) => node.type !== 'text')
+          .map((node) => {
+            const base: AIComposerPayload['entities'][number] = { type: node.type, key: node.key };
+            const record = node as unknown as Record<string, unknown>;
+            if (typeof record.id === 'string') base.id = record.id;
+            if (typeof record.label === 'string') base.label = record.label;
+            if (typeof record.name === 'string') base.name = record.name;
+            if (node.type === 'custom') base.data = record.data;
+            return base;
+          }),
+        ...(document.metadata ? { metadata: document.metadata } : {}),
+      };
+    },
+  };
+}
+
+export function createDefaultSerializers(): Serializer[] {
+  return [
+    createJsonSerializer(),
+    createTextSerializer(),
+    createMarkdownSerializer(),
+    createHtmlSerializer(),
+    createAiSerializer(),
+  ];
+}

package/src/serialization/index.ts

@@ -0,0 +1,20 @@
+export type {
+  SerializationFormat,
+  Serializer,
+  SerializerContext,
+} from './serializers';
+export {
+  createSerializerRegistry,
+  type SerializerRegistry,
+} from './registry';
+export {
+  createAiSerializer,
+  createDefaultSerializers,
+  createHtmlSerializer,
+  createJsonSerializer,
+  createMarkdownSerializer,
+  createTextSerializer,
+  documentToText,
+  nodeToText,
+  type AIComposerPayload,
+} from './builtins';

package/src/serialization/registry.ts

@@ -0,0 +1,49 @@
+/**
+ * Serializer registry (ADR-0006). Built-in formats: json, text, markdown,
+ * html, ai. Plugins can add formats or override built-ins by re-registering
+ * the same format id (last registration wins).
+ */
+
+import type { Unsubscribe } from '../events/event-bus';
+import { AIComposerError } from '../errors';
+import type { AIComposerDocument } from '../model/document';
+import type { SerializationFormat, Serializer, SerializerContext } from './serializers';
+
+export interface SerializerRegistry {
+  register(serializer: Serializer): Unsubscribe;
+  get(format: SerializationFormat): Serializer | undefined;
+  formats(): SerializationFormat[];
+  serialize(format: SerializationFormat, document: AIComposerDocument, context: SerializerContext): unknown;
+  clear(): void;
+}
+
+export function createSerializerRegistry(): SerializerRegistry {
+  const serializers = new Map<SerializationFormat, Serializer>();
+  return {
+    register(serializer) {
+      serializers.set(serializer.format, serializer);
+      return () => {
+        if (serializers.get(serializer.format) === serializer) serializers.delete(serializer.format);
+      };
+    },
+    get(format) {
+      return serializers.get(format);
+    },
+    formats() {
+      return [...serializers.keys()];
+    },
+    serialize(format, document, context) {
+      const serializer = serializers.get(format);
+      if (!serializer) {
+        throw new AIComposerError(
+          'UNKNOWN_FORMAT',
+          `No serializer registered for "${format}". Registered: ${[...serializers.keys()].join(', ') || 'none'}`,
+        );
+      }
+      return serializer.serialize(document, context);
+    },
+    clear() {
+      serializers.clear();
+    },
+  };
+}

package/src/serialization/serializers.ts

@@ -0,0 +1,15 @@
+/** Serializer contracts. Built-in implementations live in ./builtins.ts. */
+
+import type { AIComposerDocument } from '../model/document';
+import type { NodeRegistry } from '../nodes/registry';
+
+export type SerializationFormat = 'json' | 'text' | 'markdown' | 'html' | 'ai';
+
+export interface SerializerContext {
+  nodes: NodeRegistry;
+}
+
+export interface Serializer {
+  format: SerializationFormat;
+  serialize(document: AIComposerDocument, context: SerializerContext): unknown;
+}

package/src/state/state.ts

@@ -0,0 +1,57 @@
+/**
+ * Observable, framework-neutral editor state. Adapters expose it as
+ * React hooks state, Angular signals, Vue refs, Svelte stores — core stays UI-free.
+ */
+
+import type { AIComposerDocument } from '../model/document';
+import type { AttachmentNode } from '../model/nodes';
+import type { SelectionState } from '../model/selection';
+
+/** One entry of a trigger's suggestion list. */
+export interface SuggestionItem {
+  id: string;
+  label: string;
+  description?: string;
+  /** Optional grouping heading in the suggestion UI. */
+  group?: string;
+  /** Icon name/URL — rendering is up to the UI layer. */
+  icon?: string;
+  /** Plugin-specific payload handed back on select. */
+  data?: Record<string, unknown>;
+}
+
+/** Live trigger session, e.g. while the user types "@jo". */
+export interface TriggerState {
+  triggerId: string;
+  /** Text typed after the trigger character. */
+  query: string;
+  /** Index of the text node containing the trigger run. */
+  nodeIndex: number;
+  /** Offset of the trigger character within that text node. */
+  triggerOffset: number;
+  /** Offset where the query ends (the caret at scan time). */
+  endOffset: number;
+}
+
+export interface AIComposerState {
+  /** Current document value. */
+  value: AIComposerDocument;
+  focused: boolean;
+  disabled: boolean;
+  readonly: boolean;
+  /** True while an async submit handler is running. */
+  submitting: boolean;
+  selection: SelectionState;
+  activeTrigger: TriggerState | null;
+  suggestions: SuggestionItem[];
+  /** Highlighted suggestion (-1 when none). */
+  activeSuggestionIndex: number;
+  /** Convenience view of attachment nodes inside the document. */
+  attachments: AttachmentNode[];
+  canUndo: boolean;
+  canRedo: boolean;
+  /** Active presentation mode / preset name (e.g. 'chat'). */
+  mode: string;
+  placeholder: string;
+  empty: boolean;
+}