@visulima/dev-toolbar 1.0.0-alpha.12 → 1.0.0-alpha.14

package/dist/toolbar/utils/index.d.ts

@@ -1,12 +0,0 @@
-/**
- * Clamps a value between min and max.
- */
-export declare const clamp: (value: number, min: number, max: number) => number;
-/**
- * Returns true when the current browser is Safari.
- */
-export declare const checkIsSafari: () => boolean;
-/**
- * Converts a pixel string value to a number (e.g. "10px" becomes 10).
- */
-export declare const pixelToNumber: (value: string | number) => number;

package/dist/types/annotations.d.ts

@@ -1,156 +0,0 @@
-/**
- * Annotation intent — describes what the user wants to communicate.
- */
-export type AnnotationIntent = "approve" | "change" | "fix" | "question";
-/**
- * Annotation severity — how urgent or important the annotation is.
- */
-export type AnnotationSeverity = "blocking" | "important" | "suggestion";
-/**
- * Annotation status — lifecycle state.
- */
-export type AnnotationStatus = "acknowledged" | "dismissed" | "pending" | "resolved";
-/**
- * A single message in a conversation thread attached to an annotation.
- */
-export interface ThreadMessage {
-    /** Message text */
-    content: string;
-    /** Unique message identifier */
-    id?: string;
-    /** Who wrote it — e.g. "human", "agent", or a specific agent name */
-    role: string;
-    /** ISO 8601 timestamp */
-    timestamp: string;
-}
-/**
- * Bounding box of the annotated element relative to the viewport.
- */
-export interface BoundingBox {
-    height: number;
-    width: number;
-    x: number;
-    y: number;
-}
-/**
- * Detected framework component information.
- */
-export interface FrameworkContext {
-    /** Component name */
-    componentName?: string;
-    /** Full component stack (e.g. ["App", "Layout", "Header", "Button"]) */
-    componentStack?: string[];
-    /** Additional framework-specific data (e.g. props) */
-    data?: Record<string, unknown>;
-    /** Framework identifier (react, vue, svelte, etc.) */
-    framework: string;
-    /** Source file path */
-    sourceFile?: string;
-    /** Source line number */
-    sourceLine?: number;
-}
-/**
- * Captured accessibility attributes for an element.
- */
-export interface AccessibilityInfo {
-    /** aria-describedby content */
-    ariaDescribedBy?: string;
-    /** aria-label value */
-    ariaLabel?: string;
-    /** Whether the element is focusable */
-    focusable: boolean;
-    /** ARIA role (explicit or implicit) */
-    role?: string;
-    /** tabindex value */
-    tabindex?: number;
-}
-/**
- * A visual annotation placed on a page element during development.
- * Stored in `.devtoolbar/annotations.json`.
- */
-export interface Annotation {
-    /** Captured accessibility attributes */
-    accessibility?: AccessibilityInfo;
-    /** Element bounding box at annotation time */
-    boundingBox?: BoundingBox;
-    /** User feedback / description */
-    comment: string;
-    /** Key computed CSS properties for forensic context */
-    computedStyles?: string;
-    /** ISO 8601 creation timestamp */
-    createdAt: string;
-    /** CSS classes on the annotated element (module hashes cleaned) */
-    cssClasses?: string;
-    /** Bounding boxes for multi-select annotations */
-    elementBoundingBoxes?: BoundingBox[];
-    /** Human-readable element label (e.g. 'button "Submit"') */
-    elementLabel?: string;
-    /** CSS selector path to the element */
-    elementPath?: string;
-    /** HTML tag name of the annotated element */
-    elementTag: string;
-    /** Detected framework component context */
-    frameworkContext?: FrameworkContext;
-    /** Full DOM ancestry path (e.g. "body > main > article > p") */
-    fullPath?: string;
-    /** Unique identifier (crypto.randomUUID) */
-    id: string;
-    /** What the user wants — fix, change, question, or approve */
-    intent: AnnotationIntent;
-    /** Whether the element has fixed/sticky positioning */
-    isFixed?: boolean;
-    /** Whether this is a multi-select (drag) annotation */
-    isMultiSelect?: boolean;
-    /** Sibling elements for spatial context */
-    nearbyElements?: string;
-    /** Text near the annotated element for additional context */
-    nearbyText?: string;
-    /** ISO 8601 resolution timestamp */
-    resolvedAt?: string;
-    /** Who resolved it — "human" or "agent" (or a specific agent name) */
-    resolvedBy?: string;
-    /** Path to screenshot file relative to .devtoolbar/ (e.g. "screenshots/&lt;id>.png") */
-    screenshot?: string;
-    /** Text the user had selected when annotating */
-    selectedText?: string;
-    /** Severity level */
-    severity: AnnotationSeverity;
-    /** Source file location from data-vdt-source (file:line:col) */
-    source?: string;
-    /** Lifecycle status */
-    status: AnnotationStatus;
-    /** Conversation thread (human ↔ AI agent) */
-    thread?: ThreadMessage[];
-    /** ISO 8601 last-updated timestamp */
-    updatedAt: string;
-    /** Page URL where the annotation was created */
-    url: string;
-    /** Click X as percentage of viewport width (0-100) — survives resize */
-    x: number;
-    /**
-     * Click Y as absolute page position (pixels from document top) — survives scroll.
-     *  For fixed/sticky elements, Y is viewport-relative instead.
-     */
-    y: number;
-}
-/**
- * Data required to create a new annotation (server-generated fields omitted).
- */
-export type CreateAnnotationData = Omit<Annotation, "createdAt" | "id" | "resolvedAt" | "resolvedBy" | "status" | "thread" | "updatedAt">;
-/**
- * Fields that can be updated on an existing annotation.
- */
-export interface UpdateAnnotationData {
-    /** Updated comment text */
-    comment?: string;
-    /** Updated intent */
-    intent?: AnnotationIntent;
-    /** Who resolved the annotation */
-    resolvedBy?: string;
-    /** Updated severity */
-    severity?: AnnotationSeverity;
-    /** New status */
-    status?: AnnotationStatus;
-    /** Append a thread message */
-    threadMessage?: ThreadMessage;
-}

package/dist/types/app.d.ts

@@ -1,175 +0,0 @@
-import type { ComponentType } from "preact";
-import type { NotificationLevel } from "./toolbar.d.ts";
-/**
- * Server helpers available to apps
- */
-export interface ServerHelpers {
-    /**
-     * RPC client for calling server functions
-     */
-    rpc: {
-        [K in keyof ServerFunctions]: ServerFunctions[K];
-    };
-}
-/**
- * Props passed to app tooltip (hover mini-canvas) components.
- * Keep compact — tooltip components should be lightweight.
- */
-export interface AppTooltipProps {
-    /**
-     * Server helpers (RPC, etc.)
-     */
-    helpers: ServerHelpers;
-}
-/**
- * Event target for app communication
- */
-export interface ToolbarAppEventTarget extends EventTarget {
-    /**
-     * Dispatch a custom event
-     */
-    dispatchEvent: (event: Event) => boolean;
-}
-/**
- * App view configuration
- */
-export type AppView = {
-    /**
-     * Render app inline in shadow DOM (default)
-     */
-    type: "inline";
-} | {
-    /**
-     * URL to load in iframe
-     */
-    src: string;
-    /**
-     * Render app in iframe for isolation
-     */
-    type: "iframe";
-};
-/**
- * Props passed to Preact component apps
- */
-export interface AppComponentProps {
-    /**
-     * Event target for app communication
-     */
-    eventTarget: ToolbarAppEventTarget;
-    /**
-     * Server helpers (RPC, etc.)
-     */
-    helpers: ServerHelpers;
-}
-/**
- * Dev toolbar app definition
- */
-export interface DevToolbarApp {
-    /**
-     * Called before app is toggled off
-     * Return false to prevent closing
-     * @param canvas Shadow root of the app
-     * @returns Whether to allow closing
-     */
-    beforeTogglingOff?: (canvas: ShadowRoot) => boolean | Promise<boolean>;
-    /**
-     * Preact component for rendering (alternative to init)
-     * If provided, this will be used instead of init
-     */
-    component?: ComponentType<AppComponentProps>;
-    /**
-     * When true, this app is automatically activated when the toolbar opens for
-     * the first time (or when no other app has been activated yet).
-     * Only the first registered app with defaultOpen: true is used.
-     * @default false
-     */
-    defaultOpen?: boolean;
-    /**
-     * Called when the app is unregistered / removed from the toolbar.
-     * Use this for final cleanup (event listeners, timers, subscriptions).
-     * @param canvas Shadow root of the app
-     */
-    destroy?: (canvas: ShadowRoot) => Promise<void> | void;
-    /**
-     * Icon HTML string (SVG)
-     */
-    icon: string;
-    /**
-     * Unique identifier for the app
-     */
-    id: string;
-    /**
-     * Initialize the app when opened (vanilla JS/CSS/HTML)
-     * @param canvas Shadow root to render into
-     * @param eventTarget Event target for app communication
-     * @param helpers Server helpers (RPC, etc.)
-     */
-    init?: (canvas: ShadowRoot, eventTarget: ToolbarAppEventTarget, helpers: ServerHelpers) => void | Promise<void>;
-    /**
-     * Display name of the app
-     */
-    name: string;
-    /**
-     * Action button callback — called when the button is activated (active: false → true).
-     * When present, clicking the toolbar button will NOT open a panel.
-     * Instead the button toggles its active state and calls onClick (activate)
-     * or onDeactivate (deactivate).
-     */
-    onClick?: () => Promise<void> | void;
-    /**
-     * Called when the action button is deactivated (active: true → false).
-     * Only meaningful when onClick is also provided.
-     */
-    onDeactivate?: () => Promise<void> | void;
-    /**
-     * Optional hover tooltip component — renders a compact live preview when the
-     * user hovers over this app's button in the toolbar pill.
-     * The component should be small (≤280px wide) and self-contained.
-     * If omitted, hovering shows the native title tooltip only.
-     */
-    tooltip?: ComponentType<AppTooltipProps>;
-    /**
-     * App rendering mode
-     */
-    view?: AppView;
-}
-/**
- * Internal app state (extends DevToolbarApp)
- */
-export interface DevToolbarAppState extends DevToolbarApp {
-    /**
-     * Whether the app is currently active/open
-     */
-    active: boolean;
-    /**
-     * Whether this is a built-in app
-     */
-    builtIn: boolean;
-    /**
-     * Event target for this app
-     */
-    eventTarget: ToolbarAppEventTarget;
-    /**
-     * Notification state
-     */
-    notification: {
-        /**
-         * Notification level
-         */
-        level?: NotificationLevel;
-        /**
-         * Whether notification is active
-         */
-        state: boolean;
-    };
-    /**
-     * App initialization status
-     */
-    status: "ready" | "loading" | "pending" | "error";
-}
-/**
- * Placeholder for ServerFunctions (defined in rpc.ts)
- */
-export interface ServerFunctions {
-    [key: string]: (...args: any[]) => Promise<any>;
-}

package/dist/types/global-api.d.ts

@@ -1,91 +0,0 @@
-import type { DevToolbarApp } from "./app.d.ts";
-import type { DevToolbarHook } from "./hooks.d.ts";
-import type { ServerFunctions } from "./rpc.d.ts";
-import type { ToolbarSettings } from "./toolbar.d.ts";
-/**
- * Global DevTools API interface.
- * Exposed as window.__VISULIMA_DEVTOOLS__
- */
-interface VisulimaDevTools {
-    /**
-     * Clears notification for an app.
-     */
-    clearNotification: (appId: string) => void;
-    /**
-     * Closes the currently active app.
-     */
-    closeApp: () => Promise<void>;
-    /**
-     * Gets the currently active app ID.
-     */
-    getActiveApp: () => string | undefined;
-    /**
-     * Gets all registered apps.
-     */
-    getApps: () => DevToolbarApp[];
-    /**
-     * Gets current toolbar settings.
-     */
-    getSettings: () => ToolbarSettings;
-    /**
-     * Hides the toolbar.
-     */
-    hide: () => void;
-    /**
-     * Hook instance for event subscriptions.
-     */
-    hook: DevToolbarHook;
-    /**
-     * Shows a notification for an app.
-     */
-    notify: (appId: string, level: "info" | "warning" | "error") => void;
-    /**
-     * Opens an app by ID.
-     */
-    openApp: (appId: string) => Promise<void>;
-    /**
-     * Registers a custom app.
-     */
-    registerApp: (app: DevToolbarApp) => void;
-    /**
-     * RPC client for calling server functions.
-     */
-    rpc: ServerFunctions;
-    /**
-     * Directly sets the active state of an action button without invoking callbacks.
-     * Useful for deactivating a button from async work running outside the toolbar.
-     */
-    setAppActive: (appId: string, active: boolean) => void;
-    /**
-     * Shows the toolbar.
-     */
-    show: () => void;
-    /**
-     * Toggles toolbar visibility.
-     */
-    toggle: () => void;
-    /**
-     * Unregisters an app by ID.
-     */
-    unregisterApp: (appId: string) => void;
-    /**
-     * Updates toolbar settings.
-     */
-    updateSettings: (settings: Partial<ToolbarSettings>) => void;
-    /**
-     * Package version.
-     */
-    version: string;
-}
-/**
- * Global API declaration
- */
-declare global {
-    interface Window {
-        /**
-         * Visulima DevTools global API.
-         */
-        __VISULIMA_DEVTOOLS__?: VisulimaDevTools;
-    }
-}
-export type { VisulimaDevTools };

package/dist/types/hooks.d.ts

@@ -1,86 +0,0 @@
-import type { DevToolbarApp } from "./app.d.ts";
-import type { TimelineEvent } from "./timeline.d.ts";
-/**
- * Hook event definitions
- */
-interface HookEvents {
-    [key: string]: (...args: any[]) => void;
-    /**
-     * App error occurred.
-     * @param error Error object.
-     * @param appId Optional app ID where error occurred.
-     */
-    "app:error": (error: Error, appId?: string) => void;
-    /**
-     * DevTools closed.
-     */
-    "devtools:close": () => void;
-    /**
-     * DevTools initialized.
-     */
-    "devtools:init": () => void;
-    /**
-     * DevTools opened.
-     * @param appId ID of the opened app.
-     */
-    "devtools:open": (appId: string) => void;
-    /**
-     * Timeline event added.
-     * @param event Timeline event.
-     */
-    "timeline:event": (event: TimelineEvent) => void;
-}
-/**
- * Dev toolbar hook interface.
- * Exposed as window.__DEV_TOOLBAR_HOOK__
- */
-interface DevToolbarHook {
-    /**
-     * Adds a timeline event.
-     * @param groupId Timeline group ID.
-     * @param event Timeline event.
-     */
-    addTimelineEvent: (groupId: string, event: TimelineEvent) => void;
-    /**
-     * Emits an event.
-     * @param event Event name.
-     * @param args Event arguments.
-     */
-    emit: <T extends keyof HookEvents>(event: T, ...args: Parameters<HookEvents[T]>) => void;
-    /**
-     * Unsubscribes from an event.
-     * @param event Event name.
-     * @param handler Optional specific handler to remove.
-     */
-    off: <T extends keyof HookEvents>(event: T, handler?: HookEvents[T]) => void;
-    /**
-     * Subscribes to an event.
-     * @param event Event name.
-     * @param handler Event handler.
-     * @returns Unsubscribe function.
-     */
-    on: <T extends keyof HookEvents>(event: T, handler: HookEvents[T]) => () => void;
-    /**
-     * Subscribes to an event once.
-     * @param event Event name.
-     * @param handler Event handler.
-     */
-    once: <T extends keyof HookEvents>(event: T, handler: HookEvents[T]) => void;
-    /**
-     * Registers a custom app.
-     * @param app App definition.
-     */
-    registerApp: (app: DevToolbarApp) => void;
-}
-/**
- * Global hook declaration
- */
-declare global {
-    interface Window {
-        /**
-         * Dev toolbar hook for library integrations.
-         */
-        __DEV_TOOLBAR_HOOK__?: DevToolbarHook;
-    }
-}
-export type { DevToolbarHook, HookEvents };

package/dist/types/index.d.ts

@@ -1,13 +0,0 @@
-/**
- * Public type exports
- */
-export type { AccessibilityInfo, Annotation, AnnotationIntent, AnnotationSeverity, AnnotationStatus, BoundingBox, CreateAnnotationData, FrameworkContext, ThreadMessage, UpdateAnnotationData, } from "./annotations.d.ts";
-export type { AppView, DevToolbarApp, DevToolbarAppState, ServerFunctions, ServerHelpers, ToolbarAppEventTarget } from "./app.d.ts";
-export type { VisulimaDevTools } from "./global-api.d.ts";
-export type { DevToolbarHook, HookEvents } from "./hooks.d.ts";
-export type { ChannelFactory, MessageChannel, MessageChannelContext } from "./messaging.d.ts";
-export type { ClientRPCContext, ClientFunctions as RPCClientFunctions, ServerFunctions as RPCServerFunctions, ServerRPCContext } from "./rpc.d.ts";
-export type { TimelineEvent, TimelineEventLevel, TimelineGroup } from "./timeline.d.ts";
-export { DEFAULT_TIMELINE_GROUPS } from "./timeline.d.ts";
-export type { FrameState, NotificationLevel, PositionAnchor, ToolbarPlacement, ToolbarSettings } from "./toolbar.d.ts";
-export { DEFAULT_TOOLBAR_SETTINGS } from "./toolbar.d.ts";

package/dist/types/messaging.d.ts

@@ -1,43 +0,0 @@
-/**
- * Message channel interface for bidirectional communication
- */
-export interface MessageChannel<TEvents extends Record<string, (...args: any[]) => void>> {
-    /**
-     * Unsubscribe from an event
-     * @param event Event name
-     * @param handler Optional specific handler to remove
-     */
-    off: <K extends keyof TEvents>(event: K, handler?: TEvents[K]) => void;
-    /**
-     * Subscribe to an event
-     * @param event Event name
-     * @param handler Event handler
-     * @returns Unsubscribe function
-     */
-    on: <K extends keyof TEvents>(event: K, handler: TEvents[K]) => () => void;
-    /**
-     * Subscribe to an event once
-     * @param event Event name
-     * @param handler Event handler
-     */
-    once: <K extends keyof TEvents>(event: K, handler: TEvents[K]) => void;
-    /**
-     * Send a message/event
-     * @param event Event name
-     * @param data Event data
-     */
-    send: <K extends keyof TEvents>(event: K, ...args: Parameters<TEvents[K]>) => void;
-}
-/**
- * Channel factory function
- */
-export type ChannelFactory<TEvents extends Record<string, (...args: any[]) => void>> = () => MessageChannel<TEvents>;
-/**
- * Factory result providing a method to instantiate named message channels.
- */
-export interface MessageChannelContext<TEvents extends Record<string, (...args: any[]) => void>> {
-    /**
-     * Creates and returns a new channel instance.
-     */
-    createChannel: () => MessageChannel<TEvents>;
-}