@hypen-space/core 0.4.2 → 0.4.5

package/dist/loader.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Component Loader
+ *
+ * Loads and registers Hypen components from file system.
+ * Works in both Node.js and Bun environments.
+ */
+import type { HypenModuleDefinition } from "./app.js";
+export interface ComponentDefinition {
+    name: string;
+    module: HypenModuleDefinition<any>;
+    template: string;
+    path: string;
+}
+export declare class ComponentLoader {
+    private components;
+    /**
+     * Register a component with its module and template
+     */
+    register(name: string, module: HypenModuleDefinition<any>, template: string, path?: string): void;
+    /**
+     * Get a registered component by name
+     */
+    get(name: string): ComponentDefinition | undefined;
+    /**
+     * Check if a component is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered component names
+     */
+    getNames(): string[];
+    /**
+     * Get all registered components
+     */
+    getAll(): ComponentDefinition[];
+    /**
+     * Clear all registered components
+     */
+    clear(): void;
+    /**
+     * Load a component from a directory
+     * Expects: component.ts and component.hypen in the same directory
+     */
+    loadFromDirectory(name: string, dirPath: string): Promise<void>;
+    /**
+     * Auto-load all components from a directory
+     * Scans for subdirectories containing component.ts and component.hypen
+     */
+    loadFromComponentsDir(baseDir: string): Promise<void>;
+}
+export declare const componentLoader: ComponentLoader;

package/dist/logger.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Configurable Debug Logger
+ *
+ * Provides environment-aware logging that can be disabled in production.
+ * Supports log levels, tagged output, and performance timing.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error" | "none";
+export interface LoggerConfig {
+    /** Minimum log level (default: "debug" in dev, "error" in prod) */
+    level: LogLevel;
+    /** Enable colored output (default: true) */
+    colors: boolean;
+    /** Include timestamps (default: false) */
+    timestamps: boolean;
+    /** Custom log handler (default: console) */
+    handler?: LogHandler;
+}
+export interface LogHandler {
+    debug(tag: string, ...args: unknown[]): void;
+    info(tag: string, ...args: unknown[]): void;
+    warn(tag: string, ...args: unknown[]): void;
+    error(tag: string, ...args: unknown[]): void;
+}
+/**
+ * Set the global log level
+ */
+export declare function setLogLevel(level: LogLevel): void;
+/**
+ * Get the current log level
+ */
+export declare function getLogLevel(): LogLevel;
+/**
+ * Configure the logger
+ */
+export declare function configureLogger(options: Partial<LoggerConfig>): void;
+/**
+ * Enable all logging (sets level to "debug")
+ */
+export declare function enableLogging(): void;
+/**
+ * Disable all logging (sets level to "none")
+ */
+export declare function disableLogging(): void;
+/**
+ * Enable debug mode - alias for enableLogging()
+ * Call this at app startup to see all debug logs
+ *
+ * @example
+ * ```typescript
+ * import { setDebugMode } from "@hypen-space/core";
+ * setDebugMode(true);
+ * ```
+ */
+export declare function setDebugMode(enabled: boolean): void;
+/**
+ * Check if debug mode is enabled
+ */
+export declare function isDebugMode(): boolean;
+/**
+ * Tagged logger instance
+ *
+ * @example
+ * ```typescript
+ * const log = createLogger("MyComponent");
+ * log.debug("initialized with", { props });
+ * log.error("failed to load", error);
+ * ```
+ */
+export declare class Logger {
+    private readonly tag;
+    constructor(tag: string);
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    /**
+     * Time a function execution
+     */
+    time<T>(label: string, fn: () => T): T;
+    /**
+     * Time an async function execution
+     */
+    timeAsync<T>(label: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Create a child logger with additional context
+     */
+    child(subTag: string): Logger;
+    /**
+     * Conditionally log based on a condition
+     */
+    debugIf(condition: boolean, ...args: unknown[]): void;
+    warnIf(condition: boolean, ...args: unknown[]): void;
+    errorIf(condition: boolean, ...args: unknown[]): void;
+    /**
+     * Log once (useful for deprecation warnings)
+     */
+    private loggedOnce;
+    warnOnce(key: string, ...args: unknown[]): void;
+    debugOnce(key: string, ...args: unknown[]): void;
+}
+/**
+ * Create a tagged logger
+ *
+ * @example
+ * ```typescript
+ * const log = createLogger("Router");
+ * log.info("navigating to", path);
+ * ```
+ */
+export declare function createLogger(tag: string): Logger;
+/**
+ * Default logger for general use
+ */
+export declare const logger: Logger;
+/**
+ * Shorthand logging functions for quick use
+ * Prefer createLogger() for component-specific logging
+ */
+export declare const log: {
+    debug: (tag: string, ...args: unknown[]) => void;
+    info: (tag: string, ...args: unknown[]) => void;
+    warn: (tag: string, ...args: unknown[]) => void;
+    error: (tag: string, ...args: unknown[]) => void;
+};
+export declare const frameworkLoggers: {
+    hypen: Logger;
+    engine: Logger;
+    router: Logger;
+    state: Logger;
+    events: Logger;
+    remote: Logger;
+    renderer: Logger;
+    module: Logger;
+    lifecycle: Logger;
+    loader: Logger;
+    context: Logger;
+    discovery: Logger;
+    plugin: Logger;
+    canvas: Logger;
+    debug: Logger;
+};

package/dist/managed-router.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Managed Router — orchestrates module mount/unmount on route changes.
+ *
+ * When the router navigates to a route:
+ * 1. Unmounts the previous module (destroy instance, unregister from GlobalContext)
+ * 2. Mounts the new module (create instance with namespaced state, register)
+ *
+ * Module names are used as state prefixes (lowercased) for isolation.
+ */
+import type { IEngine, HypenModuleDefinition } from "./app.js";
+import { HypenModuleInstance, HypenApp } from "./app.js";
+import type { HypenRouter } from "./router.js";
+import type { HypenGlobalContext } from "./context.js";
+export interface RouteDefinition {
+    /** Route path pattern (e.g., "/", "/profile/:id") */
+    path: string;
+    /** Component name — used to look up in app registry */
+    component: string;
+    /** Inline module definition (alternative to registry lookup) */
+    module?: HypenModuleDefinition;
+}
+export declare class ManagedRouter {
+    private router;
+    private engine;
+    private registry;
+    private globalContext;
+    private routes;
+    private activeModule;
+    private activeRoute;
+    private unsubscribe;
+    /** Cached instances for modules with persist=true */
+    private persistedModules;
+    constructor(router: HypenRouter, engine: IEngine, registry: HypenApp, globalContext: HypenGlobalContext);
+    /**
+     * Add a route definition.
+     */
+    addRoute(route: RouteDefinition): this;
+    /**
+     * Start listening for route changes and mount the initial route.
+     */
+    start(): void;
+    /**
+     * Stop listening and unmount the active module.
+     * Also destroys all persisted modules.
+     */
+    stop(): void;
+    /**
+     * Get the currently active module instance.
+     */
+    getActiveModule(): HypenModuleInstance | null;
+    /**
+     * Get the currently active route.
+     */
+    getActiveRoute(): RouteDefinition | null;
+    private handleRouteChange;
+    private matchRoute;
+    private mount;
+    private unmountActive;
+}

package/dist/plugin.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Enhanced Bun Plugin for Hypen
+ *
+ * Automatically pairs .hypen templates with their TypeScript modules.
+ *
+ * Usage:
+ *   import Counter from "./Counter.hypen";
+ *   // Returns: { module, template, name: "Counter" }
+ *
+ * Supported conventions:
+ *   1. Sibling: Name.ts + Name.hypen
+ *   2. Folder: Name/component.ts + Name/component.hypen
+ *   3. Index: Name/index.ts + Name/index.hypen
+ */
+import type { BunPlugin } from "bun";
+export interface HypenPluginOptions {
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+    /**
+     * Custom patterns for finding module files
+     * Default: ["sibling", "component", "index"]
+     */
+    patterns?: ("sibling" | "component" | "index")[];
+}
+/**
+ * Create the enhanced Hypen plugin for Bun
+ */
+export declare function hypenPlugin(options?: HypenPluginOptions): BunPlugin;
+/**
+ * Default plugin instance with standard options
+ */
+export declare const defaultHypenPlugin: BunPlugin;
+/**
+ * Register the plugin globally (call this in your preload file)
+ */
+export declare function registerHypenPlugin(options?: HypenPluginOptions): void;
+export default hypenPlugin;

package/dist/remote/client.d.ts

@@ -0,0 +1,154 @@
+/**
+ * RemoteEngine - Connect to a remote Hypen app over WebSocket
+ * Platform-agnostic client (uses standard WebSocket API)
+ *
+ * Usage:
+ * ```typescript
+ * const engine = new RemoteEngine("ws://localhost:3000", {
+ *   session: {
+ *     id: localStorage.getItem("sessionId") ?? undefined,
+ *     props: { platform: "web", version: "1.0" }
+ *   }
+ * });
+ *
+ * engine.onSessionEstablished(({ sessionId, isNew, isRestored }) => {
+ *   localStorage.setItem("sessionId", sessionId);
+ *   console.log(isRestored ? "Welcome back!" : "New session");
+ * });
+ *
+ * engine.onSessionExpired((reason) => {
+ *   localStorage.removeItem("sessionId");
+ * });
+ *
+ * const result = await engine.connect();
+ * if (!result.ok) {
+ *   console.error("Connection failed:", result.error);
+ * }
+ * ```
+ */
+import type { Patch } from "../types.js";
+import { type Result, ConnectionError } from "../result.js";
+import { type Disposable } from "../disposable.js";
+export type RemoteConnectionState = "disconnected" | "connecting" | "connected" | "error";
+/**
+ * Session configuration for the client
+ */
+export interface SessionOptions {
+    /** Session ID to resume (omit for new session) */
+    id?: string;
+    /** Client metadata (platform, version, userId, etc.) */
+    props?: Record<string, unknown>;
+}
+/**
+ * Session information received from server
+ */
+export interface SessionInfo {
+    sessionId: string;
+    isNew: boolean;
+    isRestored: boolean;
+}
+export interface RemoteEngineOptions {
+    autoReconnect?: boolean;
+    reconnectInterval?: number;
+    maxReconnectAttempts?: number;
+    /** Session configuration */
+    session?: SessionOptions;
+}
+/**
+ * Client-side engine that connects to a remote Hypen app
+ */
+export declare class RemoteEngine implements Disposable {
+    private ws;
+    private readonly url;
+    private state;
+    private readonly options;
+    private reconnectAttempts;
+    private readonly disposables;
+    private reconnectDisposable;
+    private currentSessionId;
+    private readonly sessionOptions?;
+    private readonly patchCallbacks;
+    private readonly stateCallbacks;
+    private readonly connectionCallbacks;
+    private readonly disconnectionCallbacks;
+    private readonly errorCallbacks;
+    private readonly sessionEstablishedCallbacks;
+    private readonly sessionExpiredCallbacks;
+    private currentState;
+    private currentRevision;
+    private moduleName;
+    constructor(url: string, options?: RemoteEngineOptions);
+    /**
+     * Connect to the remote server
+     * Returns a Result indicating success or failure
+     */
+    connect(): Promise<Result<void, ConnectionError>>;
+    /**
+     * Send hello message to establish session
+     */
+    private sendHello;
+    /**
+     * Disconnect from the remote server and clean up resources
+     */
+    disconnect(): void;
+    /**
+     * Dispose all resources (alias for disconnect)
+     */
+    dispose(): void;
+    /**
+     * Dispatch an action to the remote server
+     */
+    dispatchAction(action: string, payload?: unknown): void;
+    /**
+     * Register callback for patches
+     */
+    onPatches(callback: (patches: Patch[]) => void): this;
+    /**
+     * Register callback for state updates
+     */
+    onStateUpdate(callback: (state: unknown) => void): this;
+    /**
+     * Register callback for connection
+     */
+    onConnect(callback: () => void): this;
+    /**
+     * Register callback for disconnection
+     */
+    onDisconnect(callback: () => void): this;
+    /**
+     * Register callback for errors
+     */
+    onError(callback: (error: Error) => void): this;
+    /**
+     * Register callback for session establishment
+     * Called when server confirms session (new or resumed)
+     */
+    onSessionEstablished(callback: (info: SessionInfo) => void): this;
+    /**
+     * Register callback for session expiration
+     * Called when session is kicked or expires
+     */
+    onSessionExpired(callback: (reason: string) => void): this;
+    /**
+     * Get current connection state
+     */
+    getConnectionState(): RemoteConnectionState;
+    /**
+     * Get current app state
+     */
+    getCurrentState(): unknown;
+    /**
+     * Get current revision
+     */
+    getRevision(): number;
+    /**
+     * Get current session ID
+     */
+    getSessionId(): string | null;
+    private handleMessage;
+    private handleSessionAck;
+    private handleSessionExpired;
+    private handleInitialTree;
+    private handlePatch;
+    private attemptReconnect;
+}

package/dist/remote/client.js

@@ -312,7 +312,20 @@ function all(results) {
   }
   return Ok(values);
 }
-var HypenError, ActionError, ConnectionError, StateError;
+function classifyEngineError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  if (message.startsWith("Parse error:")) {
+    return new ParseError(message);
+  }
+  if (message.startsWith("Invalid state:") || message.startsWith("Invalid state patch:")) {
+    return new StateError(message);
+  }
+  if (message.startsWith("Parent node not found:")) {
+    return new RenderError(message);
+  }
+  return new RenderError(message);
+}
+var HypenError, ActionError, ConnectionError, StateError, ParseError, RenderError;
 var init_result = __esm(() => {
   HypenError = class HypenError extends Error {
     code;
@@ -362,6 +375,25 @@ var init_result = __esm(() => {
       this.path = path;
     }
   };
+  ParseError = class ParseError extends HypenError {
+    source;
+    constructor(message, source, cause) {
+      super("PARSE_ERROR", message, {
+        context: { source },
+        cause: cause instanceof Error ? cause : undefined
+      });
+      this.name = "ParseError";
+      this.source = source;
+    }
+  };
+  RenderError = class RenderError extends HypenError {
+    constructor(message, cause) {
+      super("RENDER_ERROR", message, {
+        cause: cause instanceof Error ? cause : undefined
+      });
+      this.name = "RenderError";
+    }
+  };
 });
 
 // src/disposable.ts
@@ -892,4 +924,4 @@ export {
   RemoteEngine
 };
 
-//# debugId=9BAD9D906A24336464756E2164756E21
+//# debugId=680F812DA42FB83E64756E2164756E21