@abraca/orchestrator 2.3.0

package/dist/index.d.ts

@@ -0,0 +1,261 @@
+//#region packages/orchestrator/src/types.d.ts
+/**
+ * Type definitions for the orchestrator scene format.
+ */
+interface ServerConfig {
+  url: string;
+  inviteCode?: string;
+}
+interface ActorDef {
+  name: string;
+  color: string;
+  keyFile?: string;
+  avatar?: string;
+}
+type EasingName = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';
+interface ConnectAction {
+  type: 'connect';
+}
+interface DisconnectAction {
+  type: 'disconnect';
+}
+interface NavigateAction {
+  type: 'navigate';
+  docId: string;
+}
+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;
+}
+interface SelectAction {
+  type: 'select';
+  docId: string;
+  anchor: number;
+  head: number;
+}
+interface MoveCursorAction {
+  type: 'moveCursor';
+  docId: string;
+  from: number;
+  to: number;
+  duration: number;
+  easing?: EasingName;
+}
+interface SetStatusAction {
+  type: 'setStatus';
+  status: string | null;
+}
+interface SetAwarenessAction {
+  type: 'setAwareness';
+  /** If set, applies to child provider; otherwise root */
+  docId?: string;
+  fields: Record<string, unknown>;
+}
+interface ClearAwarenessAction {
+  type: 'clearAwareness';
+  docId?: string;
+  fields: string[];
+}
+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;
+}
+interface MoveDocumentAction {
+  type: 'moveDocument';
+  docId: string;
+  newParentId: string;
+  order?: number;
+}
+interface WriteContentAction {
+  type: 'writeContent';
+  docId: string;
+  markdown: string;
+}
+interface DeleteContentAction {
+  type: 'deleteContent';
+  docId: string;
+  from: number;
+  length: number;
+}
+interface SetMetaAction {
+  type: 'setMeta';
+  docId: string;
+  meta: Record<string, unknown>;
+}
+interface PointerMoveAction {
+  type: 'pointerMove';
+  docId: string;
+  from: {
+    x: number;
+    y: number;
+  };
+  to: {
+    x: number;
+    y: number;
+  };
+  duration: number;
+  easing?: EasingName;
+}
+interface ScrollToAction {
+  type: 'scrollTo';
+  docId: string;
+  /** 0-1 normalized scroll position */
+  position: number;
+}
+interface KanbanHoverAction {
+  type: 'kanbanHover';
+  docId: string;
+  cardId: string | null;
+}
+interface KanbanDragAction {
+  type: 'kanbanDrag';
+  docId: string;
+  cardId: string;
+  toColumnId: string;
+  duration: number;
+}
+interface RenameDocumentAction {
+  type: 'renameDocument';
+  docId: string;
+  label: string;
+}
+interface SendChatAction {
+  type: 'sendChat';
+  /** Channel key (e.g. 'group:docId' or 'dm:key1:key2') */
+  channel: string;
+  message: string;
+}
+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;
+}
+interface RepeatAction {
+  type: 'repeat';
+  /** Number of times to repeat */
+  times: number;
+  actions: TimelineEntry[];
+}
+interface WaitAction {
+  type: 'wait';
+  duration: number;
+}
+interface ParallelAction {
+  type: 'parallel';
+  actions: TimelineEntry[];
+}
+interface SequenceAction {
+  type: 'sequence';
+  actions: TimelineEntry[];
+}
+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;
+interface TimelineEntry {
+  /** ms from scene start (or parent start for nested entries) */
+  at?: number;
+  /** Which actor performs this action */
+  actor?: string;
+  action: Action;
+}
+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;
+}
+//#endregion
+//#region packages/orchestrator/src/define.d.ts
+/** Define a complete scene. */
+declare function defineScene(scene: Scene): Scene;
+/** Define an actor. */
+declare function actor(name: string, opts: Omit<ActorDef, 'name'>): ActorDef;
+/** Factory functions for all action types. */
+declare const actions: {
+  connect(): ConnectAction;
+  disconnect(): DisconnectAction;
+  navigate(docId: string): NavigateAction;
+  type(docId: string, text: string, opts?: {
+    speed?: number;
+    variance?: number;
+    position?: number;
+  }): TypeAction;
+  typeDelete(docId: string, count: number, opts?: {
+    speed?: number;
+    variance?: number;
+    position?: number;
+  }): TypeDeleteAction;
+  select(docId: string, anchor: number, head: number): SelectAction;
+  moveCursor(docId: string, from: number, to: number, duration: number, easing?: EasingName): MoveCursorAction;
+  setStatus(status: string | null): SetStatusAction;
+  setAwareness(fields: Record<string, unknown>, docId?: string): SetAwarenessAction;
+  clearAwareness(fields: string[], docId?: string): ClearAwarenessAction;
+  createDocument(parentId: string, label: string, opts?: {
+    docType?: string;
+    meta?: Record<string, unknown>;
+    assignId?: string;
+  }): CreateDocumentAction;
+  moveDocument(docId: string, newParentId: string, order?: number): MoveDocumentAction;
+  renameDocument(docId: string, label: string): RenameDocumentAction;
+  writeContent(docId: string, markdown: string): WriteContentAction;
+  deleteContent(docId: string, from: number, length: number): DeleteContentAction;
+  setMeta(docId: string, meta: Record<string, unknown>): SetMetaAction;
+  pointerMove(docId: string, from: {
+    x: number;
+    y: number;
+  }, to: {
+    x: number;
+    y: number;
+  }, duration: number, easing?: EasingName): PointerMoveAction;
+  scrollTo(docId: string, position: number): ScrollToAction;
+  kanbanHover(docId: string, cardId: string | null): KanbanHoverAction;
+  kanbanDrag(docId: string, cardId: string, toColumnId: string, duration: number): KanbanDragAction;
+  sendChat(channel: string, message: string): SendChatAction;
+  wait(duration: number): WaitAction;
+  parallel(entries: TimelineEntry[]): ParallelAction;
+  sequence(entries: TimelineEntry[]): SequenceAction;
+  repeat(times: number, entries: TimelineEntry[]): RepeatAction;
+};
+//#endregion
+//#region packages/orchestrator/src/orchestrator.d.ts
+declare class Orchestrator {
+  private scene;
+  private actors;
+  private vars;
+  /** Load a scene from a TypeScript file. */
+  load(scriptPath: string): Promise<void>;
+  /** Prepare actor connections (does not connect yet — that's a timeline action). */
+  prepare(): void;
+  /** Validate the scene without connecting. Logs the timeline structure. */
+  dryRun(): void;
+  /** Run the timeline. */
+  run(): Promise<void>;
+  /** Disconnect all actors gracefully. */
+  cleanup(): Promise<void>;
+}
+//#endregion
+export { type Action, type ActorDef, type ClearAwarenessAction, type ConnectAction, type CreateDocumentAction, type DeleteContentAction, type DisconnectAction, type EasingName, type KanbanDragAction, type KanbanHoverAction, type MoveCursorAction, type MoveDocumentAction, type NavigateAction, Orchestrator, type ParallelAction, type PointerMoveAction, type RenameDocumentAction, type RepeatAction, type Scene, type ScrollToAction, type SelectAction, type SendChatAction, type SequenceAction, type ServerConfig, type SetAwarenessAction, type SetMetaAction, type SetStatusAction, type TimelineEntry, type TypeAction, type TypeDeleteAction, type WaitAction, type WriteContentAction, actions, actor, defineScene };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@abraca/orchestrator",
+  "version": "2.3.0",
+  "description": "CouShell commercial director — orchestrate simulated actors on Abracadabra for screen recording",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/abracadabra-orchestrator.cjs",
+  "module": "dist/abracadabra-orchestrator.esm.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "abracadabra-orchestrator": "./dist/abracadabra-orchestrator.esm.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "source": {
+      "import": "./src/index.ts"
+    },
+    "default": {
+      "import": "./dist/abracadabra-orchestrator.esm.js",
+      "require": "./dist/abracadabra-orchestrator.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "dependencies": {
+    "@noble/ed25519": "^3.1.0",
+    "@noble/hashes": "^2.2.0"
+  },
+  "peerDependencies": {
+    "@abraca/dabra": ">=1.0.0",
+    "y-protocols": "^1.0.6",
+    "yjs": "^13.6.8"
+  }
+}

package/src/actions/awareness.ts

@@ -0,0 +1,101 @@
+/**
+ * Awareness actions: setStatus, setAwareness, clearAwareness, pointerMove, scrollTo,
+ * kanbanHover, kanbanDrag.
+ */
+import type { ActorConnection } from '../actor-connection.ts'
+import type {
+  SetStatusAction,
+  SetAwarenessAction,
+  ClearAwarenessAction,
+  PointerMoveAction,
+  ScrollToAction,
+  KanbanHoverAction,
+  KanbanDragAction,
+} from '../types.ts'
+import { sleep } from '../utils.ts'
+import { getEasing } from '../easing.ts'
+
+export async function executeSetStatus(
+  actor: ActorConnection,
+  action: SetStatusAction
+): Promise<void> {
+  actor.setRootAwareness('status', action.status)
+}
+
+export async function executeSetAwareness(
+  actor: ActorConnection,
+  action: SetAwarenessAction
+): Promise<void> {
+  if (action.docId) {
+    // Ensure child provider is loaded
+    await actor.getChildProvider(action.docId)
+    for (const [key, value] of Object.entries(action.fields)) {
+      actor.setChildAwareness(action.docId, key, value)
+    }
+  } else {
+    for (const [key, value] of Object.entries(action.fields)) {
+      actor.setRootAwareness(key, value)
+    }
+  }
+}
+
+export async function executeClearAwareness(
+  actor: ActorConnection,
+  action: ClearAwarenessAction
+): Promise<void> {
+  if (action.docId) {
+    for (const field of action.fields) {
+      actor.setChildAwareness(action.docId, field, null)
+    }
+  } else {
+    for (const field of action.fields) {
+      actor.setRootAwareness(field, null)
+    }
+  }
+}
+
+export async function executePointerMove(
+  actor: ActorConnection,
+  action: PointerMoveAction
+): Promise<void> {
+  const easing = getEasing(action.easing)
+  const steps = Math.max(1, Math.round(action.duration / 16)) // ~60fps
+  const stepDuration = action.duration / steps
+
+  for (let i = 0; i <= steps; i++) {
+    const t = easing(i / steps)
+    const x = action.from.x + (action.to.x - action.from.x) * t
+    const y = action.from.y + (action.to.y - action.from.y) * t
+    actor.setChildAwareness(action.docId, 'pos', { x, y })
+    if (i < steps) await sleep(stepDuration)
+  }
+}
+
+export async function executeScrollTo(
+  actor: ActorConnection,
+  action: ScrollToAction
+): Promise<void> {
+  actor.setChildAwareness(action.docId, 'doc:scroll', action.position)
+}
+
+export async function executeKanbanHover(
+  actor: ActorConnection,
+  action: KanbanHoverAction
+): Promise<void> {
+  actor.setChildAwareness(action.docId, 'kanban:hovering', action.cardId)
+}
+
+export async function executeKanbanDrag(
+  actor: ActorConnection,
+  action: KanbanDragAction
+): Promise<void> {
+  // Set drag state
+  actor.setChildAwareness(action.docId, 'kanban:dragging', {
+    cardId: action.cardId,
+    toColumnId: action.toColumnId,
+  })
+  // Hold for duration
+  await sleep(action.duration)
+  // Clear drag state
+  actor.setChildAwareness(action.docId, 'kanban:dragging', null)
+}

package/src/actions/chat.ts

@@ -0,0 +1,30 @@
+/**
+ * Chat action — send a stateless message via the provider.
+ *
+ * Routes through the unified `messages:send` protocol. `action.channel` is
+ * interpreted as a doc id (the channel/dm doc UUID); legacy `group:<docId>`
+ * strings are accepted with the prefix stripped.
+ */
+import type { ActorConnection } from '../actor-connection.ts'
+import type { SendChatAction } from '../types.ts'
+
+export async function executeSendChat(
+  actor: ActorConnection,
+  action: SendChatAction
+): Promise<void> {
+  const rootProvider = actor.rootProvider
+  if (!rootProvider) throw new Error(`${actor.actor.name}: not connected`)
+
+  const channel_doc_id = action.channel.startsWith('group:')
+    ? action.channel.slice(6)
+    : action.channel
+
+  const payload = JSON.stringify({
+    type: 'messages:send',
+    channel_doc_id,
+    content: action.message,
+    mentions: [],
+  })
+
+  rootProvider.sendStateless(payload)
+}

package/src/actions/connect.ts

@@ -0,0 +1,16 @@
+/**
+ * Connect / disconnect actions.
+ */
+import type { ActorConnection } from '../actor-connection.ts'
+import type { ServerConfig } from '../types.ts'
+
+export async function executeConnect(
+  actor: ActorConnection,
+  serverConfig: ServerConfig
+): Promise<void> {
+  await actor.connect(serverConfig)
+}
+
+export async function executeDisconnect(actor: ActorConnection): Promise<void> {
+  await actor.disconnect()
+}

package/src/actions/content.ts

@@ -0,0 +1,46 @@
+/**
+ * Content actions: writeContent (markdown → Y.js), deleteContent.
+ *
+ * Preserves TipTap schema nodes (documentHeader, documentMeta) —
+ * only body content is cleared/replaced.
+ */
+import type { ActorConnection } from '../actor-connection.ts'
+import type { WriteContentAction, DeleteContentAction } from '../types.ts'
+import { populateYDocFromMarkdown } from '../converters/markdownToYjs.ts'
+import { bodyStartIndex } from '../yjs-utils.ts'
+
+export async function executeWriteContent(
+  actor: ActorConnection,
+  action: WriteContentAction
+): Promise<void> {
+  const provider = await actor.getChildProvider(action.docId)
+  const fragment = provider.document.getXmlFragment('default')
+
+  // Clear entire fragment (schema nodes + body) — populateYDocFromMarkdown rebuilds them
+  provider.document.transact(() => {
+    while (fragment.length > 0) {
+      fragment.delete(0, 1)
+    }
+  })
+
+  // Populate from markdown (creates fresh documentHeader + documentMeta + body)
+  populateYDocFromMarkdown(fragment, action.markdown)
+}
+
+export async function executeDeleteContent(
+  actor: ActorConnection,
+  action: DeleteContentAction
+): Promise<void> {
+  const provider = await actor.getChildProvider(action.docId)
+  const fragment = provider.document.getXmlFragment('default')
+
+  provider.document.transact(() => {
+    // Offset from by the schema nodes to protect them
+    const start = bodyStartIndex(fragment)
+    const adjustedFrom = start + action.from
+    const count = Math.min(action.length, fragment.length - adjustedFrom)
+    if (count > 0) {
+      fragment.delete(adjustedFrom, count)
+    }
+  })
+}

package/src/actions/cursor.ts

@@ -0,0 +1,30 @@
+/**
+ * Cursor actions: moveCursor (animated), select.
+ */
+import type { ActorConnection } from '../actor-connection.ts'
+import type { MoveCursorAction, SelectAction } from '../types.ts'
+import { sleep } from '../utils.ts'
+import { getEasing } from '../easing.ts'
+
+export async function executeMoveCursor(
+  actor: ActorConnection,
+  action: MoveCursorAction
+): Promise<void> {
+  const easing = getEasing(action.easing)
+  const steps = Math.max(1, Math.round(action.duration / 16))
+  const stepDuration = action.duration / steps
+
+  for (let i = 0; i <= steps; i++) {
+    const t = easing(i / steps)
+    const pos = Math.round(action.from + (action.to - action.from) * t)
+    actor.setCursor(action.docId, pos)
+    if (i < steps) await sleep(stepDuration)
+  }
+}
+
+export async function executeSelect(
+  actor: ActorConnection,
+  action: SelectAction
+): Promise<void> {
+  actor.setSelection(action.docId, action.anchor, action.head)
+}

package/src/actions/document.ts

@@ -0,0 +1,120 @@
+/**
+ * Document management actions: createDocument, moveDocument, setMeta.
+ * These operate on the Y.js doc-tree map (same as the dashboard and MCP do).
+ */
+import type { ActorConnection } from '../actor-connection.ts'
+import type { CreateDocumentAction, MoveDocumentAction, SetMetaAction, RenameDocumentAction } from '../types.ts'
+import { log } from '../utils.ts'
+
+export async function executeCreateDocument(
+  actor: ActorConnection,
+  action: CreateDocumentAction,
+  vars: Map<string, string>
+): Promise<void> {
+  const rootProvider = actor.rootProvider
+  if (!rootProvider) throw new Error(`${actor.actor.name}: not connected`)
+
+  const treeMap = rootProvider.document.getMap('doc-tree')
+  const id = crypto.randomUUID()
+  const now = Date.now()
+
+  // Normalize parentId: if it matches the root doc, use null (top-level)
+  const normalizedParent = action.parentId === actor.rootDocId ? null : action.parentId
+
+  rootProvider.document.transact(() => {
+    treeMap.set(id, {
+      label: action.label,
+      parentId: normalizedParent,
+      order: now,
+      type: action.docType,
+      meta: action.meta,
+      createdAt: now,
+      updatedAt: now,
+    })
+  })
+
+  log(`${actor.actor.name}: created document "${action.label}" (${id})`)
+
+  // Store the created ID for later reference in the script
+  if (action.assignId) {
+    vars.set(action.assignId, id)
+  }
+}
+
+export async function executeMoveDocument(
+  actor: ActorConnection,
+  action: MoveDocumentAction
+): Promise<void> {
+  const rootProvider = actor.rootProvider
+  if (!rootProvider) throw new Error(`${actor.actor.name}: not connected`)
+
+  const treeMap = rootProvider.document.getMap('doc-tree')
+  const entry = treeMap.get(action.docId) as Record<string, unknown> | undefined
+  if (!entry) {
+    log(`${actor.actor.name}: document ${action.docId} not found in tree`)
+    return
+  }
+
+  // Normalize parentId
+  const normalizedParent = action.newParentId === actor.rootDocId ? null : action.newParentId
+
+  rootProvider.document.transact(() => {
+    treeMap.set(action.docId, {
+      ...entry,
+      parentId: normalizedParent,
+      order: action.order ?? Date.now(),
+      updatedAt: Date.now(),
+    })
+  })
+
+  log(`${actor.actor.name}: moved document ${action.docId} to ${action.newParentId}`)
+}
+
+export async function executeSetMeta(
+  actor: ActorConnection,
+  action: SetMetaAction
+): Promise<void> {
+  const rootProvider = actor.rootProvider
+  if (!rootProvider) throw new Error(`${actor.actor.name}: not connected`)
+
+  const treeMap = rootProvider.document.getMap('doc-tree')
+  const entry = treeMap.get(action.docId) as Record<string, unknown> | undefined
+  if (!entry) {
+    log(`${actor.actor.name}: document ${action.docId} not found in tree`)
+    return
+  }
+
+  rootProvider.document.transact(() => {
+    const currentMeta = (entry.meta as Record<string, unknown>) ?? {}
+    treeMap.set(action.docId, {
+      ...entry,
+      meta: { ...currentMeta, ...action.meta },
+      updatedAt: Date.now(),
+    })
+  })
+}
+
+export async function executeRenameDocument(
+  actor: ActorConnection,
+  action: RenameDocumentAction
+): Promise<void> {
+  const rootProvider = actor.rootProvider
+  if (!rootProvider) throw new Error(`${actor.actor.name}: not connected`)
+
+  const treeMap = rootProvider.document.getMap('doc-tree')
+  const entry = treeMap.get(action.docId) as Record<string, unknown> | undefined
+  if (!entry) {
+    log(`${actor.actor.name}: document ${action.docId} not found in tree`)
+    return
+  }
+
+  rootProvider.document.transact(() => {
+    treeMap.set(action.docId, {
+      ...entry,
+      label: action.label,
+      updatedAt: Date.now(),
+    })
+  })
+
+  log(`${actor.actor.name}: renamed ${action.docId} to "${action.label}"`)
+}

package/src/actions/flow.ts

@@ -0,0 +1,46 @@
+/**
+ * Flow control actions: wait, parallel, sequence.
+ */
+import type { WaitAction, ParallelAction, SequenceAction, RepeatAction, TimelineEntry } from '../types.ts'
+import { sleep } from '../utils.ts'
+import type { ActionExecutor } from './index.ts'
+
+export async function executeWait(action: WaitAction): Promise<void> {
+  await sleep(action.duration)
+}
+
+export async function executeParallel(
+  action: ParallelAction,
+  execute: ActionExecutor
+): Promise<void> {
+  const promises = action.actions.map(async (entry) => {
+    const delay = entry.at ?? 0
+    if (delay > 0) await sleep(delay)
+    await execute(entry)
+  })
+  await Promise.all(promises)
+}
+
+export async function executeSequence(
+  action: SequenceAction,
+  execute: ActionExecutor
+): Promise<void> {
+  for (const entry of action.actions) {
+    const delay = entry.at ?? 0
+    if (delay > 0) await sleep(delay)
+    await execute(entry)
+  }
+}
+
+export async function executeRepeat(
+  action: RepeatAction,
+  execute: ActionExecutor
+): Promise<void> {
+  for (let n = 0; n < action.times; n++) {
+    for (const entry of action.actions) {
+      const delay = entry.at ?? 0
+      if (delay > 0) await sleep(delay)
+      await execute(entry)
+    }
+  }
+}