@modcore/plugin-ui-sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Initial public iframe-bridge types, constrained client, UI binding declaration, accessibility contract, and deterministic mock host.

package/README.md

@@ -0,0 +1,27 @@
+# `@modcore/plugin-ui-sdk`
+
+Framework-independent public SDK for a ModCore plugin UI. It is designed for the sandboxed iframe bridge and deliberately does not expose Vue, Router, Pinia, browser cookies, tokens, raw `fetch`, arbitrary URLs, or host-private modules.
+
+## Support contract
+
+- License: Apache-2.0
+- Protocol: `modcore.ui.bridge/v1`
+- Supported host range: `>=0.1.0 <0.2.0`
+- Node: `>=22.12.0`; package manager: pnpm `10.32.1`
+- Deprecation window: at least one complete SDK minor release
+- Security reports: <https://modcore.quatbyte.com/security>
+
+The built `dist/release-metadata.json` contains the exact source revision, protocol range, integrity-algorithm location, deprecation window, and security channel. Package-manager registry metadata provides the release tarball SHA-512 integrity value.
+
+## Usage
+
+```ts
+import { createPluginUiClient, defineUiBinding } from "@modcore/plugin-ui-sdk";
+import { createMockUiHost } from "@modcore/plugin-ui-sdk/testing";
+```
+
+Use `defineUiBinding()` for a `UI_ONLY` theme’s explicit target contract. `createPluginUiClient()` accepts only the authenticated host bridge transport; it has no API for URLs, authorization headers, cookies, or raw network clients. Use `createMockUiHost()` for local tests without a ModCore checkout, management token, or production host.
+
+## Release evidence
+
+Before a public release, run `pnpm test`, `pnpm test:types`, `pnpm build`, and `pnpm pack:check`; publish the generated package metadata, registry integrity value, source revision, changelog, and this support contract together. This source checkout does not publish to a registry automatically.

package/SECURITY.md

@@ -0,0 +1,5 @@
+# Security policy
+
+Report SDK vulnerabilities through <https://modcore.quatbyte.com/security>. Do not include tokens, cookies, customer data, or exploit payloads in public issues.
+
+The SDK never accepts arbitrary URLs, authorization headers, browser cookies, or raw `fetch` implementations. Hosts must still enforce all bridge authorization, tenant, rate, timeout, audit, and lifecycle checks.

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import { type UiAccessibilityDescriptor, type UiBinding, type UiBootstrapContext, type UiBridgeTransport, type UiContract, type UiLocalizer, type UiMessageCatalog, type UiTelemetryEvent } from "./types.js";
+export { BRIDGE_PROTOCOL } from "./types.js";
+export type * from "./types.js";
+/** Defines a static target binding without granting arbitrary HTTP or host access. */
+export declare function defineUiBinding<TContract extends UiContract>(binding: UiBinding<TContract>): UiBinding<TContract>;
+/** Rejects descriptors that cannot make the iframe boundary accessible to keyboard and AT users. */
+export declare function defineUiAccessibility(descriptor: UiAccessibilityDescriptor): UiAccessibilityDescriptor;
+/**
+ * Creates an isolated plugin-local translator. Host locale changes remain observable through the
+ * bridge client, while plugins retain ownership of their namespaced message catalogs.
+ */
+export declare function createUiLocalizer(locale: string, messages: UiMessageCatalog): UiLocalizer;
+export interface PluginUiClient<TContract extends UiContract> {
+    readonly context: UiBootstrapContext;
+    request<TOperationId extends keyof TContract["operations"] & string>(operationId: TOperationId, request: TContract["operations"][TOperationId]["request"]): Promise<TContract["operations"][TOperationId]["response"]>;
+    navigate(navigationId: string): Promise<void>;
+    telemetry(event: UiTelemetryEvent): Promise<void>;
+    onLocaleChange(listener: (locale: string) => void): () => void;
+    onThemeChange(listener: (tokens: Readonly<Record<string, string>>) => void): () => void;
+    dispose(): Promise<void>;
+}
+/**
+ * Creates a narrow client for an already-authenticated MessagePort bridge. The SDK intentionally
+ * accepts no URL, token, cookie, header, raw fetch implementation, Router, or framework object.
+ */
+export declare function createPluginUiClient<TContract extends UiContract>(context: UiBootstrapContext, transport: UiBridgeTransport<TContract>): PluginUiClient<TContract>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,mBAAmB,YAAY,CAAC;AAEhC,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,SAAS,SAAS,UAAU,EAAE,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC,SAAS,CAAC,CAQjH;AAED,oGAAoG;AACpG,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,yBAAyB,GAAG,yBAAyB,CAatG;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,WAAW,CAYzF;AAED,MAAM,WAAW,cAAc,CAAC,SAAS,SAAS,UAAU;IAC1D,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,OAAO,CAAC,YAAY,SAAS,MAAM,SAAS,CAAC,YAAY,CAAC,GAAG,MAAM,EACjE,WAAW,EAAE,YAAY,EACzB,OAAO,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,GACxD,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,YAAY,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,SAAS,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,cAAc,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC/D,aAAa,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACxF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,SAAS,UAAU,EAC/D,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,iBAAiB,CAAC,SAAS,CAAC,GACtC,cAAc,CAAC,SAAS,CAAC,CA0C3B"}

package/dist/index.js

@@ -0,0 +1,89 @@
+import { BRIDGE_PROTOCOL, } from "./types.js";
+export { BRIDGE_PROTOCOL } from "./types.js";
+/** Defines a static target binding without granting arbitrary HTTP or host access. */
+export function defineUiBinding(binding) {
+    if (!binding.id || !binding.targetPluginInstanceId || !binding.targetSurfaceId) {
+        throw new Error("A UI binding requires stable IDs for itself and its target surface.");
+    }
+    if (!binding.uiContract.id || !binding.uiContract.version || !/^[a-f0-9]{64}$/.test(binding.uiContract.schemaSha256)) {
+        throw new Error("A UI binding requires a versioned contract with a SHA-256 schema digest.");
+    }
+    return Object.freeze({ ...binding, uiContract: Object.freeze({ ...binding.uiContract }) });
+}
+/** Rejects descriptors that cannot make the iframe boundary accessible to keyboard and AT users. */
+export function defineUiAccessibility(descriptor) {
+    if (!descriptor.localizedIframeTitle.trim()) {
+        throw new Error("A plugin UI requires a localized iframe title.");
+    }
+    if (!descriptor.supportsKeyboardReturn ||
+        !descriptor.supportsReducedMotion ||
+        !descriptor.supportsUserColors ||
+        !descriptor.supportsTextZoom) {
+        throw new Error("A plugin UI must support keyboard return, reduced motion, user colors, and text zoom.");
+    }
+    return Object.freeze({ ...descriptor });
+}
+/**
+ * Creates an isolated plugin-local translator. Host locale changes remain observable through the
+ * bridge client, while plugins retain ownership of their namespaced message catalogs.
+ */
+export function createUiLocalizer(locale, messages) {
+    if (!locale.trim())
+        throw new Error("A plugin UI localizer requires a locale.");
+    return Object.freeze({
+        locale,
+        t(key, parameters = {}) {
+            const template = messages[key];
+            if (!template)
+                return key;
+            return template.replace(/\{([a-zA-Z][a-zA-Z0-9_.-]*)\}/g, (placeholder, name) => Object.hasOwn(parameters, name) ? String(parameters[name]) : placeholder);
+        },
+    });
+}
+/**
+ * Creates a narrow client for an already-authenticated MessagePort bridge. The SDK intentionally
+ * accepts no URL, token, cookie, header, raw fetch implementation, Router, or framework object.
+ */
+export function createPluginUiClient(context, transport) {
+    if (context.protocol !== BRIDGE_PROTOCOL || context.policyGeneration < 1) {
+        throw new Error("The host supplied an unsupported UI bridge context.");
+    }
+    let disposed = false;
+    const requireActive = () => {
+        if (disposed)
+            throw new Error("The plugin UI bridge has been disposed.");
+    };
+    return Object.freeze({
+        context: Object.freeze({ ...context, themeTokens: Object.freeze({ ...context.themeTokens }) }),
+        async request(operationId, request) {
+            requireActive();
+            return transport.request(operationId, request);
+        },
+        async navigate(navigationId) {
+            requireActive();
+            if (!context.allowedNavigationIds.includes(navigationId)) {
+                throw new Error("Navigation target is not authorized by the host.");
+            }
+            await transport.navigate(navigationId);
+        },
+        async telemetry(event) {
+            requireActive();
+            await transport.telemetry(event);
+        },
+        onLocaleChange(listener) {
+            requireActive();
+            return transport.onLocaleChange(listener);
+        },
+        onThemeChange(listener) {
+            requireActive();
+            return transport.onThemeChange(listener);
+        },
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            await transport.dispose();
+        },
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/release-metadata.json

@@ -0,0 +1,14 @@
+{
+  "license": "Apache-2.0",
+  "sourceRevision": "86fb0c51b0de6734dd9fe1dedb2f7d03b1727b78",
+  "protocols": [
+    "modcore.ui.bridge/v1"
+  ],
+  "supportedHostVersions": ">=0.1.0 <0.2.0",
+  "integrity": {
+    "algorithm": "sha512",
+    "location": "package-manager registry metadata"
+  },
+  "deprecationWindow": "At least one complete SDK minor release.",
+  "securityDisclosure": "https://modcore.quatbyte.com/security"
+}

package/dist/testing.d.ts

@@ -0,0 +1,16 @@
+import { type UiBootstrapContext, type UiBridgeTransport, type UiContract } from "./types.js";
+export interface MockUiHost<TContract extends UiContract> {
+    readonly context: UiBootstrapContext;
+    readonly transport: UiBridgeTransport<TContract>;
+    readonly calls: readonly {
+        readonly kind: string;
+        readonly value: unknown;
+    }[];
+    setLocale(locale: string): void;
+    setTheme(tokens: Readonly<Record<string, string>>): void;
+}
+/** A deterministic local host for SDK tests; it exposes only operations declared by the contract. */
+export declare function createMockUiHost<TContract extends UiContract>(contract: TContract, responses: Partial<{
+    [K in keyof TContract["operations"] & string]: TContract["operations"][K]["response"];
+}>, context: Omit<UiBootstrapContext, "protocol">): MockUiHost<TContract>;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,KAAK,UAAU,EAAyB,MAAM,YAAY,CAAC;AAEtI,MAAM,WAAW,UAAU,CAAC,SAAS,SAAS,UAAU;IACtD,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IACjD,QAAQ,CAAC,KAAK,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IAC9E,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC;CAC1D;AAED,qGAAqG;AACrG,wBAAgB,gBAAgB,CAAC,SAAS,SAAS,UAAU,EAC3D,QAAQ,EAAE,SAAS,EACnB,SAAS,EAAE,OAAO,CAAC;KAAG,CAAC,IAAI,MAAM,SAAS,CAAC,YAAY,CAAC,GAAG,MAAM,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;CAAE,CAAC,EAC7G,OAAO,EAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC,GAC5C,UAAU,CAAC,SAAS,CAAC,CAiDvB"}

package/dist/testing.js

@@ -0,0 +1,54 @@
+import { BRIDGE_PROTOCOL } from "./types.js";
+/** A deterministic local host for SDK tests; it exposes only operations declared by the contract. */
+export function createMockUiHost(contract, responses, context) {
+    const calls = [];
+    const localeListeners = new Set();
+    const themeListeners = new Set();
+    let disposed = false;
+    const requireActive = () => {
+        if (disposed)
+            throw new Error("Mock UI host is disposed.");
+    };
+    const transport = {
+        async request(operationId, request) {
+            requireActive();
+            if (!(operationId in contract.operations) || !(operationId in responses)) {
+                throw new Error("Mock host rejected an undeclared or unconfigured operation.");
+            }
+            calls.push({ kind: "request", value: { operationId, request } });
+            return responses[operationId];
+        },
+        async navigate(navigationId) {
+            requireActive();
+            calls.push({ kind: "navigate", value: navigationId });
+        },
+        async telemetry(event) {
+            requireActive();
+            calls.push({ kind: "telemetry", value: event });
+        },
+        async dispose() {
+            disposed = true;
+            calls.push({ kind: "dispose", value: null });
+        },
+        onLocaleChange(listener) {
+            localeListeners.add(listener);
+            return () => localeListeners.delete(listener);
+        },
+        onThemeChange(listener) {
+            themeListeners.add(listener);
+            return () => themeListeners.delete(listener);
+        },
+    };
+    return {
+        context: Object.freeze({ ...context, protocol: BRIDGE_PROTOCOL }),
+        transport,
+        calls,
+        setLocale(locale) {
+            localeListeners.forEach((listener) => listener(locale));
+        },
+        setTheme(tokens) {
+            themeListeners.forEach((listener) => listener(tokens));
+        },
+    };
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAA2F,MAAM,YAAY,CAAC;AAUtI,qGAAqG;AACrG,MAAM,UAAU,gBAAgB,CAC9B,QAAmB,EACnB,SAA6G,EAC7G,OAA6C;IAE7C,MAAM,KAAK,GAAuC,EAAE,CAAC;IACrD,MAAM,eAAe,GAAG,IAAI,GAAG,EAA4B,CAAC;IAC5D,MAAM,cAAc,GAAG,IAAI,GAAG,EAAsD,CAAC;IACrF,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,MAAM,aAAa,GAAG,GAAS,EAAE;QAC/B,IAAI,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC7D,CAAC,CAAC;IACF,MAAM,SAAS,GAAiC;QAC9C,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO;YAChC,aAAa,EAAE,CAAC;YAChB,IAAI,CAAC,CAAC,WAAW,IAAI,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,WAAW,IAAI,SAAS,CAAC,EAAE,CAAC;gBACzE,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;YACjF,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;YACjE,OAAO,SAAS,CAAC,WAAW,CAA4D,CAAC;QAC3F,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,YAAY;YACzB,aAAa,EAAE,CAAC;YAChB,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,KAAK,CAAC,SAAS,CAAC,KAAuB;YACrC,aAAa,EAAE,CAAC;YAChB,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAClD,CAAC;QACD,KAAK,CAAC,OAAO;YACX,QAAQ,GAAG,IAAI,CAAC;YAChB,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/C,CAAC;QACD,cAAc,CAAC,QAAQ;YACrB,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC9B,OAAO,GAAG,EAAE,CAAC,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAChD,CAAC;QACD,aAAa,CAAC,QAAQ;YACpB,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC7B,OAAO,GAAG,EAAE,CAAC,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC/C,CAAC;KACF,CAAC;IACF,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC;QACjE,SAAS;QACT,KAAK;QACL,SAAS,CAAC,MAAM;YACd,eAAe,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QAC1D,CAAC;QACD,QAAQ,CAAC,MAAM;YACb,cAAc,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACzD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+/** Stable types for the framework-independent ModCore UI bridge. */
+export declare const BRIDGE_PROTOCOL: "modcore.ui.bridge/v1";
+export type BridgeProtocol = typeof BRIDGE_PROTOCOL;
+export interface UiCandidateIdentity {
+    readonly providerPluginInstanceId: string;
+    readonly providerPluginId: string;
+    readonly artifactSha256: string;
+    readonly uiId: string;
+    readonly bindingId?: string;
+}
+export interface UiBootstrapContext {
+    readonly protocol: BridgeProtocol;
+    readonly candidate: UiCandidateIdentity;
+    readonly surfaceId: string;
+    readonly policyGeneration: number;
+    readonly locale: string;
+    readonly themeTokens: Readonly<Record<string, string>>;
+    readonly allowedNavigationIds: readonly string[];
+}
+export interface UiContractOperation<TRequest = unknown, TResponse = unknown> {
+    readonly id: string;
+    readonly request: TRequest;
+    readonly response: TResponse;
+    readonly access: "read" | "write";
+}
+export interface UiContract<TOperation extends UiContractOperation = UiContractOperation> {
+    readonly id: string;
+    readonly version: string;
+    readonly schemaSha256: string;
+    readonly operations: Readonly<Record<string, TOperation>>;
+}
+export interface UiBinding<TContract extends UiContract = UiContract> {
+    readonly id: string;
+    readonly targetPluginInstanceId: string;
+    readonly targetSurfaceId: string;
+    readonly uiContract: Pick<TContract, "id" | "version" | "schemaSha256">;
+}
+export interface UiTelemetryEvent {
+    readonly name: string;
+    readonly numericValues?: Readonly<Record<string, number>>;
+    readonly reviewedLabels?: Readonly<Record<string, string>>;
+}
+export interface UiAccessibilityDescriptor {
+    readonly localizedIframeTitle: string;
+    readonly statusRole: "status" | "alert";
+    readonly supportsKeyboardReturn: true;
+    readonly supportsReducedMotion: true;
+    readonly supportsUserColors: true;
+    readonly supportsTextZoom: true;
+}
+export type UiMessageCatalog = Readonly<Record<string, string>>;
+export interface UiLocalizer {
+    readonly locale: string;
+    t(key: string, parameters?: Readonly<Record<string, string | number>>): string;
+}
+export interface UiBridgeTransport<TContract extends UiContract = UiContract> {
+    request<TOperationId extends keyof TContract["operations"] & string>(operationId: TOperationId, request: TContract["operations"][TOperationId]["request"]): Promise<TContract["operations"][TOperationId]["response"]>;
+    navigate(navigationId: string): Promise<void>;
+    telemetry(event: UiTelemetryEvent): Promise<void>;
+    dispose(): Promise<void>;
+    onLocaleChange(listener: (locale: string) => void): () => void;
+    onThemeChange(listener: (tokens: Readonly<Record<string, string>>) => void): () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,3 @@
+/** Stable types for the framework-independent ModCore UI bridge. */
+export const BRIDGE_PROTOCOL = "modcore.ui.bridge/v1";
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,oEAAoE;AAEpE,MAAM,CAAC,MAAM,eAAe,GAAG,sBAA+B,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@modcore/plugin-ui-sdk",
+  "version": "0.1.0",
+  "description": "Public, framework-independent UI bridge SDK for ModCore plugins.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "packageManager": "pnpm@10.32.1",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "clean": "node ./scripts/clean.mjs",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json && node ./scripts/write-release-metadata.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && node --test test/**/*.test.mjs",
+    "test:types": "tsc -p tsconfig.test.json --noEmit",
+    "pack:check": "pnpm pack --pack-destination .artifacts"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "modcore": {
+    "protocol": "modcore.ui.bridge/v1",
+    "supportedHostVersions": ">=0.1.0 <0.2.0",
+    "sourceRevision": "generated-at-build",
+    "deprecationWindow": "At least one complete SDK minor release.",
+    "securityDisclosure": "https://modcore.quatbyte.com/security"
+  }
+}