@cymohanshu/runtime 0.1.0

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@cymohanshu/runtime",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./vue": {
+      "types": "./src/adapters/vue/index.ts",
+      "import": "./src/adapters/vue/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "!src/__tests__"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  }
+}

package/src/adapters/browserAdapter.ts

@@ -0,0 +1,41 @@
+import type { RuntimeBrowser, RuntimeEnv, RuntimeInputMode, RuntimePlatform } from '../types';
+
+export function detectBrowser(userAgent: string): RuntimeBrowser {
+  const ua = userAgent.toLowerCase();
+  if (ua.includes('edg/')) return 'edge';
+  if (ua.includes('chrome/') || ua.includes('chromium/')) return 'chrome';
+  if (ua.includes('safari/') && !ua.includes('chrome/')) return 'safari';
+  return 'unknown';
+}
+
+export function detectPlatform(win: Window): RuntimePlatform {
+  const ua = win.navigator.userAgent.toLowerCase();
+  if (win.self !== win.top) return 'webview';
+  if (ua.includes('tablet') || ua.includes('ipad')) return 'tablet';
+  if (ua.includes('whiteboard')) return 'whiteboard';
+  return 'desktop';
+}
+
+export function detectInputMode(win: Window): RuntimeInputMode {
+  const nav = win.navigator as Navigator & { maxTouchPoints?: number };
+  const hasTouch = (nav.maxTouchPoints ?? 0) > 0;
+  const hasPointer = 'PointerEvent' in win;
+
+  if (hasTouch && hasPointer) return 'mixed';
+  if (hasTouch) return 'touch';
+  return 'mouse';
+}
+
+export function detectRuntimeEnv(win: Window): RuntimeEnv {
+  const documentElement = win.document;
+  return {
+    platform: detectPlatform(win),
+    inputMode: detectInputMode(win),
+    browser: detectBrowser(win.navigator.userAgent),
+    dpr: win.devicePixelRatio || 1,
+    supportsPointerEvent: 'PointerEvent' in win,
+    supportsFullscreen:
+      'requestFullscreen' in documentElement.documentElement &&
+      'fullscreenElement' in documentElement,
+  };
+}

package/src/adapters/vue/createVueCourseware.ts

@@ -0,0 +1,54 @@
+import { createApp, type App as VueApp, type Component } from 'vue';
+import type { CoursewareModule, RuntimeContext } from '../../types';
+import { runtimeContextKey } from './runtimeContext';
+
+export interface VueCoursewareExpose {
+  resetCourseware?: () => void | Promise<void>;
+  pauseCourseware?: () => void | Promise<void>;
+  resumeCourseware?: () => void | Promise<void>;
+}
+
+export interface VueCoursewareOptions {
+  rootClassName?: string;
+}
+
+export function createVueCourseware(
+  rootComponent: Component,
+  options: VueCoursewareOptions = {},
+): CoursewareModule {
+  const rootClassName = options.rootClassName ?? 'courseware-root';
+  let app: VueApp<Element> | undefined;
+  let root: HTMLElement | undefined;
+  let exposed: VueCoursewareExpose | undefined;
+
+  return {
+    mount(context: RuntimeContext): void {
+      root = document.createElement('div');
+      root.className = rootClassName;
+      context.container.replaceChildren(root);
+
+      app = createApp(rootComponent);
+      app.provide(runtimeContextKey, context);
+      exposed = app.mount(root) as VueCoursewareExpose;
+    },
+
+    unmount(): void {
+      app?.unmount();
+      app = undefined;
+      root = undefined;
+      exposed = undefined;
+    },
+
+    async reset(): Promise<void> {
+      await exposed?.resetCourseware?.();
+    },
+
+    async pause(): Promise<void> {
+      await exposed?.pauseCourseware?.();
+    },
+
+    async resume(): Promise<void> {
+      await exposed?.resumeCourseware?.();
+    },
+  };
+}

package/src/adapters/vue/index.ts

@@ -0,0 +1,3 @@
+export { createVueCourseware } from './createVueCourseware';
+export type { VueCoursewareExpose, VueCoursewareOptions } from './createVueCourseware';
+export { runtimeContextKey } from './runtimeContext';

package/src/adapters/vue/runtimeContext.ts

@@ -0,0 +1,4 @@
+import type { InjectionKey } from 'vue';
+import type { RuntimeContext } from '../../types';
+
+export const runtimeContextKey: InjectionKey<RuntimeContext> = Symbol('RuntimeContext');

package/src/createRuntime.ts

@@ -0,0 +1,100 @@
+import { detectRuntimeEnv } from './adapters/browserAdapter';
+import { createAssetService } from './services/assets';
+import { createEventBus } from './services/eventBus';
+import { createInputService } from './services/input';
+import { createLogger } from './services/logger';
+import { createStorageService } from './services/storage';
+import { createViewportService } from './services/viewport';
+import type { CoursewareModule, Runtime, RuntimeContext, RuntimeOptions } from './types';
+
+export function createRuntime(options: RuntimeOptions): Runtime {
+  const windowRef = options.windowRef ?? window;
+  const logger = options.logger ?? createLogger();
+  let currentModule: CoursewareModule | undefined;
+
+  const input = createInputService({
+    root: options.container,
+    windowRef,
+  });
+  const viewport = createViewportService({
+    container: options.container,
+    designWidth: options.designWidth,
+    designHeight: options.designHeight,
+    windowRef,
+  });
+
+  const context: RuntimeContext = {
+    container: options.container,
+    env: detectRuntimeEnv(windowRef),
+    input,
+    viewport,
+    assets: createAssetService(options.assetBaseUrl),
+    storage: createStorageService(windowRef.localStorage, options.storagePrefix),
+    logger,
+    events: createEventBus(),
+  };
+
+  const handleRuntimeError = (event: ErrorEvent): void => {
+    logger.error('Unhandled runtime error.', event.error ?? event.message);
+    context.events.emit('runtime:error', event.error ?? event.message);
+  };
+
+  const handleUnhandledRejection = (event: PromiseRejectionEvent): void => {
+    logger.error('Unhandled runtime rejection.', event.reason);
+    context.events.emit('runtime:error', event.reason);
+  };
+
+  windowRef.addEventListener('error', handleRuntimeError);
+  windowRef.addEventListener('unhandledrejection', handleUnhandledRejection);
+
+  return {
+    context,
+
+    async mount(module: CoursewareModule): Promise<void> {
+      if (currentModule) await this.unmount();
+      currentModule = module;
+
+      try {
+        await module.mount(context);
+      } catch (error) {
+        logger.error('Failed to mount courseware module.', error);
+        context.events.emit('runtime:error', error);
+        throw error;
+      }
+    },
+
+    async unmount(): Promise<void> {
+      if (!currentModule) return;
+      const module = currentModule;
+      currentModule = undefined;
+      await module.unmount();
+    },
+
+    async reset(): Promise<void> {
+      await currentModule?.reset?.();
+    },
+
+    async destroy(): Promise<void> {
+      await this.unmount();
+      input.destroy();
+      viewport.destroy();
+      context.events.clear();
+      windowRef.removeEventListener('error', handleRuntimeError);
+      windowRef.removeEventListener('unhandledrejection', handleUnhandledRejection);
+    },
+  };
+}
+
+export type {
+  AssetService,
+  CoursewareModule,
+  EventBus,
+  InputService,
+  LoggerService,
+  Runtime,
+  RuntimeContext,
+  RuntimeEnv,
+  RuntimeOptions,
+  StorageService,
+  ViewportService,
+} from './types';

package/src/index.ts

@@ -0,0 +1,22 @@
+export { createRuntime } from './createRuntime';
+export type {
+  AssetService,
+  CoursewareModule,
+  Dispose,
+  EventBus,
+  InputService,
+  LoggerService,
+  Point,
+  PointerHandler,
+  PointerPayload,
+  ResizeHandler,
+  Runtime,
+  RuntimeBrowser,
+  RuntimeContext,
+  RuntimeEnv,
+  RuntimeInputMode,
+  RuntimeOptions,
+  RuntimePlatform,
+  StorageService,
+  ViewportService,
+} from './types';

package/src/services/assets.ts

@@ -0,0 +1,42 @@
+import type { AssetService } from '../types';
+
+export function createAssetService(baseUrl = '', fetcher: typeof fetch = fetch): AssetService {
+  const normalizedBase = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+
+  const resolve = (path: string): string => {
+    if (/^(https?:)?\/\//.test(path) || path.startsWith('data:') || path.startsWith('blob:')) {
+      return path;
+    }
+
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    return `${normalizedBase}${normalizedPath}`;
+  };
+
+  return {
+    resolve,
+
+    loadImage(url: string): Promise<HTMLImageElement> {
+      return new Promise((resolveImage, reject) => {
+        const image = new Image();
+        image.onload = () => resolveImage(image);
+        image.onerror = () => reject(new Error(`Failed to load image: ${url}`));
+        image.src = resolve(url);
+      });
+    },
+
+    async loadSvg(url: string): Promise<string> {
+      const response = await fetcher(resolve(url));
+      if (!response.ok) throw new Error(`Failed to load svg: ${url}`);
+      return response.text();
+    },
+
+    async preload(urls: string[]): Promise<void> {
+      await Promise.all(
+        urls.map((url) => {
+          if (url.toLowerCase().endsWith('.svg')) return this.loadSvg(url);
+          return this.loadImage(url);
+        }),
+      );
+    },
+  };
+}

package/src/services/eventBus.ts

@@ -0,0 +1,28 @@
+import type { Dispose, EventBus } from '../types';
+
+export function createEventBus(): EventBus {
+  const handlers = new Map<string, Set<(payload: unknown) => void>>();
+
+  return {
+    on<T>(eventName: string, handler: (payload: T) => void): Dispose {
+      const bucket = handlers.get(eventName) ?? new Set();
+      bucket.add(handler as (payload: unknown) => void);
+      handlers.set(eventName, bucket);
+
+      return () => {
+        bucket.delete(handler as (payload: unknown) => void);
+        if (bucket.size === 0) handlers.delete(eventName);
+      };
+    },
+
+    emit<T>(eventName: string, payload: T): void {
+      for (const handler of handlers.get(eventName) ?? []) {
+        handler(payload);
+      }
+    },
+
+    clear(): void {
+      handlers.clear();
+    },
+  };
+}

package/src/services/input.ts

@@ -0,0 +1,115 @@
+import type { Dispose, InputService, Point, PointerHandler, PointerPayload } from '../types';
+
+interface InputOptions {
+  root: HTMLElement;
+  windowRef: Window;
+}
+
+type InputEventName = 'pointerdown' | 'pointermove' | 'pointerup';
+
+export function createInputService(options: InputOptions): InputService {
+  const { root, windowRef } = options;
+  const disposers: Dispose[] = [];
+
+  const toPayload = (event: Event): PointerPayload => {
+    if (isPointerEvent(event)) {
+      return {
+        id: String(event.pointerId),
+        x: event.clientX,
+        y: event.clientY,
+        type: normalizePointerType(event.pointerType),
+        target: event.target,
+        originalEvent: event,
+      };
+    }
+
+    if (isTouchEvent(event)) {
+      const touch = event.changedTouches[0] ?? event.touches[0];
+      return {
+        id: touch ? String(touch.identifier) : 'touch',
+        x: touch?.clientX ?? 0,
+        y: touch?.clientY ?? 0,
+        type: 'touch',
+        target: event.target,
+        originalEvent: event,
+      };
+    }
+
+    const mouseEvent = event as MouseEvent;
+    return {
+      id: 'mouse',
+      x: mouseEvent.clientX,
+      y: mouseEvent.clientY,
+      type: 'mouse',
+      target: event.target,
+      originalEvent: event,
+    };
+  };
+
+  const bind = (eventName: InputEventName, fallbackNames: string[], handler: PointerHandler): Dispose => {
+    const listener = (event: Event): void => {
+      handler(toPayload(event));
+    };
+
+    if (typeof (windowRef as Window & { PointerEvent?: typeof PointerEvent }).PointerEvent === 'function') {
+      root.addEventListener(eventName, listener);
+      const dispose = () => root.removeEventListener(eventName, listener);
+      disposers.push(dispose);
+      return dispose;
+    }
+
+    for (const fallbackName of fallbackNames) {
+      root.addEventListener(fallbackName, listener, { passive: false });
+    }
+
+    const dispose = () => {
+      for (const fallbackName of fallbackNames) {
+        root.removeEventListener(fallbackName, listener);
+      }
+    };
+    disposers.push(dispose);
+    return dispose;
+  };
+
+  return {
+    onPointerDown(handler: PointerHandler): Dispose {
+      return bind('pointerdown', ['mousedown', 'touchstart'], handler);
+    },
+
+    onPointerMove(handler: PointerHandler): Dispose {
+      return bind('pointermove', ['mousemove', 'touchmove'], handler);
+    },
+
+    onPointerUp(handler: PointerHandler): Dispose {
+      return bind('pointerup', ['mouseup', 'touchend', 'touchcancel'], handler);
+    },
+
+    getLocalPoint(event: Event, target: HTMLElement): Point {
+      const payload = toPayload(event);
+      const rect = target.getBoundingClientRect();
+      return {
+        x: payload.x - rect.left,
+        y: payload.y - rect.top,
+      };
+    },
+
+    destroy(): void {
+      for (const dispose of disposers.splice(0)) {
+        dispose();
+      }
+    },
+  };
+}
+
+function normalizePointerType(pointerType: string): 'mouse' | 'touch' | 'pen' {
+  if (pointerType === 'touch' || pointerType === 'pen') return pointerType;
+  return 'mouse';
+}
+
+function isPointerEvent(event: Event): event is PointerEvent {
+  return 'pointerId' in event && 'pointerType' in event;
+}
+
+function isTouchEvent(event: Event): event is TouchEvent {
+  return 'changedTouches' in event || 'touches' in event;
+}

package/src/services/logger.ts

@@ -0,0 +1,25 @@
+import type { LoggerService } from '../types';
+
+export function createLogger(enabled = true): LoggerService {
+  const write = (level: 'info' | 'warn' | 'error', message: string, data?: unknown): void => {
+    if (!enabled) return;
+    const prefix = `[@cymohanshu/runtime] ${message}`;
+    if (data === undefined) {
+      console[level](prefix);
+      return;
+    }
+    console[level](prefix, data);
+  };
+
+  return {
+    info(message, data) {
+      write('info', message, data);
+    },
+    warn(message, data) {
+      write('warn', message, data);
+    },
+    error(message, error) {
+      write('error', message, error);
+    },
+  };
+}

package/src/services/storage.ts

@@ -0,0 +1,26 @@
+import type { StorageService } from '../types';
+
+export function createStorageService(storage: Storage, prefix = 'courseware'): StorageService {
+  const namespaced = (key: string) => `${prefix}:${key}`;
+
+  return {
+    get<T>(key: string, fallback: T): T {
+      const raw = storage.getItem(namespaced(key));
+      if (raw == null) return fallback;
+
+      try {
+        return JSON.parse(raw) as T;
+      } catch {
+        return fallback;
+      }
+    },
+
+    set<T>(key: string, value: T): void {
+      storage.setItem(namespaced(key), JSON.stringify(value));
+    },
+
+    remove(key: string): void {
+      storage.removeItem(namespaced(key));
+    },
+  };
+}

package/src/services/viewport.ts

@@ -0,0 +1,81 @@
+import type { Dispose, Point, ResizeHandler, ViewportService } from '../types';
+
+interface ViewportOptions {
+  container: HTMLElement;
+  designWidth: number;
+  designHeight: number;
+  windowRef: Window;
+}
+
+export function createViewportService(options: ViewportOptions): ViewportService {
+  const { container, designWidth, designHeight, windowRef } = options;
+  const handlers = new Set<ResizeHandler>();
+  let scale = 1;
+  let size = { width: designWidth, height: designHeight };
+
+  const measure = (): void => {
+    const rect = container.getBoundingClientRect();
+    const width = rect.width || designWidth;
+    const height = rect.height || designHeight;
+    scale = Math.min(width / designWidth, height / designHeight);
+    size = { width, height };
+    container.style.setProperty('--runtime-scale', String(scale));
+    container.style.setProperty('--runtime-design-width', `${designWidth}px`);
+    container.style.setProperty('--runtime-design-height', `${designHeight}px`);
+
+    for (const handler of handlers) {
+      handler({ ...size, scale });
+    }
+  };
+
+  const onWindowResize = (): void => measure();
+  windowRef.addEventListener('resize', onWindowResize);
+  measure();
+
+  return {
+    getSize() {
+      return size;
+    },
+
+    getScale() {
+      return scale;
+    },
+
+    toDesignPoint(point: Point): Point {
+      return {
+        x: point.x / scale,
+        y: point.y / scale,
+      };
+    },
+
+    onResize(handler: ResizeHandler): Dispose {
+      handlers.add(handler);
+      return () => {
+        handlers.delete(handler);
+      };
+    },
+
+    async requestFullscreen(): Promise<void> {
+      const fullscreenElement = container as HTMLElement & {
+        webkitRequestFullscreen?: () => Promise<void> | void;
+      };
+
+      if (fullscreenElement.requestFullscreen) {
+        await fullscreenElement.requestFullscreen();
+        return;
+      }
+
+      if (fullscreenElement.webkitRequestFullscreen) {
+        await fullscreenElement.webkitRequestFullscreen();
+        return;
+      }
+
+      throw new Error('Fullscreen is not supported in this environment.');
+    },
+
+    destroy(): void {
+      windowRef.removeEventListener('resize', onWindowResize);
+      handlers.clear();
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,110 @@
+export type Dispose = () => void;
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export type RuntimePlatform = 'desktop' | 'tablet' | 'whiteboard' | 'webview';
+export type RuntimeInputMode = 'mouse' | 'touch' | 'pen' | 'mixed';
+export type RuntimeBrowser = 'chrome' | 'edge' | 'safari' | 'unknown';
+
+export interface RuntimeEnv {
+  platform: RuntimePlatform;
+  inputMode: RuntimeInputMode;
+  browser: RuntimeBrowser;
+  dpr: number;
+  supportsPointerEvent: boolean;
+  supportsFullscreen: boolean;
+}
+
+export interface PointerPayload {
+  id: string;
+  x: number;
+  y: number;
+  type: 'mouse' | 'touch' | 'pen';
+  target?: EventTarget | null;
+  originalEvent: Event;
+}
+
+export type PointerHandler = (payload: PointerPayload) => void;
+export type ResizeHandler = (size: { width: number; height: number; scale: number }) => void;
+
+export interface InputService {
+  onPointerDown(handler: PointerHandler): Dispose;
+  onPointerMove(handler: PointerHandler): Dispose;
+  onPointerUp(handler: PointerHandler): Dispose;
+  getLocalPoint(event: Event, target: HTMLElement): Point;
+  destroy(): void;
+}
+
+export interface ViewportService {
+  getSize(): { width: number; height: number };
+  getScale(): number;
+  toDesignPoint(point: Point): Point;
+  onResize(handler: ResizeHandler): Dispose;
+  requestFullscreen(): Promise<void>;
+  destroy(): void;
+}
+
+export interface AssetService {
+  loadImage(url: string): Promise<HTMLImageElement>;
+  loadSvg(url: string): Promise<string>;
+  preload(urls: string[]): Promise<void>;
+  resolve(path: string): string;
+}
+
+export interface StorageService {
+  get<T>(key: string, fallback: T): T;
+  set<T>(key: string, value: T): void;
+  remove(key: string): void;
+}
+
+export interface LoggerService {
+  info(message: string, data?: unknown): void;
+  warn(message: string, data?: unknown): void;
+  error(message: string, error?: unknown): void;
+}
+
+export interface EventBus {
+  on<T>(eventName: string, handler: (payload: T) => void): Dispose;
+  emit<T>(eventName: string, payload: T): void;
+  clear(): void;
+}
+
+export interface RuntimeContext {
+  container: HTMLElement;
+  env: RuntimeEnv;
+  input: InputService;
+  viewport: ViewportService;
+  assets: AssetService;
+  storage: StorageService;
+  logger: LoggerService;
+  events: EventBus;
+}
+
+export interface CoursewareModule {
+  mount(context: RuntimeContext): void | Promise<void>;
+  unmount(): void | Promise<void>;
+  reset?(): void | Promise<void>;
+  pause?(): void | Promise<void>;
+  resume?(): void | Promise<void>;
+}
+
+export interface RuntimeOptions {
+  container: HTMLElement;
+  designWidth: number;
+  designHeight: number;
+  assetBaseUrl?: string;
+  storagePrefix?: string;
+  logger?: LoggerService;
+  windowRef?: Window;
+}
+
+export interface Runtime {
+  context: RuntimeContext;
+  mount(module: CoursewareModule): Promise<void>;
+  unmount(): Promise<void>;
+  reset(): Promise<void>;
+  destroy(): Promise<void>;
+}