@snap/react-camera-kit 0.0.1

package/LICENSE.md

@@ -0,0 +1,37 @@
+Copyright © 2026 Snap Inc.
+
+Camera Kit Web React Bindings are made available under the MIT License. Access to or use of Camera Kit is subject to the Snap Developer Terms and Snap Camera Kit Terms linked to below.
+
+**MIT License**
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+**Snap Developer Terms**
+
+Access to or use of developer products and services made available to you by Snap Inc. and its affiliates (“Snap”), is subject to the Snap Developer Terms, which can be found at:
+
+https://snap.com/en-US/terms/developer
+
+If you do not agree to these terms, do not use or otherwise access Snap developer products, including Camera Kit.
+
+—-
+
+**Snap Camera Kit Terms**
+
+Access to or use of Camera Kit and its associated documentation, software code, and other materials (collectively, “Camera Kit”), made available by Snap Inc. and its affiliates ("Snap"), is subject to the Snap Camera Kit Terms, which can be found at:
+
+https://www.snap.com/terms/snap-camera-kit
+
+If you do not agree to these terms, do not use or otherwise access Camera Kit.
+
+**Third-Party Software**
+
+Camera Kit Web React Bindings includes or interacts with third-party software. A detailed report of the third-party software used, including their respective licenses, can be found at the following link.
+
+https://portal.fossa.com/p/snap/release/5555/30311
+
+We aim to maintain transparency and compliance with all third-party license requirements. If you spot an issue or believe attribution is missing, please reach out to us at [opensource@snap.com](mailto:opensource@snap.com).

package/README.md

@@ -0,0 +1,130 @@
+# @snap/react-camera-kit
+
+React Camera Kit for web applications.
+
+**[Live Demo](https://snapchat.github.io/react-camera-kit/)**
+
+## Installation
+
+```bash
+npm install @snap/react-camera-kit @snap/camera-kit
+```
+
+## Prerequisites
+
+Before using this package, complete Camera Kit Web setup and obtain:
+
+- `apiToken`
+- `lensId`
+- `lensGroupId`
+- `https://` for deployed apps (`http://localhost` should works for local dev)
+
+Full setup guides:
+
+- Camera Kit Web configuration: https://developers.snap.com/camera-kit/integrate-sdk/web/web-configuration
+- `@snap/camera-kit` docs: https://www.npmjs.com/package/@snap/camera-kit
+
+## Compatibility
+
+- Requires `@snap/camera-kit` `^1.13.0`, because `1.13.0+` includes the SDK-side font bootstrap behavior needed by this package.
+
+## Usage
+
+This package provides a simple API for integrating Camera Kit into React applications.
+
+The simplest use case is:
+
+```tsx
+<CameraKitProvider apiToken="YOUR_TOKEN">
+  <LensPlayer lensId="YOUR_LENS_ID" lensGroupId="YOUR_GROUP_ID" />
+</CameraKitProvider>
+```
+
+if you need to render specific canvas with custom layout:
+
+```tsx
+<CameraKitProvider apiToken="YOUR_TOKEN">
+  <LensPlayer lensId="YOUR_LENS_ID" lensGroupId="YOUR_GROUP_ID" canvasType="both">
+    <div>
+      <LiveCanvas />
+    </div>
+    <div>
+      <CaptureCanvas />
+    </div>
+  </LensPlayer>
+</CameraKitProvider>
+```
+
+if you need to access lens status (assuming `CameraKitProvider` context):
+
+```tsx
+function Preview() {
+  const { lens } = useCameraKit();
+  return (
+    <LensPlayer lensId="YOUR_LENS_ID" lensGroupId="YOUR_GROUP_ID">
+      {lens.status !== "ready" && lens.status !== "error" && <Spinner />}
+      {lens.status === "error" && <Error error={lens.error} />}
+      {lens.status === "ready" && <LiveCanvas />}
+    </LensPlayer>
+  );
+}
+```
+
+When you need full control (assuming `CameraKitProvider` context):
+
+```tsx
+function Preview() {
+  const { sdkStatus, source, lens } = useCameraKit();
+  useApplySource({ kind: "video", url: "/demo.mp4" }, { mode: "fixed", width: 720, height: 1280 });
+  useApplyLens("123", "abc", launchData);
+  usePlaybackOptions({ onError: (error) => console.error(error) });
+
+  if (sdkStatus !== "ready" || source.status !== "ready" || lens.status !== "ready") {
+    return <Spinner />;
+  }
+  return <CaptureCanvas className="rounded-xl" />;
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package (ESM + CJS)
+npm run build
+
+# Build in watch mode (for development)
+npm run watch
+
+# Type checking
+npm run typecheck
+
+# Run tests
+npm test
+
+# Clean dist folder
+npm run clean
+```
+
+## Demo App
+
+A Vite demo app is available at `demo`.
+
+```bash
+npm run demo:install
+cp demo/.env.example demo/.env
+npm run demo:dev
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to get started.
+
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Security Policy](SECURITY.md)
+
+## License
+
+[MIT](LICENSE.md)

package/dist/cjs/CameraKitProvider.d.ts

@@ -0,0 +1,203 @@
+import React, { ReactNode } from "react";
+import { CameraKit, CameraKitBootstrapConfiguration, CameraKitSession, PublicContainer, Lens, LensLaunchData, ScreenRegions, Keyboard } from "@snap/camera-kit";
+import { CurrentLens, CurrentSource, SourceInput, OutputSize } from "./types";
+import { CameraKitLogger, LogLevel } from "./internal/logging";
+export type MetricEventHandlerFactory = () => (event: {
+    kind: "bootstrap-attempt" | "bootstrap-success";
+} | {
+    kind: "bootstrap-failure" | "lens-failure";
+    error: Error;
+}) => void;
+/**
+ * Public context interface exposed to consumers via useCameraKit hook.
+ * Provides access to Camera Kit SDK state, Lens management, source control, and playback options.
+ */
+interface CameraKitContextValue {
+    /** Current SDK initialization status. */
+    sdkStatus: "uninitialized" | "initializing" | "ready" | "error";
+    /** Error that occurred during SDK initialization, if any. */
+    sdkError: Error | undefined;
+    /** Live canvas element for real-time preview rendering. */
+    liveCanvas: HTMLCanvasElement | undefined;
+    /** Capture canvas element for snapshot rendering. */
+    captureCanvas: HTMLCanvasElement | undefined;
+    /** Source state including status, input parameters, and any errors. */
+    source: CurrentSource;
+    /** Lens state including status, Lens object, and any errors. */
+    lens: CurrentLens;
+    /**
+     * The {@link Keyboard} API enables applications to handle keyboard input requests from lenses.
+     * When a lens requests a keyboard, the app displays it in its preferred UI. As users type,
+     * the app sends the text back to the lens for display. The lens can also request keyboard dismissal,
+     * prompting the app to remove the displayed keyboard.
+     */
+    keyboard: Keyboard | undefined;
+    /** Attempts to re-initialize the SDK after an error. Only available when SDK is in error state. */
+    reinitialize: () => void;
+    /** Applies a media source (camera, video, or image) to the session. */
+    applySource: (input: SourceInput, size?: OutputSize) => Promise<void>;
+    /** Removes the current source from the session. */
+    removeSource: () => Promise<void>;
+    /** Array of lenses that have been loaded via fetchLens or fetchLenses. */
+    lenses: Lens[];
+    /** Loads a single Lens by ID and group ID. Returns cached Lens if already loaded. */
+    fetchLens: (lensId: string, groupId: string) => Promise<Lens>;
+    /** Loads all lenses from one or more Lens groups. */
+    fetchLenses: (groupId: string | string[]) => Promise<Lens[]>;
+    /**
+     * Applies a Lens to the current session.
+     * @param lensId - The Lens identifier
+     * @param groupId - The Lens group identifier
+     * @param launchData - Optional launch parameters for the Lens
+     * @param lensReadyGuard - Optional async guard for coordinating Lens application
+     * @returns Promise that resolves to true if Lens was applied successfully
+     */
+    applyLens: (lensId: string, groupId: string, launchData?: LensLaunchData, lensReadyGuard?: () => Promise<void>) => Promise<boolean>;
+    /** Removes the currently applied Lens from the session. */
+    removeLens: () => Promise<boolean>;
+    /** Refreshes the current Lens by removing and reapplying it. */
+    refreshLens: () => Promise<void>;
+    /** Sets the muted state for audio playback. */
+    setMuted: (muted: boolean) => void;
+    /** Toggles the current muted state. */
+    toggleMuted: () => void;
+    /** Whether audio is currently muted. */
+    isMuted: boolean;
+    /** Current FPS limit, if set. */
+    fpsLimit: number | undefined;
+    /** Sets the maximum FPS for rendering. Useful for reducing resource usage. */
+    setFPSLimit: (fpsLimit: number) => Promise<void>;
+    /** Current screen regions configuration, if set. */
+    screenRegions: ScreenRegions | undefined;
+    /** Sets screen regions for Lens-aware UI layout. */
+    setScreenRegions: (screenRegions: ScreenRegions) => Promise<void>;
+}
+interface InternalCameraKitContextValue extends CameraKitContextValue {
+    cameraKit: CameraKit | undefined;
+    currentSession: CameraKitSession | undefined;
+    getLogger: (ns: string) => CameraKitLogger;
+}
+/**
+ * Props for the CameraKitProvider component.
+ * Extends Camera Kit bootstrap configuration with React-specific options.
+ */
+interface CameraKitProviderProps extends Omit<CameraKitBootstrapConfiguration, "logger"> {
+    /**
+     * Optional function to extend the Camera Kit dependency injection container.
+     * This is the second parameter to bootstrapCameraKit and allows customization
+     * of the SDK's internal dependencies.
+     */
+    extendContainer?: (container: PublicContainer) => PublicContainer;
+    /**
+     * Optional factory for creating bootstrap event handlers for metrics/analytics.
+     * Useful for tracking SDK initialization success/failure in your analytics system.
+     */
+    createBootstrapEventHandler?: MetricEventHandlerFactory;
+    /**
+     * Optional custom logger implementation. If not provided, a no-op logger is used by default.
+     * Pass createConsoleLogger() from './logging' for console-based logging in development.
+     *
+     * @example
+     * ```tsx
+     * import { createConsoleLogger } from '@snap/react-camera-kit';
+     *
+     * <CameraKitProvider logger={createConsoleLogger()} logLevel="debug">
+     *   {children}
+     * </CameraKitProvider>
+     * ```
+     */
+    logger?: CameraKitLogger;
+    /**
+     * Optional log level to control logger verbosity. Defaults to "info" if not specified.
+     * Supported levels: "debug", "info", "warn", "error".
+     */
+    logLevel?: LogLevel;
+    /**
+     * Browsers optimize tabs when they are hidden - for example, by pausing the execution of requestAnimationFrame
+     * callbacks.
+     *
+     * If you need the CameraKitSession to continue rendering even when the tab is in the background, set this to true.
+     * There is a small performance penalty, and it's a good practice to only render in the background if absolutely
+     * necessary.
+     */
+    renderWhileTabHidden?: boolean;
+    /**
+     * Optional manual override for bootstrap stability. If provided, the provider will re-bootstrap
+     * whenever this value changes, regardless of other config details.
+     *
+     * Useful when you want explicit control over when the SDK reinitializes.
+     */
+    stabilityKey?: string | number;
+    /**
+     * React children to render within the provider.
+     */
+    children: ReactNode;
+}
+/**
+ * Provider component that initializes and manages the Camera Kit SDK.
+ *
+ * This component handles SDK bootstrapping, session creation, and provides access to
+ * Camera Kit functionality through React context. All Camera Kit hooks and components
+ * must be used within this provider.
+ *
+ * The provider automatically manages SDK lifecycle, including initialization, cleanup,
+ * and re-initialization when configuration changes.
+ *
+ * @example
+ * ```tsx
+ * import { CameraKitProvider, createConsoleLogger } from '@snap/react-camera-kit';
+ *
+ * function App() {
+ *   return (
+ *     <CameraKitProvider
+ *       apiToken="your-api-token"
+ *       logger={createConsoleLogger()}
+ *       logLevel="debug"
+ *     >
+ *       <YourCameraKitComponents />
+ *     </CameraKitProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare const CameraKitProvider: React.FC<CameraKitProviderProps>;
+/**
+ * Internal hook with access to Camera Kit internals.
+ * Only for use within react-camera-kit library components and hooks.
+ *
+ * @internal
+ */
+export declare const useInternalCameraKit: () => InternalCameraKitContextValue;
+/**
+ * Hook to access Camera Kit context and methods.
+ *
+ * Provides access to SDK state, Lens management, source control, and playback options.
+ * Must be used within a CameraKitProvider.
+ *
+ * @returns Camera Kit context value with state and methods
+ * @throws Error if used outside of CameraKitProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const {
+ *     sdkStatus,
+ *     lens,
+ *     applyLens,
+ *     removeLens,
+ *     liveCanvas
+ *   } = useCameraKit();
+ *
+ *   useEffect(() => {
+ *     if (sdkStatus === 'ready') {
+ *       applyLens('lens-id', 'group-id');
+ *     }
+ *   }, [sdkStatus, applyLens]);
+ *
+ *   return <div>{lens.status}</div>;
+ * }
+ * ```
+ */
+export declare const useCameraKit: () => CameraKitContextValue;
+export {};
+//# sourceMappingURL=CameraKitProvider.d.ts.map

package/dist/cjs/CameraKitProvider.d.ts.map

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