@ekrooh/bare 0.1.0

package/dist/index-DjulYFJL.d.mts

@@ -0,0 +1,261 @@
+//#region core/messages/constants.d.ts
+declare const VERSION = 1;
+declare const MessageType: {
+  readonly ENVELOPE: 1;
+};
+type MessageTypeValue = (typeof MessageType)[keyof typeof MessageType];
+/** Canonical error codes. Everything the framework throws uses these; peers
+ * may carry arbitrary codes over the wire, and consumers may return app-scoped
+ * codes (e.g. `app.photos/not-found`) which are preserved verbatim. Keep
+ * `android/src/main/.../ErrorCodes.kt` in sync with the canonical union. */
+declare const ErrorCode: {
+  readonly UNSUPPORTED_CAPABILITY: 'UNSUPPORTED_CAPABILITY';
+  readonly UNSUPPORTED_EVENT: 'UNSUPPORTED_EVENT';
+  readonly HOST_ERROR: 'HOST_ERROR';
+  readonly TRANSPORT_ERROR: 'TRANSPORT_ERROR';
+  readonly PLUGIN_ERROR: 'PLUGIN_ERROR';
+  readonly INVALID_RESPONSE: 'INVALID_RESPONSE';
+  readonly FRAME_TOO_LARGE: 'FRAME_TOO_LARGE';
+  readonly FRAME_INVALID: 'FRAME_INVALID';
+  readonly TIMEOUT: 'TIMEOUT';
+};
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/** A JSON header must fit a 16-bit big-endian length field. */
+declare const MAX_HEADER_BYTES = 65535;
+/** Upper bound on one encoded frame. Large binary transfers are a plugin-level
+ * concern (out-of-band handles), not an in-band payload. */
+declare const MAX_FRAME_BYTES: number;
+//#endregion
+//#region core/messages/types.d.ts
+/** Decoded binary frame (version byte stripped); used by WebSocket and other transports. */
+interface WireMessage {
+  type: MessageTypeValue;
+  header: MessageHeader;
+  payload: Uint8Array;
+}
+type HeaderBase = {
+  type: string;
+  requestId?: string;
+};
+/** Canonical wire codes plus any app-scoped code consumers define (e.g.
+ * `app.photos/not-found`). Framework plugins use the canonical union;
+ * arbitrary codes ride the wire verbatim and are never flattened. */
+type ErrorCodeOrString = ErrorCode | (string & {});
+declare class CoreError extends Error {
+  code: ErrorCodeOrString;
+  constructor(code: ErrorCodeOrString, message: string);
+}
+type CoreErrorWire = {
+  code: string;
+  message: string;
+};
+type RuntimeTarget = 'web' | 'android' | 'ios' | 'bare';
+type Either<E, A> = [E, null] | [null, A];
+type DispatchEnvelope<TEvent extends string = string, TArgs extends Record<string, unknown> = Record<string, unknown>> = {
+  kind: 'dispatch';
+  pluginId: string;
+  event: TEvent;
+  args: TArgs;
+  payload?: Uint8Array | ArrayBuffer | string | null;
+};
+type InvokeEnvelope<TEvent extends string = string, TArgs extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> = {
+  kind: 'invoke';
+  pluginId: string;
+  event: TEvent;
+  args: TArgs;
+  payload?: Uint8Array | ArrayBuffer | string | null;
+  timeoutMs?: number;
+  __result?: TResult;
+};
+type PluginInvokeRequestHeader = HeaderBase & {
+  type: 'INVOKE_REQUEST';
+  pluginId: string;
+  event: string;
+  args?: Record<string, unknown>;
+};
+type PluginInvokeResponseHeader = HeaderBase & {
+  type: 'INVOKE_RESPONSE';
+  pluginId: string;
+  event: string;
+  result?: unknown;
+  error?: CoreErrorWire;
+};
+type PluginDispatchHeader = HeaderBase & {
+  type: 'DISPATCH';
+  pluginId: string;
+  event: string;
+  args?: Record<string, unknown>;
+};
+type PluginHeader = PluginInvokeRequestHeader | PluginInvokeResponseHeader | PluginDispatchHeader;
+/** Worklet → host: ask for merged capability list (host registry + static knowledge). */
+type HostCapabilitiesQueryHeader = {
+  type: 'HOST_CAPABILITIES_QUERY';
+  requestId: string;
+};
+/** Host → worklet: capability rows contributed by the host. */
+type HostCapabilitiesResponseHeader = {
+  type: 'HOST_CAPABILITIES_RESPONSE';
+  requestId: string;
+  capabilities: CapabilityDescriptor[];
+};
+/** Worklet → host: run a host-registered handler (same pluginId/event as frontend invokes). */
+type HostInvokeRequestHeader = {
+  type: 'HOST_INVOKE_REQUEST';
+  requestId: string;
+  pluginId: string;
+  event: string;
+  args?: Record<string, unknown>;
+};
+/** Host → worklet: result for {@link HostInvokeRequestHeader}. */
+type HostInvokeResponseHeader = {
+  type: 'HOST_INVOKE_RESPONSE';
+  requestId: string;
+  pluginId: string;
+  event: string;
+  result?: unknown;
+  error?: CoreErrorWire;
+};
+/** Serializable row for discovery and host registry listing. */
+type CapabilityDescriptor = {
+  pluginId: string;
+  capabilities: string[];
+  events: string[];
+  runtimes: RuntimeTarget[];
+};
+type MessageHeader = PluginHeader | HostCapabilitiesQueryHeader | HostCapabilitiesResponseHeader | HostInvokeRequestHeader | HostInvokeResponseHeader;
+interface PluginContext {
+  runtime: RuntimeTarget;
+  payload: Uint8Array;
+}
+interface PluginRuntimeAdapter {
+  dispatch?: (event: string, args: Record<string, unknown> | undefined, context: PluginContext) => void | Promise<void>;
+  invoke?: (event: string, args: Record<string, unknown> | undefined, context: PluginContext) => Either<CoreError, unknown> | Promise<Either<CoreError, unknown>>;
+}
+interface PluginManifest {
+  id: string;
+  version?: string;
+  capabilities?: string[];
+  events?: string[];
+  runtimes: Partial<Record<RuntimeTarget, PluginRuntimeAdapter>>;
+}
+//#endregion
+//#region core/messages/errors.d.ts
+/** Success half of an `Either` tuple. */
+declare function ok<T>(result: T): [null, T];
+/** Failure half of an `Either` tuple. Accepts a canonical error code or any
+ * app-scoped code (`app.photos/not-found`) — the code is preserved verbatim. */
+declare function err(code: ErrorCodeOrString, message: string): [CoreError, null];
+/** Convenience for constructing a `CoreError` from a possibly-non-canonical
+ * wire code: preserves known codes, maps anything else to `PLUGIN_ERROR`.
+ * Framework callers that want app codes preserved construct the error
+ * directly instead. */
+declare function coerceErrorCode(code: string | undefined): ErrorCode;
+type Ok<T> = [null, T];
+type Err = [CoreError, null];
+type PluginResult<T> = Either<CoreError, T>;
+//#endregion
+//#region core/messages/rpc-messenger.d.ts
+type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K> : never;
+type InternalDispatchRequest = (PluginDispatchHeader & {
+  requestId: string;
+}) | (PluginInvokeRequestHeader & {
+  requestId: string;
+});
+type DispatchRequest = DistributiveOmit<PluginDispatchHeader, 'requestId'>;
+type InvokeRequest = DistributiveOmit<PluginInvokeRequestHeader, 'requestId'>;
+interface ProtocolMessenger {
+  dispatch(request: DispatchRequest, payload?: Uint8Array | ArrayBuffer | string | null): string;
+  invoke(request: InvokeRequest, payload?: Uint8Array | ArrayBuffer | string | null, timeoutMs?: number): Promise<MessageHeader>;
+  handleIncoming(header: MessageHeader): void;
+}
+declare function createProtocolMessenger(send: (request: InternalDispatchRequest, payload?: Uint8Array | ArrayBuffer | string | null) => void): ProtocolMessenger;
+//#endregion
+//#region core/messages/plugin-kernel.d.ts
+interface PluginRegistry {
+  register(plugin: PluginManifest): void;
+  resolve(pluginId: string, runtime: RuntimeTarget): PluginManifest['runtimes'][RuntimeTarget] | undefined;
+  get(pluginId: string): PluginManifest | undefined;
+  listCapabilities(runtime?: RuntimeTarget): Array<{
+    pluginId: string;
+    capabilities: string[];
+    events: string[];
+    runtimes: RuntimeTarget[];
+  }>;
+}
+declare function createPluginRegistry(): PluginRegistry;
+interface PluginRouter {
+  route(header: MessageHeader, payload: Uint8Array): Promise<PluginInvokeResponseHeader | null>;
+}
+type PluginRouterOptions = {
+  delegateToHost?: (header: PluginInvokeRequestHeader, payload: Uint8Array) => Promise<PluginInvokeResponseHeader | null>;
+  logger?: Pick<Console, 'warn' | 'error'>;
+};
+declare function createPluginRouter(registry: PluginRegistry, runtime: RuntimeTarget, options?: PluginRouterOptions): PluginRouter;
+interface PluginBus {
+  dispatch(envelope: DispatchEnvelope): string;
+  invoke<TResult>(envelope: InvokeEnvelope<string, Record<string, unknown>, TResult>): Promise<Either<CoreError, TResult>>;
+}
+declare function createPluginBus(messenger: ProtocolMessenger): PluginBus;
+//#endregion
+//#region core/messages/wire-codec.d.ts
+type Encoder = (str: string) => Uint8Array;
+type Decoder = (bytes: Uint8Array) => string;
+interface ProtocolOptions {
+  encode?: Encoder;
+  decode?: Decoder;
+  allowUnknownTypes?: boolean;
+  /** Override the default {@link MAX_FRAME_BYTES} cap. */
+  maxFrameBytes?: number;
+}
+declare class MessageProtocol {
+  private encodeStr;
+  private decodeStr;
+  private allowUnknownTypes;
+  private maxFrameBytes;
+  constructor(options?: ProtocolOptions);
+  encode(type: MessageTypeValue, header: MessageHeader, payload?: Uint8Array | ArrayBuffer | string | null): Uint8Array;
+  decode(data: ArrayBuffer | Uint8Array): WireMessage;
+}
+//#endregion
+//#region core/messages/define-plugin.d.ts
+/**
+ * One event's wire identity and type shape — the single source of truth for
+ * the manifest `events` list, the generated handler table, and the typed
+ * builders in `events.ts`. `args`/`result` are phantom values that carry the
+ * handler and builder types so they can never drift apart.
+ */
+interface EventSpec<TArgs extends Record<string, unknown> = Record<string, never>, TResult = unknown> {
+  readonly pluginId: string;
+  readonly name: string;
+  readonly args: TArgs;
+  readonly result: TResult;
+}
+type InvokeHandler<TArgs extends Record<string, unknown> = Record<string, never>, TResult = unknown> = (args: TArgs, context: PluginContext) => Either<CoreError, TResult> | Promise<Either<CoreError, TResult>>;
+type DispatchHandler<TArgs extends Record<string, unknown> = Record<string, never>> = (args: TArgs, context: PluginContext) => void | Promise<void>;
+type InvokeHandlers<TSpecs extends Record<string, EventSpec<any, any>>> = { [K in keyof TSpecs]?: InvokeHandler<TSpecs[K]['args'], TSpecs[K]['result']>; };
+type DispatchHandlers<TSpecs extends Record<string, EventSpec<any, any>>> = { [K in keyof TSpecs]?: DispatchHandler<TSpecs[K]['args']>; };
+/**
+ * Builds a {@link PluginManifest} from an event spec table. The `events` list
+ * is derived from the specs and handlers are dispatched by event name — no
+ * hand-written if-chains. Handlers receive typed args. Plugins with no local
+ * handlers (host-delegated, e.g. `core.permissions`) pass no `invoke`/`dispatch`.
+ */
+declare function definePlugin<const TSpecs extends Record<string, EventSpec<any, any>>>(id: string, specs: TSpecs, options?: {
+  capabilities?: string[];
+  invoke?: InvokeHandlers<TSpecs>;
+  dispatch?: DispatchHandlers<TSpecs>;
+}): PluginManifest;
+/** Typed builder: an invoke envelope for a spec's event. */
+declare function invokeEvent<TSpec extends EventSpec<any, any>>(spec: TSpec, args: TSpec['args'], payload?: Uint8Array | ArrayBuffer | string | null, timeoutMs?: number): InvokeEnvelope<TSpec['name'], TSpec['args'], TSpec['result']>;
+/** Typed builder: a dispatch envelope for a spec's event. */
+declare function dispatchEvent<TSpec extends EventSpec<any, any>>(spec: TSpec, args: TSpec['args'], payload?: Uint8Array | ArrayBuffer | string | null): DispatchEnvelope<TSpec['name'], TSpec['args']>;
+//#endregion
+//#region core/messages/create-bare-runtime-context.d.ts
+interface BareRuntimeContext {
+  protocol: MessageProtocol;
+  pluginRegistry: PluginRegistry;
+  pluginRouter: PluginRouter;
+}
+declare function createBareRuntimeContext(plugins?: PluginManifest[], routerOptions?: PluginRouterOptions): BareRuntimeContext;
+//#endregion
+export { MAX_HEADER_BYTES as $, CapabilityDescriptor as A, InvokeEnvelope as B, createProtocolMessenger as C, coerceErrorCode as D, PluginResult as E, ErrorCodeOrString as F, PluginInvokeRequestHeader as G, PluginContext as H, HostCapabilitiesQueryHeader as I, PluginRuntimeAdapter as J, PluginInvokeResponseHeader as K, HostCapabilitiesResponseHeader as L, CoreErrorWire as M, DispatchEnvelope as N, err as O, Either as P, MAX_FRAME_BYTES as Q, HostInvokeRequestHeader as R, ProtocolMessenger as S, Ok as T, PluginDispatchHeader as U, MessageHeader as V, PluginHeader as W, WireMessage as X, RuntimeTarget as Y, ErrorCode as Z, createPluginBus as _, InvokeHandler as a, DispatchRequest as b, invokeEvent as c, MessageProtocol as d, MessageType as et, ProtocolOptions as f, PluginRouterOptions as g, PluginRouter as h, EventSpec as i, CoreError as j, ok as k, Decoder as l, PluginRegistry as m, createBareRuntimeContext as n, VERSION as nt, definePlugin as o, PluginBus as p, PluginManifest as q, DispatchHandler as r, dispatchEvent as s, BareRuntimeContext as t, MessageTypeValue as tt, Encoder as u, createPluginRegistry as v, Err as w, InvokeRequest as x, createPluginRouter as y, HostInvokeResponseHeader as z };

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import { $ as MAX_HEADER_BYTES, A as CapabilityDescriptor, B as InvokeEnvelope, C as createProtocolMessenger, D as coerceErrorCode, E as PluginResult, F as ErrorCodeOrString, G as PluginInvokeRequestHeader, H as PluginContext, I as HostCapabilitiesQueryHeader, J as PluginRuntimeAdapter, K as PluginInvokeResponseHeader, L as HostCapabilitiesResponseHeader, M as CoreErrorWire, N as DispatchEnvelope, O as err, P as Either, Q as MAX_FRAME_BYTES, R as HostInvokeRequestHeader, S as ProtocolMessenger, T as Ok, U as PluginDispatchHeader, V as MessageHeader, W as PluginHeader, X as WireMessage, Y as RuntimeTarget, Z as ErrorCode, _ as createPluginBus, a as InvokeHandler, b as DispatchRequest, c as invokeEvent, d as MessageProtocol, et as MessageType, f as ProtocolOptions, g as PluginRouterOptions, h as PluginRouter, i as EventSpec, j as CoreError, k as ok, l as Decoder, m as PluginRegistry, n as createBareRuntimeContext, nt as VERSION, o as definePlugin, p as PluginBus, q as PluginManifest, r as DispatchHandler, s as dispatchEvent, t as BareRuntimeContext, tt as MessageTypeValue, u as Encoder, v as createPluginRegistry, w as Err, x as InvokeRequest, y as createPluginRouter, z as HostInvokeResponseHeader } from "./index-DjulYFJL.mjs";
+export { BareRuntimeContext, CapabilityDescriptor, CoreError, CoreErrorWire, Decoder, DispatchEnvelope, DispatchHandler, DispatchRequest, Either, Encoder, Err, ErrorCode, ErrorCodeOrString, EventSpec, HostCapabilitiesQueryHeader, HostCapabilitiesResponseHeader, HostInvokeRequestHeader, HostInvokeResponseHeader, InvokeEnvelope, InvokeHandler, InvokeRequest, MAX_FRAME_BYTES, MAX_HEADER_BYTES, MessageHeader, MessageProtocol, MessageType, MessageTypeValue, Ok, PluginBus, PluginContext, PluginDispatchHeader, PluginHeader, PluginInvokeRequestHeader, PluginInvokeResponseHeader, PluginManifest, PluginRegistry, PluginResult, PluginRouter, PluginRouterOptions, PluginRuntimeAdapter, ProtocolMessenger, ProtocolOptions, RuntimeTarget, VERSION, WireMessage, coerceErrorCode, createBareRuntimeContext, createPluginBus, createPluginRegistry, createPluginRouter, createProtocolMessenger, definePlugin, dispatchEvent, err, invokeEvent, ok };