@useclickly/react 1.0.3 → 1.1.0

package/dist/index.d.cts

@@ -1,4 +1,3 @@
-import * as react from 'react';
 import * as zustand from 'zustand';
 import { Annotation } from '@useclickly/core';
 export { Annotation, AnnotationKind, AnnotationStatus, ScreenshotData } from '@useclickly/core';
@@ -25,8 +24,17 @@ interface ClicklyProps {
  *
  * Renders a small floating button (FAB) in the bottom-right corner.
  * Click it (or press `⌘/Ctrl+Shift+F`) to open the full toolbar.
+ *
+ * Implementation note: we create a *separate* React root inside the shadow
+ * (via `createRoot(portal)`) rather than using `createPortal` from this
+ * component. Reason: React's event delegation listens at the React root
+ * container. With createPortal from the parent app tree, clicks bubbling
+ * out of the shadow are retargeted to `<clickly-root>`, which has no React
+ * fiber attached, so onClick handlers on toolbar buttons never fire. A
+ * dedicated root inside the shadow keeps the entire dispatch path inside
+ * the shadow boundary, which is what React's synthetic events need.
  */
-declare function Clickly({ className }?: ClicklyProps): react.ReactPortal | null;
+declare function Clickly({ className }?: ClicklyProps): null;
 
 interface AnnotationsStore {
     byId: Record<string, Annotation>;
@@ -37,6 +45,9 @@ interface AnnotationsStore {
     clear: () => void;
     /** Imperative read. Hooks should use `useAnnotationsList()` instead. */
     list: () => Annotation[];
+    /** Bulk-merge strokes loaded from IndexedDB on mount. Does NOT trigger
+     *  a save back — these annotations already exist on disk. */
+    hydrateStrokes: (strokesById: Record<string, NonNullable<Annotation["strokes"]>>) => void;
 }
 declare const useAnnotations: zustand.UseBoundStore<zustand.StoreApi<AnnotationsStore>>;
 /**
@@ -49,11 +60,29 @@ declare const useAnnotations: zustand.UseBoundStore<zustand.StoreApi<Annotations
 declare function useAnnotationsList(): Annotation[];
 
 type OutputDetail = "compact" | "standard" | "detailed" | "forensic";
+/**
+ * Theme: `"system"` follows the OS preference via `prefers-color-scheme`;
+ * `"light"` and `"dark"` lock the choice. ClicklyRoot resolves "system"
+ * to a concrete value at render time and sets `data-clickly-theme` on
+ * the shadow-root wrapper so the CSS in styles.ts can target it.
+ */
+type Theme = "system" | "light" | "dark";
 interface Settings {
     outputDetail: OutputDetail;
     copyOnAdd: boolean;
     showReactComponents: boolean;
     markerColor: string;
+    theme: Theme;
+    /** MCP sync — push new annotations to a running mcp-server's HTTP bridge. */
+    mcpEnabled: boolean;
+    /** HTTP-bridge URL the React side connects to (default localhost:4747). */
+    mcpEndpoint: string;
+    /**
+     * Session ID returned by POST /sessions. Persisted so a reload re-attaches
+     * to the same session and the agent keeps seeing one continuous stream
+     * of annotations from this page.
+     */
+    mcpSessionId: string | null;
 }
 interface SettingsStore extends Settings {
     set: (patch: Partial<Settings>) => void;
@@ -62,11 +91,6 @@ interface SettingsStore extends Settings {
 declare const DEFAULTS: Settings;
 declare const useSettings: zustand.UseBoundStore<zustand.StoreApi<SettingsStore>>;
 
-/**
- * Phase 5 placeholder formatter — Phase 9 adds the React + Source lines
- * when those fields are populated. Phase 8 replaces the whole thing with
- * a full AFS-compliant implementation.
- */
 declare function annotationsToMarkdown(annotations: Annotation[], detail?: OutputDetail): string;
 
 export { type AnnotationsStore, Clickly, type ClicklyProps, DEFAULTS as DEFAULT_SETTINGS, type OutputDetail, type Settings, type SettingsStore, annotationsToMarkdown, useAnnotations, useAnnotationsList, useSettings };

package/dist/index.d.ts

@@ -1,15 +1,96 @@
+import * as zustand from 'zustand';
+import { Annotation } from '@useclickly/core';
+export { Annotation, AnnotationKind, AnnotationStatus, ScreenshotData } from '@useclickly/core';
+
+interface ClicklyProps {
+    /** Custom class on the host element (for z-index / positioning overrides). */
+    className?: string;
+    /** Optional MCP server endpoint, e.g. "http://localhost:4747". */
+    endpoint?: string;
+    /** Join an existing MCP session by ID. */
+    sessionId?: string;
+    onAnnotationAdd?: (id: string) => void;
+    onAnnotationDelete?: (id: string) => void;
+    onAnnotationsClear?: () => void;
+    onCopy?: (markdown: string) => void;
+    onSessionCreated?: (sessionId: string) => void;
+}
 /**
- * @useclickly/react — public surface
+ * Mount once near the root of your React app. Dev-only by convention:
  *
- * The single export is `<Clickly />`. Stores and types are also
- * re-exported for advanced integrations.
+ * ```tsx
+ * {process.env.NODE_ENV === "development" && <Clickly />}
+ * ```
+ *
+ * Renders a small floating button (FAB) in the bottom-right corner.
+ * Click it (or press `⌘/Ctrl+Shift+F`) to open the full toolbar.
+ *
+ * Implementation note: we create a *separate* React root inside the shadow
+ * (via `createRoot(portal)`) rather than using `createPortal` from this
+ * component. Reason: React's event delegation listens at the React root
+ * container. With createPortal from the parent app tree, clicks bubbling
+ * out of the shadow are retargeted to `<clickly-root>`, which has no React
+ * fiber attached, so onClick handlers on toolbar buttons never fire. A
+ * dedicated root inside the shadow keeps the entire dispatch path inside
+ * the shadow boundary, which is what React's synthetic events need.
+ */
+declare function Clickly({ className }?: ClicklyProps): null;
+
+interface AnnotationsStore {
+    byId: Record<string, Annotation>;
+    order: string[];
+    add: (a: Annotation) => void;
+    remove: (id: string) => void;
+    update: (id: string, patch: Partial<Annotation>) => void;
+    clear: () => void;
+    /** Imperative read. Hooks should use `useAnnotationsList()` instead. */
+    list: () => Annotation[];
+    /** Bulk-merge strokes loaded from IndexedDB on mount. Does NOT trigger
+     *  a save back — these annotations already exist on disk. */
+    hydrateStrokes: (strokesById: Record<string, NonNullable<Annotation["strokes"]>>) => void;
+}
+declare const useAnnotations: zustand.UseBoundStore<zustand.StoreApi<AnnotationsStore>>;
+/**
+ * Subscribe to the annotation list with shallow equality — re-renders
+ * only when items add/remove/reorder/update. Always use this from
+ * component code; never call `useAnnotations(s => s.list())`, which
+ * returns a new array reference on every store change and infinite-loops
+ * `useSyncExternalStore`.
+ */
+declare function useAnnotationsList(): Annotation[];
+
+type OutputDetail = "compact" | "standard" | "detailed" | "forensic";
+/**
+ * Theme: `"system"` follows the OS preference via `prefers-color-scheme`;
+ * `"light"` and `"dark"` lock the choice. ClicklyRoot resolves "system"
+ * to a concrete value at render time and sets `data-clickly-theme` on
+ * the shadow-root wrapper so the CSS in styles.ts can target it.
  */
-export { Clickly } from "./Clickly";
-export type { ClicklyProps } from "./Clickly";
-export { useAnnotations, useAnnotationsList } from "./state/annotations";
-export { useSettings, DEFAULTS as DEFAULT_SETTINGS } from "./state/settings";
-export type { AnnotationsStore } from "./state/annotations";
-export type { Settings, SettingsStore, OutputDetail } from "./state/settings";
-export { annotationsToMarkdown } from "./output/markdown";
-export type { Annotation, AnnotationStatus, AnnotationKind, ScreenshotData, } from "@useclickly/core";
-//# sourceMappingURL=index.d.ts.map
+type Theme = "system" | "light" | "dark";
+interface Settings {
+    outputDetail: OutputDetail;
+    copyOnAdd: boolean;
+    showReactComponents: boolean;
+    markerColor: string;
+    theme: Theme;
+    /** MCP sync — push new annotations to a running mcp-server's HTTP bridge. */
+    mcpEnabled: boolean;
+    /** HTTP-bridge URL the React side connects to (default localhost:4747). */
+    mcpEndpoint: string;
+    /**
+     * Session ID returned by POST /sessions. Persisted so a reload re-attaches
+     * to the same session and the agent keeps seeing one continuous stream
+     * of annotations from this page.
+     */
+    mcpSessionId: string | null;
+}
+interface SettingsStore extends Settings {
+    set: (patch: Partial<Settings>) => void;
+    reset: () => void;
+}
+declare const DEFAULTS: Settings;
+declare const useSettings: zustand.UseBoundStore<zustand.StoreApi<SettingsStore>>;
+
+declare function annotationsToMarkdown(annotations: Annotation[], detail?: OutputDetail): string;
+
+export { type AnnotationsStore, Clickly, type ClicklyProps, DEFAULTS as DEFAULT_SETTINGS, type OutputDetail, type Settings, type SettingsStore, annotationsToMarkdown, useAnnotations, useAnnotationsList, useSettings };