@mmapp/player-core 0.1.0-alpha.1

package/src/dsl/types.ts

@@ -0,0 +1,256 @@
+/**
+ * AST types for the noun-first DSL grammar.
+ *
+ * The DSL is line-oriented: each line is one thought, and indentation
+ * defines parent-child relationships. This module defines the types
+ * for line-level classification and parsed data.
+ */
+
+// =============================================================================
+// Line Classification
+// =============================================================================
+
+export type LineType =
+  | 'comment'
+  | 'blank'
+  | 'space_decl'
+  | 'thing_decl'
+  | 'thing_ref'
+  | 'fragment_def'
+  | 'field_def'
+  | 'state_decl'
+  | 'starts_at'
+  | 'transition'
+  | 'when'
+  | 'set_action'
+  | 'do_action'
+  | 'go_action'
+  | 'tell_action'
+  | 'show_action'
+  | 'data_source'
+  | 'iteration'
+  | 'grouping'
+  | 'content'
+  | 'string_literal'
+  | 'search'
+  | 'qualifier'
+  | 'navigation'
+  | 'path_mapping'
+  | 'section'
+  | 'tagged'
+  | 'level_def'
+  | 'pages'
+  | 'unknown';
+
+// =============================================================================
+// Emphasis & Modifiers
+// =============================================================================
+
+export type Emphasis = 'big' | 'small';
+
+export interface Constraint {
+  kind: string;       // max, min, default, between, unique
+  value: string | number;
+  value2?: string | number; // for "between X and Y"
+}
+
+// =============================================================================
+// Parsed Line Data (per line type)
+// =============================================================================
+
+export interface SpaceDeclData {
+  name: string;
+  version: string;
+}
+
+export interface ThingDeclData {
+  name: string;
+  version?: string;
+}
+
+export interface ThingRefData {
+  name: string;
+  kind?: string; // primary, child, derived
+}
+
+export interface FragmentDefData {
+  name: string;
+}
+
+export interface FieldDefData {
+  name: string;
+  adjectives: string[];
+  baseType: string;
+  constraints: Constraint[];
+}
+
+export interface StateDeclData {
+  name: string;
+  isFinal: boolean;
+}
+
+export interface StartsAtData {
+  state: string;
+}
+
+export interface TransitionData {
+  verb: string;
+  target: string;
+  guard?: string; // role restriction like "admin only"
+}
+
+export interface WhenData {
+  condition: string;
+}
+
+export interface SetActionData {
+  field: string;
+  expression: string;
+}
+
+export interface DoActionData {
+  action: string;
+}
+
+export interface GoActionData {
+  path: string;
+}
+
+export interface TellActionData {
+  target: string;
+  message: string;
+}
+
+export interface ShowActionData {
+  content: string;
+  modifier?: string;
+}
+
+export interface DataSourceData {
+  alias: string;
+  source: string;
+  scope?: string;    // "for this project"
+  isLive?: boolean;
+  qualifier?: string; // "5 newest", "current"
+}
+
+export interface IterationData {
+  subject: string;
+  role?: string; // "as card"
+  emphasis?: Emphasis;
+}
+
+export interface GroupingData {
+  collection: string;
+  key: string;
+}
+
+export interface ContentData {
+  pronoun?: string;    // its, my, the
+  field: string;
+  emphasis?: Emphasis;
+  role?: string;
+  label?: string;      // with "XP"
+}
+
+export interface StringLiteralData {
+  text: string;
+  emphasis?: Emphasis;
+}
+
+export interface SearchData {
+  target: string;
+}
+
+export interface QualifierData {
+  kind: 'order' | 'searchable' | 'filterable' | 'pagination';
+  value: string;
+}
+
+export interface NavigationData {
+  trigger: string;  // tap, label text
+  target: string;
+}
+
+export interface PathMappingData {
+  path: string;
+  view: string;
+  context?: string;
+}
+
+export interface SectionData {
+  name: string;
+}
+
+export interface TaggedData {
+  tags: string[];
+}
+
+export interface LevelDefData {
+  level: number;
+  title: string;
+  fromXp: number;
+}
+
+// =============================================================================
+// Unified Line Token
+// =============================================================================
+
+export type LineData =
+  | { type: 'comment'; text: string }
+  | { type: 'blank' }
+  | { type: 'space_decl' } & SpaceDeclData
+  | { type: 'thing_decl' } & ThingDeclData
+  | { type: 'thing_ref' } & ThingRefData
+  | { type: 'fragment_def' } & FragmentDefData
+  | { type: 'field_def' } & FieldDefData
+  | { type: 'state_decl' } & StateDeclData
+  | { type: 'starts_at' } & StartsAtData
+  | { type: 'transition' } & TransitionData
+  | { type: 'when' } & WhenData
+  | { type: 'set_action' } & SetActionData
+  | { type: 'do_action' } & DoActionData
+  | { type: 'go_action' } & GoActionData
+  | { type: 'tell_action' } & TellActionData
+  | { type: 'show_action' } & ShowActionData
+  | { type: 'data_source' } & DataSourceData
+  | { type: 'iteration' } & IterationData
+  | { type: 'grouping' } & GroupingData
+  | { type: 'content' } & ContentData
+  | { type: 'string_literal' } & StringLiteralData
+  | { type: 'search' } & SearchData
+  | { type: 'qualifier' } & QualifierData
+  | { type: 'navigation' } & NavigationData
+  | { type: 'path_mapping' } & PathMappingData
+  | { type: 'section' } & SectionData
+  | { type: 'tagged' } & TaggedData
+  | { type: 'level_def' } & LevelDefData
+  | { type: 'pages' }
+  | { type: 'unknown'; text: string };
+
+export interface LineToken {
+  indent: number;
+  lineNumber: number;
+  raw: string;
+  data: LineData;
+}
+
+// =============================================================================
+// AST Tree (structural nesting)
+// =============================================================================
+
+export interface ASTNode {
+  token: LineToken;
+  children: ASTNode[];
+}
+
+export interface ParseResult {
+  nodes: ASTNode[];
+  errors: ParseError[];
+}
+
+export interface ParseError {
+  lineNumber: number;
+  message: string;
+  raw: string;
+}

package/src/events/event-bus.ts

@@ -0,0 +1,68 @@
+/**
+ * Event Bus — browser-side pub/sub for on_event subscriptions.
+ *
+ * Lightweight event bus that matches published topics against
+ * glob-pattern subscriptions. Used by the player to wire
+ * on_event declarations to action handlers.
+ */
+
+import { compilePattern, matchTopic } from './pattern-matcher';
+import type { BusEvent, EventHandler, EventSubscription, Unsubscribe } from './types';
+
+export class EventBus {
+  private subscriptions: EventSubscription[] = [];
+
+  /**
+   * Subscribe to events matching a glob pattern.
+   * Returns an unsubscribe function.
+   */
+  subscribe(pattern: string, handler: EventHandler): Unsubscribe {
+    const regex = compilePattern(pattern);
+    const subscription: EventSubscription = { pattern, regex, handler };
+    this.subscriptions.push(subscription);
+
+    return () => {
+      const idx = this.subscriptions.indexOf(subscription);
+      if (idx !== -1) this.subscriptions.splice(idx, 1);
+    };
+  }
+
+  /**
+   * Publish an event. All matching subscriptions fire (async).
+   * Errors in handlers are caught and logged, never propagated.
+   */
+  async publish(topic: string, payload: Record<string, unknown> = {}): Promise<void> {
+    const event: BusEvent = { topic, payload };
+
+    for (const sub of this.subscriptions) {
+      if (matchTopic(sub.regex, topic)) {
+        try {
+          await sub.handler(event);
+        } catch (error) {
+          console.warn(
+            `[player-core] Event handler error for pattern "${sub.pattern}" on topic "${topic}":`,
+            error,
+          );
+        }
+      }
+    }
+  }
+
+  /**
+   * Publish synchronously (fire-and-forget).
+   * Useful when you don't need to await handler completion.
+   */
+  emit(topic: string, payload: Record<string, unknown> = {}): void {
+    void this.publish(topic, payload);
+  }
+
+  /** Get count of active subscriptions */
+  get size(): number {
+    return this.subscriptions.length;
+  }
+
+  /** Remove all subscriptions */
+  clear(): void {
+    this.subscriptions.length = 0;
+  }
+}

package/src/events/index.ts

@@ -0,0 +1,9 @@
+export type {
+  EventSubscription,
+  BusEvent,
+  EventHandler,
+  Unsubscribe,
+} from './types';
+
+export { compilePattern, matchTopic, clearPatternCache } from './pattern-matcher';
+export { EventBus } from './event-bus';

package/src/events/pattern-matcher.ts

@@ -0,0 +1,61 @@
+/**
+ * Pattern Matcher — glob-style topic matching for on_event subscriptions.
+ *
+ * Supports:
+ * - Exact match: "workflow.order:state_enter"
+ * - Single-level wildcard (*): "workflow.*:state_enter" matches "workflow.order:state_enter"
+ * - Multi-level wildcard (**): "workflow.**" matches "workflow.order:state_enter:completed"
+ * - Colon-separated segments (like EventEmitter2)
+ *
+ * Compiled regex is cached per pattern for performance.
+ */
+
+const patternCache = new Map<string, RegExp>();
+const MAX_CACHE = 200;
+
+/**
+ * Compile a glob pattern into a RegExp.
+ *
+ * Pattern rules:
+ * - Segments separated by `:` or `.`
+ * - `*` matches exactly one segment (any chars except `:` and `.`)
+ * - `**` matches zero or more segments (greedy)
+ * - Everything else is literal
+ */
+export function compilePattern(pattern: string): RegExp {
+  const cached = patternCache.get(pattern);
+  if (cached) return cached;
+
+  // Escape regex special chars except * and separators
+  const escaped = pattern
+    .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+    // ** (double star) → placeholder
+    .replace(/\*\*/g, '<<DOUBLESTAR>>')
+    // * (single star) → match one segment
+    .replace(/\*/g, '[^:.]+')
+    // Restore ** → match anything
+    .replace(/<<DOUBLESTAR>>/g, '.*');
+
+  const regex = new RegExp(`^${escaped}$`);
+
+  // LRU eviction
+  if (patternCache.size >= MAX_CACHE) {
+    const firstKey = patternCache.keys().next().value;
+    if (firstKey) patternCache.delete(firstKey);
+  }
+
+  patternCache.set(pattern, regex);
+  return regex;
+}
+
+/**
+ * Test if a topic matches a compiled pattern.
+ */
+export function matchTopic(pattern: RegExp, topic: string): boolean {
+  return pattern.test(topic);
+}
+
+/** Clear pattern cache (for testing) */
+export function clearPatternCache(): void {
+  patternCache.clear();
+}

package/src/events/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Event System Types — browser-side on_event matching and dispatch.
+ */
+
+/** Subscription registered with the event bus */
+export interface EventSubscription {
+  /** Glob-style pattern: "workflow.*:state_enter" or "*:*:completed" */
+  pattern: string;
+  /** Compiled regex for fast matching (derived from pattern) */
+  regex: RegExp;
+  /** Conditions evaluated before actions fire */
+  conditions?: string[];
+  /** Handler called when pattern matches and conditions pass */
+  handler: EventHandler;
+}
+
+/** Event payload passed to handlers */
+export interface BusEvent {
+  topic: string;
+  payload: Record<string, unknown>;
+}
+
+/** Handler function for matched events */
+export type EventHandler = (event: BusEvent) => void | Promise<void>;
+
+/** Unsubscribe function returned by subscribe */
+export type Unsubscribe = () => void;