@fntio/infra-client-plugin-sdk 0.0.0-stage → 0.2.0

package/dist/fixtures/fakeDocument.d.ts

@@ -0,0 +1,12 @@
+import { PluginThemeDocument, PluginThemeStyleElement } from "../browser/theme-apply";
+export interface FakeThemeDocument {
+    readonly doc: PluginThemeDocument;
+    /** Attributes set on the root element (`data-theme`). */
+    readonly attributes: Record<string, string>;
+    /** Style elements by id; `applyPluginTheme` rewrites the same one in place. */
+    readonly styles: Map<string, PluginThemeStyleElement>;
+    /** Ids in append order, to prove nothing is appended twice. */
+    readonly appended: string[];
+}
+/** The slice of `document` the SDK themes, for tests of plugins and of the SDK itself. */
+export declare function createFakeThemeDocument(): FakeThemeDocument;

package/dist/fixtures/fakeDocument.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFakeThemeDocument = createFakeThemeDocument;
+/** The slice of `document` the SDK themes, for tests of plugins and of the SDK itself. */
+function createFakeThemeDocument() {
+    const attributes = {};
+    const styles = new Map();
+    const appended = [];
+    const doc = {
+        documentElement: { setAttribute: (name, value) => void (attributes[name] = value) },
+        head: {
+            appendChild: (node) => {
+                const element = node;
+                appended.push(element.id);
+                styles.set(element.id, element);
+            },
+        },
+        getElementById: (id) => styles.get(id) ?? null,
+        createElement: () => ({ id: "", textContent: null }),
+    };
+    return { doc, attributes, styles, appended };
+}

package/dist/fixtures/fakeWindows.d.ts

@@ -0,0 +1,22 @@
+import { PluginMessageEventLike, PluginMessageListenerTarget, PluginMessagePort } from "../contracts/transport";
+export interface FakeWindow extends PluginMessagePort, PluginMessageListenerTarget {
+    readonly origin: string;
+    /** Everything posted TO this window (`window.postMessage` is called on the target), oldest
+     *  first, with the origin the caller addressed. */
+    readonly inbox: ReadonlyArray<{
+        readonly message: unknown;
+        readonly targetOrigin: string;
+    }>;
+    /** Deliver an event straight to this window's listeners, bypassing the peer (spoofing tests). */
+    receive(event: PluginMessageEventLike): void;
+}
+export interface FakeWindowPair {
+    readonly host: FakeWindow;
+    readonly plugin: FakeWindow;
+}
+/** Two windows wired like a portal page and its plugin iframe. Browser semantics: calling
+ *  `postMessage` on a window delivers to that window's listeners, on a microtask, with the OTHER
+ *  window as `source`; a `targetOrigin` other than `*` or the target's own origin drops the message. */
+export declare function createFakeWindowPair(hostOrigin?: string, pluginOrigin?: string): FakeWindowPair;
+/** Let queued deliveries and the promise chains behind them run. */
+export declare function settle(): Promise<void>;

package/dist/fixtures/fakeWindows.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFakeWindowPair = createFakeWindowPair;
+exports.settle = settle;
+// jest-environment-jsdom 29 has no structuredClone; JSON is close enough for protocol payloads.
+const clone = typeof structuredClone === "function" ? structuredClone : (value) => JSON.parse(JSON.stringify(value));
+/** Two windows wired like a portal page and its plugin iframe. Browser semantics: calling
+ *  `postMessage` on a window delivers to that window's listeners, on a microtask, with the OTHER
+ *  window as `source`; a `targetOrigin` other than `*` or the target's own origin drops the message. */
+function createFakeWindowPair(hostOrigin = "https://portal.example", pluginOrigin = hostOrigin) {
+    const make = (origin) => {
+        const listeners = new Set();
+        const inbox = [];
+        let peer;
+        const self = {
+            origin,
+            inbox,
+            link: (other) => (peer = other),
+            postMessage(message, targetOrigin) {
+                inbox.push({ message, targetOrigin });
+                const data = clone(message);
+                const source = peer;
+                if (!source || (targetOrigin !== "*" && targetOrigin !== origin))
+                    return;
+                // A promise microtask, not queueMicrotask: fake timers stub the latter and would stall delivery.
+                void Promise.resolve().then(() => self.receive({ data, origin: source.origin, source }));
+            },
+            addEventListener: (_type, listener) => void listeners.add(listener),
+            removeEventListener: (_type, listener) => void listeners.delete(listener),
+            receive: (event) => {
+                for (const listener of [...listeners])
+                    listener(event);
+            },
+        };
+        return self;
+    };
+    const host = make(hostOrigin);
+    const plugin = make(pluginOrigin);
+    host.link(plugin);
+    plugin.link(host);
+    return { host, plugin };
+}
+/** Let queued deliveries and the promise chains behind them run. */
+async function settle() {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+}

package/dist/fixtures/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./samples";
+export * from "./fakeWindows";
+export * from "./fakeDocument";
+export * from "./devHost";

package/dist/fixtures/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./samples"), exports);
+__exportStar(require("./fakeWindows"), exports);
+__exportStar(require("./fakeDocument"), exports);
+__exportStar(require("./devHost"), exports);

package/dist/fixtures/samples.d.ts

@@ -0,0 +1,37 @@
+import { PluginAuthorizerContextV1 } from "../contracts/authorizer";
+import { PluginCatalogRecordV1 } from "../contracts/catalog";
+import { PluginDiscoveryResponseV1 } from "../contracts/discovery";
+import { PluginManifestV1 } from "../contracts/manifest";
+import { HostToPluginPayloads, PluginAccountContext } from "../contracts/messages";
+import { PluginTheme } from "../contracts/theme";
+import { PluginValidationCode } from "../contracts/validate";
+export declare const FIXTURE_ACCOUNT_A = "111111111111";
+export declare const FIXTURE_ACCOUNT_B = "222222222222";
+/** The reference plugin: user + admin, two UI entries, three routes on one handler. */
+export declare const parametersManifest: PluginManifestV1;
+export declare const PARAMETERS_HANDLER_KEYS: readonly string[];
+export declare const uiOnlyManifest: PluginManifestV1;
+export declare const backendOnlyManifest: PluginManifestV1;
+export declare const adminOnlyUiManifest: PluginManifestV1;
+export declare const disabledManifest: PluginManifestV1;
+export interface ValidManifestFixture {
+    readonly name: string;
+    readonly manifest: PluginManifestV1;
+    readonly handlerKeys?: readonly string[];
+}
+export declare const validManifests: readonly ValidManifestFixture[];
+export interface InvalidManifestFixture {
+    readonly name: string;
+    readonly manifest: unknown;
+    /** The code the validator must report (it may report others too). */
+    readonly code: PluginValidationCode;
+    readonly handlerKeys?: readonly string[];
+}
+export declare const invalidManifests: readonly InvalidManifestFixture[];
+export declare const sampleTheme: PluginTheme;
+export declare const sampleDarkTheme: PluginTheme;
+export declare const sampleCatalogRecord: PluginCatalogRecordV1;
+export declare const sampleAccounts: readonly PluginAccountContext[];
+export declare const sampleDiscoveryResponse: PluginDiscoveryResponseV1;
+export declare const sampleInitPayload: HostToPluginPayloads["init"];
+export declare const sampleAuthorizerContext: PluginAuthorizerContextV1;

package/dist/fixtures/samples.js

@@ -0,0 +1,220 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sampleAuthorizerContext = exports.sampleInitPayload = exports.sampleDiscoveryResponse = exports.sampleAccounts = exports.sampleCatalogRecord = exports.sampleDarkTheme = exports.sampleTheme = exports.invalidManifests = exports.validManifests = exports.disabledManifest = exports.adminOnlyUiManifest = exports.backendOnlyManifest = exports.uiOnlyManifest = exports.PARAMETERS_HANDLER_KEYS = exports.parametersManifest = exports.FIXTURE_ACCOUNT_B = exports.FIXTURE_ACCOUNT_A = void 0;
+const paths_1 = require("../contracts/paths");
+exports.FIXTURE_ACCOUNT_A = "111111111111";
+exports.FIXTURE_ACCOUNT_B = "222222222222";
+/** The reference plugin: user + admin, two UI entries, three routes on one handler. */
+exports.parametersManifest = {
+    schemaVersion: 1,
+    id: "parameters",
+    displayName: "Application parameters",
+    description: "Read and edit SSM parameters under the configured prefixes.",
+    version: "1.0.0",
+    hostApiVersion: 1,
+    enabled: true,
+    accounts: [{ accountNumber: exports.FIXTURE_ACCOUNT_A, regions: ["eu-central-1"] }, { accountNumber: exports.FIXTURE_ACCOUNT_B }],
+    permissions: [
+        { id: "user", label: "View application parameters" },
+        { id: "admin", label: "Edit application parameters", description: "Includes viewing." },
+    ],
+    ui: {
+        user: { label: "Parameters", icon: "sliders", order: 10, entry: "index.html#/user" },
+        admin: { label: "Parameters", icon: "sliders", order: 10, entry: "index.html#/admin" },
+    },
+    routes: [
+        { id: "list", method: "GET", path: "/parameters", permission: "user", handlerKey: "api" },
+        { id: "get", method: "GET", path: "/parameters/{name}", permission: "user", handlerKey: "api" },
+        { id: "update", method: "PUT", path: "/parameters/{name}", permission: "admin", handlerKey: "api" },
+    ],
+};
+exports.PARAMETERS_HANDLER_KEYS = ["api"];
+exports.uiOnlyManifest = {
+    schemaVersion: 1,
+    id: "status-board",
+    displayName: "Status board",
+    version: "2.3.1",
+    hostApiVersion: 1,
+    enabled: true,
+    accounts: [{ accountNumber: exports.FIXTURE_ACCOUNT_A }],
+    permissions: [{ id: "user", label: "View the status board" }],
+    ui: { user: { label: "Status", entry: "board.html" } },
+    routes: [],
+};
+exports.backendOnlyManifest = {
+    schemaVersion: 1,
+    id: "backup-jobs",
+    displayName: "Database backups",
+    version: "0.4.0",
+    hostApiVersion: 1,
+    enabled: true,
+    accounts: [{ accountNumber: exports.FIXTURE_ACCOUNT_B, regions: ["eu-central-1", "eu-west-1"] }],
+    permissions: [{ id: "admin", label: "Run and inspect backups" }],
+    routes: [
+        { id: "start", method: "POST", path: "/jobs", permission: "admin", handlerKey: "jobs" },
+        { id: "status", method: "GET", path: "/jobs/{jobId}", permission: "admin", handlerKey: "jobs" },
+        { id: "cancel", method: "DELETE", path: "/jobs/{jobId}", permission: "admin", handlerKey: "jobs" },
+    ],
+};
+exports.adminOnlyUiManifest = {
+    schemaVersion: 1,
+    id: "feature-flags",
+    displayName: "Feature flags",
+    version: "1.0.0",
+    hostApiVersion: 1,
+    enabled: true,
+    accounts: [{ accountNumber: exports.FIXTURE_ACCOUNT_A }],
+    permissions: [{ id: "admin", label: "Manage feature flags" }],
+    ui: { admin: { label: "Feature flags", entry: "index.html" } },
+    routes: [{ id: "root", method: "GET", path: "/", permission: "admin", handlerKey: "flags" }],
+};
+exports.disabledManifest = { ...exports.parametersManifest, id: "parameters-legacy", enabled: false };
+exports.validManifests = [
+    { name: "user + admin with UI and routes", manifest: exports.parametersManifest, handlerKeys: exports.PARAMETERS_HANDLER_KEYS },
+    { name: "UI-only", manifest: exports.uiOnlyManifest, handlerKeys: [] },
+    { name: "backend-only", manifest: exports.backendOnlyManifest, handlerKeys: ["jobs"] },
+    { name: "admin-only with a root route", manifest: exports.adminOnlyUiManifest, handlerKeys: ["flags"] },
+    { name: "disabled", manifest: exports.disabledManifest, handlerKeys: exports.PARAMETERS_HANDLER_KEYS },
+];
+const patch = (p) => ({ ...exports.parametersManifest, ...p });
+const route = (o) => ({
+    id: "r", method: "GET", path: "/x", permission: "user", handlerKey: "api", ...o,
+});
+const userUi = { user: exports.parametersManifest.ui.user };
+exports.invalidManifests = [
+    { name: "not an object", manifest: "parameters", code: "not-an-object" },
+    { name: "unknown top-level field", manifest: patch({ handler: "api" }), code: "unknown-field" },
+    { name: "schemaVersion 2", manifest: patch({ schemaVersion: 2 }), code: "schema-version" },
+    { name: "hostApiVersion 2", manifest: patch({ hostApiVersion: 2 }), code: "host-api-version" },
+    { name: "id with uppercase", manifest: patch({ id: "Parameters" }), code: "plugin-id" },
+    { name: "id starting with a digit", manifest: patch({ id: "1parameters" }), code: "plugin-id" },
+    { name: "id too long", manifest: patch({ id: "a".repeat(65) }), code: "plugin-id" },
+    { name: "blank displayName", manifest: patch({ displayName: " " }), code: "display-name" },
+    { name: "version with a space", manifest: patch({ version: "1.0 beta" }), code: "version" },
+    { name: "enabled as a string", manifest: patch({ enabled: "yes" }), code: "enabled" },
+    { name: "no accounts", manifest: patch({ accounts: [] }), code: "accounts-empty" },
+    { name: "short account number", manifest: patch({ accounts: [{ accountNumber: "12345" }] }), code: "account-number" },
+    { name: "account bound twice", manifest: patch({ accounts: [{ accountNumber: exports.FIXTURE_ACCOUNT_A }, { accountNumber: exports.FIXTURE_ACCOUNT_A }] }), code: "account-duplicate" },
+    { name: "invalid region", manifest: patch({ accounts: [{ accountNumber: exports.FIXTURE_ACCOUNT_A, regions: ["europe"] }] }), code: "region" },
+    { name: "region listed twice", manifest: patch({ accounts: [{ accountNumber: exports.FIXTURE_ACCOUNT_A, regions: ["eu-central-1", "eu-central-1"] }] }), code: "region-duplicate" },
+    { name: "no permissions", manifest: patch({ permissions: [] }), code: "permissions-empty" },
+    { name: "unknown permission id", manifest: patch({ permissions: [{ id: "owner", label: "Owner" }] }), code: "permission-id" },
+    { name: "permission declared twice", manifest: patch({ permissions: [{ id: "user", label: "A" }, { id: "user", label: "B" }] }), code: "permission-duplicate" },
+    { name: "permission without a label", manifest: patch({ permissions: [{ id: "user", label: "" }, { id: "admin", label: "Edit" }] }), code: "permission-label" },
+    { name: "empty ui object", manifest: patch({ ui: {} }), code: "ui-empty" },
+    { name: "a third UI entry", manifest: patch({ ui: { ...exports.parametersManifest.ui, reports: { label: "Reports", entry: "index.html#/reports" } } }), code: "ui-unknown-entry" },
+    { name: "admin entry without the admin permission", manifest: patch({ permissions: [{ id: "user", label: "View" }], routes: [route({})], ui: { admin: { label: "Admin", entry: "index.html#/admin" } } }), code: "ui-undeclared-permission" },
+    { name: "absolute entry path", manifest: patch({ ui: { user: { label: "P", entry: "/index.html" } } }), code: "ui-entry-path" },
+    { name: "entry is a URL", manifest: patch({ ui: { user: { label: "P", entry: "https://example.com/index.html" } } }), code: "ui-entry-path" },
+    { name: "entry escapes the asset directory", manifest: patch({ ui: { user: { label: "P", entry: "../index.html" } } }), code: "ui-entry-path" },
+    { name: "entry without a file before the hash", manifest: patch({ ui: { user: { label: "P", entry: "#/user" } } }), code: "ui-entry-path" },
+    { name: "icon with spaces", manifest: patch({ ui: { user: { label: "P", icon: "my icon", entry: "index.html" } } }), code: "ui-icon" },
+    { name: "order not an integer", manifest: patch({ ui: { user: { label: "P", order: 1.5, entry: "index.html" } } }), code: "ui-order" },
+    { name: "route id used twice", manifest: patch({ routes: [route({ id: "list", path: "/a" }), route({ id: "list", path: "/b" })] }), code: "route-duplicate-id" },
+    { name: "route method ANY", manifest: patch({ routes: [route({ method: "ANY" })] }), code: "route-method" },
+    { name: "route path without a leading slash", manifest: patch({ routes: [route({ path: "parameters" })] }), code: "route-path" },
+    { name: "route path with a trailing slash", manifest: patch({ routes: [route({ path: "/parameters/" })] }), code: "route-path" },
+    { name: "greedy proxy route", manifest: patch({ routes: [route({ path: "/{proxy+}" })] }), code: "route-greedy" },
+    { name: "route declares the account parameter", manifest: patch({ routes: [route({ path: "/{accountNumber}/x" })] }), code: "route-reserved-param" },
+    { name: "same parameter twice in one path", manifest: patch({ routes: [route({ path: "/a/{id}/b/{id}" })] }), code: "route-param-duplicate" },
+    { name: "parameter name conflict at one position", manifest: patch({ routes: [route({ id: "a", path: "/items/{id}" }), route({ id: "b", path: "/items/{name}/history" })] }), code: "route-param-conflict" },
+    { name: "same shape with different parameter names", manifest: patch({ routes: [route({ id: "a", path: "/items/{id}" }), route({ id: "b", path: "/items/{key}" })] }), code: "route-duplicate-shape" },
+    { name: "same method and path twice", manifest: patch({ routes: [route({ id: "a" }), route({ id: "b" })] }), code: "route-duplicate-shape" },
+    { name: "route requires an undeclared permission", manifest: patch({ permissions: [{ id: "user", label: "View" }], ui: userUi, routes: [route({ permission: "admin" })] }), code: "route-undeclared-permission" },
+    { name: "route with an unknown handler key", manifest: patch({ routes: [route({ handlerKey: "missing" })] }), handlerKeys: ["api"], code: "route-handler-key" },
+    { name: "neither UI nor routes", manifest: patch({ ui: undefined, routes: [] }), code: "no-surface" },
+    { name: "routes missing entirely", manifest: patch({ routes: undefined }), code: "route-path" },
+    {
+        name: "manifest over the size limit",
+        manifest: patch({ routes: Array.from({ length: 1400 }, (_, i) => route({ id: `route-${i}`, path: `/resource-${i}/items` })) }),
+        code: "manifest-too-large",
+    },
+];
+exports.sampleTheme = {
+    appearance: "light",
+    tokens: {
+        "--background": "#ffffff",
+        "--surface": "#f7f7f8",
+        "--surface-foreground": "#1b1f26",
+        "--muted-foreground": "#6d7583",
+        "--border": "rgba(27, 31, 38, 0.12)",
+        "--accent-9": "#ea580c",
+        "--brand-primary": "#ea580c",
+        "--brand-foreground": "#ffffff",
+        "--radius": "0.5rem",
+        "--font-sans": "\"Inter\", system-ui, sans-serif",
+    },
+    branding: { projectName: "Example Portal" },
+};
+exports.sampleDarkTheme = {
+    ...exports.sampleTheme,
+    appearance: "dark",
+    tokens: {
+        ...exports.sampleTheme.tokens,
+        "--background": "#111318",
+        "--surface": "#1b1f26",
+        "--surface-foreground": "#e6e8ec",
+        "--muted-foreground": "#9aa3b2",
+        "--border": "rgba(230, 232, 236, 0.14)",
+        "--accent-9": "#f97316",
+        "--brand-primary": "#f97316",
+        "--brand-foreground": "#111318",
+    },
+};
+const ASSET_PREFIX = (0, paths_1.pluginAssetPrefix)("parameters", "1.0.0", "0123abcd");
+exports.sampleCatalogRecord = {
+    pluginId: "parameters",
+    schemaVersion: 1,
+    manifest: exports.parametersManifest,
+    revision: "0123abcd0123abcd",
+    assetPrefix: ASSET_PREFIX,
+    installed: true,
+    owner: "WebStack/parameters",
+    ui: {
+        user: { label: "Parameters", icon: "sliders", order: 10, url: (0, paths_1.pluginUiUrl)(ASSET_PREFIX, "index.html#/user") },
+        admin: { label: "Parameters", icon: "sliders", order: 10, url: (0, paths_1.pluginUiUrl)(ASSET_PREFIX, "index.html#/admin") },
+    },
+    routes: exports.parametersManifest.routes.map((r) => ({ ...r, resourcePath: (0, paths_1.pluginRouteResourcePath)("parameters", r.path) })),
+    installedAt: "2026-09-16T09:00:00.000Z",
+    updatedAt: "2026-09-16T09:00:00.000Z",
+};
+exports.sampleAccounts = [
+    { accountNumber: exports.FIXTURE_ACCOUNT_A, displayName: "Example workloads", regions: ["eu-central-1"], permissions: ["user", "admin"] },
+    { accountNumber: exports.FIXTURE_ACCOUNT_B, displayName: "Example sandbox", permissions: ["user"] },
+];
+exports.sampleDiscoveryResponse = {
+    schemaVersion: 1,
+    refreshAfterSeconds: 60,
+    plugins: [
+        {
+            id: "parameters",
+            displayName: "Application parameters",
+            description: exports.parametersManifest.description,
+            version: "1.0.0",
+            revision: "0123abcd0123abcd",
+            apiBaseUrl: "/api/plugins/parameters",
+            ui: { user: { label: "Parameters", icon: "sliders", order: 10, url: (0, paths_1.pluginUiUrl)(ASSET_PREFIX, "index.html#/user") } },
+            accounts: [{ accountNumber: exports.FIXTURE_ACCOUNT_A, displayName: "Example workloads", regions: ["eu-central-1"], permissions: ["user"] }],
+        },
+    ],
+};
+exports.sampleInitPayload = {
+    // Relative, not a timestamp: a fixed one expired on 2026-09-21 and every suite built on this
+    // fixture (ours and any plugin author's) started asking the host for an "expiring" refresh.
+    session: { token: "eyJhbGciOiJSUzI1NiJ9.example.signature", expiresAt: Date.now() + 3_600_000 },
+    user: { subject: "6f1e2d3c-0000-4000-8000-000000000001", principalType: "user", email: "admin@example.com", displayName: "Example Admin" },
+    plugin: { id: "parameters", displayName: "Application parameters", version: "1.0.0", revision: "0123abcd0123abcd", apiBaseUrl: "/api/plugins/parameters" },
+    entry: "user",
+    accounts: exports.sampleAccounts,
+    theme: exports.sampleTheme,
+};
+exports.sampleAuthorizerContext = {
+    pluginId: "parameters",
+    pluginRevision: "0123abcd0123abcd",
+    routeId: "list",
+    accountNumber: exports.FIXTURE_ACCOUNT_A,
+    requiredPermission: "user",
+    subject: "6f1e2d3c-0000-4000-8000-000000000001",
+    principalType: "user",
+    correlationId: "req-0001",
+};

package/dist/host/host.d.ts

@@ -0,0 +1,47 @@
+import { HostToPluginPayloads, PluginSession, PluginToHostPayloads } from "../contracts/messages";
+import { PluginTheme } from "../contracts/theme";
+import { PluginMessageListenerTarget, PluginMessagePort } from "../contracts/transport";
+export type PluginHostInitState = HostToPluginPayloads["init"];
+export type PluginSessionEndReason = HostToPluginPayloads["sessionEnded"]["reason"];
+export type PluginHostState = "waiting" | "connected" | "ended";
+/** An `HTMLIFrameElement` satisfies this. */
+export interface PluginHostFrame {
+    readonly contentWindow: PluginMessagePort | null;
+}
+export interface PluginHostOptions {
+    readonly frame: PluginHostFrame;
+    /** The exact origin messages are sent to and required from. Plugins share the portal's origin. */
+    readonly origin: string;
+    readonly listenOn: PluginMessageListenerTarget;
+    /** Read on every `ready`, so a reloaded frame starts from the host's current state. */
+    readonly initialState: () => PluginHostInitState;
+    /** The host's own renewal; `null` (or a throw, sync or async) means the session is over. */
+    readonly refreshSession: () => Promise<PluginSession | null>;
+    /** 0 disables. */
+    readonly handshakeTimeoutMs?: number;
+    readonly onReady?: (info: {
+        instanceId: string;
+        sdkVersion: string;
+        reconnect: boolean;
+    }) => void;
+    readonly onHandshakeTimeout?: () => void;
+    readonly onRequestAccessRefresh?: (reason: PluginToHostPayloads["requestAccessRefresh"]["reason"]) => void;
+    /** A frame speaking another protocol version; it is never initialised. */
+    readonly onIncompatible?: (info: {
+        version: unknown;
+    }) => void;
+    /** Fires for every `end`/`dispose`, connected or not; discriminate on `reason`. */
+    readonly onEnded?: (reason: PluginSessionEndReason) => void;
+}
+export interface PluginHost {
+    state(): PluginHostState;
+    instanceId(): string | null;
+    sendSession(session: PluginSession): void;
+    sendAccess(payload: HostToPluginPayloads["accessChanged"]): void;
+    sendTheme(theme: PluginTheme): void;
+    /** Tell the frame the session is over and stop listening. Terminal. */
+    end(reason: PluginSessionEndReason): void;
+    /** `end("unloaded")` unless already ended. Call from the host's own teardown. */
+    dispose(): void;
+}
+export declare function createPluginHost(options: PluginHostOptions): PluginHost;

package/dist/host/host.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPluginHost = createPluginHost;
+const messages_1 = require("../contracts/messages");
+function createPluginHost(options) {
+    let state = "waiting";
+    let current = null;
+    let refreshing = null;
+    /** The frame the in-flight renewal belongs to, and the latest request awaiting its one answer. */
+    let refreshFor = null;
+    let replyTo;
+    let replyPending = false;
+    const timeoutMs = options.handshakeTimeoutMs ?? messages_1.PLUGIN_HANDSHAKE_TIMEOUT_MS;
+    const handshakeTimer = timeoutMs > 0
+        ? setTimeout(() => {
+            if (state === "waiting")
+                options.onHandshakeTimeout?.();
+        }, timeoutMs)
+        : undefined;
+    const post = (type, payload, requestId) => {
+        const target = options.frame.contentWindow;
+        if (state !== "connected" || !current || !target)
+            return;
+        target.postMessage((0, messages_1.createPluginMessage)(type, current, payload, requestId), options.origin);
+    };
+    const end = (reason) => {
+        if (state === "ended")
+            return;
+        post("sessionEnded", { reason });
+        state = "ended";
+        replyPending = false;
+        clearTimeout(handshakeTimer);
+        options.listenOn.removeEventListener("message", listener);
+        options.onEnded?.(reason);
+    };
+    const onReady = (message) => {
+        const duplicate = current === message.instanceId;
+        const reconnect = current !== null && !duplicate;
+        if (reconnect)
+            replyPending = false; // the new frame never asked for the old one's renewal
+        current = message.instanceId;
+        state = "connected";
+        clearTimeout(handshakeTimer);
+        post("init", options.initialState());
+        if (!duplicate)
+            options.onReady?.({ instanceId: current, sdkVersion: message.payload.sdkVersion, reconnect });
+    };
+    /** One renewal at a time, one answer per renewal: a frame that asks repeatedly while it runs
+     *  gets a single `sessionChanged`, and a frame replaced mid-flight gets nothing (its answer must
+     *  not end the session of the frame that took its place). */
+    const refresh = (instanceId, requestId) => {
+        replyPending = true;
+        replyTo = requestId;
+        if (refreshing)
+            return;
+        refreshFor = instanceId;
+        refreshing = Promise.resolve()
+            .then(() => options.refreshSession())
+            .catch(() => null);
+        void refreshing.then((session) => {
+            refreshing = null;
+            const startedFor = refreshFor;
+            const answered = replyPending;
+            const id = replyTo;
+            refreshFor = null;
+            replyPending = false;
+            replyTo = undefined;
+            if (state === "ended" || !answered || startedFor !== current)
+                return;
+            if (!session) {
+                end("expired");
+                return;
+            }
+            post("sessionChanged", session, id);
+        });
+    };
+    const listener = (event) => {
+        if (state === "ended")
+            return;
+        if (event.source !== options.frame.contentWindow || event.origin !== options.origin)
+            return;
+        const seen = (0, messages_1.inspectPluginMessage)(event.data);
+        if (seen.kind === "incompatible") {
+            options.onIncompatible?.({ version: seen.version });
+            return;
+        }
+        if (seen.kind !== "message" || !(0, messages_1.isPluginToHostMessage)(seen.message))
+            return;
+        const message = seen.message;
+        if (message.type === "ready") {
+            onReady(message);
+            return;
+        }
+        if (message.instanceId !== current)
+            return; // a frame that was replaced or reloaded
+        switch (message.type) {
+            case "requestSessionRefresh":
+                refresh(message.instanceId, message.requestId);
+                return;
+            case "requestAccessRefresh":
+                options.onRequestAccessRefresh?.(message.payload.reason);
+                return;
+            default:
+                return;
+        }
+    };
+    options.listenOn.addEventListener("message", listener);
+    return {
+        state: () => state,
+        instanceId: () => current,
+        sendSession: (session) => post("sessionChanged", session),
+        sendAccess: (payload) => post("accessChanged", payload),
+        sendTheme: (theme) => post("themeChanged", theme),
+        end,
+        dispose: () => end("unloaded"),
+    };
+}

package/dist/host/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./host";
+export * from "../contracts/messages";
+export * from "../contracts/theme";
+export * from "../contracts/transport";
+export type { PluginPermission } from "../contracts/manifest";

package/dist/host/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Entry point for the portal shell and the local development host: the host side of the iframe
+// protocol. Browser code; must stay free of Node, CDK, AWS and Angular imports.
+__exportStar(require("./host"), exports);
+__exportStar(require("../contracts/messages"), exports);
+__exportStar(require("../contracts/theme"), exports);
+__exportStar(require("../contracts/transport"), exports);

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./contracts/manifest";
+export * from "./contracts/validate";
+export * from "./contracts/canonical";
+export * from "./contracts/paths";
+export * from "./contracts/access";
+export * from "./contracts/catalog";
+export * from "./contracts/discovery";
+export * from "./contracts/theme";
+export * from "./contracts/messages";
+export * from "./contracts/authorizer";

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// The shared contract: what deployment (CDK), the core backend, the authorizer, the portal
+// shell and plugin frames all agree on. Browser-safe: no Node, CDK or AWS imports here.
+__exportStar(require("./contracts/manifest"), exports);
+__exportStar(require("./contracts/validate"), exports);
+__exportStar(require("./contracts/canonical"), exports);
+__exportStar(require("./contracts/paths"), exports);
+__exportStar(require("./contracts/access"), exports);
+__exportStar(require("./contracts/catalog"), exports);
+__exportStar(require("./contracts/discovery"), exports);
+__exportStar(require("./contracts/theme"), exports);
+__exportStar(require("./contracts/messages"), exports);
+__exportStar(require("./contracts/authorizer"), exports);