blocfeed 0.1.0

package/dist/controller-5O3OHUFm.d.cts

@@ -0,0 +1,217 @@
+type MaybePromise<T> = T | Promise<T>;
+type ScreenshotMime = "image/png" | "image/jpeg";
+interface ImageAsset {
+    mime: ScreenshotMime;
+    /**
+     * A Data URL representation of the image (default capture output).
+     * Consumers that need a Blob can convert via `dataUrlToBlob`.
+     */
+    dataUrl: string;
+    width: number;
+    height: number;
+}
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface ElementDescriptor {
+    selector: string;
+    tagName: string;
+    id?: string;
+    className?: string;
+    textSnippet?: string;
+    /**
+     * Optional host-provided React/Next.js component name.
+     *
+     * Set by adding `data-blocfeed-component="MyComponent"` to a DOM element
+     * (usually the root element of a component).
+     */
+    componentName?: string;
+    /**
+     * Best-effort test identifier extracted from common attributes like:
+     * `data-testid`, `data-test-id`, `data-cy`, etc.
+     */
+    testId?: string;
+    rect: Rect;
+    pageRect: Rect;
+}
+interface CaptureDiagnostics {
+    startedAt: number;
+    finishedAt: number;
+    durationMs: number;
+    errors?: BlocFeedError[];
+}
+interface CaptureResult {
+    element?: ImageAsset;
+    fullPage?: ImageAsset;
+    diagnostics: CaptureDiagnostics;
+}
+interface BlocFeedError {
+    kind: "unknown" | "configuration" | "capture_failed" | "webhook_failed" | "callback_failed" | "aborted";
+    message: string;
+    detail?: Record<string, unknown>;
+}
+interface MetadataContext {
+    selection?: ElementDescriptor;
+    capture?: CaptureResult;
+}
+interface ScreenshotAdapterOptions {
+    mime: ScreenshotMime;
+    quality?: number;
+    pixelRatio: number;
+    /**
+     * Upper bound for width/height of the generated image.
+     */
+    maxDimension: number;
+    signal?: AbortSignal;
+}
+interface ScreenshotAdapter {
+    captureElement: (element: Element, options: ScreenshotAdapterOptions) => MaybePromise<ImageAsset>;
+    captureFullPage: (options: ScreenshotAdapterOptions) => MaybePromise<ImageAsset>;
+}
+interface CaptureConfig {
+    element?: boolean;
+    fullPage?: boolean;
+    mime?: ScreenshotMime;
+    quality?: number;
+    timeoutMs?: number;
+    /**
+     * Upper bound for width/height of generated screenshots.
+     * Prevents pathological memory use on very large pages.
+     */
+    maxDimension?: number;
+    /**
+     * Screenshot scale multiplier. Default is `window.devicePixelRatio` (capped).
+     */
+    pixelRatio?: number;
+    /**
+     * Override the screenshot capture implementation.
+     */
+    adapter?: ScreenshotAdapter;
+}
+interface PickerConfig {
+    /**
+     * CSS selectors to exclude from picking. Any element matching (or contained by)
+     * one of these selectors is not selectable.
+     */
+    ignoreSelectors?: readonly string[];
+    /**
+     * Optional predicate to allow/deny selection.
+     */
+    isSelectable?: (element: Element) => boolean;
+}
+interface MetadataConfig {
+    enabled?: boolean;
+    /**
+     * Hook to add host-specific metadata (e.g. user/org ids, route names).
+     * Must return JSON-serializable values.
+     */
+    enrich?: (context: MetadataContext) => MaybePromise<Record<string, unknown>>;
+}
+interface WebhookConfig {
+    url: string;
+    headers?: Record<string, string> | (() => MaybePromise<Record<string, string>>);
+    timeoutMs?: number;
+    /**
+     * Optional: set fetch credentials mode for the request.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * Basic retry behavior for transient failures (network errors, 5xx).
+     */
+    retry?: {
+        /**
+         * Total attempts including the initial request. Default: 2.
+         */
+        attempts?: number;
+        /**
+         * Base delay used for exponential backoff. Default: 500ms.
+         */
+        backoffMs?: number;
+    };
+}
+interface SubmitConfig {
+    /**
+     * Local delivery mode. If provided, called with the final payload.
+     */
+    onSubmit?: (payload: FeedbackPayload) => MaybePromise<void>;
+    /**
+     * Remote delivery mode. If provided, BlocFeed will POST the payload to the webhook.
+     */
+    webhook?: WebhookConfig;
+    /**
+     * If both `onSubmit` and `webhook` are present, require both to succeed.
+     * Default: false (success if at least one succeeds).
+     */
+    requireAll?: boolean;
+    /**
+     * Last chance to transform/redact the payload before delivery.
+     */
+    beforeSubmit?: (payload: FeedbackPayload) => MaybePromise<FeedbackPayload>;
+}
+interface BlocFeedConfig {
+    capture?: CaptureConfig;
+    picker?: PickerConfig;
+    metadata?: MetadataConfig;
+    submit?: SubmitConfig;
+    ui?: {
+        /**
+         * z-index for the widget overlay/panel.
+         */
+        zIndex?: number;
+    };
+}
+interface FeedbackPayload {
+    version: 1;
+    createdAt: string;
+    message: string;
+    selection?: ElementDescriptor;
+    screenshots?: CaptureResult;
+    metadata: Record<string, unknown>;
+}
+interface TransportResult {
+    ok: boolean;
+    error?: BlocFeedError;
+    status?: number;
+}
+interface SubmitResult {
+    ok: boolean;
+    callback?: TransportResult;
+    webhook?: TransportResult;
+}
+type SessionPhase = "idle" | "picking" | "review" | "capturing" | "submitting" | "success" | "error";
+interface BlocFeedState {
+    phase: SessionPhase;
+    selection?: ElementDescriptor;
+    capture?: CaptureResult;
+    lastSubmit?: SubmitResult;
+    lastError?: BlocFeedError;
+}
+
+type HoverInfo = {
+    element: Element;
+    rect: Rect;
+} | null;
+
+type StateListener = (state: BlocFeedState) => void;
+type HoverListener = (hover: HoverInfo) => void;
+interface BlocFeedController {
+    getState: () => BlocFeedState;
+    subscribe: (listener: StateListener) => () => void;
+    subscribeHover: (listener: HoverListener) => () => void;
+    start: () => void;
+    stop: () => void;
+    clearSelection: () => void;
+    setConfig: (nextConfig: BlocFeedConfig) => void;
+    submit: (message: string, options?: {
+        capture?: CaptureConfig;
+    }) => Promise<SubmitResult>;
+    /** Internal: used by UI to access the live element handle. */
+    __unsafeGetSelectedElement: () => Element | null;
+    destroy: () => void;
+}
+declare function createBlocFeedController(config: BlocFeedConfig): BlocFeedController;
+
+export { type BlocFeedConfig as B, type CaptureConfig as C, type ElementDescriptor as E, type FeedbackPayload as F, type HoverListener as H, type ImageAsset as I, type MaybePromise as M, type PickerConfig as P, type Rect as R, type SubmitResult as S, type TransportResult as T, type WebhookConfig as W, type BlocFeedState as a, type BlocFeedController as b, type BlocFeedError as c, type CaptureDiagnostics as d, type CaptureResult as e, type MetadataConfig as f, type MetadataContext as g, type ScreenshotAdapter as h, type ScreenshotAdapterOptions as i, type ScreenshotMime as j, type SessionPhase as k, type SubmitConfig as l, type StateListener as m, createBlocFeedController as n };

package/dist/controller-5O3OHUFm.d.ts

@@ -0,0 +1,217 @@
+type MaybePromise<T> = T | Promise<T>;
+type ScreenshotMime = "image/png" | "image/jpeg";
+interface ImageAsset {
+    mime: ScreenshotMime;
+    /**
+     * A Data URL representation of the image (default capture output).
+     * Consumers that need a Blob can convert via `dataUrlToBlob`.
+     */
+    dataUrl: string;
+    width: number;
+    height: number;
+}
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface ElementDescriptor {
+    selector: string;
+    tagName: string;
+    id?: string;
+    className?: string;
+    textSnippet?: string;
+    /**
+     * Optional host-provided React/Next.js component name.
+     *
+     * Set by adding `data-blocfeed-component="MyComponent"` to a DOM element
+     * (usually the root element of a component).
+     */
+    componentName?: string;
+    /**
+     * Best-effort test identifier extracted from common attributes like:
+     * `data-testid`, `data-test-id`, `data-cy`, etc.
+     */
+    testId?: string;
+    rect: Rect;
+    pageRect: Rect;
+}
+interface CaptureDiagnostics {
+    startedAt: number;
+    finishedAt: number;
+    durationMs: number;
+    errors?: BlocFeedError[];
+}
+interface CaptureResult {
+    element?: ImageAsset;
+    fullPage?: ImageAsset;
+    diagnostics: CaptureDiagnostics;
+}
+interface BlocFeedError {
+    kind: "unknown" | "configuration" | "capture_failed" | "webhook_failed" | "callback_failed" | "aborted";
+    message: string;
+    detail?: Record<string, unknown>;
+}
+interface MetadataContext {
+    selection?: ElementDescriptor;
+    capture?: CaptureResult;
+}
+interface ScreenshotAdapterOptions {
+    mime: ScreenshotMime;
+    quality?: number;
+    pixelRatio: number;
+    /**
+     * Upper bound for width/height of the generated image.
+     */
+    maxDimension: number;
+    signal?: AbortSignal;
+}
+interface ScreenshotAdapter {
+    captureElement: (element: Element, options: ScreenshotAdapterOptions) => MaybePromise<ImageAsset>;
+    captureFullPage: (options: ScreenshotAdapterOptions) => MaybePromise<ImageAsset>;
+}
+interface CaptureConfig {
+    element?: boolean;
+    fullPage?: boolean;
+    mime?: ScreenshotMime;
+    quality?: number;
+    timeoutMs?: number;
+    /**
+     * Upper bound for width/height of generated screenshots.
+     * Prevents pathological memory use on very large pages.
+     */
+    maxDimension?: number;
+    /**
+     * Screenshot scale multiplier. Default is `window.devicePixelRatio` (capped).
+     */
+    pixelRatio?: number;
+    /**
+     * Override the screenshot capture implementation.
+     */
+    adapter?: ScreenshotAdapter;
+}
+interface PickerConfig {
+    /**
+     * CSS selectors to exclude from picking. Any element matching (or contained by)
+     * one of these selectors is not selectable.
+     */
+    ignoreSelectors?: readonly string[];
+    /**
+     * Optional predicate to allow/deny selection.
+     */
+    isSelectable?: (element: Element) => boolean;
+}
+interface MetadataConfig {
+    enabled?: boolean;
+    /**
+     * Hook to add host-specific metadata (e.g. user/org ids, route names).
+     * Must return JSON-serializable values.
+     */
+    enrich?: (context: MetadataContext) => MaybePromise<Record<string, unknown>>;
+}
+interface WebhookConfig {
+    url: string;
+    headers?: Record<string, string> | (() => MaybePromise<Record<string, string>>);
+    timeoutMs?: number;
+    /**
+     * Optional: set fetch credentials mode for the request.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * Basic retry behavior for transient failures (network errors, 5xx).
+     */
+    retry?: {
+        /**
+         * Total attempts including the initial request. Default: 2.
+         */
+        attempts?: number;
+        /**
+         * Base delay used for exponential backoff. Default: 500ms.
+         */
+        backoffMs?: number;
+    };
+}
+interface SubmitConfig {
+    /**
+     * Local delivery mode. If provided, called with the final payload.
+     */
+    onSubmit?: (payload: FeedbackPayload) => MaybePromise<void>;
+    /**
+     * Remote delivery mode. If provided, BlocFeed will POST the payload to the webhook.
+     */
+    webhook?: WebhookConfig;
+    /**
+     * If both `onSubmit` and `webhook` are present, require both to succeed.
+     * Default: false (success if at least one succeeds).
+     */
+    requireAll?: boolean;
+    /**
+     * Last chance to transform/redact the payload before delivery.
+     */
+    beforeSubmit?: (payload: FeedbackPayload) => MaybePromise<FeedbackPayload>;
+}
+interface BlocFeedConfig {
+    capture?: CaptureConfig;
+    picker?: PickerConfig;
+    metadata?: MetadataConfig;
+    submit?: SubmitConfig;
+    ui?: {
+        /**
+         * z-index for the widget overlay/panel.
+         */
+        zIndex?: number;
+    };
+}
+interface FeedbackPayload {
+    version: 1;
+    createdAt: string;
+    message: string;
+    selection?: ElementDescriptor;
+    screenshots?: CaptureResult;
+    metadata: Record<string, unknown>;
+}
+interface TransportResult {
+    ok: boolean;
+    error?: BlocFeedError;
+    status?: number;
+}
+interface SubmitResult {
+    ok: boolean;
+    callback?: TransportResult;
+    webhook?: TransportResult;
+}
+type SessionPhase = "idle" | "picking" | "review" | "capturing" | "submitting" | "success" | "error";
+interface BlocFeedState {
+    phase: SessionPhase;
+    selection?: ElementDescriptor;
+    capture?: CaptureResult;
+    lastSubmit?: SubmitResult;
+    lastError?: BlocFeedError;
+}
+
+type HoverInfo = {
+    element: Element;
+    rect: Rect;
+} | null;
+
+type StateListener = (state: BlocFeedState) => void;
+type HoverListener = (hover: HoverInfo) => void;
+interface BlocFeedController {
+    getState: () => BlocFeedState;
+    subscribe: (listener: StateListener) => () => void;
+    subscribeHover: (listener: HoverListener) => () => void;
+    start: () => void;
+    stop: () => void;
+    clearSelection: () => void;
+    setConfig: (nextConfig: BlocFeedConfig) => void;
+    submit: (message: string, options?: {
+        capture?: CaptureConfig;
+    }) => Promise<SubmitResult>;
+    /** Internal: used by UI to access the live element handle. */
+    __unsafeGetSelectedElement: () => Element | null;
+    destroy: () => void;
+}
+declare function createBlocFeedController(config: BlocFeedConfig): BlocFeedController;
+
+export { type BlocFeedConfig as B, type CaptureConfig as C, type ElementDescriptor as E, type FeedbackPayload as F, type HoverListener as H, type ImageAsset as I, type MaybePromise as M, type PickerConfig as P, type Rect as R, type SubmitResult as S, type TransportResult as T, type WebhookConfig as W, type BlocFeedState as a, type BlocFeedController as b, type BlocFeedError as c, type CaptureDiagnostics as d, type CaptureResult as e, type MetadataConfig as f, type MetadataContext as g, type ScreenshotAdapter as h, type ScreenshotAdapterOptions as i, type ScreenshotMime as j, type SessionPhase as k, type SubmitConfig as l, type StateListener as m, createBlocFeedController as n };

package/dist/engine.cjs

@@ -0,0 +1 @@
+'use strict';var chunk52FWOTRN_cjs=require('./chunk-52FWOTRN.cjs');function d(n){let[r,o]=n.split(",",2);if(!r||!o)throw new Error("Invalid data URL");let c=/data:(.*?);base64/.exec(r)?.[1]||"application/octet-stream",t=atob(o),a=new Uint8Array(t.length);for(let e=0;e<t.length;e+=1)a[e]=t.charCodeAt(e);return new Blob([a],{type:c})}Object.defineProperty(exports,"collectMetadata",{enumerable:true,get:function(){return chunk52FWOTRN_cjs.e}});Object.defineProperty(exports,"createBlocFeedController",{enumerable:true,get:function(){return chunk52FWOTRN_cjs.f}});Object.defineProperty(exports,"createHtmlToImageAdapter",{enumerable:true,get:function(){return chunk52FWOTRN_cjs.c}});Object.defineProperty(exports,"runCapture",{enumerable:true,get:function(){return chunk52FWOTRN_cjs.d}});exports.dataUrlToBlob=d;

package/dist/engine.d.cts

@@ -0,0 +1,19 @@
+import { h as ScreenshotAdapter, C as CaptureConfig, e as CaptureResult, f as MetadataConfig, g as MetadataContext } from './controller-5O3OHUFm.cjs';
+export { B as BlocFeedConfig, b as BlocFeedController, c as BlocFeedError, a as BlocFeedState, E as ElementDescriptor, F as FeedbackPayload, H as HoverListener, I as ImageAsset, R as Rect, i as ScreenshotAdapterOptions, j as ScreenshotMime, k as SessionPhase, m as StateListener, S as SubmitResult, n as createBlocFeedController } from './controller-5O3OHUFm.cjs';
+
+declare function createHtmlToImageAdapter(): ScreenshotAdapter;
+
+declare function runCapture(params: {
+    selectionElement: Element | null;
+    capture: CaptureConfig | undefined;
+    signal?: AbortSignal;
+}): Promise<CaptureResult | undefined>;
+
+declare function collectMetadata(params: {
+    config: MetadataConfig | undefined;
+    context: MetadataContext;
+}): Promise<Record<string, unknown>>;
+
+declare function dataUrlToBlob(dataUrl: string): Blob;
+
+export { CaptureResult, ScreenshotAdapter, collectMetadata, createHtmlToImageAdapter, dataUrlToBlob, runCapture };

package/dist/engine.d.ts

@@ -0,0 +1,19 @@
+import { h as ScreenshotAdapter, C as CaptureConfig, e as CaptureResult, f as MetadataConfig, g as MetadataContext } from './controller-5O3OHUFm.js';
+export { B as BlocFeedConfig, b as BlocFeedController, c as BlocFeedError, a as BlocFeedState, E as ElementDescriptor, F as FeedbackPayload, H as HoverListener, I as ImageAsset, R as Rect, i as ScreenshotAdapterOptions, j as ScreenshotMime, k as SessionPhase, m as StateListener, S as SubmitResult, n as createBlocFeedController } from './controller-5O3OHUFm.js';
+
+declare function createHtmlToImageAdapter(): ScreenshotAdapter;
+
+declare function runCapture(params: {
+    selectionElement: Element | null;
+    capture: CaptureConfig | undefined;
+    signal?: AbortSignal;
+}): Promise<CaptureResult | undefined>;
+
+declare function collectMetadata(params: {
+    config: MetadataConfig | undefined;
+    context: MetadataContext;
+}): Promise<Record<string, unknown>>;
+
+declare function dataUrlToBlob(dataUrl: string): Blob;
+
+export { CaptureResult, ScreenshotAdapter, collectMetadata, createHtmlToImageAdapter, dataUrlToBlob, runCapture };

package/dist/engine.js

@@ -0,0 +1 @@
+export{e as collectMetadata,f as createBlocFeedController,c as createHtmlToImageAdapter,d as runCapture}from'./chunk-4EGJPVEG.js';function d(n){let[r,o]=n.split(",",2);if(!r||!o)throw new Error("Invalid data URL");let c=/data:(.*?);base64/.exec(r)?.[1]||"application/octet-stream",t=atob(o),a=new Uint8Array(t.length);for(let e=0;e<t.length;e+=1)a[e]=t.charCodeAt(e);return new Blob([a],{type:c})}export{d as dataUrlToBlob};