@abraca/orchestrator 2.3.0

package/src/timeline-runner.ts

@@ -0,0 +1,84 @@
+/**
+ * TimelineRunner — schedules and executes timed actions with drift correction.
+ */
+import type { TimelineEntry } from './types.ts'
+import type { ActionExecutor } from './actions/index.ts'
+import { sleep, log } from './utils.ts'
+
+export type ErrorStrategy = 'log' | 'abort'
+
+export interface TimelineRunnerOptions {
+  /** How to handle action errors. 'log' continues, 'abort' stops. Default: 'log'. */
+  onError?: ErrorStrategy
+}
+
+export class TimelineRunner {
+  private sceneStartTime = 0
+  private options: TimelineRunnerOptions
+  readonly errors: { entry: TimelineEntry; error: Error; elapsed: number }[] = []
+
+  constructor(options?: TimelineRunnerOptions) {
+    this.options = options ?? {}
+  }
+
+  /** Get elapsed ms since scene start. */
+  get elapsed(): number {
+    return Date.now() - this.sceneStartTime
+  }
+
+  /** Execute all timeline entries in order with proper timing. */
+  async run(timeline: TimelineEntry[], execute: ActionExecutor): Promise<void> {
+    const sorted = [...timeline].sort((a, b) => (a.at ?? 0) - (b.at ?? 0))
+    const errorStrategy = this.options.onError ?? 'log'
+
+    this.sceneStartTime = Date.now()
+    const pending: Promise<void>[] = []
+
+    for (let i = 0; i < sorted.length; i++) {
+      const entry = sorted[i]!
+      const targetTime = entry.at ?? 0
+      const elapsed = Date.now() - this.sceneStartTime
+      const delay = targetTime - elapsed
+
+      if (delay > 0) {
+        await sleep(delay)
+      }
+
+      // Log progress
+      const ts = `${((Date.now() - this.sceneStartTime) / 1000).toFixed(1)}s`
+      const actorLabel = entry.actor ?? '—'
+      log(`[${ts}] ${actorLabel}: ${entry.action.type}`)
+
+      const actionPromise = execute(entry).catch((err: Error) => {
+        const errorInfo = {
+          entry,
+          error: err,
+          elapsed: Date.now() - this.sceneStartTime,
+        }
+        this.errors.push(errorInfo)
+        log(`Error in ${entry.action.type}${entry.actor ? ` for ${entry.actor}` : ''}: ${err.message}`)
+        if (errorStrategy === 'abort') {
+          throw err
+        }
+      })
+
+      // Check if the next entry has the same timestamp — if so, run in parallel
+      const nextEntry = sorted[i + 1]
+      if (nextEntry && (nextEntry.at ?? 0) === targetTime) {
+        pending.push(actionPromise)
+      } else {
+        pending.push(actionPromise)
+        await Promise.all(pending)
+        pending.length = 0
+      }
+    }
+
+    if (pending.length) {
+      await Promise.all(pending)
+    }
+
+    if (this.errors.length) {
+      log(`Timeline finished with ${this.errors.length} error(s)`)
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,245 @@
+/**
+ * Type definitions for the orchestrator scene format.
+ */
+
+// ── Server & Actor ──────────────────────────────────────────────────────────
+
+export interface ServerConfig {
+  url: string
+  inviteCode?: string
+}
+
+export interface ActorDef {
+  name: string
+  color: string
+  keyFile?: string
+  avatar?: string
+}
+
+// ── Easing ──────────────────────────────────────────────────────────────────
+
+export type EasingFn = (t: number) => number
+export type EasingName = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut'
+
+// ── Actions ─────────────────────────────────────────────────────────────────
+
+export interface ConnectAction { type: 'connect' }
+export interface DisconnectAction { type: 'disconnect' }
+
+export interface NavigateAction {
+  type: 'navigate'
+  docId: string
+}
+
+export interface TypeAction {
+  type: 'type'
+  docId: string
+  text: string
+  /** ms per character (default 80) */
+  speed?: number
+  /** random variance +/- ms (default 30) */
+  variance?: number
+  /** character index to start typing at (default: end of doc) */
+  position?: number
+}
+
+export interface SelectAction {
+  type: 'select'
+  docId: string
+  anchor: number
+  head: number
+}
+
+export interface MoveCursorAction {
+  type: 'moveCursor'
+  docId: string
+  from: number
+  to: number
+  duration: number
+  easing?: EasingName
+}
+
+export interface SetStatusAction {
+  type: 'setStatus'
+  status: string | null
+}
+
+export interface SetAwarenessAction {
+  type: 'setAwareness'
+  /** If set, applies to child provider; otherwise root */
+  docId?: string
+  fields: Record<string, unknown>
+}
+
+export interface ClearAwarenessAction {
+  type: 'clearAwareness'
+  docId?: string
+  fields: string[]
+}
+
+export interface CreateDocumentAction {
+  type: 'createDocument'
+  parentId: string
+  label: string
+  docType?: string
+  meta?: Record<string, unknown>
+  /** Store created doc ID under this key in vars for later reference */
+  assignId?: string
+}
+
+export interface MoveDocumentAction {
+  type: 'moveDocument'
+  docId: string
+  newParentId: string
+  order?: number
+}
+
+export interface WriteContentAction {
+  type: 'writeContent'
+  docId: string
+  markdown: string
+}
+
+export interface DeleteContentAction {
+  type: 'deleteContent'
+  docId: string
+  from: number
+  length: number
+}
+
+export interface SetMetaAction {
+  type: 'setMeta'
+  docId: string
+  meta: Record<string, unknown>
+}
+
+export interface PointerMoveAction {
+  type: 'pointerMove'
+  docId: string
+  from: { x: number; y: number }
+  to: { x: number; y: number }
+  duration: number
+  easing?: EasingName
+}
+
+export interface ScrollToAction {
+  type: 'scrollTo'
+  docId: string
+  /** 0-1 normalized scroll position */
+  position: number
+}
+
+export interface KanbanHoverAction {
+  type: 'kanbanHover'
+  docId: string
+  cardId: string | null
+}
+
+export interface KanbanDragAction {
+  type: 'kanbanDrag'
+  docId: string
+  cardId: string
+  toColumnId: string
+  duration: number
+}
+
+export interface RenameDocumentAction {
+  type: 'renameDocument'
+  docId: string
+  label: string
+}
+
+export interface SendChatAction {
+  type: 'sendChat'
+  /** Channel key (e.g. 'group:docId' or 'dm:key1:key2') */
+  channel: string
+  message: string
+}
+
+export interface TypeDeleteAction {
+  type: 'typeDelete'
+  docId: string
+  /** Number of characters to delete (backspace) */
+  count: number
+  /** ms per deletion (default 60) */
+  speed?: number
+  /** random variance +/- ms (default 20) */
+  variance?: number
+  /** character index to start deleting from (default: end of doc) */
+  position?: number
+}
+
+export interface RepeatAction {
+  type: 'repeat'
+  /** Number of times to repeat */
+  times: number
+  actions: TimelineEntry[]
+}
+
+export interface WaitAction {
+  type: 'wait'
+  duration: number
+}
+
+export interface ParallelAction {
+  type: 'parallel'
+  actions: TimelineEntry[]
+}
+
+export interface SequenceAction {
+  type: 'sequence'
+  actions: TimelineEntry[]
+}
+
+export type Action =
+  | ConnectAction
+  | DisconnectAction
+  | NavigateAction
+  | TypeAction
+  | TypeDeleteAction
+  | SelectAction
+  | MoveCursorAction
+  | SetStatusAction
+  | SetAwarenessAction
+  | ClearAwarenessAction
+  | CreateDocumentAction
+  | MoveDocumentAction
+  | RenameDocumentAction
+  | WriteContentAction
+  | DeleteContentAction
+  | SetMetaAction
+  | PointerMoveAction
+  | ScrollToAction
+  | KanbanHoverAction
+  | KanbanDragAction
+  | SendChatAction
+  | WaitAction
+  | ParallelAction
+  | SequenceAction
+  | RepeatAction
+
+// ── Timeline ────────────────────────────────────────────────────────────────
+
+export interface TimelineEntry {
+  /** ms from scene start (or parent start for nested entries) */
+  at?: number
+  /** Which actor performs this action */
+  actor?: string
+  action: Action
+}
+
+// ── Scene ───────────────────────────────────────────────────────────────────
+
+export interface Scene {
+  server: ServerConfig
+  actors: ActorDef[]
+  timeline: TimelineEntry[]
+  /** Pre-defined variables (e.g. known doc IDs) */
+  vars?: Record<string, string>
+  /** Max scene duration in ms. Auto-cleanup after this time. */
+  duration?: number
+  /** Called after all actors are prepared but before timeline runs. */
+  onStart?: () => Promise<void> | void
+  /** Called after timeline completes (before cleanup). */
+  onEnd?: () => Promise<void> | void
+}

package/src/utils.ts

@@ -0,0 +1,50 @@
+/**
+ * Utility functions for the orchestrator.
+ */
+
+/** Wait for a provider's `synced` event with a timeout. Resolves immediately if already synced. */
+export function waitForSync(
+  provider: { on(event: string, cb: () => void): void; off(event: string, cb: () => void): void; synced?: boolean },
+  timeoutMs = 15000
+): Promise<void> {
+  // If already synced, resolve immediately
+  if (provider.synced) return Promise.resolve()
+
+  return new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      provider.off('synced', handler)
+      reject(new Error(`Sync timed out after ${timeoutMs}ms`))
+    }, timeoutMs)
+
+    function handler() {
+      clearTimeout(timer)
+      resolve()
+    }
+
+    provider.on('synced', handler)
+  })
+}
+
+/** Sleep for a given number of milliseconds. */
+export function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+/** Wraps a promise with a timeout. */
+export function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message?: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error(message ?? `Operation timed out after ${timeoutMs}ms`)),
+      timeoutMs
+    )
+    promise.then(
+      (val) => { clearTimeout(timer); resolve(val) },
+      (err) => { clearTimeout(timer); reject(err) }
+    )
+  })
+}
+
+/** Log to stderr with [orchestrator] prefix. */
+export function log(msg: string): void {
+  console.error(`[orchestrator] ${msg}`)
+}

package/src/yjs-utils.ts

@@ -0,0 +1,238 @@
+/**
+ * Y.js document structure utilities for TipTap-compatible editing.
+ *
+ * TipTap documents have the structure:
+ *   XmlFragment('default') → [documentHeader, documentMeta, ...body paragraphs]
+ *
+ * All text position functions skip documentHeader and documentMeta —
+ * character index 0 maps to the first character of the first body paragraph.
+ */
+import * as Y from 'yjs'
+
+const SCHEMA_NODES = new Set(['documentHeader', 'documentMeta'])
+
+/** Check if an XmlElement is a TipTap schema node (not body content). */
+function isSchemaNode(el: Y.XmlElement): boolean {
+  return SCHEMA_NODES.has(el.nodeName)
+}
+
+/**
+ * Ensure the fragment has documentHeader and documentMeta nodes.
+ * Creates them if missing. Idempotent — safe to call multiple times.
+ */
+export function ensureDocumentStructure(fragment: Y.XmlFragment): void {
+  let hasHeader = false
+  let hasMeta = false
+
+  for (let i = 0; i < fragment.length; i++) {
+    const child = fragment.get(i)
+    if (child instanceof Y.XmlElement) {
+      if (child.nodeName === 'documentHeader') hasHeader = true
+      if (child.nodeName === 'documentMeta') hasMeta = true
+    }
+  }
+
+  // Insert in reverse order so indices stay correct
+  if (!hasMeta) {
+    const meta = new Y.XmlElement('documentMeta')
+    fragment.insert(hasHeader ? 1 : 0, [meta])
+  }
+  if (!hasHeader) {
+    const header = new Y.XmlElement('documentHeader')
+    fragment.insert(0, [header])
+  }
+}
+
+/**
+ * Find the index where body content starts (after documentHeader + documentMeta).
+ */
+export function bodyStartIndex(fragment: Y.XmlFragment): number {
+  let idx = 0
+  for (let i = 0; i < fragment.length; i++) {
+    const child = fragment.get(i)
+    if (child instanceof Y.XmlElement && isSchemaNode(child)) {
+      idx = i + 1
+    } else {
+      break
+    }
+  }
+  return idx
+}
+
+/**
+ * Walk the XmlFragment body (skipping schema nodes) to find the XmlText node
+ * and local offset for a given global character index.
+ */
+export function findTextPosition(
+  fragment: Y.XmlFragment,
+  globalIndex: number
+): { text: Y.XmlText; offset: number } | null {
+  let consumed = 0
+  for (let i = 0; i < fragment.length; i++) {
+    const child = fragment.get(i)
+    if (child instanceof Y.XmlElement) {
+      if (isSchemaNode(child)) continue
+      const result = findTextInElement(child, globalIndex - consumed)
+      if (result) return result
+      consumed += elementTextLength(child)
+    }
+  }
+  return null
+}
+
+function findTextInElement(
+  el: Y.XmlElement,
+  remaining: number
+): { text: Y.XmlText; offset: number } | null {
+  for (let i = 0; i < el.length; i++) {
+    const child = el.get(i)
+    if (child instanceof Y.XmlText) {
+      if (remaining <= child.length) {
+        return { text: child, offset: remaining }
+      }
+      remaining -= child.length
+    } else if (child instanceof Y.XmlElement) {
+      const result = findTextInElement(child, remaining)
+      if (result) return result
+      remaining -= elementTextLength(child)
+    }
+  }
+  return null
+}
+
+/** Total text length of an XmlElement (recursive). */
+export function elementTextLength(el: Y.XmlElement): number {
+  let len = 0
+  for (let i = 0; i < el.length; i++) {
+    const child = el.get(i)
+    if (child instanceof Y.XmlText) {
+      len += child.length
+    } else if (child instanceof Y.XmlElement) {
+      len += elementTextLength(child)
+    }
+  }
+  return len
+}
+
+/** Total text length of all body paragraphs (skips schema nodes). */
+export function fragmentTextLength(fragment: Y.XmlFragment): number {
+  let len = 0
+  for (let i = 0; i < fragment.length; i++) {
+    const child = fragment.get(i)
+    if (child instanceof Y.XmlElement && !isSchemaNode(child)) {
+      len += elementTextLength(child)
+    }
+  }
+  return len
+}
+
+/**
+ * Compute the global character index of a position within a known XmlText node.
+ * Re-derives from current document state — safe under concurrent edits.
+ * Only counts body content (skips schema nodes).
+ */
+export function globalIndexOf(
+  fragment: Y.XmlFragment,
+  targetText: Y.XmlText,
+  localOffset: number
+): number {
+  let index = 0
+  for (let i = 0; i < fragment.length; i++) {
+    const child = fragment.get(i)
+    if (child instanceof Y.XmlElement) {
+      if (isSchemaNode(child)) continue
+      const result = globalIndexInElement(child, targetText, localOffset, index)
+      if (result !== null) return result
+      index += elementTextLength(child)
+    }
+  }
+  return index + localOffset // fallback
+}
+
+function globalIndexInElement(
+  el: Y.XmlElement,
+  targetText: Y.XmlText,
+  localOffset: number,
+  base: number
+): number | null {
+  for (let i = 0; i < el.length; i++) {
+    const child = el.get(i)
+    if (child instanceof Y.XmlText) {
+      if (child === targetText) {
+        return base + localOffset
+      }
+      base += child.length
+    } else if (child instanceof Y.XmlElement) {
+      const result = globalIndexInElement(child, targetText, localOffset, base)
+      if (result !== null) return result
+      base += elementTextLength(child)
+    }
+  }
+  return null
+}
+
+/**
+ * Get or create the last body paragraph's XmlText.
+ * Skips documentHeader and documentMeta. Creates a new paragraph if none exist.
+ */
+export function getOrCreateLastParagraph(
+  fragment: Y.XmlFragment
+): { text: Y.XmlText; globalOffset: number } {
+  // Search backwards for the last body paragraph
+  for (let i = fragment.length - 1; i >= 0; i--) {
+    const child = fragment.get(i)
+    if (child instanceof Y.XmlElement) {
+      if (isSchemaNode(child)) continue
+      if (child.nodeName === 'paragraph') {
+        for (let j = child.length - 1; j >= 0; j--) {
+          const grandchild = child.get(j)
+          if (grandchild instanceof Y.XmlText) {
+            return { text: grandchild, globalOffset: fragmentTextLength(fragment) }
+          }
+        }
+        // Paragraph exists but has no XmlText — add one
+        const xt = new Y.XmlText()
+        child.insert(0, [xt])
+        return { text: xt, globalOffset: fragmentTextLength(fragment) }
+      }
+    }
+  }
+
+  // No body paragraph found — create one after schema nodes
+  const para = new Y.XmlElement('paragraph')
+  const xt = new Y.XmlText()
+  para.insert(0, [xt])
+  fragment.push([para])
+  return { text: xt, globalOffset: 0 }
+}
+
+/**
+ * Insert a new paragraph after the one containing the given global character index.
+ * Skips schema nodes when computing positions.
+ */
+export function insertParagraphAfter(
+  fragment: Y.XmlFragment,
+  afterGlobalIndex: number
+): Y.XmlText {
+  let offset = 0
+  let insertAt = fragment.length
+
+  for (let i = 0; i < fragment.length; i++) {
+    const child = fragment.get(i)
+    if (child instanceof Y.XmlElement) {
+      if (isSchemaNode(child)) continue
+      const elLen = elementTextLength(child)
+      if (offset + elLen >= afterGlobalIndex) {
+        insertAt = i + 1
+        break
+      }
+      offset += elLen
+    }
+  }
+
+  const para = new Y.XmlElement('paragraph')
+  const xt = new Y.XmlText()
+  para.insert(0, [xt])
+  fragment.insert(insertAt, [para])
+  return xt
+}