@hypen-space/core 0.4.2 → 0.4.3

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,60 @@
+/**
+ * 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 } from "./app.js";
+import type { HypenRouter } from "./router.js";
+import type { HypenGlobalContext } from "./context.js";
+import { ModuleRegistry } from "./module-registry.js";
+export interface RouteDefinition {
+    /** Route path pattern (e.g., "/", "/profile/:id") */
+    path: string;
+    /** Component name — used to look up in ModuleRegistry */
+    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: ModuleRegistry, 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/module-registry.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Module Registry — maps component names to module definitions.
+ *
+ * Used by the import resolution pipeline and ManagedRouter to look up
+ * module definitions by their component name (e.g., "HomePage", "ProfilePage").
+ */
+import type { HypenModuleDefinition } from "./app.js";
+export declare class ModuleRegistry {
+    private definitions;
+    /**
+     * Register a module definition under a component name.
+     */
+    register(name: string, definition: HypenModuleDefinition): void;
+    /**
+     * Get a module definition by component name.
+     */
+    get(name: string): HypenModuleDefinition | undefined;
+    /**
+     * Check if a module definition exists.
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered definitions.
+     */
+    getAll(): Map<string, HypenModuleDefinition>;
+    /**
+     * Get all registered component names.
+     */
+    getNames(): string[];
+    /**
+     * Unregister a module definition.
+     */
+    unregister(name: string): void;
+    /**
+     * Number of registered definitions.
+     */
+    get size(): number;
+    /**
+     * Clear all registered definitions.
+     */
+    clear(): void;
+}

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/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Remote UI streaming for Hypen
+ *
+ * Client-side: Connect to remote Hypen apps
+ * Server-side: Stream Hypen apps over WebSocket
+ */
+export { RemoteEngine } from "./client.js";
+export type { RemoteConnectionState, RemoteEngineOptions, SessionOptions, SessionInfo, } from "./client.js";
+export { RemoteServer, serve } from "./server.js";
+export { SessionManager } from "./session.js";
+export type { SessionExpireCallback } from "./session.js";
+export type { RemoteMessage, InitialTreeMessage, PatchMessage, DispatchActionMessage, StateUpdateMessage, HelloMessage, SessionAckMessage, SessionExpiredMessage, Session, SessionConfig, RemoteClient, RemoteServerConfig, } from "./types.js";
+export type { Patch } from "../types.js";

package/dist/remote/server.d.ts

@@ -0,0 +1,142 @@
+/**
+ * RemoteServer - Stream Hypen apps over WebSocket with Session Management
+ *
+ * Usage:
+ * ```typescript
+ * import { RemoteServer, app } from "@hypen-space/core";
+ *
+ * const counter = app
+ *   .defineState({ count: 0 })
+ *   .onAction("increment", ({ state }) => state.count++)
+ *   .onDisconnect(async ({ state, session }) => {
+ *     await redis.set(`session:${session.id}`, JSON.stringify(state));
+ *   })
+ *   .onReconnect(async ({ session, restore }) => {
+ *     const saved = await redis.get(`session:${session.id}`);
+ *     if (saved) restore(JSON.parse(saved));
+ *   })
+ *   .onExpire(async ({ session }) => {
+ *     await redis.del(`session:${session.id}`);
+ *   })
+ *   .build();
+ *
+ * new RemoteServer()
+ *   .module("Counter", counter)
+ *   .ui(`Column { Text("Count: \${state.count}") }`)
+ *   .session({ ttl: 3600, concurrent: "kick-old" })
+ *   .listen(3000);
+ * ```
+ */
+import type { HypenModule } from "../app.js";
+import type { RemoteMessage, RemoteClient, RemoteServerConfig, SessionConfig } from "./types.js";
+/**
+ * Builder pattern for hosting Hypen apps over WebSocket
+ */
+export declare class RemoteServer {
+    private _module;
+    private _moduleName;
+    private _ui;
+    private _config;
+    private _sessionConfig;
+    private _onConnectionCallbacks;
+    private _onDisconnectionCallbacks;
+    private clients;
+    private nextClientId;
+    private server;
+    private sessionManager;
+    /**
+     * Set the module for this app
+     */
+    module(name: string, module: HypenModule<any>): this;
+    /**
+     * Set the UI DSL string
+     */
+    ui(dsl: string): this;
+    /**
+     * Set server configuration
+     */
+    config(config: RemoteServerConfig): this;
+    /**
+     * Configure session management
+     */
+    session(config: SessionConfig): this;
+    /**
+     * Register connection callback
+     */
+    onConnection(callback: (client: RemoteClient) => void): this;
+    /**
+     * Register disconnection callback
+     */
+    onDisconnection(callback: (client: RemoteClient) => void): this;
+    /**
+     * Start the WebSocket server
+     */
+    listen(port?: number): this;
+    /**
+     * Stop the server
+     */
+    stop(): void;
+    /**
+     * Get the server URL
+     */
+    get url(): string | null;
+    /**
+     * Handle new WebSocket connection
+     * Waits for hello message before fully initializing
+     */
+    private handleOpen;
+    /**
+     * Initialize session for a client (new or resumed)
+     */
+    private initializeSession;
+    /**
+     * Set up the render callback for streaming patches
+     */
+    private setupRenderCallback;
+    /**
+     * Handle concurrent connection based on policy
+     * Returns true if connection is allowed, false if rejected
+     */
+    private handleConcurrentConnection;
+    /**
+     * Trigger onReconnect hook
+     */
+    private triggerReconnect;
+    /**
+     * Handle incoming WebSocket message
+     */
+    private handleMessage;
+    /**
+     * Handle WebSocket close - suspend session instead of destroying
+     */
+    private handleClose;
+    /**
+     * Get current client count
+     */
+    getClientCount(): number;
+    /**
+     * Get session stats
+     */
+    getSessionStats(): {
+        activeSessions: number;
+        pendingSessions: number;
+        totalConnections: number;
+    };
+    /**
+     * Broadcast a message to all connected clients
+     */
+    broadcast(message: RemoteMessage): void;
+}
+/**
+ * Convenience function to create and start a RemoteServer
+ */
+export declare function serve(options: {
+    module: HypenModule<any>;
+    moduleName?: string;
+    ui: string;
+    port?: number;
+    hostname?: string;
+    session?: SessionConfig;
+    onConnection?: (client: RemoteClient) => void;
+    onDisconnection?: (client: RemoteClient) => void;
+}): RemoteServer;