@zihanw/pi-forge 0.5.0 → 0.5.2

package/dist/ui-contribution/contrib-port.d.ts

@@ -0,0 +1,170 @@
+import type { FormSchema, FormValues } from "../web-editor/schema-form.ts";
+/**
+ * Cross-extension UI contribution port v1 over the Pi event bus.
+ *
+ * This is the generic, versioned RPC contract used by optional packages to
+ * contribute schema-driven tabs to the pi-forge web editor. Messages are plain,
+ * recursively validated, JSON-compatible data only — no functions, components,
+ * live contexts, or internal registries cross the bus. The port itself is not a
+ * trust boundary.
+ *
+ * Ownership: the contributing package owns the schema, current values, and
+ * persistence/validation for its tab. The pi-forge web server only proxies
+ * descriptors to the browser and writes submitted values back over the bus.
+ */
+export declare const UI_CONTRIBUTION_PORT_VERSION = 1;
+export declare const UI_CONTRIBUTION_PORT_NAMESPACE = "@zihanw/pi-forge/ui-contribution/v1";
+export declare const UI_CONTRIBUTION_PORT_OPERATIONS: readonly ["listContributions", "writeValues"];
+export type UiContributionPortOperation = (typeof UI_CONTRIBUTION_PORT_OPERATIONS)[number];
+export declare const UI_CONTRIBUTION_CHANNEL: {
+    readonly discover: "@zihanw/pi-forge/ui-contribution/v1/discover";
+    readonly available: "@zihanw/pi-forge/ui-contribution/v1/available";
+    readonly request: "@zihanw/pi-forge/ui-contribution/v1/request";
+    readonly reply: "@zihanw/pi-forge/ui-contribution/v1/reply";
+    readonly unavailable: "@zihanw/pi-forge/ui-contribution/v1/unavailable";
+};
+export interface UiContributionTransport {
+    emit(channel: string, data: unknown): void;
+    on(channel: string, handler: (data: unknown) => void): () => void;
+}
+export type UiContributionWireMessage = {
+    type: "discover";
+    protocolVersion: number;
+    minVersion: number;
+    maxVersion: number;
+    clientId: string;
+} | {
+    type: "available";
+    hostId: string;
+    protocolVersion: number;
+    minVersion: number;
+    maxVersion: number;
+    capabilities: string[];
+    generation: number;
+} | {
+    type: "request";
+    requestId: string;
+    hostId: string;
+    generation: number;
+    operation: string;
+    payload: unknown;
+} | {
+    type: "reply";
+    requestId: string;
+    hostId: string;
+    generation: number;
+    ok: boolean;
+    data?: unknown;
+    error?: string;
+} | {
+    type: "unavailable";
+    hostId: string;
+    generation: number;
+};
+export type UiContributionPortResult = {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+export interface UiContributionRequestContext {
+    /** Aborted when the provider generation stops; handlers must check before side effects after an await. */
+    signal: AbortSignal;
+    generation: number;
+}
+export interface UiContributionProviderOptions {
+    providerId?: string;
+    capabilities?: readonly string[];
+    minVersion?: number;
+    maxVersion?: number;
+    /** Operation handler; must never throw across the bus. */
+    handle(operation: string, payload: unknown, context: UiContributionRequestContext): UiContributionPortResult | Promise<UiContributionPortResult>;
+}
+export interface UiContributionConnection {
+    hostId: string;
+    protocolVersion: number;
+    capabilities: readonly string[];
+    generation: number;
+}
+export interface UiContributionTabDescriptor {
+    tabId: string;
+    title: string;
+    icon: string;
+    schema: FormSchema;
+    values: FormValues;
+}
+export interface UiListContributionsResponse {
+    tabs: UiContributionTabDescriptor[];
+}
+export interface UiWriteValuesRequest {
+    tabId: string;
+    patch: FormValues;
+}
+export type UiWriteValuesResponse = {
+    ok: true;
+    values?: FormValues;
+} | {
+    ok: false;
+    errors: Record<string, string>;
+};
+export type ValidationResult<T = unknown> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+};
+export declare class UiContributionPortError extends Error {
+    readonly code: "timeout" | "duplicate" | "unavailable" | "protocol" | "invalid";
+    constructor(code: UiContributionPortError["code"], message: string);
+}
+export declare function validateListContributionsRequest(value: unknown): ValidationResult<Record<string, never>>;
+export declare function validateListContributionsResponse(value: unknown): ValidationResult<UiListContributionsResponse>;
+export declare function validateUiContributionTabDescriptor(value: unknown): ValidationResult<UiContributionTabDescriptor>;
+export declare function validateWriteValuesRequest(value: unknown): ValidationResult<UiWriteValuesRequest>;
+export declare function validateWriteValuesResponse(value: unknown): ValidationResult<UiWriteValuesResponse>;
+export declare function validateFormSchema(value: unknown): ValidationResult<FormSchema>;
+export declare class UiContributionProvider {
+    private readonly transport;
+    private readonly options;
+    readonly hostId: string;
+    private generationId;
+    private started;
+    private unsubscribers;
+    private readonly pendingRequests;
+    constructor(transport: UiContributionTransport, options: UiContributionProviderOptions);
+    get generation(): number;
+    get isLive(): boolean;
+    private availableMessage;
+    start(): void;
+    stop(): void;
+    private onDiscover;
+    private onRequest;
+}
+export interface UiContributionClientOptions {
+    clientId?: string;
+    defaultTimeoutMs?: number;
+    discoverSettleMs?: number;
+}
+export declare class UiContributionClient {
+    private readonly transport;
+    readonly clientId: string;
+    private readonly defaultTimeoutMs;
+    private readonly discoverSettleMs;
+    private connectionUnsubscribe?;
+    private unavailableHandlers;
+    private activeConnection?;
+    constructor(transport: UiContributionTransport, options?: UiContributionClientOptions);
+    onUnavailable(handler: () => void): () => void;
+    private teardownPersistentListener;
+    private onUnavailableMessage;
+    discover(timeoutMs?: number): Promise<UiContributionConnection>;
+    connect(connection: UiContributionConnection): UiContributionConnection;
+    request(connection: UiContributionConnection, operation: string, payload: unknown, timeoutMs?: number): Promise<UiContributionPortResult>;
+    listContributions(connection: UiContributionConnection, timeoutMs?: number): Promise<UiContributionPortResult>;
+    writeValues(connection: UiContributionConnection, tabId: string, patch: FormValues, timeoutMs?: number): Promise<UiContributionPortResult>;
+    disconnect(): void;
+    get subscriptionCount(): number;
+}
+//# sourceMappingURL=contrib-port.d.ts.map

package/dist/ui-contribution/contrib-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contrib-port.d.ts","sourceRoot":"","sources":["../../src/ui-contribution/contrib-port.ts"],"names":[],"mappings":"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"}