@nicmeriano/spool-server 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,426 @@
+/**
+ * Author - simple for MVP, extensible for future collaboration
+ */
+interface Author {
+    id: string;
+    name: string;
+    avatar?: string;
+}
+/**
+ * Attachment for comments (images only for MVP)
+ */
+interface Attachment {
+    id: string;
+    filename: string;
+    mimeType: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp';
+    /** Size in bytes */
+    size: number;
+    /** Base64 data URL */
+    dataUrl: string;
+    createdAt: string;
+}
+/**
+ * Comment within an annotation thread
+ */
+interface Comment {
+    id: string;
+    content: string;
+    author: Author;
+    createdAt: string;
+    /** Image attachments (optional) */
+    attachments?: Attachment[];
+}
+/**
+ * Annotation status
+ * - open (blue bubble): Annotation created, Claude should address when submitted
+ * - in_progress (spinner): Claude is actively working on it
+ * - done (green bubble): Claude has implemented the change
+ */
+type AnnotationStatus = 'open' | 'in_progress' | 'done';
+/**
+ * Element information captured during annotation
+ */
+interface ElementInfo {
+    /** CSS selector that uniquely identifies the element */
+    selector: string;
+    /** HTML tag name (e.g., "button", "div") */
+    tagName: string;
+    /** CSS class names */
+    className: string;
+    /** Element ID if present */
+    id?: string;
+    /** Text content (truncated) */
+    textContent?: string;
+    /** React component name if available */
+    componentName?: string;
+    /** Source file path of the React component */
+    componentFile?: string;
+    /** Line number in the source file */
+    lineNumber?: number;
+    /** React component props (if available) */
+    props?: Record<string, unknown>;
+}
+/**
+ * Core annotation with thread support
+ */
+interface Annotation {
+    id: string;
+    /** Primary CSS selector to find element (for backward compatibility) */
+    selector: string;
+    /** Additional CSS selectors for multi-element annotations */
+    selectors?: string[];
+    /** Viewport-relative anchor point */
+    position: {
+        x: number;
+        y: number;
+    };
+    /** 3-state workflow status */
+    status: AnnotationStatus;
+    createdAt: string;
+    createdBy: Author;
+    /** When Claude completed it */
+    doneAt?: string;
+    /** Claude marks this when done */
+    doneBy?: Author;
+    /** Git commit SHA for this annotation's changes (enables per-annotation revert) */
+    commitSha?: string;
+    /** Thread of comments */
+    comments: Comment[];
+    /** Primary element metadata (for backward compatibility) */
+    element: ElementInfo;
+    /** Additional element metadata for multi-element annotations */
+    elements?: ElementInfo[];
+    /** True for page-level comments (not tied to any element) */
+    isPageLevel?: boolean;
+    /** Exact click position for bubble placement (viewport + scroll offset) */
+    clickPosition?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Default author for Claude
+ */
+declare const CLAUDE_AUTHOR: Author;
+declare const CLAUDE_MODEL = "claude-opus-4-5-20251101";
+/**
+ * Pending change status
+ */
+type PendingChangeStatus = 'pending' | 'in_progress' | 'done' | 'error';
+/**
+ * Base interface for all pending changes
+ */
+interface PendingChangeBase {
+    id: string;
+    selector: string;
+    element: ElementInfo;
+    status: PendingChangeStatus;
+    createdAt: string;
+    errorMessage?: string;
+}
+/**
+ * Variant data
+ */
+interface Variant {
+    html: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A pending variant change
+ */
+interface VariantChange extends PendingChangeBase {
+    type: 'variant';
+    prompt: string;
+    variants: Variant[];
+    selectedVariantIndex: number;
+    originalHtml: string;
+}
+/**
+ * A pending style change
+ */
+interface StyleChange extends PendingChangeBase {
+    type: 'style';
+    styles: Record<string, string>;
+    originalStyles: Record<string, string>;
+}
+/**
+ * A pending note change
+ */
+interface NoteChange extends PendingChangeBase {
+    type: 'note';
+    content: string;
+}
+/**
+ * Union type for all pending changes
+ */
+type PendingChange = VariantChange | StyleChange | NoteChange;
+/**
+ * Page-specific annotation data
+ */
+interface PageState {
+    url: string;
+    annotations: Annotation[];
+    pendingChanges?: PendingChange[];
+    lastModified: string;
+}
+/**
+ * Root state stored in .spool/state.json
+ */
+interface SpoolState {
+    appId: string;
+    status: 'idle' | 'generating';
+    currentTaskId: string | null;
+    pages: Record<string, PageState>;
+    /** Chat messages persisted across hot reloads */
+    chatMessages?: ChatMessageData[];
+    /** App URL reported by the Vite plugin (dynamic port resolution) */
+    appUrl?: string;
+}
+/**
+ * Task payload for addressing annotations
+ */
+interface TaskPayload {
+    action: 'address';
+    /** Optional: specific annotation IDs, or address all ready if omitted */
+    annotationIds?: string[];
+    /** Optional: additional user feedback/context */
+    feedback?: string;
+}
+/**
+ * Task result on completion
+ */
+interface TaskResult {
+    success: boolean;
+    annotationsAddressed: number;
+    message?: string;
+}
+/**
+ * Error details
+ */
+interface TaskError {
+    code: string;
+    message: string;
+}
+interface TaskSubmitMessage {
+    type: 'task:submit';
+    id: string;
+    payload: TaskPayload;
+}
+interface TaskCancelMessage {
+    type: 'task:cancel';
+    taskId: string;
+}
+interface AnnotationCreateMessage {
+    type: 'annotation:create';
+    url: string;
+    annotation: Annotation;
+}
+interface AnnotationUpdateMessage {
+    type: 'annotation:update';
+    id: string;
+    changes: Partial<Annotation>;
+}
+interface AnnotationDeleteMessage {
+    type: 'annotation:delete';
+    id: string;
+}
+interface AnnotationRevertMessage {
+    type: 'annotation:revert';
+    id: string;
+}
+interface ChangeAddMessage {
+    type: 'change:add';
+    url: string;
+    change: PendingChange;
+}
+interface ChangeRemoveMessage {
+    type: 'change:remove';
+    id: string;
+}
+interface ChangeApplyAllMessage {
+    type: 'change:apply_all';
+    url: string;
+}
+interface ChangeApplyMessage {
+    type: 'change:apply';
+    url: string;
+    changeId: string;
+}
+interface ChangeApplyDirectMessage {
+    type: 'change:apply_direct';
+    change: PendingChange;
+}
+interface VariantGenerateMessage {
+    type: 'variant:generate';
+    id: string;
+    payload: {
+        selector: string;
+        prompt: string;
+        elementHtml: string;
+        elementInfo: {
+            tagName: string;
+            componentName?: string;
+            componentFile?: string;
+        };
+    };
+}
+/**
+ * Element reference included in a chat message
+ */
+interface ChatElementReference {
+    id: string;
+    selector: string;
+    element: ElementInfo;
+}
+/**
+ * Chat message data for server-side persistence
+ */
+interface ChatMessageData {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    elementRefs?: ChatElementReference[];
+    timestamp: string;
+}
+/**
+ * A message in the chat conversation
+ */
+interface ChatMessageData {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    elementRefs?: ChatElementReference[];
+    timestamp: string;
+}
+interface ChatSendMessage {
+    type: 'chat:send';
+    id: string;
+    content: string;
+    elementRefs: ChatElementReference[];
+    history: ChatMessageData[];
+}
+interface ChatCancelMessage {
+    type: 'chat:cancel';
+    messageId: string;
+}
+interface ChatHistoryUpdateMessage {
+    type: 'chat:history:update';
+    messages: ChatMessageData[];
+}
+type ClientMessage = TaskSubmitMessage | TaskCancelMessage | AnnotationCreateMessage | AnnotationUpdateMessage | AnnotationDeleteMessage | AnnotationRevertMessage | ChangeAddMessage | ChangeRemoveMessage | ChangeApplyAllMessage | ChangeApplyMessage | ChangeApplyDirectMessage | VariantGenerateMessage | ChatSendMessage | ChatCancelMessage | ChatHistoryUpdateMessage;
+interface TaskAckMessage {
+    type: 'task:ack';
+    taskId: string;
+    status: 'started';
+}
+interface StreamTextMessage {
+    type: 'stream:text';
+    taskId: string;
+    content: string;
+    isPartial: boolean;
+}
+interface StreamToolCallMessage {
+    type: 'stream:tool_call';
+    taskId: string;
+    toolName: string;
+    toolInput: Record<string, unknown>;
+}
+interface StateUpdateMessage {
+    type: 'state:update';
+    taskId: string | null;
+    state: SpoolState;
+}
+interface TaskCompleteMessage {
+    type: 'task:complete';
+    taskId: string;
+    result: TaskResult;
+}
+interface TaskErrorMessage {
+    type: 'task:error';
+    taskId: string;
+    error: TaskError;
+}
+interface RevertResultMessage {
+    type: 'revert:result';
+    annotationId: string;
+    success: boolean;
+    error?: string;
+}
+interface AppUrlMessage {
+    type: 'app:url';
+    url: string;
+}
+interface ApplyProgressMessage {
+    type: 'apply:progress';
+    changeId: string;
+    status: 'in_progress' | 'done' | 'error';
+    error?: string;
+}
+interface ApplyCompleteMessage {
+    type: 'apply:complete';
+    success: boolean;
+    message?: string;
+}
+interface VariantResultMessage {
+    type: 'variant:result';
+    requestId: string;
+    variants: Variant[];
+    error?: string;
+}
+interface ChatAckMessage {
+    type: 'chat:ack';
+    messageId: string;
+}
+interface ChatStreamMessage {
+    type: 'chat:stream';
+    messageId: string;
+    content: string;
+    isPartial: boolean;
+}
+interface ChatToolCallMessage {
+    type: 'chat:tool_call';
+    messageId: string;
+    toolName: string;
+    toolInput: Record<string, unknown>;
+}
+interface ChatCompleteMessage {
+    type: 'chat:complete';
+    messageId: string;
+    success: boolean;
+    error?: string;
+}
+type ServerMessage = TaskAckMessage | StreamTextMessage | StreamToolCallMessage | StateUpdateMessage | TaskCompleteMessage | TaskErrorMessage | RevertResultMessage | ApplyProgressMessage | ApplyCompleteMessage | VariantResultMessage | ChatAckMessage | ChatStreamMessage | ChatToolCallMessage | ChatCompleteMessage | AppUrlMessage;
+/**
+ * Create an empty state structure
+ */
+declare function createEmptyState(appId: string): SpoolState;
+/**
+ * Get all annotations from state, optionally filtered by status
+ */
+declare function getAnnotationsFromState(state: SpoolState, filter?: {
+    status?: AnnotationStatus;
+}): Annotation[];
+/**
+ * Find an annotation by ID in state
+ */
+declare function findAnnotationInState(state: SpoolState, annotationId: string): {
+    annotation: Annotation;
+    pageUrl: string;
+} | null;
+/**
+ * Update an annotation in state (returns new state, immutable)
+ */
+declare function updateAnnotationInState(state: SpoolState, annotationId: string, updates: Partial<Annotation>): SpoolState;
+
+/**
+ * Options for starting the server
+ */
+interface ServerOptions {
+    /** Port to listen on (default: 3142) */
+    port?: number;
+    /** Working directory for state file and agent (default: process.cwd()) */
+    cwd?: string;
+}
+declare function startServer(options?: ServerOptions): Promise<void>;
+
+export { type Annotation, type AnnotationCreateMessage, type AnnotationDeleteMessage, type AnnotationRevertMessage, type AnnotationStatus, type AnnotationUpdateMessage, type AppUrlMessage, type ApplyCompleteMessage, type ApplyProgressMessage, type Attachment, type Author, CLAUDE_AUTHOR, CLAUDE_MODEL, type ChangeAddMessage, type ChangeApplyAllMessage, type ChangeApplyDirectMessage, type ChangeApplyMessage, type ChangeRemoveMessage, type ChatAckMessage, type ChatCancelMessage, type ChatCompleteMessage, type ChatElementReference, type ChatHistoryUpdateMessage, type ChatMessageData, type ChatSendMessage, type ChatStreamMessage, type ChatToolCallMessage, type ClientMessage, type Comment, type ElementInfo, type NoteChange, type PageState, type PendingChange, type PendingChangeBase, type PendingChangeStatus, type RevertResultMessage, type ServerMessage, type ServerOptions, type SpoolState, type StateUpdateMessage, type StreamTextMessage, type StreamToolCallMessage, type StyleChange, type TaskAckMessage, type TaskCancelMessage, type TaskCompleteMessage, type TaskError, type TaskErrorMessage, type TaskPayload, type TaskResult, type TaskSubmitMessage, type Variant, type VariantChange, type VariantGenerateMessage, type VariantResultMessage, createEmptyState, findAnnotationInState, getAnnotationsFromState, startServer, updateAnnotationInState };