epos 2.0.0 → 2.0.2

package/dist/epos.d.ts

@@ -9,195 +9,361 @@ import type * as yjs from 'yjs';
 import type { Browser } from './browser.js';
 import type { Spec } from './spec.js';
 export interface Epos {
-    /** Like regular `fetch`, but bypasses CORS. Does not support streams. */
+    /**
+     * Fetch a resource through the extension runtime.
+     *
+     * Behaves like `fetch`, but bypasses page CORS restrictions and returns a
+     * simplified response object without stream support.
+     */
     fetch: EposFetch;
-    /** WebExtensions API. Like `chrome.*`, but works in any context. */
+    /**
+     * WebExtensions API. Like `chrome.*`, but works in any context.
+     */
     browser: Browser;
-    /** Render React node. */
+    /**
+     * Render a React tree into the provided container.
+     *
+     * When `container` is omitted, Epos uses its pre-created default view.
+     */
     render(node: react.ReactNode, container?: reactDomClient.Container): void;
-    /** Make React component Epos-aware, so it reacts to state changes. */
+    /**
+     * Wrap a React component so it reacts to Epos-managed observable state.
+     */
     component<T>(Component: react.FC<T>): react.FC<T>;
-    /** Environment variables. */
+    /**
+     * Environment variables.
+     */
     env: EposEnv;
-    /** DOM elements created by Epos. */
+    /**
+     * DOM elements created by Epos.
+     */
     dom: EposDom;
-    /** Event bus for cross-context communication. */
+    /**
+     * Event bus for cross-context communication.
+     */
     bus: EposBus;
-    /** State management. */
+    /**
+     * State management.
+     */
     state: EposState;
-    /** Storage management. */
+    /**
+     * Storage management.
+     */
     storage: EposStorage;
-    /** Asset management. */
+    /**
+     * Asset management.
+     */
     assets: EposAssets;
-    /** Background frames management. */
+    /**
+     * Background frames management.
+     */
     frames: EposFrames;
-    /** Project management. */
+    /**
+     * Project management.
+     */
     projects: EposProjects;
-    /** Third party libraries used by Epos. */
+    /**
+     * Third party libraries used by Epos.
+     */
     libs: EposLibs;
 }
 export type EposFetch = (url: string | URL, init?: ReqInit) => Promise<Res>;
 export interface EposEnv {
-    /** Tab identifier, -1 for background and iframes. */
+    /**
+     * Tab identifier, -1 for background and iframes.
+     */
     tabId: -1 | number;
-    /** Window identifier, -1 for background and iframes. */
+    /**
+     * Window identifier, -1 for background and iframes.
+     */
     windowId: -1 | number;
-    /** Indicates if running in `<popup>` context. */
+    /**
+     * Indicates if running in `<popup>` context.
+     */
     isPopup: boolean;
-    /** Indicates if running in `<sidePanel>` context. */
+    /**
+     * Indicates if running in `<sidePanel>` context.
+     */
     isSidePanel: boolean;
-    /** Indicates if running in `<background>` context. */
+    /**
+     * Indicates if running in `<background>` context.
+     */
     isBackground: boolean;
-    /** Current project data. */
+    /**
+     * Current project data.
+     */
     project: Project;
 }
 export interface EposDom {
-    /** Project's root element. */
+    /**
+     * Project's root element.
+     */
     root: HTMLDivElement;
-    /** Pre-created element used as default container for React. */
+    /**
+     * Pre-created element used as default container for React.
+     */
     view: HTMLDivElement;
-    /** Pre-created shadow DOM. */
+    /**
+     * Pre-created shadow DOM.
+     */
     shadowRoot: ShadowRoot;
-    /** Pre-created element inside shadow DOM used as default container for React. */
+    /**
+     * Pre-created element inside shadow DOM used as default container for React.
+     */
     shadowView: HTMLDivElement;
 }
 export interface EposBus {
-    /** Register an event listener. */
+    /**
+     * Register an event listener.
+     *
+     * Listeners added with the same `name` are invoked in registration order.
+     * `thisArg` becomes `this` inside non-arrow callbacks.
+     *
+     * A listener may return a value, and that value becomes the resolved result
+     * of `send()` for the matching event.
+     */
     on<T extends Fn>(name: string, callback: T, thisArg?: unknown): void;
-    /** Remove an event listener. */
+    /**
+     * Remove a previously registered event listener.
+     *
+     * When `callback` is omitted, every listener registered for `name` is removed.
+     */
     off<T extends Fn>(name: string, callback?: T): void;
-    /** Register a one-time event listener. */
+    /**
+     * Register a one-time event listener.
+     *
+     * The listener is removed immediately after the first matching event.
+     */
     once<T extends Fn>(name: string, callback: T, thisArg?: unknown): void;
-    /** Send an event to all remote listeners. */
+    /**
+     * Send an event to other extension contexts.
+     *
+     * Resolves with the first value returned by a remote `on()` listener, if any
+     * remote listener responds.
+     */
     send<T>(name: string, ...args: FnArgsOrArr<T>): Promise<FnResultOrValue<T> | undefined>;
-    /** Call local listeners for an event. */
+    /**
+     * Emit an event to local listeners only. Does not trigger remote listeners in other contexts.
+     *
+     * Resolves with the first returned value, if any local listener responds.
+     */
     emit<T>(name: string, ...args: FnArgsOrArr<T>): Promise<FnResultOrValue<T> | undefined>;
-    /** Set a signal with an optional value. */
+    /**
+     * Set a signal that can be awaited with `waitSignal()`.
+     */
     setSignal(name: string, value?: unknown): void;
-    /** Wait for a signal to be set. */
+    /**
+     * Wait for a signal to be set with `setSignal()`.
+     */
     waitSignal<T>(name: string, timeout?: number): Promise<T | undefined>;
-    /** Register as a service. */
+    /**
+     * Register a service that can be used remotely with `use()`.
+     */
     register(name: string, api: Obj<any>): void;
-    /** Unregister a service. */
+    /**
+     * Remove a previously registered service.
+     */
     unregister(name: string): void;
-    /** Use a service. */
+    /**
+     * Get an object that represents remote service registered with `register()`.
+     */
     use<T extends Obj<any>>(name: string): BusService<T>;
-    /** Create a namespaced bus instance. */
+    /**
+     * Create a namespaced bus API to avoid naming collisions.
+     */
     for(namespace: string): Omit<EposBus, 'for'> & {
-        /** Dispose namespaced bus instance. Removes all its listeners and ignores any further method calls. */
+        /**
+         * Dispose namespaced bus instance. Removes all its listeners and ignores any further method calls.
+         */
         dispose: () => void;
     };
 }
 export interface EposState {
-    /** Connect to the state. */
+    /**
+     * Connect to a shared reactive state.
+     */
     connect: {
         <T>(initial?: Initial<T>, versioner?: Versioner<T>): Promise<T>;
         <T>(name?: string, initial?: Initial<T>, versioner?: Versioner<T>): Promise<T>;
     };
-    /** Disconnect from the state. */
+    /**
+     * Disconnect from a shared reactive state.
+     */
     disconnect(name?: string): void;
-    /** Run state changes in a batch. */
+    /**
+     * Batch multiple state mutations into a single reactive update.
+     */
     transaction: (fn: () => void) => void;
-    /** Create a reactive effect that runs when observed state changes. */
+    /**
+     * MobX `reaction` method placed on `epos.state` for convenience.
+     */
     reaction: typeof mobx.reaction;
-    /** Create local state (no sync). */
+    /**
+     * Create observable local state that is not synchronized across contexts.
+     */
     local<T extends {}>(initial?: Initial<T>): T;
-    /** Get list of all state names. */
+    /**
+     * List known shared states.
+     */
     list(filter?: {
         connected?: boolean;
     }): Promise<{
         name: string | null;
         connected: boolean;
     }[]>;
-    /** Remove state and all its data. */
+    /**
+     * Delete a shared state and its data.
+     */
     remove(name?: string): Promise<void>;
-    /** Register models that can be used by all states. */
+    /**
+     * Register models that can be used in any shared state.
+     *
+     * Models should be registered before `epos.state.connect` is called.
+     */
     register(models: Record<string, Ctor>): void;
-    /** Parent access for state objects and array. */
+    /**
+     * Parent access for state objects and arrays.
+     */
     PARENT: symbol;
+    /**
+     * Attach hook for state objects and arrays.
+     */
     ATTACH: symbol;
+    /**
+     * Detach hook for state objects and arrays.
+     */
     DETACH: symbol;
 }
 export interface EposStorage {
-    /** Get value from storage. */
+    /**
+     * Read a value from storage.
+     */
     get: {
         <T>(key: string): Promise<T | null>;
         <T>(name: string, key: string): Promise<T | null>;
     };
-    /** Set value in storage. */
+    /**
+     * Write a value to storage.
+     */
     set: {
         <T>(key: string, value: T): Promise<void>;
         <T>(name: string, key: string, value: T): Promise<void>;
     };
-    /** Check if key exists in storage. */
+    /**
+     * Check whether a key exists in storage.
+     */
     has: {
         (key: string): Promise<boolean>;
         (name: string, key: string): Promise<boolean>;
     };
-    /** Delete key from storage. */
+    /**
+     * Delete a key from storage.
+     */
     delete: {
         (key: string): Promise<void>;
         (name: string, key: string): Promise<void>;
     };
-    /** Get all storage keys. */
+    /**
+     * List storage keys.
+     */
     keys(name?: string): Promise<string[]>;
-    /** List existing storages. */
+    /**
+     * List all existing storages.
+     */
     list(): Promise<{
         name: string | null;
     }[]>;
-    /** Remove storage and all its data. */
+    /**
+     * Remove storage and all its data.
+     */
     clear(name?: string): Promise<void>;
-    /** Create API for the specific storage. */
+    /**
+     * Create a namespaced storage API.
+     */
     for(name?: string): {
-        /** Get value from storage. */
+        /**
+         * Read a value from storage.
+         */
         get<T>(key: string): Promise<T | null>;
-        /** Set value in storage. */
+        /**
+         * Write a value to storage.
+         */
         set(key: string, value: unknown): Promise<void>;
-        /** Check if key exists in storage. */
+        /**
+         * Check whether a key exists in storage.
+         */
         has(key: string): Promise<boolean>;
-        /** Delete key from storage. */
+        /**
+         * Delete a key from storage.
+         */
         delete(key: string): Promise<void>;
-        /** Get all storage keys. */
+        /**
+         * List all keys in storage.
+         */
         keys(): Promise<string[]>;
-        /** Remove storage and all its data. */
+        /**
+         * Remove storage and all its data.
+         */
         clear(): Promise<void>;
     };
 }
 export interface EposAssets {
-    /** Get asset URL.*/
+    /**
+     * Get a URL for an asset.
+     */
     url(path: string): string;
-    /** Get asset as Blob. */
+    /**
+     * Read an asset as a `Blob`.
+     *
+     * If the asset is not currently loaded, Epos reads it from IndexedDB directly.
+     *
+     * Returns `null` when the asset is unknown or not available.
+     */
     get(path: string): Promise<Blob | null>;
-    /** Get list of all available assets. */
+    /**
+     * List declared assets and whether each one is currently loaded in memory.
+     */
     list(filter?: {
         loaded?: boolean;
     }): {
         path: string;
         loaded: boolean;
     }[];
-    /** Load specified asset to memory. Loads all assets if no path is provided. */
+    /**
+     * Load an asset into memory.
+     *
+     * Call without arguments to load all assets.
+     */
     load: {
-        /** Load all assets. */
         (): Promise<void>;
-        /** Load specified asset. */
         (path: string): Promise<void>;
     };
-    /** Unload specified asset from memory. Unloads all assets if no path is provided. */
+    /**
+     * Unload an asset from memory.
+     *
+     * Call without arguments to unload all assets.
+     */
     unload: {
-        /** Unload all assets. */
         (): void;
-        /** Unload specified asset. */
         (path: string): void;
     };
 }
 export interface EposFrames {
-    /** Open background frame. */
+    /**
+     * Create a hidden background frame and return its id.
+     */
     create(url: string, attrs?: Attrs): Promise<string>;
-    /** Remove background frame. */
-    remove(id?: string): Promise<void>;
-    /** Check if background frame with the given id exists. */
-    has(id?: string): Promise<boolean>;
-    /** Get list of all open background frames. */
+    /**
+     * Remove a background frame by id.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * Check whether a background frame with the given id exists.
+     */
+    has(id: string): Promise<boolean>;
+    /**
+     * List all currently open background frames.
+     */
     list(): Promise<{
         id: string;
         name: string;
@@ -205,26 +371,50 @@ export interface EposFrames {
     }[]>;
 }
 export interface EposProjects {
-    /** Check if project with the given id exists. */
+    /**
+     * Check whether a project exists.
+     */
     has(id: string): Promise<boolean>;
-    /** Get project with the given id. */
+    /**
+     * Load a project by id.
+     *
+     * `query` controls whether heavyweight fields like `sources` and `assets`
+     * are included in the returned object.
+     */
     get<T extends ProjectQuery>(id: string, query?: T): Promise<Project<T> | null>;
-    /** Get list of all projects. */
+    /**
+     * List projects.
+     *
+     * `query` controls whether heavyweight fields like `sources` and `assets`
+     * are included in each returned object.
+     */
     list<T extends ProjectQuery>(query?: T): Promise<Project<T>[]>;
-    /** Create a new project. */
+    /**
+     * Create a project from a bundle and optional settings.
+     */
     create<T extends string>(params: Bundle & Partial<{
         id: T;
     } & ProjectSettings>): Promise<T>;
-    /** Update an existing project. */
+    /**
+     * Update an existing project's bundle data or runtime settings.
+     */
     update(id: string, updates: Partial<Bundle & ProjectSettings>): Promise<void>;
-    /** Remove a project. */
+    /**
+     * Permanently remove a project.
+     */
     remove(id: string): Promise<void>;
-    /** Export a project. */
+    /**
+     * Export a project as a map of files ready for download or external use.
+     */
     export(id: string): Promise<Record<string, Blob>>;
-    /** Watch for any project changes. */
+    /**
+     * Subscribe to project registry changes.
+     */
     watch(listener: () => void): void;
-    /** Fetch project bundle from project's spec URL (epos.json). */
-    fetch(url: string): Promise<Bundle>;
+    /**
+     * Fetch and assemble a project bundle from a remote `epos.json` spec URL.
+     */
+    fetch(eposJsonUrl: string): Promise<Bundle>;
 }
 export interface EposLibs {
     mobx: typeof mobx;

package/dist/epos.js.map

@@ -1 +1 @@
-{"version":3,"file":"epos.js","sourceRoot":"","sources":["../src/epos.ts"],"names":[],"mappings":"AA2SA,MAAM,KAAK,GAAG,IAAI,CAAA;AAClB,OAAO,EAAE,KAAK,IAAI,IAAI,EAAE,CAAA;AAExB,eAAe,KAAK,CAAA"}
+{"version":3,"file":"epos.js","sourceRoot":"","sources":["../src/epos.ts"],"names":[],"mappings":"AAweA,MAAM,KAAK,GAAG,IAAI,CAAA;AAClB,OAAO,EAAE,KAAK,IAAI,IAAI,EAAE,CAAA;AAExB,eAAe,KAAK,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "epos",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "type": "module",
   "license": "MIT",
   "author": "imkost",
@@ -27,8 +27,8 @@
     "dist"
   ],
   "dependencies": {
-    "@eposlabs/utils": "^1.25.0",
-    "@types/chrome": "^0.1.38",
+    "@eposlabs/utils": "^1.26.0",
+    "@types/chrome": "^0.1.39",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "browser-extension-url-match": "^1.2.0",

package/readme.md

@@ -0,0 +1,3 @@
+# epos
+
+A Vite plugin and type definitions for [Epos](https://epos.dev).