@mirrorstack-ai/app-module-client 0.5.1

package/dist/web/runtime.js

@@ -0,0 +1,73 @@
+import { assertModuleRef } from "../plugin.js";
+import { resolveMaxResponseBytes } from "../response.js";
+import { createScopedTransports } from "../transport.js";
+/**
+ * Creates full public and platform transports for one mounted module.
+ *
+ * The host-provided fetch owns authentication and application identity.
+ * Browser module code cannot select trusted `X-MS-*` identity headers.
+ */
+function composeWebTransports(options, scopePaths) {
+    assertModuleRef(options.moduleRef);
+    let apiBase = options.apiBase ?? "";
+    while (apiBase.endsWith("/"))
+        apiBase = apiBase.slice(0, -1);
+    const hostFetch = options.fetch;
+    const contextualFetch = async (input, init) => {
+        if (!hostFetch) {
+            throw new Error("Module " + options.moduleRef + " cannot request data before the host supplies fetch.");
+        }
+        return hostFetch(input, init);
+    };
+    return createScopedTransports({
+        baseUrl: apiBase,
+        fetch: contextualFetch,
+        credentials: "include",
+        maxResponseBytes: resolveMaxResponseBytes(options.maxResponseBytes),
+    }, options.moduleRef, apiBase, scopePaths);
+}
+export function createModuleWebTransports(options) {
+    // The Go SDK mounts each scope under its own name — ms.Public routes live at
+    // /public/ — so the public scope owns that segment exactly as platform owns
+    // /platform/. A module must never have to spell it in the path it requests.
+    return composeWebTransports(options, { public: "public", platform: "platform" });
+}
+function routeTarget(route, transports) {
+    if (route === "/platform") {
+        return { path: "/", transport: transports.platform };
+    }
+    if (route.startsWith("/platform/")) {
+        return { path: route.slice("/platform".length), transport: transports.platform };
+    }
+    return { path: route, transport: transports.public };
+}
+/**
+ * Creates the direct route-dispatching transport released in v0.1.0.
+ *
+ * @deprecated Prefer {@link createModuleWebTransports}, which keeps public and
+ * platform routes structurally separate and exposes the full scoped contract.
+ */
+export function createModuleWebTransport(options) {
+    // This transport is documented as serving "public-root and platform-scoped
+    // routes": its callers pass whole paths, including the /public segment and
+    // root-level routes. It therefore keeps addressing the module ROOT, and does
+    // not inherit the /public segment createModuleWebTransports now owns.
+    const transports = composeWebTransports({
+        moduleRef: options.moduleRef,
+        ...(options.apiBase === undefined ? {} : { apiBase: options.apiBase }),
+        ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+    }, { public: "", platform: "platform" });
+    const invoke = async (method, route, requestOptions, responseType) => {
+        const target = routeTarget(route, transports);
+        const request = target.transport.request;
+        return request(method, target.path, {
+            ...requestOptions,
+            responseType,
+        });
+    };
+    return Object.freeze({
+        request: (method, route, requestOptions) => invoke(method, route, requestOptions, "json"),
+        text: (method, route, requestOptions) => invoke(method, route, requestOptions, "text"),
+    });
+}
+//# sourceMappingURL=runtime.js.map

package/dist/web/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/web/runtime.ts"],"names":[],"mappings":"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","sourcesContent":["import { assertModuleRef, type ModuleClientContext } from \"../plugin.js\";\nimport { resolveMaxResponseBytes } from \"../response.js\";\nimport { createScopedTransports } from \"../transport.js\";\nimport type { PlatformFetch } from \"./types.js\";\n\n/** Configuration owned by the host at module mount time. */\nexport interface CreateModuleWebTransportsOptions {\n  /** Canonical 1-16 character catalog slug or UUID used for routing and diagnostics. */\n  readonly moduleRef: string;\n  /** Dispatch root for this mounted module. Empty means same-origin. */\n  readonly apiBase?: string;\n  /** Authenticated fetch capability supplied by the platform host. */\n  readonly fetch?: PlatformFetch;\n  /** Maximum bytes parsed from response bodies. Defaults to one mebibyte. */\n  readonly maxResponseBytes?: number;\n}\n\n/** Public-root and platform-scoped transports for one mounted module. */\nexport type ModuleWebTransports = ModuleClientContext;\n\n/**\n * Creates full public and platform transports for one mounted module.\n *\n * The host-provided fetch owns authentication and application identity.\n * Browser module code cannot select trusted `X-MS-*` identity headers.\n */\nfunction composeWebTransports(\n  options: CreateModuleWebTransportsOptions,\n  scopePaths: Partial<Record<\"public\" | \"platform\", string>>,\n): ModuleWebTransports {\n  assertModuleRef(options.moduleRef);\n  let apiBase = options.apiBase ?? \"\";\n  while (apiBase.endsWith(\"/\")) apiBase = apiBase.slice(0, -1);\n  const hostFetch = options.fetch;\n\n  const contextualFetch: typeof globalThis.fetch = async (input, init) => {\n    if (!hostFetch) {\n      throw new Error(\n        \"Module \" + options.moduleRef + \" cannot request data before the host supplies fetch.\",\n      );\n    }\n    return hostFetch(input, init);\n  };\n\n  return createScopedTransports(\n    {\n      baseUrl: apiBase,\n      fetch: contextualFetch,\n      credentials: \"include\",\n      maxResponseBytes: resolveMaxResponseBytes(options.maxResponseBytes),\n    },\n    options.moduleRef,\n    apiBase,\n    scopePaths,\n  );\n}\n\nexport function createModuleWebTransports(\n  options: CreateModuleWebTransportsOptions,\n): ModuleWebTransports {\n  // The Go SDK mounts each scope under its own name — ms.Public routes live at\n  // /public/ — so the public scope owns that segment exactly as platform owns\n  // /platform/. A module must never have to spell it in the path it requests.\n  return composeWebTransports(options, { public: \"public\", platform: \"platform\" });\n}\n\n/**\n * Options for an API request made through the v0.1.0 compatibility transport.\n *\n * @deprecated Prefer the complete scoped request options exposed by\n * `createModuleWebTransports()`.\n */\nexport interface ModuleWebRequestOptions {\n  body?: unknown;\n  headers?: HeadersInit;\n  query?: Record<string, boolean | number | string | null | undefined>;\n  signal?: AbortSignal;\n}\n\n/**\n * Configuration for the v0.1.0 compatibility transport.\n *\n * `appId` remains accepted for source compatibility but is informational.\n * It is never converted into a trusted `X-MS-App-ID` browser header.\n *\n * @deprecated Prefer {@link CreateModuleWebTransportsOptions}.\n */\nexport interface CreateModuleWebTransportOptions {\n  moduleRef: string;\n  apiBase?: string;\n  appId?: string;\n  fetch?: PlatformFetch;\n}\n\n/**\n * Direct v0.1.0 module transport for public-root and platform-scoped routes.\n *\n * @deprecated Prefer {@link ModuleWebTransports}.\n */\nexport interface ModuleWebTransport {\n  /** Sends a request and parses a successful JSON body. */\n  request<T>(method: string, route: string, options?: ModuleWebRequestOptions): Promise<T>;\n\n  /** Sends a request and returns its successful body as text. */\n  text(method: string, route: string, options?: ModuleWebRequestOptions): Promise<string>;\n}\n\ntype RequestInvoker = (\n  method: string,\n  path: string,\n  options?: Record<string, unknown>,\n) => Promise<unknown>;\n\nfunction routeTarget(\n  route: string,\n  transports: ModuleWebTransports,\n) {\n  if (route === \"/platform\") {\n    return { path: \"/\", transport: transports.platform };\n  }\n  if (route.startsWith(\"/platform/\")) {\n    return { path: route.slice(\"/platform\".length), transport: transports.platform };\n  }\n  return { path: route, transport: transports.public };\n}\n\n/**\n * Creates the direct route-dispatching transport released in v0.1.0.\n *\n * @deprecated Prefer {@link createModuleWebTransports}, which keeps public and\n * platform routes structurally separate and exposes the full scoped contract.\n */\nexport function createModuleWebTransport(\n  options: CreateModuleWebTransportOptions,\n): ModuleWebTransport {\n  // This transport is documented as serving \"public-root and platform-scoped\n  // routes\": its callers pass whole paths, including the /public segment and\n  // root-level routes. It therefore keeps addressing the module ROOT, and does\n  // not inherit the /public segment createModuleWebTransports now owns.\n  const transports = composeWebTransports(\n    {\n      moduleRef: options.moduleRef,\n      ...(options.apiBase === undefined ? {} : { apiBase: options.apiBase }),\n      ...(options.fetch === undefined ? {} : { fetch: options.fetch }),\n    },\n    { public: \"\", platform: \"platform\" },\n  );\n\n  const invoke = async <T>(\n    method: string,\n    route: string,\n    requestOptions: ModuleWebRequestOptions | undefined,\n    responseType: \"json\" | \"text\",\n  ): Promise<T> => {\n    const target = routeTarget(route, transports);\n    const request = target.transport.request as unknown as RequestInvoker;\n    return request(method, target.path, {\n      ...requestOptions,\n      responseType,\n    }) as Promise<T>;\n  };\n\n  return Object.freeze({\n    request: <T>(\n      method: string,\n      route: string,\n      requestOptions?: ModuleWebRequestOptions,\n    ) => invoke<T>(method, route, requestOptions, \"json\"),\n    text: (\n      method: string,\n      route: string,\n      requestOptions?: ModuleWebRequestOptions,\n    ) => invoke<string>(method, route, requestOptions, \"text\"),\n  });\n}\n"]}

package/dist/web/subpath.d.ts

@@ -0,0 +1,22 @@
+import type { ModuleSubpath, SubpathCrumb } from "./types.js";
+/** Mount-local observable state synchronized with the platform subpath bridge. */
+export interface ModuleSubpathStore {
+    /** Returns the stable current segment snapshot. */
+    getSnapshot(): readonly string[];
+    /** Subscribes to snapshot changes. */
+    subscribe(listener: () => void): () => void;
+    /** Publishes breadcrumbs to the host and updates the local snapshot. */
+    publish(crumbs: readonly SubpathCrumb[], opts?: {
+        replace?: boolean;
+    }): void;
+    /** Releases the host subscription and local listeners. */
+    dispose(): void;
+}
+/**
+ * Creates subpath state isolated to one mounted module surface.
+ *
+ * Publishing updates local state even when the host does not echo its own
+ * navigation event. Without a host bridge, the store remains useful as an
+ * in-memory navigation source.
+ */
+export declare function createModuleSubpathStore(bridge?: ModuleSubpath): ModuleSubpathStore;

package/dist/web/subpath.js

@@ -0,0 +1,50 @@
+function snapshot(segments) {
+    return Object.freeze([...segments]);
+}
+function equal(first, second) {
+    return first.length === second.length
+        && first.every((segment, index) => segment === second[index]);
+}
+/**
+ * Creates subpath state isolated to one mounted module surface.
+ *
+ * Publishing updates local state even when the host does not echo its own
+ * navigation event. Without a host bridge, the store remains useful as an
+ * in-memory navigation source.
+ */
+export function createModuleSubpathStore(bridge) {
+    let current = snapshot(bridge?.get() ?? []);
+    let disposed = false;
+    const listeners = new Set();
+    const update = (segments) => {
+        if (disposed || equal(current, segments))
+            return;
+        current = snapshot(segments);
+        for (const listener of listeners)
+            listener();
+    };
+    const unsubscribe = bridge?.subscribe(update);
+    return Object.freeze({
+        getSnapshot: () => current,
+        subscribe(listener) {
+            if (disposed)
+                return () => { };
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        publish(crumbs, opts) {
+            if (disposed)
+                return;
+            bridge?.set([...crumbs], opts);
+            update(crumbs.map(({ segment }) => segment));
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            unsubscribe?.();
+            listeners.clear();
+        },
+    });
+}
+//# sourceMappingURL=subpath.js.map

package/dist/web/subpath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subpath.js","sourceRoot":"","sources":["../../src/web/subpath.ts"],"names":[],"mappings":"AAcA,SAAS,QAAQ,CAAC,QAA2B;IAC3C,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,KAAK,CAAC,KAAwB,EAAE,MAAyB;IAChE,OAAO,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;WAChC,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CACtC,MAAsB;IAEtB,IAAI,OAAO,GAAG,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAC;IAExC,MAAM,MAAM,GAAG,CAAC,QAA2B,EAAE,EAAE;QAC7C,IAAI,QAAQ,IAAI,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC;YAAE,OAAO;QACjD,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC7B,KAAK,MAAM,QAAQ,IAAI,SAAS;YAAE,QAAQ,EAAE,CAAC;IAC/C,CAAC,CAAC;IACF,MAAM,WAAW,GAAG,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IAE9C,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,WAAW,EAAE,GAAG,EAAE,CAAC,OAAO;QAC1B,SAAS,CAAC,QAAoB;YAC5B,IAAI,QAAQ;gBAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;YAC9B,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACxB,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC;QACD,OAAO,CAAC,MAA+B,EAAE,IAA4B;YACnE,IAAI,QAAQ;gBAAE,OAAO;YACrB,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC;YAC/B,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;QAC/C,CAAC;QACD,OAAO;YACL,IAAI,QAAQ;gBAAE,OAAO;YACrB,QAAQ,GAAG,IAAI,CAAC;YAChB,WAAW,EAAE,EAAE,CAAC;YAChB,SAAS,CAAC,KAAK,EAAE,CAAC;QACpB,CAAC;KACF,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { ModuleSubpath, SubpathCrumb } from \"./types.js\";\n\n/** Mount-local observable state synchronized with the platform subpath bridge. */\nexport interface ModuleSubpathStore {\n  /** Returns the stable current segment snapshot. */\n  getSnapshot(): readonly string[];\n  /** Subscribes to snapshot changes. */\n  subscribe(listener: () => void): () => void;\n  /** Publishes breadcrumbs to the host and updates the local snapshot. */\n  publish(crumbs: readonly SubpathCrumb[], opts?: { replace?: boolean }): void;\n  /** Releases the host subscription and local listeners. */\n  dispose(): void;\n}\n\nfunction snapshot(segments: readonly string[]): readonly string[] {\n  return Object.freeze([...segments]);\n}\n\nfunction equal(first: readonly string[], second: readonly string[]): boolean {\n  return first.length === second.length\n    && first.every((segment, index) => segment === second[index]);\n}\n\n/**\n * Creates subpath state isolated to one mounted module surface.\n *\n * Publishing updates local state even when the host does not echo its own\n * navigation event. Without a host bridge, the store remains useful as an\n * in-memory navigation source.\n */\nexport function createModuleSubpathStore(\n  bridge?: ModuleSubpath,\n): ModuleSubpathStore {\n  let current = snapshot(bridge?.get() ?? []);\n  let disposed = false;\n  const listeners = new Set<() => void>();\n\n  const update = (segments: readonly string[]) => {\n    if (disposed || equal(current, segments)) return;\n    current = snapshot(segments);\n    for (const listener of listeners) listener();\n  };\n  const unsubscribe = bridge?.subscribe(update);\n\n  return Object.freeze({\n    getSnapshot: () => current,\n    subscribe(listener: () => void) {\n      if (disposed) return () => {};\n      listeners.add(listener);\n      return () => listeners.delete(listener);\n    },\n    publish(crumbs: readonly SubpathCrumb[], opts?: { replace?: boolean }) {\n      if (disposed) return;\n      bridge?.set([...crumbs], opts);\n      update(crumbs.map(({ segment }) => segment));\n    },\n    dispose() {\n      if (disposed) return;\n      disposed = true;\n      unsubscribe?.();\n      listeners.clear();\n    },\n  });\n}\n"]}

package/dist/web/types.d.ts

@@ -0,0 +1,129 @@
+/** Fetch implementation supplied by the authenticated platform host. */
+export type PlatformFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/** Resolves platform actor identifiers for audit and attribution UI. */
+export interface PlatformIdentity<TIdentity = unknown> {
+    resolve: (ids: string[]) => Promise<Record<string, TIdentity>>;
+}
+/** Navigation bridge supplied by the platform shell. */
+export interface PlatformNavigate {
+    settings: () => void;
+    /** Platform-resolved settings slot: this module first, followed by installed
+     *  settings-capable modules that contribute to it. Optional for old hosts. */
+    settingsItems?: PlatformSettingsItem[];
+    openSettings?: (moduleSlug: string) => void;
+    /** Opens one user in the platform-owned User Core detail surface. */
+    userDetail?: (userId: string) => void;
+}
+/** Settings destination accepted by the platform navigation bridge. */
+export interface PlatformSettingsItem {
+    moduleSlug: string;
+    label: string;
+    icon: string;
+}
+/** State rendered by the platform unsaved-changes bar. */
+export interface UnsavedBarState {
+    message: string;
+    saveLabel: string;
+    resetLabel: string;
+    /** Disables the save action while retaining reset and warning behavior. */
+    canSave?: boolean;
+    onSave: () => void;
+    onReset: () => void;
+}
+/** Bridge used by a mounted module to control unsaved-change UI. */
+export interface PlatformUnsaved {
+    set: (state: UnsavedBarState | null) => void;
+}
+/** Event emitted from one mounted module component to another. */
+export interface PlatformModuleComponentEvent {
+    type: string;
+    payload?: unknown;
+}
+/** Request to mount one component owned by an installed module. */
+export type PlatformModuleMountRequest = {
+    /** Manifest UI component name; the host resolves its declared bundle export. */
+    component: string;
+    target: HTMLElement;
+    props?: Record<string, unknown>;
+    onEvent?: (event: PlatformModuleComponentEvent) => void;
+} & ({
+    /** Authoritative installed-module identity resolved by the platform. */
+    moduleId: string;
+    /** Optional display/routing hint; never authoritative when moduleId exists. */
+    moduleSlug?: string;
+} | {
+    moduleId?: undefined;
+    /** @deprecated Supply the platform-resolved moduleId when the host supports it. */
+    moduleSlug: string;
+});
+/** Cross-module component mount bridge supplied by the platform. */
+export interface PlatformModules {
+    mount: (request: PlatformModuleMountRequest) => Promise<() => void>;
+}
+/** Breadcrumb metadata for a module-owned subpath. */
+export interface SubpathCrumb {
+    /** URL-safe route segment owned by the module. */
+    segment: string;
+    /** Human-readable label rendered by the platform breadcrumb. */
+    label: string;
+}
+/** Router state passed to a mounted module surface. */
+export interface ModuleSubpath {
+    /** Returns the currently requested module-relative path segments. */
+    get: () => string[];
+    /** Publishes a new module-relative path and its breadcrumb labels. */
+    set: (crumbs: SubpathCrumb[], opts?: {
+        replace?: boolean;
+    }) => void;
+    /** Subscribes to navigation initiated by the platform. */
+    subscribe: (listener: (segments: string[]) => void) => () => void;
+}
+/** Complete framework-neutral contract supplied when a module web surface mounts. */
+export interface ModuleMountContext<TIdentity = unknown> {
+    /** Prefix for this module's HTTP routes; empty means same-origin. */
+    apiBase?: string;
+    /** Authenticated host transport, including platform token refresh. */
+    fetch?: PlatformFetch;
+    /**
+     * Host-supplied application identifier for mount-local state and links.
+     * Informational in browser code; never trusted as request identity.
+     */
+    appId?: string;
+    /** Active BCP-47 locale, such as `en-US` or `zh-TW`. */
+    locale?: string;
+    /** Platform-owned cross-surface navigation helpers. */
+    navigate?: PlatformNavigate;
+    /** Bridge to the platform-owned unsaved-changes interface. */
+    unsaved?: PlatformUnsaved;
+    /** Bridge for mounting contributed components from installed modules. */
+    modules?: PlatformModules;
+    /** Platform-owned principal identity resolver. */
+    identity?: PlatformIdentity<TIdentity>;
+    /** Bridge for module-relative navigation and breadcrumbs. */
+    subpath?: ModuleSubpath;
+}
+/** Backward-compatible concise name for the module mount contract. */
+export type MountContext<TIdentity = unknown> = ModuleMountContext<TIdentity>;
+/** Props and lifecycle events supplied to a manifest-declared component. */
+export interface ModuleComponentBridge<TProps extends object = Record<string, unknown>, TEventPayload = unknown> {
+    /** Props validated by the host against the component manifest. */
+    readonly props: TProps;
+    /** Emits a component lifecycle event to the surface that requested it. */
+    emit: (type: string, payload?: TEventPayload) => void;
+}
+/**
+ * Host context for one manifest-declared component mount.
+ *
+ * Component mounts always have resolved installation, transport, locale, and
+ * settings navigation context. Optional page bridges remain inherited from
+ * ModuleMountContext so a host can add them without changing this contract.
+ */
+export interface ModuleComponentMountContext<TProps extends object = Record<string, unknown>, TEventPayload = unknown, TIdentity = unknown> extends ModuleMountContext<TIdentity> {
+    apiBase: string;
+    fetch: PlatformFetch;
+    /** Informational host application value; never trusted request identity. */
+    appId: string;
+    locale: string;
+    navigate: Pick<PlatformNavigate, "settings">;
+    component: ModuleComponentBridge<TProps, TEventPayload>;
+}

package/dist/web/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/web/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/web/types.ts"],"names":[],"mappings":"","sourcesContent":["/** Fetch implementation supplied by the authenticated platform host. */\nexport type PlatformFetch = (\n  input: RequestInfo | URL,\n  init?: RequestInit,\n) => Promise<Response>;\n\n/** Resolves platform actor identifiers for audit and attribution UI. */\nexport interface PlatformIdentity<TIdentity = unknown> {\n  resolve: (ids: string[]) => Promise<Record<string, TIdentity>>;\n}\n\n/** Navigation bridge supplied by the platform shell. */\nexport interface PlatformNavigate {\n  settings: () => void;\n  /** Platform-resolved settings slot: this module first, followed by installed\n   *  settings-capable modules that contribute to it. Optional for old hosts. */\n  settingsItems?: PlatformSettingsItem[];\n  openSettings?: (moduleSlug: string) => void;\n  /** Opens one user in the platform-owned User Core detail surface. */\n  userDetail?: (userId: string) => void;\n}\n\n/** Settings destination accepted by the platform navigation bridge. */\nexport interface PlatformSettingsItem {\n  moduleSlug: string;\n  label: string;\n  icon: string;\n}\n\n/** State rendered by the platform unsaved-changes bar. */\nexport interface UnsavedBarState {\n  message: string;\n  saveLabel: string;\n  resetLabel: string;\n  /** Disables the save action while retaining reset and warning behavior. */\n  canSave?: boolean;\n  onSave: () => void;\n  onReset: () => void;\n}\n\n/** Bridge used by a mounted module to control unsaved-change UI. */\nexport interface PlatformUnsaved {\n  set: (state: UnsavedBarState | null) => void;\n}\n\n/** Event emitted from one mounted module component to another. */\nexport interface PlatformModuleComponentEvent {\n  type: string;\n  payload?: unknown;\n}\n\n/** Request to mount one component owned by an installed module. */\nexport type PlatformModuleMountRequest = {\n  /** Manifest UI component name; the host resolves its declared bundle export. */\n  component: string;\n  target: HTMLElement;\n  props?: Record<string, unknown>;\n  onEvent?: (event: PlatformModuleComponentEvent) => void;\n} & (\n  | {\n      /** Authoritative installed-module identity resolved by the platform. */\n      moduleId: string;\n      /** Optional display/routing hint; never authoritative when moduleId exists. */\n      moduleSlug?: string;\n    }\n  | {\n      moduleId?: undefined;\n      /** @deprecated Supply the platform-resolved moduleId when the host supports it. */\n      moduleSlug: string;\n    }\n);\n\n/** Cross-module component mount bridge supplied by the platform. */\nexport interface PlatformModules {\n  mount: (request: PlatformModuleMountRequest) => Promise<() => void>;\n}\n\n/** Breadcrumb metadata for a module-owned subpath. */\nexport interface SubpathCrumb {\n  /** URL-safe route segment owned by the module. */\n  segment: string;\n  /** Human-readable label rendered by the platform breadcrumb. */\n  label: string;\n}\n\n/** Router state passed to a mounted module surface. */\nexport interface ModuleSubpath {\n  /** Returns the currently requested module-relative path segments. */\n  get: () => string[];\n  /** Publishes a new module-relative path and its breadcrumb labels. */\n  set: (crumbs: SubpathCrumb[], opts?: { replace?: boolean }) => void;\n  /** Subscribes to navigation initiated by the platform. */\n  subscribe: (listener: (segments: string[]) => void) => () => void;\n}\n\n/** Complete framework-neutral contract supplied when a module web surface mounts. */\nexport interface ModuleMountContext<TIdentity = unknown> {\n  /** Prefix for this module's HTTP routes; empty means same-origin. */\n  apiBase?: string;\n  /** Authenticated host transport, including platform token refresh. */\n  fetch?: PlatformFetch;\n  /**\n   * Host-supplied application identifier for mount-local state and links.\n   * Informational in browser code; never trusted as request identity.\n   */\n  appId?: string;\n  /** Active BCP-47 locale, such as `en-US` or `zh-TW`. */\n  locale?: string;\n  /** Platform-owned cross-surface navigation helpers. */\n  navigate?: PlatformNavigate;\n  /** Bridge to the platform-owned unsaved-changes interface. */\n  unsaved?: PlatformUnsaved;\n  /** Bridge for mounting contributed components from installed modules. */\n  modules?: PlatformModules;\n  /** Platform-owned principal identity resolver. */\n  identity?: PlatformIdentity<TIdentity>;\n  /** Bridge for module-relative navigation and breadcrumbs. */\n  subpath?: ModuleSubpath;\n}\n\n/** Backward-compatible concise name for the module mount contract. */\nexport type MountContext<TIdentity = unknown> = ModuleMountContext<TIdentity>;\n\n/** Props and lifecycle events supplied to a manifest-declared component. */\nexport interface ModuleComponentBridge<\n  TProps extends object = Record<string, unknown>,\n  TEventPayload = unknown,\n> {\n  /** Props validated by the host against the component manifest. */\n  readonly props: TProps;\n  /** Emits a component lifecycle event to the surface that requested it. */\n  emit: (type: string, payload?: TEventPayload) => void;\n}\n\n/**\n * Host context for one manifest-declared component mount.\n *\n * Component mounts always have resolved installation, transport, locale, and\n * settings navigation context. Optional page bridges remain inherited from\n * ModuleMountContext so a host can add them without changing this contract.\n */\nexport interface ModuleComponentMountContext<\n  TProps extends object = Record<string, unknown>,\n  TEventPayload = unknown,\n  TIdentity = unknown,\n> extends ModuleMountContext<TIdentity> {\n  apiBase: string;\n  fetch: PlatformFetch;\n  /** Informational host application value; never trusted request identity. */\n  appId: string;\n  locale: string;\n  navigate: Pick<PlatformNavigate, \"settings\">;\n  component: ModuleComponentBridge<TProps, TEventPayload>;\n}\n"]}

package/dist/web/use-now.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns wall-clock time refreshed on a configurable, document-independent cadence.
+ *
+ * The default is suitable for relative timestamps and expiry labels that do
+ * not need second-level precision.
+ */
+export declare function useNow(intervalMs?: number): number;

package/dist/web/use-now.js

@@ -0,0 +1,22 @@
+import { useEffect, useState } from "react";
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/**
+ * Returns wall-clock time refreshed on a configurable, document-independent cadence.
+ *
+ * The default is suitable for relative timestamps and expiry labels that do
+ * not need second-level precision.
+ */
+export function useNow(intervalMs = 30_000) {
+    if (!Number.isSafeInteger(intervalMs)
+        || intervalMs <= 0
+        || intervalMs > MAX_TIMER_DELAY_MS) {
+        throw new TypeError(`useNow intervalMs must be an integer from 1 to ${MAX_TIMER_DELAY_MS}`);
+    }
+    const [now, setNow] = useState(Date.now);
+    useEffect(() => {
+        const timer = globalThis.setInterval(() => setNow(Date.now()), intervalMs);
+        return () => globalThis.clearInterval(timer);
+    }, [intervalMs]);
+    return now;
+}
+//# sourceMappingURL=use-now.js.map

package/dist/web/use-now.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-now.js","sourceRoot":"","sources":["../../src/web/use-now.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE5C,MAAM,kBAAkB,GAAG,aAAa,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,UAAU,GAAG,MAAM;IACxC,IACE,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC;WAC9B,UAAU,IAAI,CAAC;WACf,UAAU,GAAG,kBAAkB,EAClC,CAAC;QACD,MAAM,IAAI,SAAS,CACjB,kDAAkD,kBAAkB,EAAE,CACvE,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzC,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,KAAK,GAAG,UAAU,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC;QAC3E,OAAO,GAAG,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IAC/C,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;IACjB,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["import { useEffect, useState } from \"react\";\n\nconst MAX_TIMER_DELAY_MS = 2_147_483_647;\n\n/**\n * Returns wall-clock time refreshed on a configurable, document-independent cadence.\n *\n * The default is suitable for relative timestamps and expiry labels that do\n * not need second-level precision.\n */\nexport function useNow(intervalMs = 30_000): number {\n  if (\n    !Number.isSafeInteger(intervalMs)\n    || intervalMs <= 0\n    || intervalMs > MAX_TIMER_DELAY_MS\n  ) {\n    throw new TypeError(\n      `useNow intervalMs must be an integer from 1 to ${MAX_TIMER_DELAY_MS}`,\n    );\n  }\n\n  const [now, setNow] = useState(Date.now);\n  useEffect(() => {\n    const timer = globalThis.setInterval(() => setNow(Date.now()), intervalMs);\n    return () => globalThis.clearInterval(timer);\n  }, [intervalMs]);\n  return now;\n}\n"]}

package/dist/web/use-platform-unsaved-state.d.ts

@@ -0,0 +1,10 @@
+import type { PlatformUnsaved, UnsavedBarState } from "./types.js";
+/**
+ * Synchronizes one React surface with its platform-owned unsaved-state bridge.
+ *
+ * State updates replace the current value directly. The hook sends `null` only
+ * when the caller supplies it, the bridge changes, or the final owner unmounts.
+ * Cleanup is deferred by one microtask so React Strict Mode's effect replay
+ * cannot emit a false transient clear between identical registrations.
+ */
+export declare function usePlatformUnsavedState(bridge: PlatformUnsaved | undefined, state: UnsavedBarState | null): void;

package/dist/web/use-platform-unsaved-state.js

@@ -0,0 +1,35 @@
+import { useEffect } from "react";
+const latestRegistration = new WeakMap();
+/**
+ * Synchronizes one React surface with its platform-owned unsaved-state bridge.
+ *
+ * State updates replace the current value directly. The hook sends `null` only
+ * when the caller supplies it, the bridge changes, or the final owner unmounts.
+ * Cleanup is deferred by one microtask so React Strict Mode's effect replay
+ * cannot emit a false transient clear between identical registrations.
+ */
+export function usePlatformUnsavedState(bridge, state) {
+    useEffect(() => {
+        if (bridge === undefined)
+            return;
+        const registration = Symbol("platform-unsaved-state");
+        latestRegistration.set(bridge, registration);
+        return () => {
+            queueMicrotask(() => {
+                if (latestRegistration.get(bridge) !== registration)
+                    return;
+                latestRegistration.delete(bridge);
+                try {
+                    bridge.set(null);
+                }
+                catch {
+                    // A cleanup failure cannot be reported safely from a deferred effect.
+                }
+            });
+        };
+    }, [bridge]);
+    useEffect(() => {
+        bridge?.set(state);
+    }, [bridge, state]);
+}
+//# sourceMappingURL=use-platform-unsaved-state.js.map

package/dist/web/use-platform-unsaved-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-platform-unsaved-state.js","sourceRoot":"","sources":["../../src/web/use-platform-unsaved-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIlC,MAAM,kBAAkB,GAAG,IAAI,OAAO,EAA2B,CAAC;AAElE;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAmC,EACnC,KAA6B;IAE7B,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO;QACjC,MAAM,YAAY,GAAG,MAAM,CAAC,wBAAwB,CAAC,CAAC;QACtD,kBAAkB,CAAC,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAE7C,OAAO,GAAG,EAAE;YACV,cAAc,CAAC,GAAG,EAAE;gBAClB,IAAI,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,YAAY;oBAAE,OAAO;gBAC5D,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBAClC,IAAI,CAAC;oBACH,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBACnB,CAAC;gBAAC,MAAM,CAAC;oBACP,sEAAsE;gBACxE,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;AACtB,CAAC","sourcesContent":["import { useEffect } from \"react\";\n\nimport type { PlatformUnsaved, UnsavedBarState } from \"./types.js\";\n\nconst latestRegistration = new WeakMap<PlatformUnsaved, symbol>();\n\n/**\n * Synchronizes one React surface with its platform-owned unsaved-state bridge.\n *\n * State updates replace the current value directly. The hook sends `null` only\n * when the caller supplies it, the bridge changes, or the final owner unmounts.\n * Cleanup is deferred by one microtask so React Strict Mode's effect replay\n * cannot emit a false transient clear between identical registrations.\n */\nexport function usePlatformUnsavedState(\n  bridge: PlatformUnsaved | undefined,\n  state: UnsavedBarState | null,\n): void {\n  useEffect(() => {\n    if (bridge === undefined) return;\n    const registration = Symbol(\"platform-unsaved-state\");\n    latestRegistration.set(bridge, registration);\n\n    return () => {\n      queueMicrotask(() => {\n        if (latestRegistration.get(bridge) !== registration) return;\n        latestRegistration.delete(bridge);\n        try {\n          bridge.set(null);\n        } catch {\n          // A cleanup failure cannot be reported safely from a deferred effect.\n        }\n      });\n    };\n  }, [bridge]);\n\n  useEffect(() => {\n    bridge?.set(state);\n  }, [bridge, state]);\n}\n"]}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@mirrorstack-ai/app-module-client",
+  "version": "0.5.1",
+  "description": "Framework-neutral client composition for MirrorStack application modules",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20",
+    "pnpm": ">=10.29.3 <11"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mirrorstack-ai/app-module-client.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mirrorstack-ai/app-module-client/issues"
+  },
+  "homepage": "https://github.com/mirrorstack-ai/app-module-client#readme",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./web": {
+      "types": "./dist/web/index.d.ts",
+      "import": "./dist/web/index.js"
+    },
+    "./web/react": {
+      "types": "./dist/web/react.d.ts",
+      "import": "./dist/web/react.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "import": "./dist/next/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "next": "^16.3.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "peerDependencies": {
+    "next": ">=15.0.0",
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "clean": "node --eval \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "pnpm clean && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "pack:check": "pnpm pack --dry-run"
+  }
+}