skema-core 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+# Skema
+
+A drawing-based website development tool that transforms how you annotate and communicate design changes.
+
+## Overview
+
+Skema is a React component that provides a tldraw-powered drawing overlay for annotating and manipulating DOM elements visually. It sits on top of your localhost website, allowing developers to annotate, draw, and select DOM elements directly on the live page.
+
+## Features
+
+- **Drawing Overlay**: Use tldraw's powerful drawing tools directly on your website
+- **DOM Picker**: Select any element on the page to capture its selector, bounding box, and context
+- **Annotation Export**: Export all annotations in a structured JSON format optimized for AI agents
+- **Non-Invasive**: Transparent overlay that doesn't interfere with your page when not in use
+
+## Installation
+
+### 1. Install the package
+
+```bash
+bun add skema-core
+# or
+npm install skema-core
+```
+
+### 2. Create the API route
+
+Run the init command to create the Gemini API route in your Next.js App Router project:
+
+```bash
+bunx skema init
+# or
+npx skema init
+```
+
+This creates `app/api/gemini/route.ts` (or `src/app/api/gemini/route.ts`) which handles annotation processing.
+
+### 3. Set up your Gemini API key
+
+Add your [Google AI API key](https://aistudio.google.com/apikey) to your `.env` file:
+
+```env
+GEMINI_API_KEY=your_api_key_here
+```
+
+### 4. Add Skema to your app
+
+Wrap your app with the Skema component (development only):
+
+```tsx
+import { Skema } from 'skema-core';
+
+export default function Page() {
+  return (
+    <>
+      {/* Your page content */}
+      <main>...</main>
+      
+      {/* Skema overlay - only in development */}
+      {process.env.NODE_ENV === 'development' && <Skema />}
+    </>
+  );
+}
+```
+
+That's it! Press **⌘⇧E** (Cmd+Shift+E) to toggle the Skema overlay.
+
+## Keyboard Shortcuts
+
+- **⌘⇧E** (Cmd+Shift+E / Ctrl+Shift+E): Toggle Skema overlay
+- **P**: Activate DOM Picker tool
+
+## Export Format
+
+When you export annotations, Skema generates a JSON structure like this:
+
+```json
+{
+  "version": "1.0.0",
+  "timestamp": "2024-01-24T12:00:00Z",
+  "viewport": {
+    "width": 1920,
+    "height": 1080,
+    "scrollX": 0,
+    "scrollY": 150
+  },
+  "pathname": "/",
+  "annotations": [
+    {
+      "type": "dom_selection",
+      "id": "dom-1706097600000-abc123",
+      "selector": ".hero-section > button.cta-primary",
+      "tagName": "button",
+      "elementPath": ".hero-section > button",
+      "text": "Get Started",
+      "boundingBox": { "x": 100, "y": 200, "width": 150, "height": 40 },
+      "timestamp": 1706097600000,
+      "pathname": "/"
+    }
+  ]
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Whether Skema overlay is enabled |
+| `onAnnotationsChange` | `(annotations: Annotation[]) => void` | - | Callback when annotations change |
+| `toggleShortcut` | `string` | `'mod+shift+e'` | Keyboard shortcut to toggle Skema |
+| `initialAnnotations` | `Annotation[]` | `[]` | Initial annotations to load |
+| `zIndex` | `number` | `99999` | Z-index for the overlay |
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+
+var ROUTE_CONTENT = `export { POST, DELETE } from 'skema-core/server';
+`;
+function init() {
+  const cwd = process.cwd();
+  const appDir = fs.existsSync(path.join(cwd, "app")) ? path.join(cwd, "app") : fs.existsSync(path.join(cwd, "src/app")) ? path.join(cwd, "src/app") : null;
+  if (!appDir) {
+    console.error("\u274C Could not find app/ or src/app/ directory.");
+    console.error("   Make sure you run this from a Next.js App Router project root.");
+    process.exit(1);
+  }
+  const apiDir = path.join(appDir, "api", "gemini");
+  const routePath = path.join(apiDir, "route.ts");
+  if (fs.existsSync(routePath)) {
+    console.log("\u2713 API route already exists at", routePath.replace(cwd, "."));
+    return;
+  }
+  if (!fs.existsSync(apiDir)) {
+    fs.mkdirSync(apiDir, { recursive: true });
+    console.log("\u2713 Created", apiDir.replace(cwd, "."));
+  }
+  fs.writeFileSync(routePath, ROUTE_CONTENT);
+  console.log("\u2713 Created", routePath.replace(cwd, "."));
+  console.log("");
+  console.log("\u{1F389} Skema is ready! The Gemini CLI integration is now set up.");
+  console.log("");
+  console.log("Usage:");
+  console.log("  1. Add <Skema /> to your page");
+  console.log("  2. Press Cmd+Shift+E to toggle the overlay");
+  console.log("  3. Annotate elements and Gemini CLI will make the changes");
+}
+init();

package/dist/index.d.mts

@@ -0,0 +1,356 @@
+import React from 'react';
+
+/**
+ * Represents a single DOM element in a selection
+ */
+interface DOMElement {
+    selector: string;
+    tagName: string;
+    elementPath: string;
+    text: string;
+    boundingBox: BoundingBox;
+    cssClasses?: string;
+    attributes?: Record<string, string>;
+}
+/**
+ * Represents a DOM element selection (can contain one or more elements)
+ */
+interface DOMSelection {
+    id: string;
+    selector: string;
+    tagName: string;
+    elementPath: string;
+    text: string;
+    boundingBox: BoundingBox;
+    timestamp: number;
+    pathname: string;
+    cssClasses?: string;
+    attributes?: Record<string, string>;
+    /** User annotation comment */
+    comment?: string;
+    /** Whether this is a multi-element selection */
+    isMultiSelect?: boolean;
+    /** Individual elements when this is a grouped selection */
+    elements?: DOMElement[];
+}
+/**
+ * Pending annotation state for the popup
+ */
+interface PendingAnnotation {
+    /** Screen X position (percentage of viewport width) */
+    x: number;
+    /** Screen Y position (pixels from top of document) */
+    y: number;
+    /** Y position relative to viewport (for popup positioning) */
+    clientY: number;
+    /** Element identifier string */
+    element: string;
+    /** CSS selector path */
+    elementPath: string;
+    /** Selected text content if any */
+    selectedText?: string;
+    /** Bounding box of selected element(s) */
+    boundingBox?: BoundingBox;
+    /** Whether this is a multi-element selection */
+    isMultiSelect?: boolean;
+    /** The DOM selection(s) being annotated */
+    selections?: DOMSelection[];
+    /** Type of annotation */
+    annotationType: 'dom_selection' | 'drawing';
+    /** Drawing shape IDs if annotating drawings */
+    shapeIds?: string[];
+}
+/**
+ * Bounding box for element positioning
+ */
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Viewport information for coordinate calculations
+ */
+interface ViewportInfo {
+    width: number;
+    height: number;
+    scrollX: number;
+    scrollY: number;
+}
+/**
+ * Computed styles for an element
+ */
+interface ElementStyles {
+    fontFamily?: string;
+    fontSize?: string;
+    fontWeight?: string;
+    lineHeight?: string;
+    letterSpacing?: string;
+    textAlign?: string;
+    color?: string;
+    padding?: string;
+    margin?: string;
+    gap?: string;
+    display?: string;
+    flexDirection?: string;
+    alignItems?: string;
+    justifyContent?: string;
+    backgroundColor?: string;
+    borderRadius?: string;
+    border?: string;
+    boxShadow?: string;
+    width?: string;
+    height?: string;
+    maxWidth?: string;
+}
+/**
+ * Nearby element with style context for AI
+ */
+interface NearbyElement {
+    selector: string;
+    tagName: string;
+    text?: string;
+    className?: string;
+    styles?: ElementStyles;
+    tailwindClasses?: string[];
+}
+/**
+ * Project-level style context
+ */
+interface ProjectStyleContext {
+    cssFramework?: 'tailwind' | 'bootstrap' | 'material-ui' | 'chakra' | 'vanilla' | 'css-modules' | 'styled-components' | 'unknown';
+    cssVariables?: Record<string, string>;
+    colorPalette?: string[];
+    baseFontFamily?: string;
+    baseFontSize?: string;
+}
+/**
+ * Drawing annotation from tldraw
+ */
+interface DrawingAnnotation {
+    id: string;
+    type: 'drawing';
+    tool: string;
+    shapes: unknown[];
+    boundingBox: BoundingBox;
+    relatedTo?: string;
+    timestamp: number;
+    /** User annotation comment describing what to build */
+    comment?: string;
+    /** SVG representation of the drawing for AI processing */
+    drawingSvg?: string;
+    /** Base64 PNG image of the drawing for vision AI */
+    drawingImage?: string;
+    /** Extracted text content from text shapes in the drawing */
+    extractedText?: string;
+    /** Grid configuration used for positioning reference */
+    gridConfig?: {
+        color: string;
+        size: number;
+        labels: boolean;
+    };
+    /** Viewport info for relative sizing context */
+    viewport?: ViewportInfo;
+    /** Project-level style context */
+    projectStyles?: ProjectStyleContext;
+    /** Nearby DOM elements that the drawing may relate to */
+    nearbyElements?: NearbyElement[];
+}
+/**
+ * Gesture action annotation
+ */
+interface GestureAnnotation {
+    id: string;
+    type: 'gesture';
+    gesture: 'scribble_delete' | 'circle' | 'rectangle' | 'arrow';
+    target?: string;
+    boundingBox: BoundingBox;
+    timestamp: number;
+}
+/**
+ * Union type for all annotation types
+ */
+type Annotation = {
+    type: 'dom_selection';
+} & DOMSelection | DrawingAnnotation | GestureAnnotation;
+/**
+ * Complete export format for annotations
+ */
+interface AnnotationExport {
+    version: string;
+    timestamp: string;
+    viewport: ViewportInfo;
+    pathname: string;
+    annotations: Annotation[];
+}
+/**
+ * Skema component props
+ */
+interface SkemaProps {
+    /** Whether Skema overlay is enabled */
+    enabled?: boolean;
+    /** Callback when annotations change */
+    onAnnotationsChange?: (annotations: Annotation[]) => void;
+    /** Callback when a single annotation is submitted - for real-time integrations like Gemini */
+    onAnnotationSubmit?: (annotation: Annotation, comment: string) => void;
+    /** Callback when an annotation is deleted - for reverting changes */
+    onAnnotationDelete?: (annotationId: string) => void;
+    /** Keyboard shortcut to toggle Skema (default: Cmd/Ctrl + Shift + E) */
+    toggleShortcut?: string;
+    /** Initial annotations to load */
+    initialAnnotations?: Annotation[];
+    /** Z-index for the overlay (default: 99999) */
+    zIndex?: number;
+}
+/**
+ * Skema mode - determines what tools are available
+ */
+type SkemaMode = 'select' | 'draw';
+
+/**
+ * Main Skema component - renders tldraw as a transparent overlay
+ */
+declare const Skema: React.FC<SkemaProps>;
+
+interface AnnotationPopupProps {
+    /** Element name/description to display in header */
+    element: string;
+    /** Optional selected/highlighted text */
+    selectedText?: string;
+    /** Placeholder text for the textarea */
+    placeholder?: string;
+    /** Initial value for textarea (for edit mode) */
+    initialValue?: string;
+    /** Label for submit button (default: "Add") */
+    submitLabel?: string;
+    /** Called when annotation is submitted with text */
+    onSubmit: (text: string) => void;
+    /** Called when popup is cancelled/dismissed */
+    onCancel: () => void;
+    /** Position styles (left, top) */
+    style?: React.CSSProperties;
+    /** Custom accent color (hex) */
+    accentColor?: string;
+    /** External exit state (parent controls exit animation) */
+    isExiting?: boolean;
+    /** Whether this is a multi-select annotation */
+    isMultiSelect?: boolean;
+}
+interface AnnotationPopupHandle {
+    /** Shake the popup (e.g., when user clicks outside) */
+    shake: () => void;
+}
+declare const AnnotationPopup: React.ForwardRefExoticComponent<AnnotationPopupProps & React.RefAttributes<AnnotationPopupHandle>>;
+
+/**
+ * Generates a unique CSS selector for an element
+ */
+declare function generateSelector(element: HTMLElement): string;
+/**
+ * Gets a readable path for an element (e.g., "article > section > p")
+ */
+declare function getElementPath(target: HTMLElement, maxDepth?: number): string;
+/**
+ * Identifies an element and returns a human-readable name
+ */
+declare function identifyElement(target: HTMLElement): string;
+/**
+ * Gets bounding box for an element in document coordinates (includes scroll offset)
+ */
+declare function getBoundingBox(element: HTMLElement): BoundingBox;
+/**
+ * Gets CSS class names from an element (cleaned of module hashes)
+ */
+declare function getElementClasses(target: HTMLElement): string;
+/**
+ * Creates a DOMSelection from an element
+ */
+declare function createDOMSelection(element: HTMLElement): DOMSelection;
+/**
+ * Checks if an element should be ignored for DOM picking
+ */
+declare function shouldIgnoreElement(element: HTMLElement): boolean;
+
+/**
+ * Gets current viewport information
+ */
+declare function getViewportInfo(): ViewportInfo;
+/**
+ * Converts viewport-relative coordinates to document coordinates
+ */
+declare function viewportToDocument(x: number, y: number, viewport?: ViewportInfo): {
+    x: number;
+    y: number;
+};
+/**
+ * Converts document coordinates to viewport-relative coordinates
+ */
+declare function documentToViewport(x: number, y: number, viewport?: ViewportInfo): {
+    x: number;
+    y: number;
+};
+/**
+ * Converts a bounding box from viewport to document coordinates
+ */
+declare function bboxViewportToDocument(bbox: BoundingBox, viewport?: ViewportInfo): BoundingBox;
+/**
+ * Converts a bounding box from document to viewport coordinates
+ */
+declare function bboxDocumentToViewport(bbox: BoundingBox, viewport?: ViewportInfo): BoundingBox;
+/**
+ * Checks if two bounding boxes intersect
+ */
+declare function bboxIntersects(a: BoundingBox, b: BoundingBox): boolean;
+/**
+ * Checks if point is inside bounding box
+ */
+declare function pointInBbox(x: number, y: number, bbox: BoundingBox): boolean;
+/**
+ * Gets the center point of a bounding box
+ */
+declare function bboxCenter(bbox: BoundingBox): {
+    x: number;
+    y: number;
+};
+/**
+ * Expands a bounding box by a padding amount
+ */
+declare function expandBbox(bbox: BoundingBox, padding: number): BoundingBox;
+/**
+ * Creates a bounding box from two points
+ */
+declare function bboxFromPoints(x1: number, y1: number, x2: number, y2: number): BoundingBox;
+
+/**
+ * Convert a Blob to a base64 string
+ */
+declare function blobToBase64(blob: Blob): Promise<string>;
+/**
+ * Add a labeled grid overlay to an SVG string
+ * Grid uses A/B/C column labels and 0/1/2 row numbers for positioning reference
+ * @param svgString - The SVG markup to add grid to
+ * @param opts - Grid options (color, cell size, whether to show labels)
+ * @returns SVG string with grid overlay added
+ */
+declare function addGridToSvg(svgString: string, opts?: {
+    color?: string;
+    size?: number;
+    labels?: boolean;
+}): string;
+/**
+ * Get the grid cell reference (e.g., "B2") for a given position
+ * @param x - X coordinate in pixels
+ * @param y - Y coordinate in pixels
+ * @param gridSize - Size of each grid cell (default 100px)
+ * @returns Grid cell reference string (e.g., "B2")
+ */
+declare function getGridCellReference(x: number, y: number, gridSize?: number): string;
+/**
+ * Extract text content from tldraw shapes
+ * @param shapes - Array of tldraw shapes
+ * @returns Combined text content from text and note shapes
+ */
+declare function extractTextFromShapes(shapes: unknown[]): string;
+
+export { type Annotation, type AnnotationExport, AnnotationPopup, type AnnotationPopupHandle, type AnnotationPopupProps, type BoundingBox, type DOMElement, type DOMSelection, type DrawingAnnotation, type ElementStyles, type GestureAnnotation, type NearbyElement, type PendingAnnotation, type ProjectStyleContext, Skema, type SkemaMode, type SkemaProps, type ViewportInfo, addGridToSvg, bboxCenter, bboxDocumentToViewport, bboxFromPoints, bboxIntersects, bboxViewportToDocument, blobToBase64, createDOMSelection, Skema as default, documentToViewport, expandBbox, extractTextFromShapes, generateSelector, getBoundingBox, getElementClasses, getElementPath, getGridCellReference, getViewportInfo, identifyElement, pointInBbox, shouldIgnoreElement, viewportToDocument };