@popmelt.com/core 0.14.1 → 0.15.0

package/dist/index.d.mts

@@ -1,35 +1,6 @@
 import * as react from 'react';
 import { PropsWithChildren } from 'react';
 
-/** Client-side envelope used for persisted and streaming bridge events. */
-type BridgeEvent = {
-    type: string;
-    data: Record<string, unknown>;
-    timestamp: number;
-};
-
-declare global {
-    interface Window {
-        __POPMELT_BRIDGE_URL__?: string;
-        __POPMELT_PROJECT_ID__?: string;
-    }
-}
-
-type PopmeltContextValue = {
-    isEnabled: boolean;
-};
-type PopmeltProviderProps = PropsWithChildren<{
-    enabled?: boolean;
-    bridgeUrl?: string;
-    /** Stable project id generated by the framework plugin/bridge startup. */
-    projectId?: string | null;
-    /** Framework router push — used for multi-page screenshot capture.
-     *  Pass your SPA router's navigate function (e.g. Next.js `router.push`). */
-    navigate?: (url: string) => void | Promise<unknown>;
-}>;
-declare function PopmeltProvider({ children, enabled, bridgeUrl, projectId: projectIdProp, navigate: navigateProp, }: PopmeltProviderProps): react.JSX.Element;
-declare function usePopmelt(): PopmeltContextValue;
-
 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];
@@ -56,6 +27,13 @@ declare const MIX_BLEND_STEPS: readonly ["normal", "multiply", "screen", "overla
 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;
 
+/** Client-side envelope used for persisted and streaming bridge events. */
+type BridgeEvent = {
+    type: string;
+    data: Record<string, unknown>;
+    timestamp: number;
+};
+
 type AnnotationLifecycleStatus = 'pending' | 'sending' | 'in_flight' | 'resolved' | 'needs_review' | 'dismissed' | 'waiting_input' | 'failed';
 type ScopeBreadth = 'instance' | 'pattern';
 type ScopeTarget = 'element' | 'component' | 'token';
@@ -84,6 +62,8 @@ type AnnotationRevealRecipe = {
 type ElementInfo = {
     selector: string;
     tagName: string;
+    /** Adapter-owned semantic name for a non-DOM subject. */
+    subjectLabel?: string;
     id?: string;
     className?: string;
     textContent?: string;
@@ -92,6 +72,11 @@ type 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;
@@ -194,6 +179,7 @@ type Annotation = {
     replyJobIds?: string[];
     threadId?: string;
     targetBindingId?: string;
+    target?: OpaqueTargetReference;
     pathname?: string;
     elements?: ElementInfo[];
     linkedSelector?: string;
@@ -218,11 +204,68 @@ type ClaudeResponse = {
     toolsUsed: string[];
 };
 
+type PopmeltSubjectBounds = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+type PopmeltSubject = {
+    key: string;
+    label: string;
+    bounds: PopmeltSubjectBounds;
+    context?: string;
+    data?: Record<string, string>;
+};
+type PopmeltSurfaceSnapshot = {
+    element: HTMLCanvasElement;
+    dataUrl: string;
+};
+/**
+ * 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;
+    hitTest(clientPoint: {
+        x: number;
+        y: number;
+    }): PopmeltSubject | null;
+    resolve(key: string): PopmeltSubject | null;
+    /** Optional bitmap capture for renderer surfaces that DOM cloning cannot read. */
+    captureSurfaces?(): readonly PopmeltSurfaceSnapshot[] | Promise<readonly PopmeltSurfaceSnapshot[]>;
+};
+
+declare global {
+    interface Window {
+        __POPMELT_BRIDGE_URL__?: string;
+        __POPMELT_PROJECT_ID__?: string;
+    }
+}
+
+type PopmeltContextValue = {
+    isEnabled: boolean;
+};
+type PopmeltProviderProps = PropsWithChildren<{
+    enabled?: boolean;
+    bridgeUrl?: string;
+    /** Stable project id generated by the framework plugin/bridge startup. */
+    projectId?: string | null;
+    /** Framework router push — used for multi-page screenshot capture.
+     *  Pass your SPA router's navigate function (e.g. Next.js `router.push`). */
+    navigate?: (url: string) => void | Promise<unknown>;
+    /** Optional non-DOM renderer adapters, such as Three.js scene subjects. */
+    subjectAdapters?: readonly PopmeltSubjectAdapter[];
+}>;
+declare function PopmeltProvider({ children, enabled, bridgeUrl, projectId: projectIdProp, navigate: navigateProp, subjectAdapters, }: PopmeltProviderProps): react.JSX.Element;
+declare function usePopmelt(): PopmeltContextValue;
+
 type AnnotationData = {
     id: string;
     type: string;
     instruction?: string;
     linkedSelector?: string;
+    target?: Annotation['target'];
     pathname?: string;
     elements: ElementInfo[];
     imageCount?: number;
@@ -247,4 +290,4 @@ type FeedbackData = {
     spacingTokenChanges?: SpacingTokenChange[];
 };
 
-export { type Annotation, type AnnotationType, type BridgeEvent, type BridgeStatus, type ClaudeResponse, type ElementInfo, type FeedbackData, type Point, PopmeltProvider, type StyleChange, type StyleModification, type ToolType, usePopmelt };
+export { type Annotation, type AnnotationType, type BridgeEvent, type BridgeStatus, type ClaudeResponse, type ElementInfo, type FeedbackData, type OpaqueTargetReference, type Point, PopmeltProvider, type PopmeltSubject, type PopmeltSubjectAdapter, type PopmeltSubjectBounds, type PopmeltSurfaceSnapshot, type StyleChange, type StyleModification, type ToolType, usePopmelt };