@caperjs/core 0.1.0

package/src/core/config.ts

@@ -0,0 +1,168 @@
+import { IPlugin, PluginListItem } from '../plugins/Plugin';
+import { type AppTypeOverrides, ImportList, Logger } from '../utils';
+import { AppConfig } from './types';
+
+type PluginId = AppTypeOverrides['Plugins'];
+
+export type PluginConfig = PluginId | [PluginId, { autoLoad?: boolean; options?: any }];
+
+/**
+ * Resolves the config's plugin list (which may be a mix of IDs and `[id, opts]`
+ * tuples) against the discovered plugin registry injected by the Vite runtime
+ * plugin. Plugin discovery now includes everything formerly registered as a
+ * "storage adapter" — unified into a single list.
+ */
+export async function generatePluginList<T extends IPlugin = IPlugin>(plugins: PluginConfig[]): Promise<ImportList<T>> {
+  const pluginsList: PluginListItem[] = Caper.get('pluginsList') || [];
+
+  return plugins
+    .map((plugin) => {
+      const p = pluginsList.find((p) => p.id === plugin || p.id === plugin[0]);
+      if (!p) {
+        Logger.warn(`Plugin ${plugin} not found`);
+        return null;
+      }
+      const pluginAsArray = plugin as [string, { autoLoad?: boolean; options?: any }];
+      return {
+        id: p.id,
+        path: p.path,
+        module: p.module,
+        requires: p.requires ?? [],
+        options: pluginAsArray[1]?.options,
+        autoLoad: pluginAsArray[1]?.autoLoad === false ? false : true,
+      };
+    })
+    .filter(Boolean) as ImportList<T>;
+}
+
+export function defineConfig(config: Partial<AppConfig>) {
+  return config;
+}
+
+/**
+ * Topologically sort the active plugin list by each item's `requires` field
+ * so dependencies initialize before dependents. Throws on missing required
+ * plugin or on cycle. Used by `Application.registerPlugins()` at bootstrap.
+ *
+ * Behavior:
+ *   - If `B.requires = ['A']`, A is initialized before B regardless of the
+ *     order they appear in `caper.config.ts plugins[]`.
+ *   - If `B.requires = ['A']` but A is not in the active plugin list, this
+ *     throws with an error message that names B, names A, and tells the
+ *     user to add A to `caper.config.ts plugins[]`. We deliberately do NOT
+ *     auto-register the missing dep — the config file is the single source
+ *     of truth for what plugins run, and silently inserting transitive
+ *     deps would make it stop being trustworthy.
+ *   - If a cycle exists (A→B→A), throws with the cycle path printed.
+ *
+ * Stable order: items with no dependencies preserve their original
+ * relative order from `caper.config.ts`. Only items participating in a
+ * `requires` chain get reordered.
+ */
+export function sortPluginsByRequires<T extends ImportList<IPlugin>[number]>(items: T[]): T[] {
+  if (items.length < 2) return items.slice();
+
+  const byId = new Map<string, T>();
+  for (const it of items) byId.set(it.id, it);
+
+  // Verify every required id is present in the active set. Collect ALL
+  // missing deps before throwing so the user can fix them in one pass
+  // rather than play whack-a-mole.
+  const missing: Array<{ from: string; required: string }> = [];
+  for (const it of items) {
+    for (const req of it.requires ?? []) {
+      if (!byId.has(req)) missing.push({ from: it.id, required: req });
+    }
+  }
+  if (missing.length > 0) {
+    const lines = missing.map(
+      (m) => `  - Plugin '${m.from}' requires '${m.required}' which is not registered.`,
+    );
+    const fix =
+      `\nAdd the missing plugin id(s) to plugins[] in caper.config.ts:\n  ` +
+      [...new Set(missing.map((m) => `'${m.required}'`))].join(', ');
+    throw new Error(`Caper bootstrap failed:\n${lines.join('\n')}${fix}`);
+  }
+
+  // Kahn's algorithm with deterministic tie-breaking by original index.
+  const indexOf = new Map<string, number>();
+  items.forEach((it, i) => indexOf.set(it.id, i));
+
+  const inDegree = new Map<string, number>();
+  const dependents = new Map<string, string[]>(); // id → [ids that require it]
+  for (const it of items) {
+    inDegree.set(it.id, (it.requires ?? []).length);
+    for (const req of it.requires ?? []) {
+      if (!dependents.has(req)) dependents.set(req, []);
+      dependents.get(req)!.push(it.id);
+    }
+  }
+
+  // Ready queue, ordered by original index for stability.
+  const ready: string[] = [];
+  for (const it of items) {
+    if (inDegree.get(it.id) === 0) ready.push(it.id);
+  }
+  ready.sort((a, b) => indexOf.get(a)! - indexOf.get(b)!);
+
+  const result: T[] = [];
+  while (ready.length > 0) {
+    const id = ready.shift()!;
+    result.push(byId.get(id)!);
+    for (const dep of dependents.get(id) ?? []) {
+      inDegree.set(dep, inDegree.get(dep)! - 1);
+      if (inDegree.get(dep) === 0) {
+        // Insert in original-index order to keep stable.
+        const idx = indexOf.get(dep)!;
+        let i = 0;
+        while (i < ready.length && indexOf.get(ready[i])! < idx) i++;
+        ready.splice(i, 0, dep);
+      }
+    }
+  }
+
+  if (result.length !== items.length) {
+    // Cycle: find one and report it.
+    const remaining = items.filter((it) => !result.includes(it)).map((it) => it.id);
+    const cyclePath = findCyclePath(remaining, byId);
+    throw new Error(
+      `Caper bootstrap failed: plugin dependency cycle detected: ${cyclePath.join(' → ')}\n` +
+        `Plugins involved: ${remaining.join(', ')}`,
+    );
+  }
+
+  return result;
+}
+
+function findCyclePath<T extends { id: string; requires?: string[] }>(
+  remainingIds: string[],
+  byId: Map<string, T>,
+): string[] {
+  // DFS from each remaining node until we revisit a node on the current path.
+  const onStack = new Set<string>();
+  const path: string[] = [];
+  const remaining = new Set(remainingIds);
+
+  function dfs(id: string): string[] | null {
+    if (onStack.has(id)) {
+      const startIdx = path.indexOf(id);
+      return [...path.slice(startIdx), id];
+    }
+    if (!remaining.has(id)) return null;
+    onStack.add(id);
+    path.push(id);
+    for (const req of byId.get(id)?.requires ?? []) {
+      const found = dfs(req);
+      if (found) return found;
+    }
+    path.pop();
+    onStack.delete(id);
+    return null;
+  }
+
+  for (const id of remainingIds) {
+    const found = dfs(id);
+    if (found) return found;
+  }
+  return remainingIds;
+}

package/src/core/create.ts

@@ -0,0 +1,186 @@
+import { type RegisterSWOptions } from 'vite-plugin-pwa/types';
+import { sayHello } from '../hello';
+import type { PluginListItem } from '../plugins';
+import type { AppTypeOverrides, SceneImportListItem } from '../utils';
+import { triggerViteError } from '../utils/vite';
+import { checkWebGL } from '../webgl-check';
+import { Application } from './Application';
+import { registerCaperApp, signalCaperReady, type ICaperAutomation } from './globals';
+import type { IApplication } from './interfaces';
+import { AppConfig } from './types';
+
+type App = AppTypeOverrides['App'];
+
+interface CaperPWA {
+  readonly info: any;
+  register: () => void;
+  onRegisteredSW: (swScriptUrl: string) => void;
+  offlineReady: () => void;
+  onNeedRefresh?: () => void;
+  onRegisterError?: (error: any) => void;
+}
+interface CaperGlobal {
+  APP_NAME: string;
+  APP_VERSION: string | number;
+
+  readonly sceneList: SceneImportListItem<any>[];
+  readonly pluginsList: PluginListItem[];
+
+  get: (key?: string) => any;
+  // pwa
+  pwa: CaperPWA;
+
+  // app discovery + automation
+  apps: Map<string, IApplication>;
+  app?: IApplication;
+  ready(id?: string): Promise<IApplication>;
+  automation: Record<string, ICaperAutomation>;
+  __runtimeManaged?: boolean;
+}
+
+declare global {
+  const Caper: CaperGlobal;
+  const registerSW: (options: RegisterSWOptions) => void;
+  interface Window {
+    Caper: CaperGlobal;
+  }
+}
+
+export const DEFAULT_GAME_CONTAINER_ID = 'caper-game-container';
+
+export function createContainer(id: string) {
+  const container = document.createElement('div');
+  container.setAttribute('id', id);
+  document.body.appendChild(container);
+  return container;
+}
+
+export async function documentReady() {
+  return new Promise((resolve) => {
+    if (document.readyState === 'complete' || document.readyState === 'interactive') {
+      resolve(true);
+    } else {
+      document.addEventListener('DOMContentLoaded', () => {
+        resolve(true);
+      });
+    }
+  });
+}
+
+function addErrorHandler() {
+  // This guard ensures these listeners only run during development
+  if (import.meta.env.DEV) {
+    /**
+     * Listen for standard runtime errors that are not caught.
+     */
+    window.addEventListener('error', (event) => {
+      // Prevent the default browser console error log
+      event.preventDefault();
+
+      triggerViteError({
+        message: event.message,
+        // The error object might contain a more detailed stack trace
+        stack: event.error?.stack,
+        id: event.filename,
+        line: event.lineno,
+        column: event.colno,
+      });
+    });
+
+    /**
+     * Listen for unhandled promise rejections (e.g., from async functions).
+     */
+    window.addEventListener('unhandledrejection', (event) => {
+      // Prevent the default browser console error log
+      event.preventDefault();
+
+      const error = event.reason;
+
+      // The 'reason' can be any value, so we handle Error objects specifically
+      if (error instanceof Error) {
+        triggerViteError({
+          message: error.message,
+          stack: error.stack,
+          // Note: stack parsing would be needed to get file/line for promise rejections
+        });
+      } else {
+        // Handle cases where a non-error value is rejected
+        triggerViteError({
+          message: `Unhandled promise rejection: ${String(event.reason)}`,
+        });
+      }
+    });
+  }
+}
+
+export async function create(
+  config: Partial<AppConfig> = { id: 'CaperApplication' },
+  domElement: string | Window | HTMLElement = DEFAULT_GAME_CONTAINER_ID,
+  speak: boolean = true,
+): Promise<App> {
+  await documentReady();
+  checkWebGL();
+  if (speak) {
+    sayHello();
+  }
+  addErrorHandler();
+  let el: HTMLElement | null = null;
+  if (typeof domElement === 'string') {
+    el = document.getElementById(domElement);
+    if (!el) {
+      el = createContainer(domElement);
+    }
+  } else if (domElement instanceof HTMLElement) {
+    el = domElement;
+  } else if (domElement === window) {
+    el = document.body;
+  }
+  if (!el) {
+    // no element to use
+    throw new Error(
+      'You passed in a DOM Element, but none was found. If you instead pass in a string, a container will be created for you, using the string for its id.',
+    );
+  }
+  if (config.resizeToContainer) {
+    config.resizeTo = el;
+  }
+
+  if (config.useLayout) {
+    config.layout = {
+      // @ts-expect-error some config stuff isn't typed right in @pixi/layout
+      autoUpdate: false,
+      enableDebug: false,
+      debugModificationCount: 0,
+      throttle: 100,
+    };
+  }
+
+  config.container = el;
+  const ApplicationClass = config.application || Application;
+  const instance = new ApplicationClass();
+  await instance.initialize(config, el);
+
+  if (config.useLayout) {
+    instance.stage.layout = {
+      position: 'absolute',
+      width: '100%',
+      height: '100%',
+    };
+  }
+
+  // ensure all plugins are initialized
+  // run framework post-init: the plugin loop + core wiring, then the user hook
+  await instance._postInitialize();
+
+  // register with the global Caper discovery/automation surface
+  registerCaperApp(instance as unknown as IApplication);
+  // when not driven by the vite runtime (which signals readiness itself after
+  // main.ts), signal readiness here so direct create() usage still resolves
+  // Caper.ready()
+  if (!(globalThis as any).Caper?.__runtimeManaged) {
+    signalCaperReady(instance as unknown as IApplication);
+  }
+
+  // return the app instance
+  return instance as App;
+}

package/src/core/globals.ts

@@ -0,0 +1,299 @@
+import type { IActionsPlugin } from '../plugins/actions';
+import type { Application } from './Application';
+import type { IApplication } from './interfaces';
+
+/**
+ * A single entry in an app's automation log ring buffer.
+ */
+export interface AutomationLogEntry {
+  t: number;
+  kind: 'action' | 'state' | 'context';
+  name?: string;
+  data?: unknown;
+}
+
+/**
+ * The automation facade exposed on `window.Caper.automation[appId]` for
+ * Playwright / agent drivers. Only present when automation is enabled (see the
+ * gating rules in {@link registerCaperApp}).
+ */
+export interface ICaperAutomation {
+  readonly appId: string;
+  readonly log: readonly AutomationLogEntry[];
+  action(name: string, data?: unknown): void;
+  getContext(): string;
+  getState(): unknown;
+  registerStateGetter(fn: () => unknown): void;
+  notifyStateChanged(state: unknown): void;
+  waitFor(predicate: (state: unknown) => boolean, opts?: { timeoutMs?: number }): Promise<unknown>;
+}
+
+const LOG_CAP = 200;
+const FALLBACK_APP_ID = 'CaperApplication';
+
+interface CaperReadyResolver {
+  resolve: (app: IApplication) => void;
+  promise: Promise<IApplication>;
+}
+
+interface CaperGlobalInternal {
+  apps: Map<string, IApplication>;
+  app?: IApplication;
+  automation: Record<string, ICaperAutomation>;
+  ready: (id?: string) => Promise<IApplication>;
+  __runtimeManaged?: boolean;
+  /** set by the caper-runtime virtual module from the app's import.meta.env.DEV */
+  __dev?: boolean;
+  /** internal: keyed ready resolvers */
+  __readyResolvers?: Map<string, CaperReadyResolver>;
+  /** internal: ids of apps that have fully finished booting (signalCaperReady) */
+  __readyApps?: Set<string>;
+  [key: string]: unknown;
+}
+
+/**
+ * Guarded dev-env check. The caper-runtime virtual module sets `Caper.__dev`
+ * from the consumer app's `import.meta.env.DEV` (the reliable signal — inside
+ * this pre-built lib, import.meta.env has been compiled away at build time).
+ * The direct import.meta check remains as a fallback for source-linked
+ * consumers. Access to browser/env globals must stay inside a function (never
+ * at module top level) so the built entry can be evaluated in plain Node
+ * during SSR config loading.
+ */
+function isDevEnv(): boolean {
+  try {
+    if ((globalThis as any).Caper?.__dev === true) {
+      return true;
+    }
+    return typeof import.meta !== 'undefined' && (import.meta as any).env?.DEV === true;
+  } catch {
+    return false;
+  }
+}
+
+function automationEnvFlag(): boolean {
+  try {
+    return typeof import.meta !== 'undefined' && (import.meta as any).env?.VITE_CAPER_AUTOMATION === 'true';
+  } catch {
+    return false;
+  }
+}
+
+const FIRST_APP_KEY = '__first__';
+
+/**
+ * Lazily create/return the `globalThis.Caper` object with the automation +
+ * discovery surface installed. No browser globals are touched at module load
+ * time — everything happens inside this function.
+ */
+function ensureCaperGlobal(): CaperGlobalInternal {
+  const g = globalThis as any;
+  const caper: CaperGlobalInternal = (g.Caper ||= {} as CaperGlobalInternal);
+
+  if (!(caper.apps instanceof Map)) {
+    caper.apps = new Map<string, IApplication>();
+  }
+  if (typeof caper.automation !== 'object' || caper.automation === null) {
+    caper.automation = {};
+  }
+  if (!(caper.__readyResolvers instanceof Map)) {
+    caper.__readyResolvers = new Map<string, CaperReadyResolver>();
+  }
+  if (!(caper.__readyApps instanceof Set)) {
+    caper.__readyApps = new Set<string>();
+  }
+
+  if (typeof caper.ready !== 'function') {
+    caper.ready = (id?: string): Promise<IApplication> => {
+      const resolvers = caper.__readyResolvers as Map<string, CaperReadyResolver>;
+      const readyApps = caper.__readyApps as Set<string>;
+      // Only resolve immediately for apps that have FINISHED booting
+      // (signalCaperReady) — registration alone happens earlier, in create(),
+      // before main.ts has run.
+      if (id && readyApps.has(id)) {
+        return Promise.resolve(caper.apps.get(id)!);
+      }
+      // No id: resolve with the first fully-booted app if one exists.
+      if (!id && readyApps.size > 0) {
+        const firstReadyId = readyApps.values().next().value as string;
+        return Promise.resolve(caper.apps.get(firstReadyId)!);
+      }
+      const key = id ?? FIRST_APP_KEY;
+      let entry = resolvers.get(key);
+      if (!entry) {
+        let resolve!: (app: IApplication) => void;
+        const promise = new Promise<IApplication>((res) => {
+          resolve = res;
+        });
+        entry = { resolve, promise };
+        resolvers.set(key, entry);
+      }
+      return entry.promise;
+    };
+  }
+
+  return caper;
+}
+
+/**
+ * Install the `Caper` discovery surface (`apps`, `automation`, `ready()`) on
+ * `globalThis` immediately. The caper-runtime virtual module calls this before
+ * bootstrap so automation drivers (Playwright etc.) can `await Caper.ready()`
+ * from the very first moment the page scripts run, instead of polling for the
+ * function to appear at the end of boot.
+ */
+export function installCaperGlobal(): void {
+  ensureCaperGlobal();
+}
+
+function appIdOf(app: IApplication): string {
+  return (app.config?.id as string) || FALLBACK_APP_ID;
+}
+
+function buildAutomation(app: IApplication): ICaperAutomation {
+  const appId = appIdOf(app);
+  const log: AutomationLogEntry[] = [];
+  let stateGetter: (() => unknown) | undefined;
+  const pending: Array<{ predicate: (state: unknown) => boolean; resolve: (v: unknown) => void }> = [];
+
+  const push = (entry: AutomationLogEntry) => {
+    log.push(entry);
+    if (log.length > LOG_CAP) {
+      log.splice(0, log.length - LOG_CAP);
+    }
+  };
+
+  const getState = (): unknown => (stateGetter ? stateGetter() : undefined);
+
+  const checkPending = (state: unknown) => {
+    if (pending.length === 0) {
+      return;
+    }
+    for (let i = pending.length - 1; i >= 0; i--) {
+      let matched = false;
+      try {
+        matched = pending[i].predicate(state);
+      } catch {
+        matched = false;
+      }
+      if (matched) {
+        const [entry] = pending.splice(i, 1);
+        entry.resolve(state);
+      }
+    }
+  };
+
+  const facade: ICaperAutomation = {
+    appId,
+    get log() {
+      return log as readonly AutomationLogEntry[];
+    },
+    action(name: string, data?: unknown) {
+      app.sendAction(name as any, data);
+    },
+    getContext() {
+      return String(app.actionContext);
+    },
+    getState,
+    registerStateGetter(fn: () => unknown) {
+      stateGetter = fn;
+    },
+    notifyStateChanged(state: unknown) {
+      push({ t: Date.now(), kind: 'state', data: state });
+      checkPending(state);
+    },
+    waitFor(predicate: (state: unknown) => boolean, opts?: { timeoutMs?: number }) {
+      // Check immediately against current state.
+      const current = getState();
+      try {
+        if (predicate(current)) {
+          return Promise.resolve(current);
+        }
+      } catch {
+        // ignore predicate errors on the immediate check
+      }
+      return new Promise<unknown>((resolve, reject) => {
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const entry = {
+          predicate,
+          resolve: (v: unknown) => {
+            if (timer) {
+              clearTimeout(timer);
+            }
+            resolve(v);
+          },
+        };
+        pending.push(entry);
+        if (opts?.timeoutMs != null) {
+          timer = setTimeout(() => {
+            const idx = pending.indexOf(entry);
+            if (idx >= 0) {
+              pending.splice(idx, 1);
+            }
+            reject(new Error(`waitFor timed out after ${opts.timeoutMs}ms`));
+          }, opts.timeoutMs);
+        }
+      });
+    },
+  };
+
+  // Subscribe to action dispatches + context changes for the log, and re-check
+  // pending waitFor predicates after each dispatched action.
+  const actions = app.getPlugin<IActionsPlugin>('actions');
+  if (actions) {
+    actions.onActionDispatched?.connect((detail) => {
+      push({ t: Date.now(), kind: 'action', name: String(detail.id), data: detail.data });
+      checkPending(getState());
+    });
+    actions.onActionContextChanged.connect((context) => {
+      push({ t: Date.now(), kind: 'context', name: String(context) });
+    });
+  }
+
+  return facade;
+}
+
+/**
+ * Register an app with the global `Caper` discovery surface. Adds it to
+ * `Caper.apps` under its config id, sets `Caper.app` to the most-recently
+ * created app, and — when automation is enabled — builds the automation facade
+ * and stores it at `Caper.automation[id]` (and on the app instance).
+ *
+ * Automation is enabled when any of: dev env, `config.automation === true`, or
+ * `VITE_CAPER_AUTOMATION === 'true'`.
+ */
+export function registerCaperApp(app: IApplication): void {
+  const caper = ensureCaperGlobal();
+  const id = appIdOf(app);
+  caper.apps.set(id, app);
+  caper.app = app;
+
+  const automationEnabled = isDevEnv() || app.config?.automation === true || automationEnvFlag();
+  if (automationEnabled) {
+    const facade = buildAutomation(app);
+    caper.automation[id] = facade;
+    (app as Application).automation = facade;
+  }
+}
+
+/**
+ * Resolve any pending `Caper.ready()` promises for this app — both the
+ * id-keyed resolver and the first-app resolver.
+ */
+export function signalCaperReady(app: IApplication): void {
+  const caper = ensureCaperGlobal();
+  const id = appIdOf(app);
+  (caper.__readyApps as Set<string>).add(id);
+  const resolvers = caper.__readyResolvers as Map<string, CaperReadyResolver>;
+
+  const idEntry = resolvers.get(id);
+  if (idEntry) {
+    idEntry.resolve(app);
+    resolvers.delete(id);
+  }
+  const firstEntry = resolvers.get(FIRST_APP_KEY);
+  if (firstEntry) {
+    firstEntry.resolve(app);
+    resolvers.delete(FIRST_APP_KEY);
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,6 @@
+export * from './config';
+export { create, createContainer } from './create';
+export * from './globals';
+export * from './interfaces';
+export * from './registries';
+export * from './types';