@electrojs/renderer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anton Ryuben
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,431 @@
+# @electrojs/renderer
+
+Typed renderer-side runtime for Electro applications.
+
+`@electrojs/renderer` is the only public entrypoint that renderer code uses to talk to the Electro runtime. It exposes:
+
+- `ElectroRenderer.initialize(...)` — bootstraps the renderer package
+- `bridge` — typed query/command API
+- `signals` — typed runtime-to-renderer subscriptions
+
+This package does **not** know anything about preload implementation details beyond the public preload contract exposed on `window.__ELECTRO_RENDERER__`. The preload side is provided by the runtime layer.
+
+---
+
+## Installation
+
+```bash
+npm install @electrojs/renderer
+```
+
+---
+
+## Core idea
+
+The renderer cannot talk to the runtime directly. All communication goes through:
+
+- `bridge.<module>.<method>(...)` for queries and commands
+- `signals.subscribe(...)` / `signals.once(...)` for runtime-published signals
+
+Bridge and signal types are provided through declaration merging.
+
+---
+
+## Quick start
+
+```ts
+import { ElectroRenderer } from "@electrojs/renderer";
+import { createRoot } from "react-dom/client";
+import { App } from "./app";
+
+await ElectroRenderer.initialize(async () => {
+    createRoot(document.getElementById("root")!).render(<App />);
+});
+```
+
+After initialization finishes, `bridge` and `signals` are ready to use.
+
+---
+
+## Public API
+
+### `ElectroRenderer.initialize(callback?)`
+
+Initializes the renderer package exactly once.
+
+```ts
+import { ElectroRenderer } from "@electrojs/renderer";
+
+await ElectroRenderer.initialize(async () => {
+    // renderer bootstrap logic
+});
+```
+
+#### Behavior
+
+- resolves the preload API from `window.__ELECTRO_RENDERER__`
+- creates the bridge proxy
+- creates the signals client
+- executes the optional callback
+- marks the renderer as initialized only after callback success
+
+#### Important rules
+
+- `initialize()` can only be called once
+- if initialization fails, internal state is rolled back
+- `bridge` and `signals` must not be used before initialization completes
+
+---
+
+### `bridge`
+
+`bridge` is a lazily resolved typed proxy.
+
+```ts
+import { bridge } from "@electrojs/renderer";
+
+const user = await bridge.auth.getMe();
+await bridge.auth.login("john@example.com", "secret");
+```
+
+At runtime, bridge calls are translated into channel invocations:
+
+```ts
+bridge.auth.login("a", "b");
+// -> preload.invoke("auth:login", ["a", "b"])
+```
+
+#### Method calling rules
+
+A bridge method can have one of three shapes depending on generated types:
+
+- no input:
+
+```ts
+await bridge.auth.getMe();
+```
+
+- tuple input:
+
+```ts
+await bridge.auth.login(email, password);
+```
+
+- single object input:
+
+```ts
+await bridge.project.create({ name: "Electro" });
+```
+
+---
+
+### `signals`
+
+`signals` provides typed subscription helpers.
+
+```ts
+import { signals } from "@electrojs/renderer";
+
+const subscription = signals.subscribe("auth:user-logged-in", (payload) => {
+    console.log(payload);
+});
+
+subscription.unsubscribe();
+```
+
+One-time subscription:
+
+```ts
+signals.once("auth:user-logged-in", (payload) => {
+    console.log("received once", payload);
+});
+```
+
+Signal handlers support two shapes:
+
+- payload signal:
+
+```ts
+signals.subscribe("auth:user-logged-in", (payload) => {
+    console.log(payload.userId);
+});
+```
+
+- no-payload signal:
+
+```ts
+signals.subscribe("auth:user-logged-out", () => {
+    console.log("logged out");
+});
+```
+
+---
+
+## Typing bridge and signals
+
+This package exposes three empty interfaces intended for declaration merging:
+
+```ts
+export interface BridgeQueries {}
+export interface BridgeCommands {}
+export interface BridgeSignals {}
+```
+
+Generated code augments them.
+
+Example:
+
+```ts
+declare module "@electrojs/renderer" {
+    interface BridgeQueries {
+        "auth:getMe": {
+            input: undefined;
+            output: { id: string; email: string } | null;
+        };
+    }
+
+    interface BridgeCommands {
+        "auth:login": {
+            input: [email: string, password: string];
+            output: void;
+        };
+    }
+
+    interface BridgeSignals {
+        "auth:user-logged-in": { userId: string };
+        "auth:user-logged-out": undefined;
+    }
+}
+```
+
+After augmentation:
+
+```ts
+const me = await bridge.auth.getMe();
+await bridge.auth.login("john@example.com", "secret");
+
+signals.subscribe("auth:user-logged-in", (payload) => {
+    payload.userId;
+});
+
+signals.subscribe("auth:user-logged-out", () => {});
+```
+
+---
+
+## Runtime preload contract
+
+The renderer expects preload to expose this API on `window.__ELECTRO_RENDERER__`:
+
+```ts
+interface RendererPreloadApi {
+    invoke(channel: string, payload: readonly unknown[]): Promise<unknown>;
+    subscribe(signalKey: string, listener: (payload: unknown) => void): () => void;
+    once(signalKey: string, listener: (payload: unknown) => void): () => void;
+}
+```
+
+This package does not create that object. It only consumes it.
+
+---
+
+## Usage with React
+
+```tsx
+import { useEffect, useState } from "react";
+import { bridge, signals } from "@electrojs/renderer";
+
+export function App(): JSX.Element {
+    const [email, setEmail] = useState<string | null>(null);
+
+    useEffect(() => {
+        let mounted = true;
+
+        bridge.auth.getMe().then((user) => {
+            if (!mounted) {
+                return;
+            }
+
+            setEmail(user?.email ?? null);
+        });
+
+        const subscription = signals.subscribe("auth:user-logged-in", (payload) => {
+            setEmail(payload.email);
+        });
+
+        return () => {
+            mounted = false;
+            subscription.unsubscribe();
+        };
+    }, []);
+
+    return <div>{email ?? "Anonymous"}</div>;
+}
+```
+
+---
+
+## Errors
+
+All package-specific errors inherit from `RendererError`.
+
+### `RendererInitializationError`
+
+Thrown when initialization fails or is used incorrectly.
+
+Examples:
+
+- `ELECTRO_RENDERER_ALREADY_INITIALIZED`
+- `ELECTRO_RENDERER_PRELOAD_API_MISSING`
+
+### `RendererUsageError`
+
+Thrown when renderer APIs are used incorrectly.
+
+Examples:
+
+- `ELECTRO_RENDERER_NOT_INITIALIZED`
+- `ELECTRO_RENDERER_INVALID_BRIDGE_NAMESPACE_KEY`
+- `ELECTRO_RENDERER_INVALID_BRIDGE_METHOD_KEY`
+- `ELECTRO_RENDERER_INVALID_SIGNAL_KEY`
+- `ELECTRO_RENDERER_INVALID_SIGNAL_HANDLER`
+
+### `RendererTransportError`
+
+Thrown when preload transport operations fail.
+
+Examples:
+
+- `ELECTRO_RENDERER_TRANSPORT_INVOKE_FAILED`
+- `ELECTRO_RENDERER_SIGNAL_SUBSCRIBE_FAILED`
+
+Example:
+
+```ts
+import { ElectroRenderer, RendererInitializationError } from "@electrojs/renderer";
+
+try {
+    await ElectroRenderer.initialize();
+} catch (error) {
+    if (error instanceof RendererInitializationError) {
+        console.error(error.code, error.context);
+    }
+}
+```
+
+---
+
+## Initialization lifecycle
+
+Initialization is transactional.
+
+### Successful flow
+
+1. validate initialization state
+2. resolve preload API from `window.__ELECTRO_RENDERER__`
+3. create bridge transport
+4. create bridge proxy
+5. create signals client
+6. store bridge and signals
+7. run user callback
+8. mark initialized
+
+### Failed flow
+
+If any step throws:
+
+- bridge storage is cleared
+- signals storage is cleared
+- initialization state is reset
+- original error is rethrown
+
+This guarantees the package never stays in a half-initialized state.
+
+---
+
+## Design notes
+
+### Why `initialize()` is async
+
+Initialization may include async renderer bootstrap logic:
+
+```ts
+await ElectroRenderer.initialize(async () => {
+    await loadI18n();
+    await warmupCache();
+    renderApp();
+});
+```
+
+The renderer becomes initialized only after this callback succeeds.
+
+---
+
+### Why `bridge` is a proxy
+
+The runtime bridge surface is generated and typed externally. A proxy lets the package:
+
+- expose ergonomic `bridge.auth.login(...)` syntax
+- avoid static hardcoded namespaces
+- remain compatible with generated declaration merging
+
+---
+
+### Why `"then"` returns `undefined`
+
+Both root and namespace proxies explicitly return `undefined` for `"then"` to avoid accidental promise-like behavior during inspection or framework interop.
+
+---
+
+## Exports
+
+```ts
+import { bridge, signals, ElectroRenderer, RendererError, RendererInitializationError, RendererTransportError, RendererUsageError } from "@electrojs/renderer";
+```
+
+Type exports:
+
+```ts
+import type {
+    BridgeContractEntry,
+    BridgeSignalHandler,
+    ElectroRendererApi,
+    InitializeCallback,
+    RendererPreloadApi,
+    RendererSignalListener,
+    RendererSignalSubscription,
+} from "@electrojs/renderer";
+```
+
+---
+
+## Best practices
+
+Always initialize the renderer before using `bridge` or `signals`.
+
+```ts
+await ElectroRenderer.initialize(async () => {
+    // safe to render app here
+});
+```
+
+Always unsubscribe from long-lived signal subscriptions.
+
+```ts
+const subscription = signals.subscribe("project:updated", onProjectUpdated);
+
+// later
+subscription.unsubscribe();
+```
+
+Prefer generated types over handwritten declarations.
+
+Keep preload implementation thin and transport-focused. Business logic belongs in the runtime, not in preload.
+
+---
+
+## Browser requirement
+
+`@electrojs/renderer` expects a browser-like environment with a `window` global.
+
+Running tests in plain Node.js without browser mode or DOM emulation will fail for code paths that access `window`.

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+//#region src/types/transport.d.ts
+type RendererSignalListener = (payload: unknown) => void;
+interface RendererPreloadApi {
+  invoke(channel: string, payload: readonly unknown[]): Promise<unknown>;
+  subscribe(signalKey: string, listener: RendererSignalListener): () => void;
+  once(signalKey: string, listener: RendererSignalListener): () => void;
+}
+//#endregion
+//#region src/types/window.d.ts
+declare global {
+  interface Window {
+    readonly __ELECTRO_RENDERER__?: RendererPreloadApi;
+  }
+}
+//#endregion
+//#region src/types/public-api.d.ts
+type BridgeNoInput = undefined;
+type BridgeNoPayload = undefined;
+interface BridgeContractEntry<TInput = BridgeNoInput, TOutput = unknown> {
+  readonly input: TInput;
+  readonly output: TOutput;
+}
+type PromiseBridgeResult<TValue> = Promise<TValue>;
+type BridgeTupleInput = readonly unknown[];
+type IsBridgeNoInput<TValue> = [TValue] extends [BridgeNoInput] ? true : false;
+type IsBridgeNoPayload<TValue> = [TValue] extends [BridgeNoPayload] ? true : false;
+type BridgeMethodFromInput<TInput, TOutput> = IsBridgeNoInput<TInput> extends true ? () => PromiseBridgeResult<TOutput> : [TInput] extends [BridgeTupleInput] ? (...args: TInput) => PromiseBridgeResult<TOutput> : (input: TInput) => PromiseBridgeResult<TOutput>;
+type BridgeMethod<TEntry extends BridgeContractEntry<any, any>> = BridgeMethodFromInput<TEntry["input"], TEntry["output"]>;
+type Simplify<TValue> = { [TKey in keyof TValue]: TValue[TKey] } & {};
+type ContractKey<TContracts extends object> = keyof TContracts & string;
+type ContractNamespace<TKey extends string> = TKey extends `${infer TNamespace}:${infer _TMethod}` ? TNamespace : never;
+type ContractMethodName<TKey extends string> = TKey extends `${string}:${infer TMethod}` ? TMethod : never;
+type NormalizeBridgeEntry<TEntry> = TEntry extends BridgeContractEntry<infer TInput, infer TOutput> ? BridgeContractEntry<TInput, TOutput> : never;
+type ContractMethodShape<TContracts extends object, TNamespace extends string> = Simplify<{ [TKey in Extract<ContractKey<TContracts>, `${TNamespace}:${string}`> as ContractMethodName<TKey>]: BridgeMethod<NormalizeBridgeEntry<TContracts[TKey]>> }>;
+type BuildNamespaceMap<TContracts extends object> = Simplify<{ [TNamespace in ContractNamespace<ContractKey<TContracts>>]: ContractMethodShape<TContracts, TNamespace> }>;
+type BuildBridgeApi<TQueries extends object, TCommands extends object> = Simplify<BuildNamespaceMap<TQueries> & BuildNamespaceMap<TCommands>>;
+type BridgeSignalHandlerFromPayload<TPayload> = IsBridgeNoPayload<TPayload> extends true ? () => void : (payload: TPayload) => void;
+type BridgeSignalHandler<TPayload> = BridgeSignalHandlerFromPayload<TPayload>;
+interface RendererSignalSubscription {
+  unsubscribe(): void;
+}
+interface RendererSignalsApi<TSignals extends object> {
+  subscribe<TKey extends keyof TSignals & string>(signalKey: TKey, handler: BridgeSignalHandler<TSignals[TKey]>): RendererSignalSubscription;
+  once<TKey extends keyof TSignals & string>(signalKey: TKey, handler: BridgeSignalHandler<TSignals[TKey]>): RendererSignalSubscription;
+}
+type InitializeCallback = () => void | Promise<void>;
+interface ElectroRendererApi {
+  initialize(callback?: InitializeCallback): Promise<void>;
+}
+//#endregion
+//#region src/core/electro-renderer.d.ts
+declare class ElectroRendererManager implements ElectroRendererApi {
+  private readonly state;
+  initialize(callback?: InitializeCallback): Promise<void>;
+  isInitialized(): boolean;
+}
+declare const ElectroRenderer: ElectroRendererManager;
+//#endregion
+//#region src/errors/renderer.error.d.ts
+declare abstract class RendererError extends Error {
+  readonly code: string;
+  readonly context?: Readonly<Record<string, unknown>>;
+  protected constructor(message: string, code: string, context?: Readonly<Record<string, unknown>>);
+}
+declare class RendererInitializationError extends RendererError {
+  static alreadyInitialized(): RendererInitializationError;
+  static preloadApiMissing(windowKey: string): RendererInitializationError;
+}
+declare class RendererUsageError extends RendererError {
+  static notInitialized(operation: string): RendererUsageError;
+  static invalidBridgeNamespaceKey(received: unknown): RendererUsageError;
+  static invalidBridgeMethodKey(namespace: string, received: unknown): RendererUsageError;
+  static invalidSignalKey(signalKey: unknown): RendererUsageError;
+  static invalidSignalHandler(signalKey: unknown, received: unknown): RendererUsageError;
+}
+declare class RendererTransportError extends RendererError {
+  static invokeFailed(channel: string, cause: unknown): RendererTransportError;
+  static subscribeFailed(signalKey: string, cause: unknown): RendererTransportError;
+}
+//#endregion
+//#region src/index.d.ts
+interface BridgeQueries {}
+interface BridgeCommands {}
+interface BridgeSignals {}
+type BridgeApi = BuildBridgeApi<BridgeQueries, {}>;
+type SignalsApi = RendererSignalsApi<BridgeSignals>;
+declare const bridge: BridgeApi;
+declare const signals: SignalsApi;
+//#endregion
+export { BridgeApi, BridgeCommands, type BridgeContractEntry, BridgeQueries, type BridgeSignalHandler, BridgeSignals, ElectroRenderer, type ElectroRendererApi, type InitializeCallback, RendererError, RendererInitializationError, type RendererPreloadApi, type RendererSignalListener, type RendererSignalSubscription, RendererTransportError, RendererUsageError, SignalsApi, bridge, signals };

package/dist/index.js

@@ -0,0 +1 @@
+var e=class extends Error{constructor(e,t,n){super(e),this.name=new.target.name,this.code=t,this.context=n,Object.setPrototypeOf(this,new.target.prototype)}},t=class t extends e{static alreadyInitialized(){return new t(`ElectroRenderer.initialize() can only be called once.`,`ELECTRO_RENDERER_ALREADY_INITIALIZED`)}static preloadApiMissing(e){return new t(`Electro renderer preload API is not available on window.${e}.`,`ELECTRO_RENDERER_PRELOAD_API_MISSING`,{windowKey:e})}},n=class t extends e{static notInitialized(e){return new t(`${e} cannot be used before ElectroRenderer.initialize() has completed.`,`ELECTRO_RENDERER_NOT_INITIALIZED`,{operation:e})}static invalidBridgeNamespaceKey(e){return new t(`Bridge namespace key must be a non-empty string.`,`ELECTRO_RENDERER_INVALID_BRIDGE_NAMESPACE_KEY`,{received:e})}static invalidBridgeMethodKey(e,n){return new t(`Bridge method key for namespace "${e}" must be a non-empty string.`,`ELECTRO_RENDERER_INVALID_BRIDGE_METHOD_KEY`,{namespace:e,received:n})}static invalidSignalKey(e){return new t(`Signal key must be a non-empty string.`,`ELECTRO_RENDERER_INVALID_SIGNAL_KEY`,{received:e})}static invalidSignalHandler(e,n){return new t(`Signal handler for "${String(e)}" must be a function.`,`ELECTRO_RENDERER_INVALID_SIGNAL_HANDLER`,{signalKey:e,receivedType:typeof n})}},r=class t extends e{static invokeFailed(e,n){return new t(`Bridge transport invocation failed for channel "${e}".`,`ELECTRO_RENDERER_TRANSPORT_INVOKE_FAILED`,{channel:e,cause:n})}static subscribeFailed(e,n){return new t(`Signal subscription failed for "${e}".`,`ELECTRO_RENDERER_SIGNAL_SUBSCRIBE_FAILED`,{signalKey:e,cause:n})}};let i;function a(e){i=e}function o(){i=void 0}function s(){if(!i)throw n.notInitialized(`bridge`);return i}function c(e,t){return new Proxy({},{get(r,i){if(typeof i!=`string`||i===`then`)return;let a=i.trim();if(a.length===0)throw n.invalidBridgeMethodKey(t,i);return async(...n)=>e.invoke(`${t}:${a}`,n)},has(e,t){return typeof t==`string`&&t.trim().length>0&&t!==`then`},getOwnPropertyDescriptor(e,t){if(!(typeof t!=`string`||t===`then`||t.trim().length===0))return{configurable:!0,enumerable:!0}}})}function l(e){return new Proxy({},{get(t,r){if(typeof r!=`string`||r===`then`)return;let i=r.trim();if(i.length===0)throw n.invalidBridgeNamespaceKey(r);return c(e,i)},has(e,t){return typeof t==`string`&&t.trim().length>0&&t!==`then`},getOwnPropertyDescriptor(e,t){if(!(typeof t!=`string`||t===`then`||t.trim().length===0))return{configurable:!0,enumerable:!0}}})}var u=class{constructor(e){this.preloadApi=e}async invoke(e,t){try{return await this.preloadApi.invoke(e,t)}catch(t){throw r.invokeFailed(e,t)}}};let d;function f(e){d=e}function p(){d=void 0}function m(){if(!d)throw n.notInitialized(`signals`);return d}var h=class{constructor(e){this.dispose=e,this.unsubscribed=!1}unsubscribe(){this.unsubscribed||(this.unsubscribed=!0,this.dispose())}},g=class{constructor(e){this.preloadApi=e}subscribe(e,t){this.ensureValidHandler(e,t);try{return new h(this.preloadApi.subscribe(e,this.createInternalHandler(t)))}catch(t){throw r.subscribeFailed(e,t)}}once(e,t){this.ensureValidHandler(e,t);try{return new h(this.preloadApi.once(e,this.createInternalHandler(t)))}catch(t){throw r.subscribeFailed(e,t)}}createInternalHandler(e){return t=>{if(t===void 0){e();return}e(t)}}ensureValidHandler(e,t){if(typeof e!=`string`||e.trim().length===0)throw n.invalidSignalKey(e);if(typeof t!=`function`)throw n.invalidSignalHandler(e,t)}},_=class{constructor(){this.initialized=!1,this.initializing=!1}isInitialized(){return this.initialized}isInitializing(){return this.initializing}ensureCanInitialize(){if(this.initialized||this.initializing)throw t.alreadyInitialized()}markInitializing(){this.initializing=!0}markInitialized(){this.initializing=!1,this.initialized=!0}reset(){this.initializing=!1,this.initialized=!1}};const v=`__ELECTRO_RENDERER__`;var y=class{static getPreloadApi(e=window){let n=e[v];if(!n)throw t.preloadApiMissing(v);return n}};const b=new class{constructor(){this.state=new _}async initialize(e){this.state.ensureCanInitialize(),this.state.markInitializing();try{let t=y.getPreloadApi(),n=l(new u(t)),r=new g(t);a(n),f(r),e&&await e(),this.state.markInitialized()}catch(e){throw o(),p(),this.state.reset(),e}}isInitialized(){return this.state.isInitialized()}},x=new Proxy({},{get(e,t){return Reflect.get(s(),t)}}),S={subscribe(e,t){return m().subscribe(e,t)},once(e,t){return m().once(e,t)}};export{b as ElectroRenderer,e as RendererError,t as RendererInitializationError,r as RendererTransportError,n as RendererUsageError,x as bridge,S as signals};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@electrojs/renderer",
+  "version": "1.0.0",
+  "description": "Library for working with the renderer process in @electro",
+  "homepage": "https://github.com/MyraxByte/electrojs#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MyraxByte/electrojs.git",
+    "directory": "packages/renderer"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@vitest/browser-playwright": "^4.1.1",
+    "@vitest/coverage-v8": "^4.1.1",
+    "@vitest/ui": "^4.1.1",
+    "jsdom": "^29.0.1",
+    "publint": "^0.3.18",
+    "tsdown": "^0.21.4",
+    "vitest": "^4.1.1",
+    "@electrojs/config": "1.0.0"
+  },
+  "peerDependencies": {
+    "@electrojs/config": ">=1.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest",
+    "test:browser": "vitest --browser"
+  }
+}