@sidecar-ai/react 0.1.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import * as React from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { WidgetBridge, SidecarHostContext, WidgetToolResult } from '@sidecar-ai/client';
+export { HostFeatureResult, HostLogLevel, HostLogMessage, ModelMessage, SamplingMessageRequest, SamplingMessageResult, ServerResource, ServerResourceContent, ServerResourceListResult, ServerResourceReadResult, SidecarHostContext, SizeChangedMessage, ToolCancelledListener, ToolInput, ToolInputListener, WidgetBridge, WidgetToolResult, browserBridge, createBrowserBridge, createToolClient, getToolResult, log, model, sampling, server, view } from '@sidecar-ai/client';
+import { ToolWidgetOptions } from '@sidecar-ai/core';
+export { ChatGptWidgetOptions, WidgetCspOptions } from '@sidecar-ai/core';
+
+/** Props supplied to generated widget roots. Widgets read data through hooks. */
+type WidgetProps = Record<string, never>;
+/** React component returned by `widget(...)` with static Sidecar metadata. */
+type SidecarWidget = ComponentType<WidgetProps> & {
+    readonly kind: "sidecar.widget";
+    readonly options: ToolWidgetOptions;
+};
+/**
+ * Declares a React widget and its MCP Apps resource metadata.
+ *
+ * The compiler reads the options statically from `widget.tsx`; at runtime this
+ * returns the component itself so React rendering stays ordinary.
+ */
+declare function widget(options: ToolWidgetOptions, Component: ComponentType<WidgetProps>): SidecarWidget;
+/** Provides a custom widget bridge for tests or non-browser embedding. */
+declare function SidecarWidgetProvider(props: {
+    bridge: WidgetBridge;
+    children?: ReactNode;
+}): React.FunctionComponentElement<React.ProviderProps<WidgetBridge | null>>;
+/** Generated widgets mount through this root so host context is always active. */
+declare function SidecarWidgetRoot(props: {
+    children: ReactNode;
+    bridge?: WidgetBridge;
+}): React.FunctionComponentElement<{
+    bridge: WidgetBridge;
+    children?: ReactNode;
+}>;
+/** Returns the nearest bridge provider or the default browser bridge. */
+declare function useWidgetBridge(): WidgetBridge;
+/** React hook for reading the current tool result. */
+declare function useToolResult<Structured, Meta = Record<string, unknown>>(): WidgetToolResult<Structured, Meta>;
+/** React hook for the active host/theme context. */
+declare function useHost(): SidecarHostContext;
+/** React hook for just the active light/dark theme. */
+declare function useTheme(): SidecarHostContext["theme"];
+/** Session-storage backed state helper for lightweight widget state. */
+declare function useWidgetState<T>(key: string, initialValue: T): [T, (value: T) => void];
+
+export { type SidecarWidget, SidecarWidgetProvider, SidecarWidgetRoot, ToolWidgetOptions as WidgetOptions, type WidgetProps, useHost, useTheme, useToolResult, useWidgetBridge, useWidgetState, widget };

package/dist/index.js

@@ -0,0 +1,144 @@
+// packages/react/src/index.ts
+import {
+  browserBridge
+} from "@sidecar-ai/client";
+import {
+  createContext,
+  createElement,
+  useEffect,
+  useContext,
+  useMemo,
+  useState
+} from "react";
+import {
+  browserBridge as browserBridge2,
+  createBrowserBridge,
+  createToolClient,
+  getToolResult,
+  log,
+  model,
+  sampling,
+  server,
+  view
+} from "@sidecar-ai/client";
+var WidgetBridgeContext = createContext(null);
+var HostContextContext = createContext(null);
+function widget(options, Component) {
+  Object.defineProperties(Component, {
+    kind: {
+      enumerable: false,
+      value: "sidecar.widget"
+    },
+    options: {
+      enumerable: false,
+      value: Object.freeze({ ...options })
+    }
+  });
+  return Component;
+}
+function SidecarWidgetProvider(props) {
+  const [hostContext, setHostContext] = useState(
+    () => props.bridge.getHostContext()
+  );
+  useEffect(() => props.bridge.subscribeHostContext(setHostContext), [props.bridge]);
+  useEffect(() => {
+    if (typeof document === "undefined") {
+      return;
+    }
+    document.documentElement.dataset.sidecarHost = hostContext.name;
+    document.documentElement.dataset.sidecarTheme = hostContext.theme;
+  }, [hostContext]);
+  return createElement(
+    WidgetBridgeContext.Provider,
+    { value: props.bridge },
+    createElement(
+      HostContextContext.Provider,
+      { value: hostContext },
+      props.children
+    )
+  );
+}
+function SidecarWidgetRoot(props) {
+  return createElement(
+    SidecarWidgetProvider,
+    { bridge: props.bridge ?? browserBridge },
+    props.children
+  );
+}
+function useWidgetBridge() {
+  const bridge = useContext(WidgetBridgeContext);
+  if (!bridge) {
+    return browserBridge;
+  }
+  return bridge;
+}
+function useToolResult() {
+  const bridge = useWidgetBridge();
+  const [result, setResult] = useState(
+    () => bridge.getToolResult()
+  );
+  useEffect(
+    () => bridge.subscribeToolResult(
+      (next) => setResult(next)
+    ),
+    [bridge]
+  );
+  return result;
+}
+function useHost() {
+  const context = useContext(HostContextContext);
+  if (context) {
+    return context;
+  }
+  return useWidgetBridge().getHostContext();
+}
+function useTheme() {
+  return useHost().theme;
+}
+function useWidgetState(key, initialValue) {
+  const storageKey = `sidecar.widget.${key}`;
+  const [value, setValue] = useState(() => {
+    if (typeof window === "undefined") {
+      return initialValue;
+    }
+    try {
+      const stored = window.sessionStorage.getItem(storageKey);
+      return stored === null ? initialValue : JSON.parse(stored);
+    } catch {
+      return initialValue;
+    }
+  });
+  const update = useMemo(
+    () => (next) => {
+      setValue(next);
+      if (typeof window !== "undefined") {
+        try {
+          window.sessionStorage.setItem(storageKey, JSON.stringify(next));
+        } catch {
+        }
+      }
+    },
+    [storageKey]
+  );
+  return [value, update];
+}
+export {
+  SidecarWidgetProvider,
+  SidecarWidgetRoot,
+  browserBridge2 as browserBridge,
+  createBrowserBridge,
+  createToolClient,
+  getToolResult,
+  log,
+  model,
+  sampling,
+  server,
+  useHost,
+  useTheme,
+  useToolResult,
+  useWidgetBridge,
+  useWidgetState,
+  view,
+  widget
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../packages/react/src/index.ts"],"sourcesContent":["/**\n * React conveniences over the framework-agnostic `@sidecar-ai/client` bridge.\n *\n * Widgets can use this package for hooks, but the underlying iframe bridge is\n * intentionally not React-specific.\n */\nimport {\n  browserBridge,\n  type WidgetBridge,\n  type WidgetToolResult,\n  type SidecarHostContext,\n} from \"@sidecar-ai/client\";\nimport {\n  createContext,\n  createElement,\n  useEffect,\n  useContext,\n  useMemo,\n  useState,\n  type ComponentType,\n  type ReactNode,\n} from \"react\";\nimport type { ToolWidgetOptions } from \"@sidecar-ai/core\";\n\nexport {\n  browserBridge,\n  createBrowserBridge,\n  createToolClient,\n  getToolResult,\n  log,\n  model,\n  sampling,\n  server,\n  view,\n  type HostFeatureResult,\n  type HostLogLevel,\n  type HostLogMessage,\n  type SamplingMessageRequest,\n  type SamplingMessageResult,\n  type ServerResource,\n  type ServerResourceContent,\n  type ServerResourceListResult,\n  type ServerResourceReadResult,\n  type SidecarHostContext,\n  type ModelMessage,\n  type SizeChangedMessage,\n  type ToolCancelledListener,\n  type ToolInput,\n  type ToolInputListener,\n  type WidgetBridge,\n  type WidgetToolResult,\n} from \"@sidecar-ai/client\";\nexport type {\n  ChatGptWidgetOptions,\n  ToolWidgetOptions as WidgetOptions,\n  WidgetCspOptions,\n} from \"@sidecar-ai/core\";\n\n/** Props supplied to generated widget roots. Widgets read data through hooks. */\nexport type WidgetProps = Record<string, never>;\n\n/** React component returned by `widget(...)` with static Sidecar metadata. */\nexport type SidecarWidget = ComponentType<WidgetProps> & {\n  readonly kind: \"sidecar.widget\";\n  readonly options: ToolWidgetOptions;\n};\n\nconst WidgetBridgeContext = createContext<WidgetBridge | null>(null);\nconst HostContextContext = createContext<SidecarHostContext | null>(null);\n\n/**\n * Declares a React widget and its MCP Apps resource metadata.\n *\n * The compiler reads the options statically from `widget.tsx`; at runtime this\n * returns the component itself so React rendering stays ordinary.\n */\nexport function widget(\n  options: ToolWidgetOptions,\n  Component: ComponentType<WidgetProps>,\n): SidecarWidget {\n  Object.defineProperties(Component, {\n    kind: {\n      enumerable: false,\n      value: \"sidecar.widget\",\n    },\n    options: {\n      enumerable: false,\n      value: Object.freeze({ ...options }),\n    },\n  });\n\n  return Component as SidecarWidget;\n}\n\n/** Provides a custom widget bridge for tests or non-browser embedding. */\nexport function SidecarWidgetProvider(props: { bridge: WidgetBridge; children?: ReactNode }) {\n  const [hostContext, setHostContext] = useState<SidecarHostContext>(() =>\n    props.bridge.getHostContext(),\n  );\n\n  useEffect(() => props.bridge.subscribeHostContext(setHostContext), [props.bridge]);\n\n  useEffect(() => {\n    if (typeof document === \"undefined\") {\n      return;\n    }\n\n    document.documentElement.dataset.sidecarHost = hostContext.name;\n    document.documentElement.dataset.sidecarTheme = hostContext.theme;\n  }, [hostContext]);\n\n  return createElement(\n    WidgetBridgeContext.Provider,\n    { value: props.bridge },\n    createElement(\n      HostContextContext.Provider,\n      { value: hostContext },\n      props.children,\n    ),\n  );\n}\n\n/** Generated widgets mount through this root so host context is always active. */\nexport function SidecarWidgetRoot(props: { children: ReactNode; bridge?: WidgetBridge }) {\n  return createElement(\n    SidecarWidgetProvider,\n    { bridge: props.bridge ?? browserBridge },\n    props.children,\n  );\n}\n\n/** Returns the nearest bridge provider or the default browser bridge. */\nexport function useWidgetBridge(): WidgetBridge {\n  const bridge = useContext(WidgetBridgeContext);\n  if (!bridge) {\n    return browserBridge;\n  }\n  return bridge;\n}\n\n/** React hook for reading the current tool result. */\nexport function useToolResult<Structured, Meta = Record<string, unknown>>(): WidgetToolResult<Structured, Meta> {\n  const bridge = useWidgetBridge();\n  const [result, setResult] = useState<WidgetToolResult<Structured, Meta>>(() =>\n    bridge.getToolResult<Structured, Meta>(),\n  );\n\n  useEffect(\n    () =>\n      bridge.subscribeToolResult((next) =>\n        setResult(next as WidgetToolResult<Structured, Meta>),\n      ),\n    [bridge],\n  );\n\n  return result;\n}\n\n/** React hook for the active host/theme context. */\nexport function useHost(): SidecarHostContext {\n  const context = useContext(HostContextContext);\n  if (context) {\n    return context;\n  }\n\n  return useWidgetBridge().getHostContext();\n}\n\n/** React hook for just the active light/dark theme. */\nexport function useTheme(): SidecarHostContext[\"theme\"] {\n  return useHost().theme;\n}\n\n/** Session-storage backed state helper for lightweight widget state. */\nexport function useWidgetState<T>(key: string, initialValue: T): [T, (value: T) => void] {\n  const storageKey = `sidecar.widget.${key}`;\n  const [value, setValue] = useState<T>(() => {\n    if (typeof window === \"undefined\") {\n      return initialValue;\n    }\n\n    try {\n      const stored = window.sessionStorage.getItem(storageKey);\n      return stored === null ? initialValue : (JSON.parse(stored) as T);\n    } catch {\n      return initialValue;\n    }\n  });\n\n  const update = useMemo(\n    () => (next: T) => {\n      setValue(next);\n      if (typeof window !== \"undefined\") {\n        try {\n          window.sessionStorage.setItem(storageKey, JSON.stringify(next));\n        } catch {\n          // Session storage can be unavailable or quota-limited in host iframes.\n        }\n      }\n    },\n    [storageKey]\n  );\n\n  return [value, update];\n}\n"],"mappings":"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","names":["browserBridge"]}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@sidecar-ai/react",
+  "version": "0.1.0-alpha.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@sidecar-ai/client": "0.1.0-alpha.0",
+    "@sidecar-ai/core": "0.1.0-alpha.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}