@harborclient/sdk 0.7.0 → 1.0.1

package/dist/build/index.d.ts

@@ -0,0 +1,59 @@
+import type { BuildOptions, Plugin } from 'esbuild';
+/**
+ * Which JSX runtime alias (if any) the renderer bundle should use.
+ *
+ * - `host` — bind `react/jsx-runtime` to `@harborclient/sdk/jsx-runtime-host` for
+ *   bundled third-party React libraries that import jsx-runtime at module load.
+ * - `runtime` — route through the SDK runtime shims that forward to `hc.react`.
+ * - `automatic` — automatic JSX with `@harborclient/sdk` import source, no alias.
+ * - `none` — no JSX options (theme plugins that only register colors).
+ */
+export type JsxRuntimeMode = 'host' | 'runtime' | 'automatic' | 'none';
+/**
+ * Options for {@link buildRenderer}.
+ */
+export interface BuildRendererOptions {
+    /** Renderer entry file. Defaults to `src/renderer.tsx`. */
+    entry?: string;
+    /** Output bundle path. Defaults to `dist/renderer.js`. */
+    outfile?: string;
+    /** When true, watch for changes instead of a one-shot build. */
+    watch?: boolean;
+    /** JSX runtime wiring for the bundle. Defaults to `runtime`. */
+    jsxRuntime?: JsxRuntimeMode;
+    /** Modules left external (provided by the HarborClient host). */
+    external?: string[];
+    /** esbuild `define` replacements merged into the build. */
+    define?: Record<string, string>;
+    /** Extra esbuild plugins appended after built-in plugins. */
+    plugins?: Plugin[];
+    /**
+     * When set, alias `react` to this path instead of externalizing it (e.g. aws-sigv
+     * proxy shim). Implies `external: []` unless `external` is explicitly provided.
+     */
+    aliasReactTo?: string;
+    /** esbuild log level. Defaults to `info`. */
+    logLevel?: BuildOptions['logLevel'];
+    /**
+     * Files to copy after a successful build, e.g. theme stylesheets.
+     * Each pair is `[source, destination]`.
+     */
+    copy?: ReadonlyArray<readonly [string, string]>;
+}
+/**
+ * Bundles a HarborClient plugin renderer entry with canonical esbuild options.
+ *
+ * @param options - Build configuration.
+ */
+export declare function buildRenderer(options?: BuildRendererOptions): Promise<void>;
+/**
+ * esbuild plugin that stubs Node built-in modules with empty exports.
+ *
+ * Use when a dependency imports Node modules that are unused at runtime in the
+ * renderer (e.g. `dotenv` importing `fs`/`path`).
+ *
+ * @param moduleNames - Built-in module names to stub (e.g. `path`, `fs`).
+ * @returns esbuild plugin.
+ */
+export declare function nodeBuiltinStubsPlugin(moduleNames: readonly string[]): Plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/build/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEpD;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gEAAgE;IAChE,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC;IACpC;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACjD;AAwCD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqDrF;AAYD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAiB7E"}

package/dist/build/index.js

@@ -0,0 +1,116 @@
+import { cpSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import * as esbuild from 'esbuild';
+const JSX_RUNTIME_HOST = '@harborclient/sdk/jsx-runtime-host';
+const JSX_RUNTIME = '@harborclient/sdk/jsx-runtime';
+const JSX_DEV_RUNTIME = '@harborclient/sdk/jsx-dev-runtime';
+/**
+ * Builds the jsx-runtime alias map for the given mode.
+ *
+ * @param mode - JSX runtime wiring mode.
+ * @returns Alias entries to merge into esbuild options, or undefined when none apply.
+ */
+function jsxRuntimeAliases(mode) {
+    if (mode === 'host') {
+        return {
+            'react/jsx-runtime': JSX_RUNTIME_HOST,
+            'react/jsx-dev-runtime': JSX_RUNTIME_HOST
+        };
+    }
+    if (mode === 'runtime') {
+        return {
+            'react/jsx-runtime': JSX_RUNTIME,
+            'react/jsx-dev-runtime': JSX_DEV_RUNTIME
+        };
+    }
+    return undefined;
+}
+/**
+ * Copies asset files after a successful renderer build.
+ *
+ * @param pairs - Source/destination path pairs.
+ */
+function copyAssets(pairs) {
+    for (const [source, destination] of pairs) {
+        mkdirSync(dirname(destination), { recursive: true });
+        cpSync(source, destination);
+    }
+}
+/**
+ * Bundles a HarborClient plugin renderer entry with canonical esbuild options.
+ *
+ * @param options - Build configuration.
+ */
+export async function buildRenderer(options = {}) {
+    const { entry = 'src/renderer.tsx', outfile = 'dist/renderer.js', watch = false, jsxRuntime = 'runtime', define, plugins = [], aliasReactTo, logLevel = 'info', copy = [] } = options;
+    const external = options.external ?? (aliasReactTo ? [] : ['react', 'react-dom']);
+    const alias = {
+        ...jsxRuntimeAliases(jsxRuntime),
+        ...(aliasReactTo ? { react: aliasReactTo } : {})
+    };
+    const shared = {
+        entryPoints: [entry],
+        outfile,
+        bundle: true,
+        format: 'esm',
+        platform: 'browser',
+        logLevel,
+        external,
+        define,
+        plugins,
+        ...(Object.keys(alias).length > 0 ? { alias } : {}),
+        ...(jsxRuntime === 'none'
+            ? {}
+            : {
+                jsx: 'automatic',
+                jsxImportSource: '@harborclient/sdk'
+            })
+    };
+    if (watch) {
+        const context = await esbuild.context(shared);
+        await context.watch();
+        console.log('Watching for changes…');
+        return;
+    }
+    const context = await esbuild.context(shared);
+    await context.rebuild();
+    await context.dispose();
+    if (copy.length > 0) {
+        copyAssets(copy);
+    }
+}
+/**
+ * Escapes a string for use as a literal in a RegExp.
+ *
+ * @param value - Raw string to escape.
+ * @returns Regex-safe literal.
+ */
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * esbuild plugin that stubs Node built-in modules with empty exports.
+ *
+ * Use when a dependency imports Node modules that are unused at runtime in the
+ * renderer (e.g. `dotenv` importing `fs`/`path`).
+ *
+ * @param moduleNames - Built-in module names to stub (e.g. `path`, `fs`).
+ * @returns esbuild plugin.
+ */
+export function nodeBuiltinStubsPlugin(moduleNames) {
+    return {
+        name: 'node-builtins-stub',
+        setup(build) {
+            for (const moduleName of moduleNames) {
+                build.onResolve({ filter: new RegExp(`^${escapeRegExp(moduleName)}$`) }, () => ({
+                    path: moduleName,
+                    namespace: 'node-stub'
+                }));
+            }
+            build.onLoad({ filter: /.*/, namespace: 'node-stub' }, () => ({
+                contents: 'export default {};',
+                loader: 'js'
+            }));
+        }
+    };
+}

package/dist/client.d.ts

@@ -1,2 +1,2 @@
-export * from './index';
-export * from './runtime/index';
+export * from './index.js';
+export * from './runtime/index.js';

package/dist/components/index.d.ts

@@ -24,6 +24,7 @@ export type { Props as KeyValueEditorProps } from './KeyValueEditor/index.js';
 export { MethodSelect } from './MethodSelect/index.js';
 export { Modal, ModalFooter, ModalFormLayout } from './Modal/index.js';
 export { ModalHeader } from './Modal/ModalHeader.js';
+export { portalToBody } from './portalToBody.js';
 export { OverlayCloseButton } from './OverlayCloseButton/index.js';
 export { Page } from './Page/index.js';
 export { PageHeader } from './PageHeader/index.js';

package/dist/components/index.d.ts.map

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

package/dist/components/index.js

@@ -17,6 +17,7 @@ export { KeyValueEditor } from './KeyValueEditor/index.js';
 export { MethodSelect } from './MethodSelect/index.js';
 export { Modal, ModalFooter, ModalFormLayout } from './Modal/index.js';
 export { ModalHeader } from './Modal/ModalHeader.js';
+export { portalToBody } from './portalToBody.js';
 export { OverlayCloseButton } from './OverlayCloseButton/index.js';
 export { Page } from './Page/index.js';
 export { PageHeader } from './PageHeader/index.js';

package/dist/components/portalToBody.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode, ReactPortal } from 'react';
+/**
+ * Portals modal content to document.body so fixed positioning is not clipped by
+ * the sidebar or other overflow-hidden plugin webview containers.
+ *
+ * @param node - Modal element to render.
+ * @returns Portal into document.body.
+ * @throws When `document` is unavailable (SSR, tests, or misconfigured host).
+ */
+export declare function portalToBody(node: ReactNode): ReactPortal;
+//# sourceMappingURL=portalToBody.d.ts.map

package/dist/components/portalToBody.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portalToBody.d.ts","sourceRoot":"","sources":["../../src/components/portalToBody.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAEpD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,WAAW,CAKzD"}

package/dist/components/portalToBody.js

@@ -0,0 +1,15 @@
+import { createPortal } from '@harborclient/sdk/react-dom';
+/**
+ * Portals modal content to document.body so fixed positioning is not clipped by
+ * the sidebar or other overflow-hidden plugin webview containers.
+ *
+ * @param node - Modal element to render.
+ * @returns Portal into document.body.
+ * @throws When `document` is unavailable (SSR, tests, or misconfigured host).
+ */
+export function portalToBody(node) {
+    if (typeof document === 'undefined') {
+        throw new Error('portalToBody requires a DOM document');
+    }
+    return createPortal(node, document.body);
+}

package/dist/eslint/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared flat ESLint config for HarborClient plugins (ESLint 10 compatible).
+ *
+ * Plugins re-export this from `eslint.config.mjs`:
+ * `export { default } from '@harborclient/sdk/eslint';`
+ */
+declare const _default: import("typescript-eslint").FlatConfig.ConfigArray;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/eslint/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/eslint/index.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;;AACH,wBAaE"}

package/dist/eslint/index.js

@@ -0,0 +1,18 @@
+import eslint from '@eslint/js';
+import eslintConfigPrettier from 'eslint-config-prettier';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+/**
+ * Shared flat ESLint config for HarborClient plugins (ESLint 10 compatible).
+ *
+ * Plugins re-export this from `eslint.config.mjs`:
+ * `export { default } from '@harborclient/sdk/eslint';`
+ */
+export default tseslint.config({
+    ignores: ['**/node_modules', '**/dist', 'pnpm-lock.yaml']
+}, eslint.configs.recommended, tseslint.configs.recommended, {
+    files: ['**/*.mjs'],
+    languageOptions: {
+        globals: globals.node
+    }
+}, eslintConfigPrettier);

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export type * from './types';
+export type * from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAC"}

package/dist/main.d.ts

@@ -1,2 +1,2 @@
-export type { CodeEditorSetup, CodeEditorTheme, Disposable, EchoServerIncomingRequest, EchoServerStartResult, EchoServerStatus, MainPluginContext, PluginHttp, PluginHttpRequest, PluginHttpResponse, PluginIpc, PluginScriptCollectionInit, PluginScriptContext, PluginScriptContextInit, PluginScriptEnvironmentInit, PluginScriptKeyValue, PluginScriptRequestInit, PluginScriptResponseInit, PluginScriptRunResult, PluginScripts, PluginScriptTestResult, PluginServer, PluginStorage, ScriptPhase } from './types';
+export type { CodeEditorSetup, CodeEditorTheme, Disposable, EchoServerIncomingRequest, EchoServerStartResult, EchoServerStatus, MainPluginContext, PluginHttp, PluginHttpRequest, PluginHttpResponse, PluginIpc, PluginScriptCollectionInit, PluginScriptContext, PluginScriptContextInit, PluginScriptEnvironmentInit, PluginScriptKeyValue, PluginScriptRequestInit, PluginScriptResponseInit, PluginScriptRunResult, PluginScripts, PluginScriptTestResult, PluginServer, PluginStorage, ScriptPhase } from './types.js';
 //# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,eAAe,EACf,eAAe,EACf,UAAU,EACV,yBAAyB,EACzB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,SAAS,EACT,0BAA0B,EAC1B,mBAAmB,EACnB,uBAAuB,EACvB,2BAA2B,EAC3B,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,qBAAqB,EACrB,aAAa,EACb,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,WAAW,EACZ,MAAM,SAAS,CAAC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,eAAe,EACf,eAAe,EACf,UAAU,EACV,yBAAyB,EACzB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,SAAS,EACT,0BAA0B,EAC1B,mBAAmB,EACnB,uBAAuB,EACvB,2BAA2B,EAC3B,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,qBAAqB,EACrB,aAAa,EACb,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,WAAW,EACZ,MAAM,YAAY,CAAC"}

package/dist/runtime/index.d.ts

@@ -1,5 +1,5 @@
 import type * as React from 'react';
-import type { Disposable, PluginContext, ThemeContribution } from '../types';
+import type { Disposable, PluginContext, ThemeContribution } from '../types.js';
 
 /**
  * Installs the HarborClient renderer React instance for plugin JSX and hooks.

package/dist/runtime/jsx-dev-runtime.d.ts

@@ -1,6 +1,6 @@
 import type * as React from 'react';
 
-export { Fragment } from './jsx-runtime';
+export { Fragment } from './jsx-runtime.js';
 
 /**
  * Development JSX runtime entry; delegates to the production jsx helper.

package/dist/runtime/jsx-runtime-host.d.ts

@@ -0,0 +1,44 @@
+import type * as React from 'react';
+
+/**
+ * Host React fragment, resolved from the externalized `react` module at runtime.
+ */
+export declare const Fragment: React.ExoticComponent<{ children?: React.ReactNode }>;
+
+/**
+ * Automatic JSX runtime entry for third-party deps aliased to this module.
+ */
+export function jsx(
+  type: React.ElementType,
+  props: Record<string, unknown> | null | undefined,
+  key?: string | number
+): React.ReactElement;
+
+/**
+ * Automatic JSX runtime entry for elements with multiple children.
+ */
+export function jsxs(
+  type: React.ElementType,
+  props: Record<string, unknown> | null | undefined,
+  key?: string | number
+): React.ReactElement;
+
+/**
+ * Development JSX transform entry; delegates to {@link jsx}.
+ */
+export function jsxDEV(
+  type: React.ElementType,
+  props: Record<string, unknown> | null | undefined,
+  key?: string | number
+): React.ReactElement;
+
+export namespace JSX {
+  interface Element extends React.JSX.Element {}
+  interface ElementClass extends React.JSX.ElementClass {}
+  interface ElementAttributesProperty extends React.JSX.ElementAttributesProperty {}
+  interface ElementChildrenAttribute extends React.JSX.ElementChildrenAttribute {}
+  type LibraryManagedAttributes<C, P> = React.JSX.LibraryManagedAttributes<C, P>;
+  interface IntrinsicAttributes extends React.JSX.IntrinsicAttributes {}
+  interface IntrinsicClassAttributes<T> extends React.JSX.IntrinsicClassAttributes<T> {}
+  interface IntrinsicElements extends React.JSX.IntrinsicElements {}
+}

package/dist/runtime/jsx-runtime-host.js

@@ -0,0 +1,42 @@
+import * as React from 'react';
+
+export const Fragment = React.Fragment;
+
+/**
+ * Builds a React element using the externalized host React directly.
+ *
+ * Used when bundling third-party deps (e.g. @uiw/react-codemirror,
+ * @fortawesome/react-fontawesome) that import `react/jsx-runtime`. Aliasing
+ * those imports to this module keeps them on the same host React instance as
+ * the plugin shell without requiring installReact() to have run first.
+ *
+ * @param {import('react').ElementType} type - Element type or Fragment.
+ * @param {Record<string, unknown> | null | undefined} props - Element props.
+ * @param {string | number | undefined} key - React key when provided by the compiler.
+ * @returns {import('react').ReactElement}
+ */
+function build(type, props, key) {
+  const { children, ...rest } = props ?? {};
+  if (key !== undefined) {
+    rest.key = key;
+  }
+  return React.createElement(type, props === null ? props : rest, children);
+}
+
+/** @type {typeof import('react/jsx-runtime').jsx} */
+export const jsx = build;
+
+/** @type {typeof import('react/jsx-runtime').jsxs} */
+export const jsxs = build;
+
+/**
+ * Development JSX transform entry; delegates to the production jsx helper.
+ *
+ * @param {import('react').ElementType} type - Element type or Fragment.
+ * @param {Record<string, unknown> | null | undefined} props - Element props.
+ * @param {string | number | undefined} key - React key when provided by the compiler.
+ * @returns {import('react').ReactElement}
+ */
+export function jsxDEV(type, props, key) {
+  return build(type, props, key);
+}

package/dist/runtime/react-dom.d.ts

@@ -0,0 +1 @@
+export { createPortal } from 'react-dom';

package/dist/runtime/react-dom.js

@@ -0,0 +1,16 @@
+import { requireHostReactDom } from './reactHost.js';
+
+/**
+ * Creates a React portal into the host DOM tree.
+ *
+ * Delegates to the installed host React DOM instance so portals reconcile with
+ * the same React copy as {@link @harborclient/sdk/react} hooks.
+ *
+ * @param {import('react').ReactNode} children - Portal content.
+ * @param {Element | DocumentFragment} container - DOM mount target.
+ * @param {string | null} [key] - Optional React key for the portal.
+ * @returns {import('react').ReactPortal} Portal element.
+ */
+export function createPortal(children, container, key) {
+  return requireHostReactDom().createPortal(children, container, key);
+}

package/dist/runtime/react.d.ts

@@ -6,6 +6,7 @@ export {
   useRef,
   useSyncExternalStore,
   forwardRef,
+  useImperativeHandle,
   cloneElement,
   isValidElement,
   createContext,
@@ -14,3 +15,8 @@ export {
   useLayoutEffect,
   createElement
 } from 'react';
+
+import type * as React from 'react';
+
+declare const _default: typeof React;
+export default _default;

package/dist/runtime/react.js

@@ -45,9 +45,40 @@ export function useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
   return hook('useSyncExternalStore')(subscribe, getSnapshot, getServerSnapshot);
 }
 
-/** @type {typeof import('react').forwardRef} */
+/**
+ * Defers host React lookup until render so module-level `React.forwardRef(...)`
+ * calls (e.g. from @fortawesome/react-fontawesome) work before activate().
+ *
+ * @type {typeof import('react').forwardRef}
+ */
 export function forwardRef(render) {
-  return hook('forwardRef')(render);
+  /** @type {ReturnType<typeof import('react').forwardRef> | null} */
+  let forwarded = null;
+
+  /**
+   * Lazily wraps the render function with host React.forwardRef on first render.
+   *
+   * @param {Record<string, unknown>} props - Component props.
+   * @param {import('react').Ref<unknown>} ref - Ref forwarded from the parent.
+   * @returns {import('react').ReactElement}
+   */
+  function LazyForwardRef(props, ref) {
+    const react = requireHostReact();
+    if (forwarded === null) {
+      forwarded = react.forwardRef(render);
+    }
+    return react.createElement(forwarded, { ...props, ref });
+  }
+
+  const displayName = render.displayName ?? render.name ?? 'Component';
+  LazyForwardRef.displayName = `ForwardRef(${displayName})`;
+
+  return LazyForwardRef;
+}
+
+/** @type {typeof import('react').useImperativeHandle} */
+export function useImperativeHandle(ref, create, deps) {
+  return hook('useImperativeHandle')(ref, create, deps);
 }
 
 /** @type {typeof import('react').cloneElement} */
@@ -84,3 +115,40 @@ export function useLayoutEffect(effect, deps) {
 export function createElement(type, props, ...children) {
   return hook('createElement')(type, props, ...children);
 }
+
+/**
+ * Named SDK React exports used as the Proxy target for the default export.
+ */
+const reactNamespace = {
+  useState,
+  useEffect,
+  useCallback,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+  forwardRef,
+  useImperativeHandle,
+  cloneElement,
+  isValidElement,
+  createContext,
+  useContext,
+  useId,
+  useLayoutEffect,
+  createElement
+};
+
+/**
+ * Default React namespace for `import React from 'react'` when aliasing bare
+ * `react` to `@harborclient/sdk/react`. Named exports are served from the SDK;
+ * other properties fall back to the installed host React instance.
+ */
+const defaultExport = new Proxy(reactNamespace, {
+  get(target, prop, receiver) {
+    if (prop in target) {
+      return Reflect.get(target, prop, receiver);
+    }
+    return requireHostReact()[prop];
+  }
+});
+
+export default defaultExport;

package/dist/runtime/reactHost.js

@@ -1,9 +1,15 @@
 /** Global key shared across bundled plugin copies of this module and the view host. */
 const HOST_REACT_GLOBAL_KEY = '__HARBORCLIENT_HOST_REACT__';
 
+/** Global key for the host React DOM instance (createPortal, etc.). */
+const HOST_REACT_DOM_GLOBAL_KEY = '__HARBORCLIENT_HOST_REACT_DOM__';
+
 /** @type {typeof import('react') | null} */
 let hostReact = null;
 
+/** @type {typeof import('react-dom') | null} */
+let hostReactDom = null;
+
 /**
  * Reads the host React instance published on globalThis by the view host bootstrap.
  *
@@ -52,3 +58,49 @@ export function requireHostReact() {
   }
   return hostReact;
 }
+
+/**
+ * Reads the host React DOM instance published on globalThis by the view host bootstrap.
+ *
+ * @returns {typeof import('react-dom') | null} Host React DOM when available.
+ */
+function readGlobalHostReactDom() {
+  if (typeof globalThis === 'undefined') {
+    return null;
+  }
+  const candidate = globalThis[HOST_REACT_DOM_GLOBAL_KEY];
+  return candidate ?? null;
+}
+
+/**
+ * Installs the HarborClient renderer React DOM instance for plugin portals.
+ *
+ * @param {typeof import('react-dom')} reactDom - React DOM namespace from the host shim.
+ */
+export function setHostReactDom(reactDom) {
+  hostReactDom = reactDom;
+  if (typeof globalThis !== 'undefined') {
+    globalThis[HOST_REACT_DOM_GLOBAL_KEY] = reactDom;
+  }
+}
+
+/**
+ * Returns the installed host React DOM instance.
+ *
+ * @returns {typeof import('react-dom')} Host React DOM namespace.
+ * @throws {Error} When {@link setHostReactDom} has not been called yet.
+ */
+export function requireHostReactDom() {
+  if (hostReactDom == null) {
+    const globalReactDom = readGlobalHostReactDom();
+    if (globalReactDom != null) {
+      hostReactDom = globalReactDom;
+    }
+  }
+  if (hostReactDom == null) {
+    throw new Error(
+      'Plugin React DOM host is not installed. The view host must call setHostReactDom() before activate().'
+    );
+  }
+  return hostReactDom;
+}