@popmelt.com/core 0.15.0 → 0.16.0

package/dist/image-adapter-D8L8QumX.d.mts

@@ -0,0 +1,426 @@
+declare const STICKER_COLOR_NAMES: readonly ["slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose"];
+type StickerColorName = (typeof STICKER_COLOR_NAMES)[number];
+declare const STICKER_COLOR_STEPS: readonly [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+type StickerColorStep = (typeof STICKER_COLOR_STEPS)[number];
+
+declare const STICKER_FAMILIES: readonly ["padding", "margin", "border", "radius", "stack", "grid", "text", "color", "transform", "opacity"];
+type StickerFamily = (typeof STICKER_FAMILIES)[number];
+declare const SPACING_STEPS: readonly [0, 1, 2, 3, 4, 6, 8, 10, 12, 16];
+declare const TRANSLATE_STEPS: readonly [-16, -12, -10, -8, -6, -4, -3, -2, -1, 0, 1, 2, 3, 4, 6, 8, 10, 12, 16];
+declare const BORDER_STEPS: readonly [0, 1, 2, 4, 8];
+declare const DIRECTION_STEPS: readonly ["vertical", "horizontal"];
+declare const ALIGN_STEPS: readonly ["stretch", "start", "center", "end", "baseline"];
+declare const JUSTIFY_STEPS: readonly ["start", "center", "end", "between", "around", "evenly"];
+declare const GRID_COUNT_STEPS: readonly [1, 2, 3, 4, 5, 6];
+declare const FONT_SIZE_STEPS: readonly ["xs", "sm", "base", "lg", "xl", "2xl", "3xl", "4xl"];
+declare const FONT_WEIGHT_STEPS: readonly [300, 400, 500, 600, 700, 800];
+declare const LINE_HEIGHT_STEPS: readonly ["none", "tight", "snug", "normal", "relaxed", "loose"];
+declare const LETTER_SPACING_STEPS: readonly ["tighter", "tight", "normal", "wide", "wider", "widest"];
+declare const TEXT_ALIGN_STEPS: readonly ["left", "center", "right", "justify"];
+declare const SCALE_STEPS: readonly [25, 50, 75, 90, 95, 100, 105, 110, 125, 150];
+declare const ROTATE_STEPS: readonly [-180, -90, -45, -25, -12, -6, -3, -2, -1, 0, 1, 2, 3, 6, 12, 25, 45, 90, 180];
+declare const OPACITY_STEPS: readonly [0, 5, 10, 20, 25, 30, 40, 50, 60, 70, 75, 80, 90, 95, 100];
+declare const MIX_BLEND_STEPS: readonly ["normal", "multiply", "screen", "overlay", "darken", "lighten", "color-dodge", "color-burn", "hard-light", "soft-light", "difference", "exclusion", "hue", "saturation", "color", "luminosity"];
+type StickerStep = (typeof SPACING_STEPS)[number] | (typeof BORDER_STEPS)[number] | (typeof DIRECTION_STEPS)[number] | (typeof ALIGN_STEPS)[number] | (typeof JUSTIFY_STEPS)[number] | (typeof GRID_COUNT_STEPS)[number] | (typeof FONT_SIZE_STEPS)[number] | (typeof FONT_WEIGHT_STEPS)[number] | (typeof LINE_HEIGHT_STEPS)[number] | (typeof LETTER_SPACING_STEPS)[number] | (typeof TEXT_ALIGN_STEPS)[number] | (typeof TRANSLATE_STEPS)[number] | (typeof SCALE_STEPS)[number] | (typeof ROTATE_STEPS)[number] | (typeof OPACITY_STEPS)[number] | (typeof MIX_BLEND_STEPS)[number] | StickerColorStep;
+type StickerSubproperty = 'all' | 'x' | 'y' | 'top' | 'right' | 'bottom' | 'left' | 'top-left' | 'top-right' | 'bottom-right' | 'bottom-left' | 'vertical' | 'horizontal' | 'direction' | 'gap' | 'align' | 'justify' | 'rows' | 'columns' | 'size' | 'weight' | 'line-height' | 'letter-spacing' | 'text-align' | 'color' | 'translate' | 'scale' | 'rotate' | 'opacity' | 'mix-blend' | StickerColorName;
+
+type AnnotationLifecycleStatus = 'pending' | 'sending' | 'in_flight' | 'resolved' | 'needs_review' | 'dismissed' | 'waiting_input' | 'failed';
+type ScopeBreadth = 'instance' | 'pattern';
+type ScopeTarget = 'element' | 'component' | 'token';
+type Scope = {
+    breadth: ScopeBreadth;
+    target: ScopeTarget;
+};
+declare const TOOL_TYPES: readonly ["inspector", "sticker", "model"];
+type ToolType = (typeof TOOL_TYPES)[number];
+declare const LEGACY_ANNOTATION_TYPES: readonly ["freehand", "line", "rectangle", "circle"];
+type LegacyAnnotationType = (typeof LEGACY_ANNOTATION_TYPES)[number];
+type AnnotationType = LegacyAnnotationType | 'text';
+type Point = {
+    x: number;
+    y: number;
+};
+type AnnotationRevealStep = {
+    triggerSelector: string;
+    targetSelector?: string;
+    label: string;
+};
+type AnnotationRevealRecipe = {
+    steps: AnnotationRevealStep[];
+    location: string[];
+};
+type ReactSourceLocation = {
+    fileName: string;
+    lineNumber: number;
+    columnNumber?: number;
+};
+/** Coordinates refer to the original image, not its responsive DOM rectangle. */
+type ImageObjectContext = {
+    src: string;
+    alt: string;
+    width: number;
+    height: number;
+    box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    normalizedBox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+};
+type SubjectFeedbackAttachment = {
+    /** Zero-based index in this annotation's transported images. */
+    cropImageIndex?: number;
+    warning?: string;
+};
+type ElementInfo = {
+    selector: string;
+    tagName: string;
+    /** Adapter-owned semantic name for a non-DOM subject. */
+    subjectLabel?: string;
+    id?: string;
+    className?: string;
+    textContent?: string;
+    dataAttributes?: Record<string, string>;
+    reactComponent?: string;
+    reactComponentPath?: string[];
+    reactSource?: ReactSourceLocation;
+    imageObject?: ImageObjectContext;
+    /** The real DOM surface, rather than the subject's hidden projection. */
+    sourceElement?: ElementInfo;
+    context?: string;
+    revealRecipe?: AnnotationRevealRecipe;
+};
+/** Renderer-owned identity for a target that does not exist as a DOM node. */
+type OpaqueTargetReference = {
+    adapter: string;
+    key: string;
+};
+type StyleChange = {
+    property: string;
+    original: string;
+    modified: string;
+    token?: string;
+    sticker?: {
+        family: StickerFamily;
+        subproperty: StickerSubproperty;
+        step: StickerStep;
+        axisSteps?: {
+            x: StickerStep;
+            y: StickerStep;
+        };
+    };
+};
+type StyleModification = {
+    selector: string;
+    durableSelector?: string;
+    element: ElementInfo;
+    changes: StyleChange[];
+    createdAt?: number;
+    annotationNumber?: number;
+    captured?: boolean;
+    pathname?: string;
+};
+type TextModification = {
+    selector: string;
+    durableSelector?: string;
+    element: ElementInfo;
+    textNodePath: number[];
+    original: string;
+    modified: string;
+    createdAt?: number;
+    annotationNumber?: number;
+    captured?: boolean;
+    pathname?: string;
+};
+type DomInsertionPlacement = 'before' | 'after';
+type DomModification = {
+    id: string;
+    operation: 'move' | 'copy';
+    selector: string;
+    durableSelector?: string;
+    element: ElementInfo;
+    sourceSelector?: string;
+    sourceDurableSelector?: string;
+    sourceElement?: ElementInfo;
+    originalParentSelector?: string;
+    originalParentDurableSelector?: string;
+    originalIndex?: number;
+    targetParentSelector: string;
+    targetParentDurableSelector?: string;
+    targetIndex: number;
+    referenceSelector?: string;
+    referenceDurableSelector?: string;
+    placement: DomInsertionPlacement;
+    captured?: boolean;
+    pathname?: string;
+};
+type SpacingElementEvidence = {
+    selector: string;
+    reactComponent?: string;
+    className: string;
+    property: string;
+    matchedClass?: string;
+    suggestedClass?: string;
+};
+type SpacingTokenChange = {
+    id: string;
+    tokenPath: string;
+    tokenName: string;
+    originalPx: number;
+    newPx: number;
+    captured?: boolean;
+    affectedElements: SpacingElementEvidence[];
+};
+type AnnotationAttachment = {
+    id: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    kind: 'svg' | 'text';
+};
+type Annotation = {
+    id: string;
+    type: AnnotationType;
+    points: Point[];
+    color: string;
+    strokeWidth: number;
+    text?: string;
+    fontSize?: number;
+    timestamp: number;
+    groupId?: string;
+    captured?: boolean;
+    status?: AnnotationLifecycleStatus;
+    question?: string;
+    resolutionSummary?: string;
+    scope?: Scope | null;
+    replyCount?: number;
+    replyJobIds?: string[];
+    threadId?: string;
+    targetBindingId?: string;
+    target?: OpaqueTargetReference;
+    pathname?: string;
+    elements?: ElementInfo[];
+    linkedSelector?: string;
+    linkedAnchor?: 'top-left' | 'bottom-left';
+    imageCount?: number;
+    attachments?: AnnotationAttachment[];
+};
+type BridgeStatus = {
+    ok: boolean;
+    activeJob: {
+        id: string;
+        status: string;
+    } | null;
+    queueDepth: number;
+    sessionId: string | null;
+};
+type ClaudeResponse = {
+    jobId: string;
+    sessionId?: string;
+    text: string;
+    success: boolean;
+    toolsUsed: string[];
+};
+
+type PopmeltSubjectBounds = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+type PopmeltSubject = {
+    key: string;
+    label: string;
+    bounds: PopmeltSubjectBounds;
+    /** Viewport bounds of the renderer surface that owns this subject. */
+    surfaceBounds?: PopmeltSubjectBounds;
+    context?: string;
+    data?: Record<string, string>;
+    /** Live owning surface; never serialized or included in model context. */
+    sourceElement?: Element;
+    imageObject?: ImageObjectContext;
+};
+type PopmeltSurfaceSnapshot = {
+    element: HTMLCanvasElement;
+    dataUrl: string;
+};
+type PopmeltSubjectCreationSession = {
+    key: string;
+    update(clientPoint: {
+        x: number;
+        y: number;
+    }): PopmeltSubject | null;
+    commit(): PopmeltSubject | null;
+    cancel(): void;
+};
+/**
+ * Minimal renderer boundary for non-DOM subjects. The adapter owns hit testing,
+ * durable keys, and viewport projection; Popmelt owns annotations and threads.
+ */
+type PopmeltSubjectAdapter = {
+    id: string;
+    /** Surface ownership; an explicit image adapter replaces Core's default. */
+    surfaceKind?: 'image';
+    hitTest(clientPoint: {
+        x: number;
+        y: number;
+    }): PopmeltSubject | null;
+    resolve(key: string): PopmeltSubject | null;
+    /** Optional clean subject crop, without Popmelt's overlay. */
+    captureSubject?(key: string): Blob | null | Promise<Blob | null>;
+    /** Optional bitmap capture for renderer surfaces that DOM cloning cannot read. */
+    captureSurfaces?(): readonly PopmeltSurfaceSnapshot[] | Promise<readonly PopmeltSurfaceSnapshot[]>;
+    /** Begin a context-aware subject-creation gesture at a viewport point. */
+    beginCreate?(clientPoint: {
+        x: number;
+        y: number;
+    }): PopmeltSubjectCreationSession | null;
+    /** Rename a subject without changing its durable key. */
+    renameSubject?(key: string, label: string): PopmeltSubject | null;
+    /** Replace a subject's viewport bounds, projected back into adapter space. */
+    updateSubjectBounds?(key: string, bounds: PopmeltSubjectBounds): PopmeltSubject | null;
+    /** Remove a user-created subject or hide an adapter-owned subject. */
+    removeSubject?(key: string): void;
+};
+
+/** Geometry is normalized against the loaded image, not its rendered size. */
+type ImageObjectBox = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+/** A provider's observation; no inference runtime is required by Core. */
+type ImageObjectObservation = {
+    label: string;
+    score: number;
+    box: ImageObjectBox;
+};
+
+type PersistedImageSubject = {
+    id: string;
+    label: string;
+    detectedLabel?: string;
+    score: number;
+    box: ImageObjectBox;
+    detectedBox?: ImageObjectBox;
+    origin: 'detected' | 'manual';
+    boundsOverridden?: boolean;
+};
+type PersistedImageSuppression = {
+    detectedLabel: string;
+    detectedBox: ImageObjectBox;
+};
+type PersistedImageAnalysis = {
+    schemaVersion: 1;
+    source: string;
+    imageHash: string;
+    inferenceKey: string;
+    dedupeKey: string;
+    subjects: readonly PersistedImageSubject[];
+    /** Inferred objects explicitly removed by the user for this image hash. */
+    suppressions?: readonly PersistedImageSuppression[];
+    updatedAt: number;
+};
+type ImageSubjectStore = {
+    load(key: string): PersistedImageAnalysis | null | Promise<PersistedImageAnalysis | null>;
+    save(key: string, analysis: PersistedImageAnalysis): void | Promise<void>;
+    remove?(key: string): void | Promise<void>;
+    /** Older content-hash versions retained before the active record changed. */
+    loadHistory?(key: string): readonly PersistedImageAnalysis[] | Promise<readonly PersistedImageAnalysis[]>;
+};
+type BrowserImageSubjectStoreOptions = {
+    /** Prefix used for browser storage entries. */
+    namespace?: string;
+    /** Override localStorage, primarily for embedded browsers and tests. */
+    storage?: Storage;
+};
+declare function createBrowserImageSubjectStore(options?: BrowserImageSubjectStoreOptions): ImageSubjectStore;
+declare function createMemoryImageSubjectStore(): ImageSubjectStore;
+
+type ImageContentHasher = (image: HTMLImageElement) => string | Promise<string>;
+/** Optional perception boundary. Core keeps media authoring usable without it. */
+type ImageRecognitionProvider = {
+    cacheKey: string;
+    configurationKey: string;
+    detect(image: HTMLImageElement): Promise<readonly ImageObjectObservation[]>;
+    reconcile(observations: readonly ImageObjectObservation[], previousSubjects: readonly PersistedImageSubject[], suppressions: readonly PersistedImageSuppression[]): readonly PersistedImageSubject[];
+    dispose?(): void | Promise<void>;
+};
+type ImageSubjectAdapterOptions = {
+    /** Optional perception; omit for manual-only image annotation. */
+    recognition?: ImageRecognitionProvider;
+    /** Restore saved subjects without hashing or running recognition. */
+    hydrateOnly?: boolean;
+    /** Images to analyze when the adapter starts. Defaults to every image. */
+    selector?: string;
+    /** Root to scan and observe. Defaults to document. */
+    root?: Document | Element;
+    /** Observe added images and src changes. Defaults to true. */
+    observe?: boolean;
+    /** Override the durable Core adapter id. */
+    id?: string;
+    /** Persist detections and user overrides. Omit to keep adapter state ephemeral. */
+    store?: ImageSubjectStore;
+    /** Override content hashing, primarily for authenticated or virtual images. */
+    imageHasher?: ImageContentHasher;
+    onError?: (error: unknown, image: HTMLImageElement) => void;
+};
+declare class ImageSubjectAdapter implements PopmeltSubjectAdapter {
+    private readonly options;
+    readonly surfaceKind: "image";
+    readonly id: string;
+    private readonly records;
+    private readonly imageKeys;
+    private readonly analyzedSources;
+    private readonly pending;
+    private readonly analysisMetadata;
+    private readonly suppressions;
+    private readonly writeChains;
+    private readonly pendingWrites;
+    private readonly observer;
+    private refreshQueued;
+    private destroyed;
+    private readyPromise;
+    private manualSequence;
+    constructor(options?: ImageSubjectAdapterOptions);
+    whenReady(): Promise<void>;
+    listSubjects(): readonly PopmeltSubject[];
+    refresh(): Promise<void>;
+    hitTest(clientPoint: {
+        x: number;
+        y: number;
+    }): PopmeltSubject | null;
+    resolve(key: string): PopmeltSubject | null;
+    private imageObjectContext;
+    captureSubject(key: string): Promise<Blob | null>;
+    beginCreate(clientPoint: {
+        x: number;
+        y: number;
+    }): PopmeltSubjectCreationSession | null;
+    renameSubject(key: string, label: string): PopmeltSubject | null;
+    updateSubjectBounds(key: string, bounds: PopmeltSubjectBounds): PopmeltSubject | null;
+    removeSubject(key: string): void;
+    destroy(): Promise<void>;
+    private queueRefresh;
+    private analyze;
+    private replaceImageRecords;
+    private imageIdentity;
+    private matchingImages;
+    private clampedImagePoint;
+    private newObjectId;
+    private persistImage;
+    private saveImage;
+    private imageSubjects;
+    private persistencePayload;
+    private removeImage;
+}
+declare function createImageSubjectAdapter(options?: ImageSubjectAdapterOptions): ImageSubjectAdapter;
+
+export { type Annotation as A, type BridgeStatus as B, type ClaudeResponse as C, type DomModification as D, type ElementInfo as E, type ImageRecognitionProvider as I, type OpaqueTargetReference as O, type PopmeltSubjectAdapter as P, type ReactSourceLocation as R, type SubjectFeedbackAttachment as S, type TextModification as T, type ImageSubjectAdapterOptions as a, type AnnotationAttachment as b, type StyleModification as c, type SpacingTokenChange as d, type AnnotationType as e, type ImageObjectContext as f, type Point as g, type PopmeltSubject as h, type PopmeltSubjectBounds as i, type PopmeltSubjectCreationSession as j, type PopmeltSurfaceSnapshot as k, type StyleChange as l, type ToolType as m, type ImageObjectBox as n, type BrowserImageSubjectStoreOptions as o, type ImageContentHasher as p, type ImageObjectObservation as q, ImageSubjectAdapter as r, type ImageSubjectStore as s, type PersistedImageAnalysis as t, type PersistedImageSubject as u, type PersistedImageSuppression as v, createBrowserImageSubjectStore as w, createImageSubjectAdapter as x, createMemoryImageSubjectStore as y };