@foir/sdk 0.5.0 → 0.8.0

package/dist/graphql/cdn-route.d.ts

@@ -0,0 +1,26 @@
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import { type FoirEnv } from '../transport/foir-http';
+/**
+ * The shared read lane, for `@foir/sdk/client`.
+ *
+ * The mechanics — the URL, the hash, the handshake codes — moved to
+ * `../transport/persisted-query`, which has no `graphql` import, so
+ * `@foir/sdk/data` can build the same requests without dragging the parser into
+ * a storefront bundle. They are re-exported unchanged; this module's public
+ * surface is exactly what it always was. What stayed here is the part that
+ * needs a parsed document: `print`, and the eligibility rule that reads the
+ * printed text.
+ */
+export { buildCdnUrl, documentHash, hasFoirErrorCode, NOT_SHAREABLE, PERSISTED_QUERY_NOT_FOUND, persistedQueryExtension, } from '../transport/persisted-query';
+/**
+ * Whether this read can be served by the shared endpoint.
+ *
+ * These mirror the conditions the server refuses on, so a request that would be
+ * turned away is not sent there in the first place. The server is still the
+ * authority — it refuses rather than falling back, and `foirRequest` retries on
+ * `/graphql` when it does — but every condition checked here is one round trip
+ * saved.
+ */
+export declare function isCdnEligible(env: FoirEnv, documentText: string, bearerToken?: string): boolean;
+/** Print a document once, so eligibility and the URL agree on the same text. */
+export declare function printDocument<TData, TVariables>(document: TypedDocumentNode<TData, TVariables>): string;

package/dist/graphql/client.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `@foir/sdk/client` — client-agnostic GraphQL transport for SSR/edge loaders.
+ *
+ * A thin auth transport, not a GraphQL client: it carries the Foir-specific
+ * `x-api-key` + preview schema channel and runs typed documents via `fetch`.
+ * Consumers that bring their own GraphQL client (Apollo/urql/react-query) use
+ * the generated `TypedDocumentNode`s directly and replicate those two headers.
+ */
+export { foirRequest, isFoirPreview, absolutiseFoirMediaUrl, FOIR_CDN_BASE, FoirRequestError, } from './foir-request';
+export type { FoirEnv, FoirRequestOptions } from './foir-request';
+/**
+ * Failure classification. Branch on these rather than on `err.message`: the
+ * codes are a stable contract, the wording is not.
+ *
+ * The one worth knowing about is `isFoirRateLimited`. It is the only 4xx that
+ * clears on its own, and a client that lumps it in with the rest fails every
+ * read for as long as the key stays saturated — which looks, from the outside,
+ * exactly like a site with no content.
+ */
+export { isFoirRateLimited, isFoirUnauthenticated, isFoirForbidden, isFoirNotFound, readFoirRateLimit, } from './foir-request';
+export type { FoirErrorCode, FoirErrorExtensions, FoirGraphQLErrorItem, FoirRateLimitSnapshot, } from './foir-request';
+/**
+ * Retry. `createFoirContentClient` applies this for you; these are exported for
+ * a caller running its own loop, so both use one definition of "worth retrying"
+ * rather than two that disagree about the 429.
+ */
+export { withFoirRetry, foirRetryDelayMs } from './foir-request';
+export type { FoirRetryPolicy } from './foir-request';
+export { createFoirContentClient } from './content-client';
+export type { FoirContentClient, FoirContentClientConfig, FoirTokenProvider, } from './content-client';

package/dist/graphql/content-client.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Session-bound content client — forwards the customer bearer on every read
+ * when one is available, so auth/segment-targeted variants and customer-scoped
+ * records resolve out of the box, with no per-query wiring to forget.
+ *
+ * Resolution keys off the request's principal (see the platform's two-gate
+ * model): the `x-api-key` alone resolves the *anonymous baseline*
+ * (`context.authStatus = ""`); adding the customer bearer resolves the request
+ * as that customer (`context.authStatus = "authenticated"`, `customer_id` set).
+ *
+ * Caching: an api-key-only read is identical for every anonymous visitor and is
+ * shared-cacheable; a bearer-bearing read resolves per-customer and is not.
+ * Because the bearer only exists once a customer signs in, anonymous traffic
+ * keeps hitting the shared-cacheable baseline — only signed-in reads become
+ * per-customer. Bind this client wherever content is personalized (for most
+ * apps, everywhere the customer may be signed in) and use plain `foirRequest`
+ * for reads that must stay anonymous regardless of session.
+ */
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import type { FoirEnv, FoirRequestOptions } from './foir-request';
+import { type FoirRetryPolicy } from '../transport/retry';
+import type { FoirRateLimitSnapshot } from '../transport/foir-http';
+export type { FoirTokenProvider } from '../transport/foir-http';
+import type { FoirTokenProvider } from '../transport/foir-http';
+export interface FoirContentClientConfig {
+    env: FoirEnv;
+    /**
+     * Resolves the current customer bearer before every request. When it yields a
+     * token the token is forwarded, so `authStatus`/segment targeting and
+     * customer-scoped records resolve as that customer; when it yields
+     * null/undefined the read hits the anonymous baseline. Omit for a client that
+     * is always anonymous (equivalent to calling `foirRequest` directly).
+     */
+    getToken?: FoirTokenProvider;
+    /**
+     * Retry policy for transient failures — no response, 5xx, and 429.
+     *
+     * ON BY DEFAULT, which is the point of it being here. Retry that has to be
+     * opted into is retry each integrator writes for themselves, and the one
+     * detail they get wrong is the 429: it looks like the permanent 4xx family it
+     * sits in, and it is the only failure in that family that clears on its own.
+     * Pass `{ attempts: 1 }` to turn it off.
+     */
+    retry?: FoirRetryPolicy;
+    /**
+     * Called with the `X-RateLimit-*` headers of every response. Wire it to your
+     * logger and you will see a key approaching its ceiling instead of finding
+     * out when it hits one.
+     */
+    onRateLimit?: (snapshot: FoirRateLimitSnapshot | undefined) => void;
+}
+export interface FoirContentClient {
+    /**
+     * Run a typed document, forwarding the bound customer bearer when available.
+     * An explicit `options.bearerToken` still wins, so a single call can override
+     * the bound token (or force anonymous by passing `undefined` — the bound
+     * token only fills in when `options.bearerToken` is not supplied).
+     */
+    request<TData, TVariables>(document: TypedDocumentNode<TData, TVariables>, variables?: TVariables, options?: FoirRequestOptions): Promise<TData>;
+}
+/**
+ * Create a {@link FoirContentClient} bound to an env + token source. Every
+ * `request` forwards the customer bearer when `getToken` yields one, upgrading
+ * that read from the anonymous baseline to the signed-in customer.
+ */
+export declare function createFoirContentClient(config: FoirContentClientConfig): FoirContentClient;

package/dist/graphql/foir-request.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Foir GraphQL client — a single typed fetch wrapper for SSR/edge loaders.
+ *
+ * No GraphQL client (Apollo/urql) required: the Foir public API is a plain
+ * `POST` with an `x-api-key` header, and the dominant consumers (Hydrogen on
+ * Oxygen, React Router loaders, TanStack Start on CF Workers) fetch in
+ * server-only loaders and render — so Apollo's `InMemoryCache`/`useQuery`
+ * reactivity is dead weight, and a shared cache on a stateless multi-tenant
+ * edge worker is a cross-tenant hazard. This helper carries only the
+ * Foir-specific transport concerns (auth header, preview schema channel,
+ * error shape). Consumers on a GraphQL client (Apollo / urql / react-query /
+ * graphql-request) use the generated `TypedDocumentNode`s directly with their
+ * own client and replicate the two Foir-specific headers below — the
+ * `x-api-key` and, in preview, `X-Foir-Schema-Channel: draft`.
+ *
+ * Deduplicates the hand-copied `lib/foir/client.ts` that shipped identically
+ * across the Foir storefronts.
+ *
+ * The transport concerns themselves now live in `../transport/foir-http`, which
+ * has no `graphql` import, so `@foir/sdk/data` can reuse them without dragging
+ * `graphql` into a storefront bundle. Only `print` stayed here. Everything that
+ * module owns is re-exported below, unchanged, so this file's public surface is
+ * exactly what it always was.
+ */
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import { type FoirEnv, type FoirRequestOptions } from '../transport/foir-http';
+export { FoirRequestError, isFoirPreview, isFoirRateLimited, isFoirUnauthenticated, isFoirForbidden, isFoirNotFound, readFoirRateLimit, type FoirEnv, type FoirErrorCode, type FoirErrorExtensions, type FoirGraphQLErrorItem, type FoirRateLimitSnapshot, type FoirRequestOptions, } from '../transport/foir-http';
+export { withFoirRetry, foirRetryDelayMs, type FoirRetryPolicy, } from '../transport/retry';
+/** Default Foir CDN origin used to absolutise relative media URLs. */
+export declare const FOIR_CDN_BASE = "https://cdn.foir.dev/";
+/**
+ * Foir returns `hlsManifestUrl` as a relative path while every other media
+ * URL is absolute. Prefix relative paths with the CDN host so the browser
+ * doesn't request them from the consumer's own origin. Already-absolute URLs
+ * pass through untouched. `cdnBase` is overridable for non-default CDN hosts.
+ */
+export declare function absolutiseFoirMediaUrl(url: string | null | undefined, cdnBase?: string): string | undefined;
+/**
+ * Execute a typed GraphQL document against the Foir platform.
+ *
+ * Throws `FoirRequestError` on HTTP failure or GraphQL errors so the caller
+ * can decide whether to rethrow or fall back to local defaults. GraphQL can
+ * return partial data alongside errors; when data is present the errors are
+ * logged and the data returned (callers handle nulls), and we only throw when
+ * there's no data at all.
+ */
+export declare function foirRequest<TData, TVariables>(env: FoirEnv, document: TypedDocumentNode<TData, TVariables>, variables?: TVariables, options?: FoirRequestOptions): Promise<TData>;

package/dist/hooks/useAutoResize.d.ts

@@ -0,0 +1,22 @@
+export interface UseAutoResizeOptions {
+    /** Minimum height to report (prevents too-small iframes). @default 400 */
+    minHeight?: number;
+    /** Debounce delay in milliseconds. @default 100 */
+    debounce?: number;
+    /** Whether auto-resize is enabled. @default true */
+    enabled?: boolean;
+}
+/**
+ * Automatically resize the host iframe based on content height.
+ *
+ * @returns A callback ref to attach to your root container element.
+ *
+ * @example
+ * ```tsx
+ * function MyEditor() {
+ *   const containerRef = useAutoResize({ minHeight: 600 });
+ *   return <div ref={containerRef}>...</div>;
+ * }
+ * ```
+ */
+export declare function useAutoResize(options?: UseAutoResizeOptions): (node: HTMLDivElement | null) => void;

package/dist/hooks/useEditor.d.ts

@@ -0,0 +1,16 @@
+import type { EditorContextValue } from '../types';
+/**
+ * Access the Foir editor context.
+ *
+ * Must be used inside an `<EditorProvider>`.
+ *
+ * @example
+ * ```tsx
+ * function MyEditor() {
+ *   const { isReady, init, client, updateField, setDirty } = useEditor();
+ *   if (!isReady) return <p>Loading...</p>;
+ *   return <form>...</form>;
+ * }
+ * ```
+ */
+export declare function useEditor(): EditorContextValue;

package/dist/index.d.ts

@@ -1,394 +1,10 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
-
-/**
- * Public type definitions for the Editor SDK.
- */
-
-/** Data provided by the host when the editor initializes. */
-interface EditorInit {
-    values: Record<string, unknown>;
-    metadata?: Record<string, unknown>;
-    modelKey: string;
-    recordId: string;
-    naturalKey?: string;
-    versionId: string | null;
-    variantKey: string | null;
-    locale: string | null;
-    schema: unknown;
-    mode: 'edit' | 'readonly';
-    theme: 'light' | 'dark';
-    /** Secret API key for public API access. */
-    apiKey: string;
-    /** Public API GraphQL endpoint URL (provided by host). */
-    apiUrl: string;
-    /** Config connection domain (e.g. my-store.myshopify.com) */
-    connectionDomain?: string;
-    /** How this editor is rendered in the admin UI. */
-    configMode?: 'editor' | 'sidebar';
-    /** Currently selected field keys (sidebar mode). */
-    selectedFieldKeys?: string[];
-    /** Available fields for selection (sidebar mode). */
-    selectableFields?: Array<{
-        key: string;
-        label: string;
-        type: string;
-    }>;
-    /** Locale context (sidebar mode). */
-    localeContext?: LocaleContext | null;
-}
-/** Locale context passed by the host for sidebar editors. */
-interface LocaleContext {
-    currentLocale: string;
-    sourceLocale: string;
-    isTranslating: boolean;
-    locales: Array<{
-        code: string;
-        displayName: string;
-        isDefault: boolean;
-    }>;
-}
-/** Value exposed by the EditorProvider context. */
-interface EditorContextValue {
-    /** Whether the editor has received init data from the host. */
-    isReady: boolean;
-    /** Initial data from the host (available after init). */
-    init: EditorInit | null;
-    /** Current host theme. */
-    theme: 'light' | 'dark';
-    /** Platform GraphQL client (available after init). */
-    client: PlatformClient;
-    /** Send complete form values to the host (full replacement). */
-    updateValues: (values: Record<string, unknown>) => void;
-    /** Send a single field update to the host. */
-    updateField: (path: string, value: unknown) => void;
-    /** Request the host to save the current values. */
-    requestSave: () => void;
-    /** Request the host to publish the current version. */
-    requestPublish: () => void;
-    /** Report iframe height for auto-resize. */
-    resize: (height: number) => void;
-    /** Report dirty state (unsaved changes). */
-    setDirty: (isDirty: boolean) => void;
-    /** Request the host to navigate to an admin path. */
-    requestNavigate: (path: string) => void;
-    /** Request the host to execute a platform operation. Returns the result.
-     * `mode` controls whether the platform waits for the operation to complete
-     * ('sync') or returns immediately after queueing ('async'). Defaults to 'sync'. */
-    requestOperation: (operationKey: string, input?: Record<string, unknown>, options?: {
-        mode?: 'sync' | 'async';
-    }) => Promise<{
-        success: boolean;
-        result?: unknown;
-        error?: {
-            code: string;
-            message: string;
-        };
-    }>;
-    /** Editor mode ('editor' or 'sidebar'). */
-    configMode: 'editor' | 'sidebar';
-    /** Currently selected field keys (sidebar mode). */
-    selectedFieldKeys: string[];
-    /** Available fields for selection (sidebar mode). */
-    selectableFields: Array<{
-        key: string;
-        label: string;
-        type: string;
-    }>;
-    /** Locale context (sidebar mode). */
-    localeContext: LocaleContext | null;
-}
-/** Options for creating a PlatformClient. */
-interface PlatformClientOptions {
-    /** GraphQL endpoint URL. */
-    apiUrl: string;
-    /** API key for authentication. */
-    apiKey: string;
-}
-/** A minimal GraphQL error shape. */
-interface GraphQLError {
-    message: string;
-    locations?: Array<{
-        line: number;
-        column: number;
-    }>;
-    path?: Array<string | number>;
-    extensions?: Record<string, unknown>;
-}
-/** Response shape from a GraphQL query/mutation. */
-interface GraphQLResponse<T = Record<string, unknown>> {
-    data: T | null;
-    errors?: GraphQLError[];
-}
-/** Fetch-based GraphQL client for platform API calls. */
-interface PlatformClient {
-    /** Execute a GraphQL query or mutation. */
-    query<T = Record<string, unknown>>(query: string, variables?: Record<string, unknown>): Promise<GraphQLResponse<T>>;
-}
-
-interface EditorProviderProps {
-    children: ReactNode;
-    /**
-     * Parent window origin for postMessage validation.
-     * Must be an explicit origin (e.g., 'https://admin.example.com').
-     * Falls back to VITE_PARENT_ORIGIN or NEXT_PUBLIC_PARENT_ORIGIN env var.
-     */
-    parentOrigin?: string;
-    /**
-     * Platform API URL for GraphQL requests.
-     * Falls back to VITE_API_URL or NEXT_PUBLIC_API_URL env var.
-     */
-    apiUrl?: string;
-    onInit?: (init: EditorInit) => void;
-    onValuesChanged?: (values: Record<string, unknown>) => void;
-    onVariantChanged?: (variantKey: string, values: Record<string, unknown>) => void;
-    onSaveResult?: (success: boolean, error?: string, versionId?: string) => void;
-    onPublishResult?: (success: boolean, error?: string) => void;
-    onThemeChanged?: (theme: 'light' | 'dark') => void;
-    onSelectionChanged?: (keys: string[], fields: Array<{
-        key: string;
-        label: string;
-        type: string;
-    }>) => void;
-    onLocaleChanged?: (locale: LocaleContext) => void;
-}
-declare function EditorProvider({ children, parentOrigin: parentOriginProp, apiUrl: apiUrlProp, onInit, onValuesChanged, onVariantChanged, onSaveResult, onPublishResult, onThemeChanged, onSelectionChanged, onLocaleChanged, }: EditorProviderProps): react_jsx_runtime.JSX.Element;
-
-/**
- * Access the Foir editor context.
- *
- * Must be used inside an `<EditorProvider>`.
- *
- * @example
- * ```tsx
- * function MyEditor() {
- *   const { isReady, init, client, updateField, setDirty } = useEditor();
- *   if (!isReady) return <p>Loading...</p>;
- *   return <form>...</form>;
- * }
- * ```
- */
-declare function useEditor(): EditorContextValue;
-
-interface UseAutoResizeOptions {
-    /** Minimum height to report (prevents too-small iframes). @default 400 */
-    minHeight?: number;
-    /** Debounce delay in milliseconds. @default 100 */
-    debounce?: number;
-    /** Whether auto-resize is enabled. @default true */
-    enabled?: boolean;
-}
-/**
- * Automatically resize the host iframe based on content height.
- *
- * @returns A callback ref to attach to your root container element.
- *
- * @example
- * ```tsx
- * function MyEditor() {
- *   const containerRef = useAutoResize({ minHeight: 600 });
- *   return <div ref={containerRef}>...</div>;
- * }
- * ```
- */
-declare function useAutoResize(options?: UseAutoResizeOptions): (node: HTMLDivElement | null) => void;
-
-/**
- * Fetch-based GraphQL client for the EIDE platform API.
- *
- * Zero dependencies — uses the native Fetch API.
- */
-
-/** Error thrown when a platform API request fails. */
-declare class PlatformClientError extends Error {
-    status?: number | undefined;
-    response?: unknown | undefined;
-    constructor(message: string, status?: number | undefined, response?: unknown | undefined);
-}
-/**
- * Create a PlatformClient instance.
- *
- * @example
- * ```ts
- * const client = createPlatformClient({
- *   apiUrl: 'https://api.example.com/graphql',
- *   apiKey: 'sk_test_...',
- * });
- *
- * const { data } = await client.query(
- *   `query GetProduct($id: ID!) { product(id: $id) { title } }`,
- *   { id: '123' }
- * );
- * ```
- */
-declare function createPlatformClient(options: PlatformClientOptions): PlatformClient;
-
-/**
- * PostMessage protocol types between EIDE platform host and extension iframes.
- *
- * Inlined from the platform protocol to keep the SDK zero-dep.
- */
-/**
- * Messages sent FROM the platform host TO the iframe extension.
- */
-type HostToEditorMessage = {
-    type: 'init';
-    payload: {
-        values: Record<string, unknown>;
-        metadata?: Record<string, unknown>;
-        modelKey: string;
-        recordId: string;
-        naturalKey?: string;
-        versionId: string | null;
-        variantKey: string | null;
-        locale: string | null;
-        schema: unknown;
-        mode: 'edit' | 'readonly';
-        theme: 'light' | 'dark';
-        apiKey: string;
-        apiUrl: string;
-        connectionDomain?: string;
-        configMode?: 'editor' | 'sidebar';
-        selectedFieldKeys?: string[];
-        selectableFields?: Array<{
-            key: string;
-            label: string;
-            type: string;
-        }>;
-        localeContext?: {
-            currentLocale: string;
-            sourceLocale: string;
-            isTranslating: boolean;
-            locales: Array<{
-                code: string;
-                displayName: string;
-                isDefault: boolean;
-            }>;
-        };
-    };
-} | {
-    type: 'values-changed';
-    payload: {
-        values: Record<string, unknown>;
-        source: 'remote';
-    };
-} | {
-    type: 'variant-changed';
-    payload: {
-        variantKey: string;
-        values: Record<string, unknown>;
-    };
-} | {
-    type: 'save-result';
-    payload: {
-        success: boolean;
-        error?: string;
-        versionId?: string;
-    };
-} | {
-    type: 'publish-result';
-    payload: {
-        success: boolean;
-        error?: string;
-    };
-} | {
-    type: 'theme-changed';
-    payload: {
-        theme: 'light' | 'dark';
-    };
-} | {
-    type: 'selection-changed';
-    payload: {
-        selectedFieldKeys: string[];
-        fields: Array<{
-            key: string;
-            label: string;
-            type: string;
-        }>;
-    };
-} | {
-    type: 'locale-changed';
-    payload: {
-        currentLocale: string;
-        sourceLocale: string;
-        isTranslating: boolean;
-        locales: Array<{
-            code: string;
-            displayName: string;
-            isDefault: boolean;
-        }>;
-    };
-} | {
-    type: 'operation-result';
-    payload: {
-        requestId: string;
-        success: boolean;
-        result?: unknown;
-        error?: {
-            code: string;
-            message: string;
-        };
-    };
-};
-/**
- * Messages sent FROM the iframe extension TO the platform host.
- */
-type EditorToHostMessage = {
-    type: 'ready';
-    payload: Record<string, never>;
-} | {
-    type: 'update-values';
-    payload: {
-        values: Record<string, unknown>;
-    };
-} | {
-    type: 'update-field';
-    payload: {
-        path: string;
-        value: unknown;
-    };
-} | {
-    type: 'request-save';
-    payload: Record<string, never>;
-} | {
-    type: 'request-publish';
-    payload: Record<string, never>;
-} | {
-    type: 'resize';
-    payload: {
-        height: number;
-    };
-} | {
-    type: 'dirty';
-    payload: {
-        isDirty: boolean;
-    };
-} | {
-    type: 'request-navigate';
-    payload: {
-        path: string;
-    };
-} | {
-    type: 'request-operation';
-    payload: {
-        operationKey: string;
-        input?: Record<string, unknown>;
-        requestId: string;
-        /** Execution mode: 'sync' waits for completion, 'async' queues and returns. */
-        mode?: 'sync' | 'async';
-    };
-};
-
-/**
- * Runtime validation for postMessage payloads.
- */
-
-/** Validate an incoming message from a custom editor iframe (editor -> host). */
-declare function isValidEditorMessage(data: unknown): data is EditorToHostMessage;
-/** Validate an incoming message from the platform host (host -> editor). */
-declare function isValidHostMessage(data: unknown): data is HostToEditorMessage;
-
-/** Protocol version for compatibility checks. */
-declare const PROTOCOL_VERSION = "1.0";
-
-export { type EditorContextValue, type EditorInit, EditorProvider, type EditorProviderProps, type EditorToHostMessage, type GraphQLError, type GraphQLResponse, type HostToEditorMessage, type LocaleContext, PROTOCOL_VERSION, type PlatformClient, PlatformClientError, type PlatformClientOptions, type UseAutoResizeOptions, createPlatformClient, isValidEditorMessage, isValidHostMessage, useAutoResize, useEditor };
+export { EditorProvider } from './components/EditorProvider';
+export type { EditorProviderProps } from './components/EditorProvider';
+export { useEditor } from './hooks/useEditor';
+export { useAutoResize } from './hooks/useAutoResize';
+export type { UseAutoResizeOptions } from './hooks/useAutoResize';
+export { createPlatformClient, PlatformClientError, } from './client/platform-client';
+export type { EditorInit, EditorContextValue, LocaleContext, PlatformClient, PlatformClientOptions, GraphQLResponse, GraphQLError, } from './types';
+export type { HostToEditorMessage, EditorToHostMessage, } from './protocol/messages';
+export { isValidEditorMessage, isValidHostMessage, } from './protocol/validation';
+export { PROTOCOL_VERSION } from './protocol/constants';

package/dist/media/BlurhashCanvas.d.ts

@@ -0,0 +1,10 @@
+export interface BlurhashCanvasProps {
+    hash: string;
+    className?: string;
+}
+/**
+ * Decodes a BlurHash string to a 32×32 canvas. `blurhash` is an optional peer
+ * dependency loaded via dynamic import — if it isn't installed the canvas
+ * stays blank rather than throwing.
+ */
+export declare function BlurhashCanvas({ hash, className }: BlurhashCanvasProps): import("react/jsx-runtime").JSX.Element;