use-vibes 0.2.7 → 0.4.0

package/README.md

@@ -1,304 +1,202 @@
-# useVibes - App Gen Anywhere
+# use-vibes
 
-[![npm version](https://img.shields.io/npm/v/use-vibes.svg)](https://www.npmjs.com/package/use-vibes)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-useVibes is a vanilla browser TypeScript module that transforms any DOM element into an AI-augmented micro-app using an HTML inject-first approach. It leverages the current page's HTML context to create a rich environment for dynamic content generation, powered by the call-ai library.
-
----
-
-## Overview
-
-- **Purpose**: Transform any DOM element into a self-contained, AI-driven micro-app by extracting and utilizing the page's inherent state.
-- **Core Features**:
-  - **Inject-First Approach**: Operates directly on the existing page by capturing document.body.innerHTML, the associated CSS, and a visual snapshot via html2canvas.
-  - **Context-Aware Transformation**: Uses the page's current state as a germ to generate dynamic content.
-  - **Promise-Based API**: Returns an app instance once the micro-app is injected.
-  - **Ongoing Chat Interface**: The app instance provides a chat interface to facilitate live, interactive sessions.
-
----
+A lightweight library that transforms any DOM element into an AI-powered micro-app.
 
 ## Installation
 
-### npm
-
-```bash
-npm install use-vibes
-```
-
-### yarn
-
-```bash
-yarn add use-vibes
-```
-
-### pnpm
-
 ```bash
 pnpm add use-vibes
 ```
 
-## Basic Usage
+### CSS Loading
 
-```javascript
-import { useVibes } from 'use-vibes';
+The ImgGen component requires CSS styles. You can include them in two ways:
 
-// Set the API key for call-ai (required)
-window.CALLAI_API_KEY = 'your-api-key-here';
+#### Option A: Explicit CSS link (recommended for production)
 
-// Get target element (can be a CSS selector string or DOM element)
-const target = document.getElementById('my-app-container');
+Add a CSS link tag to your HTML:
 
-// Apply useVibes to the target with a prompt
-useVibes(target, {
-  prompt: 'Create a beautiful hello world message with blue styling'
-}).then(app => {
-  console.log('App created:', app);
-}).catch(error => {
-  console.error('Error creating app:', error);
-});
+```html
+<link rel="stylesheet" href="/node_modules/use-vibes/dist/components/ImgGen.css" />
 ```
 
-### Return Value
-
-The function returns a Promise that resolves to an app instance with the following properties:
-
-- **container**: The DOM element into which the micro-app has been injected
-- **database**: An optional property for state management (may be undefined)
-
-## Browser Usage
-
-### IIFE Bundle
-
-If you want to use useVibes directly in the browser without a build step, you can use the IIFE bundle:
+Or for ESM/CDN environments like importmap scenarios:
 
 ```html
-<script src="https://unpkg.com/use-vibes@latest/lib/use-vibes.iife.js"></script>
-<script>
-  // Set API key
-  window.CALLAI_API_KEY = 'your-api-key-here';
-
-  // Now the global useVibes function is available
-  useVibes(document.getElementById('my-element'), {
-    prompt: 'Create a beautiful hello world message'
-  });
-</script>
+<link rel="stylesheet" href="https://esm.sh/use-vibes@0.4.0/components/ImgGen.css" />
 ```
 
-### Bookmarklet
-
-The useVibes package also includes a bookmarklet that allows you to test useVibes on any website:
-
-1. After installing the package, you'll find a `bookmarklet.html` file in the `dist` directory
-2. Open this file in your browser
-3. Drag the bookmarklet link to your bookmarks bar
-4. Navigate to any website, click the bookmarklet, then click on any element you want to enhance
-5. Enter your prompt when prompted
-
-You'll need to edit the bookmarklet to include your API key. See the HTML file for detailed instructions.
-
-### Example
-
-```javascript
-import { useVibes } from 'useVibes';
-
-useVibes("#app", { prompt: "create a todo list with emojis" })
-  .then((app) => {
-    console.log("Micro-app created successfully!");
+#### Option B: Automatic CSS loading (convenient for prototyping)
 
-    // Log the container element
-    console.log("Injected into:", app.container);
+Import the style-loader early in your application:
 
-    // If a database is later configured, it can be accessed via app.database
-    if (app.database) {
-      console.log("Database configured as:", app.database);
-    }
-
-    // Use the chat interface to send a message to the AI
-    app.chat.sendMessage("Hello, vibe!")
-      .then(() => console.log("Message sent successfully"))
-      .catch((err) => console.error("Error sending message:", err));
-  })
-  .catch((error) => {
-    console.error("Error during injection:", error);
-  });
+```js
+import 'use-vibes/style-loader'; // Auto-loads CSS when imported
 ```
 
----
-
-## Quick Start
-
-1. **Include the Module**: Import or bundle useVibes as an ESM module in your project.
-2. **Prepare Your HTML**: Ensure your page includes a target element (e.g., `<div id="app"></div>`) for the micro-app.
-3. **Initialize useVibes**: Call useVibes with your target and configuration. The module will capture the page's state, transform it based on your prompt, and inject the resulting micro-app into your target element.
-
----
-
-## Architecture Overview
-
-- **Purpose**: Build a lightweight, agentic editor that transforms any div into a dynamic micro-app. The module leverages a minimal core—using Fireproof for local persistence and callAi for AI interactions—while preserving the page's inherent structure and style.
-- **Architecture**:
-  - **HTML Injection-First**: The library is injected into a page and operates on the current DOM state.
-  - **Vanilla Browser Module**: Written in TypeScript and built as an ESM module suitable for distribution via esm.sh/jsr style.
-
----
+This approach is perfect for quick prototypes but for production sites, Option A gives you better control over CSS loading order and timing.
 
-## Testing
+## Components
 
-The useVibes library includes a comprehensive testing suite to ensure functionality across different browsers and use cases.
+### ImgGen
 
-### Browser Testing
+A React component for generating images with AI:
 
-Browser tests are implemented using Playwright and run on Chrome, Firefox, and WebKit (Safari). The test infrastructure uses a custom build process to create a test bundle with mocked dependencies, allowing tests to run without making actual API calls.
+```jsx
+import { ImgGen } from 'use-vibes';
 
-```bash
-# Run browser tests
-pnpm test:browser
+function MyComponent() {
+  return (
+    <div>
+      <ImgGen prompt="A sunset over mountains" />
+    </div>
+  );
+}
 ```
 
-This command will:
-1. Build a test-specific bundle using the `build-browser-test.js` script
-2. Set up browser mocks for all three browser engines
-3. Run the Playwright tests with proper reporting
-
-### Unit Testing
+#### Props
 
-```bash
-# Run unit tests
-pnpm test:unit
-```
+- `prompt`: Text prompt for image generation (required unless `_id` is provided)
+- `_id`: Document ID to load a specific image instead of generating a new one
+- `options`: Options for image generation (optional)
+- `className`: CSS class name for the image element (optional)
+- `alt`: Alt text for the image (defaults to prompt)
+- `overlay`: Whether to show overlay controls and info button (default: `true`)
+- `database`: Database name or instance to use for storing images (default: `'ImgGen'`)
+- `onLoad`: Callback when image load completes successfully
+- `onError`: Callback when image load fails, receives the error as parameter
+- `onDelete`: Callback when an image is deleted, receives the document ID
+- `onPromptEdit`: Callback when the prompt is edited, receives document ID and new prompt
+- `editedPrompt`: Custom prompt text to use for regeneration (overrides document prompt)
+- `generationId`: Optional ID to trigger regeneration of existing images
+- `classes`: Object containing custom CSS classes for styling component parts (see Styling section)
 
-### Linting and TypeScript Validation
+#### Features
 
-```bash
-# Check types
-pnpm typecheck
+##### Overlay Controls
 
-# Run linter
-pnpm lint
+By default, the ImgGen component shows an info button in the bottom-left corner. Clicking it reveals an overlay with:
 
-# Run linter with auto-fixes
-pnpm lint --fix
-```
+- The prompt text (double-clickable to edit)
+- Version navigation buttons (if multiple versions exist)
+- Refresh button to generate a new version
+- Delete button
 
-## Directory Structure
+Setting `overlay={false}` will hide all these controls, showing only the image.
 
-- **src/**: Contains the source code for the useVibes library.
-- **fixtures/**: A collection of HTML challenge files. These fixtures serve as test cases for validating that useVibes can handle a variety of page structures.
-- **tests/**: Test suites including browser and unit tests.
-  - **browser/**: Playwright browser tests with mock implementations.
-  - **unit/**: Unit tests for core functionality.
-- **scripts/**: Build scripts and utilities.
-- **docs/**: Documentation directory which includes:
-  - **llms.txt**: A text file specifying the details and technical context for LLM integrations and other project guidelines.
+##### Prompt Editing
 
----
+Double-click the prompt text in the overlay to edit it. Press Enter to submit changes and regenerate the image with the new prompt.
 
-## Prerequisites
+##### Image Regeneration
 
-- Node.js (v14 or higher)
-- pnpm package manager
-- A modern web browser for testing
+When regenerating images, the component will:
+- Use the edited prompt if one has been provided (via `editedPrompt` prop, `onPromptEdit` callback, or direct editing in the UI)
+- Fall back to the original prompt from the document if no edits were made
+- Preserve versions under the same document ID to maintain history
+- Add the new image as a version to the existing document instead of creating a new one
 
----
+This allows for iterative refinement of images while maintaining version history.
 
-## Getting Started
+#### Styling
 
-1. **Clone the Repository**:
-   ```
-   git clone https://github.com/fireproof-storage/use-vibes.git
-   cd use-vibes
-   ```
+The ImgGen component uses CSS custom properties (variables) for styling, making it easy to customize the appearance while maintaining consistency. There are two primary ways to customize styling:
 
-2. **Install Dependencies**:
-   ```
-   pnpm install
-   ```
+##### 1. CSS Variables
 
-3. **Build the Project**:
-   The project is configured to compile the TypeScript source into an ESM module suitable for browser use.
-   ```
-   pnpm run build
-   ```
+Override the default styles by setting CSS custom properties in your CSS:
 
----
+```css
+/* In your CSS file */
+:root {
+  --imggen-text-color: #222;
+  --imggen-overlay-bg: rgba(245, 245, 245, 0.85);
+  --imggen-accent: #0088ff;
+  --imggen-border-radius: 4px;
+}
 
-## Testing
-
-### Fixture Loading Test
-
-Ensure that HTML fixtures load correctly:
-1. Open a test HTML file from the fixtures/ directory in your browser.
-2. Verify that the page loads as expected without any library interference.
-
-### Library Injection Test
-
-Verify that useVibes loads and executes a basic operation:
-1. Create a simple test page that includes the built useVibes module.
-2. Use the library to inject a "hello world" string into a target element. For example:
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>useVibes Test</title>
-  <!-- Direct ESM import from source during development -->
-  <script type="module">
-    // Import directly from source files
-    import useVibe from './src/index.js';
-  </script>
-</head>
-<body>
-  <div id="vibe-target"></div>
-  <script type="module">
-    // Direct import
-    import useVibe from './src/index.js';
-    
-    // Create a new vibe
-    const vibe = useVibe('HelloWorld');
-    
-    // Basic injection test
-    document.querySelector("#vibe-target").innerHTML = vibe.describe();
-  </script>
-</body>
-</html>
+/* Dark theme example */
+.dark-theme {
+  --imggen-text-color: #f0f0f0;
+  --imggen-overlay-bg: rgba(25, 25, 25, 0.85);
+  --imggen-accent: #66b2ff;
+}
 ```
 
-3. Open this page in your browser and confirm that "hello world" is injected into the target element.
+##### 2. Custom Classes
+
+For more granular control, provide a `classes` object with custom CSS classes for specific component parts:
+
+```jsx
+<ImgGen
+  prompt="A futuristic cityscape"
+  classes={{
+    root: 'my-custom-container',
+    image: 'rounded-xl shadow-lg',
+    overlay: 'bg-slate-800/70 text-white',
+    progress: 'h-2 bg-green-500',
+    button: 'hover:bg-blue-600',
+  }}
+/>
+```
 
----
+The component uses these classes in addition to the default ones, allowing you to extend or override styles as needed.
+
+##### Available CSS Variables
+
+| Variable                 | Default                    | Description                       |
+| ------------------------ | -------------------------- | --------------------------------- |
+| `--imggen-text-color`    | `#333`                     | Main text color                   |
+| `--imggen-background`    | `#333333`                  | Background color for placeholder  |
+| `--imggen-overlay-bg`    | `rgba(255, 255, 255, 0.5)` | Overlay panel background          |
+| `--imggen-accent`        | `#0066cc`                  | Accent color (progress bar, etc.) |
+| `--imggen-error-text`    | `#ff6666`                  | Error message text color          |
+| `--imggen-border-radius` | `8px`                      | Border radius for containers      |
+| `--imggen-button-bg`     | `rgba(255, 255, 255, 0.7)` | Button background color           |
+| `--imggen-font-size`     | `14px`                     | Default font size                 |
+
+##### Available Class Slots
+
+| Class Property  | Description                      |
+| --------------- | -------------------------------- |
+| `root`          | Main container element           |
+| `image`         | The image element                |
+| `container`     | Container for image and controls |
+| `overlay`       | Overlay panel with controls      |
+| `progress`      | Progress indicator               |
+| `placeholder`   | Placeholder shown during loading |
+| `error`         | Error message container          |
+| `controls`      | Control buttons container        |
+| `button`        | Individual buttons               |
+| `prompt`        | Prompt text/input container      |
+| `deleteOverlay` | Delete confirmation dialog       |
+
+## Development
 
-## Build and Deployment
+```bash
+# Install dependencies
+pnpm install
 
-- **Buildless ESM Approach**: This project uses a modern buildless ESM approach. TypeScript source files are directly imported during development, and TypeScript compiler is only used for type checking and generating type definitions. This avoids complex bundling processes while leveraging the native ESM support in modern browsers and Node.js environments.
+# Build the library
+pnpm build
 
-  ```json
-  "scripts": {
-    "build": "tsc",
-    "typecheck": "tsc --noEmit"
-  }
-  ```
+# Run tests
+pnpm test
+```
 
-- **Deployment**: Direct imports from source files are supported during development. For production, TypeScript is compiled to JavaScript while maintaining ESM imports. The package can be published to npm or JSR for easy consumption via ESM imports.
+### Testing Notes
 
----
+When writing tests for components that use the image generation functionality:
 
-## Next Steps
+- Use the provided mock implementations for `call-ai` and `use-fireproof`
+- Wrap React state updates in `act()` to prevent test warnings
+- Use `vi.useFakeTimers()` and `vi.advanceTimersByTime()` to control async behavior
+- Be aware that `imageGen` API calls need to be properly mocked
 
-1. **Vibe Check**: After completing the initial tests, review the results and gather feedback.
-2. **Iterate**: Use feedback to refine functionality and integration.
-3. **Expand**: Continue to develop additional features and tests, integrating further capabilities such as Fireproof, callAi, and more advanced micro-app interactions.
+### Browser Compatibility
 
----
+This library is compatible with all modern browsers that support React 18+ and ES6 features.
 
 ## License
 
-This project is open source. See the LICENSE file for details.
-
----
-
-## Contact
-
-For questions, feedback, or contributions, please open an issue on the repository or contact the maintainers.
+MIT

package/package.json

@@ -1,19 +1,27 @@
 {
   "name": "use-vibes",
-  "version": "0.2.7",
+  "version": "0.4.0",
   "type": "module",
   "description": "Transform any DOM element into an AI-powered micro-app",
   "main": "dist/index.js",
-  "browser": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
+      "require": "./dist/index.js"
+    },
+    "./style-loader": {
+      "types": "./dist/style-loader.d.ts",
+      "import": "./dist/style-loader.js",
+      "require": "./dist/style-loader.js"
+    },
+    "./components/ImgGen.css": "./dist/components/ImgGen.css"
   },
+  "files": [
+    "dist"
+  ],
   "keywords": [
     "ai",
     "dom",
@@ -25,61 +33,44 @@
   ],
   "author": "",
   "license": "MIT",
-  "files": [
-    "dist"
-  ],
+  "dependencies": {
+    "call-ai": "^0.10.1",
+    "use-fireproof": "^0.20.4",
+    "uuid": "^11.1.0"
+  },
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+  },
   "devDependencies": {
-    "@playwright/test": "^1.41.2",
-    "@rollup/plugin-commonjs": "^28.0.3",
-    "@rollup/plugin-node-resolve": "^16.0.1",
-    "@rollup/plugin-typescript": "^12.1.2",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",
-    "@types/jsdom": "^21.1.7",
-    "@types/node": "^20.11.19",
-    "@types/react": "^18.2.0",
-    "@typescript-eslint/eslint-plugin": "^7.0.1",
-    "@typescript-eslint/parser": "^7.0.1",
-    "esbuild": "^0.25.1",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.2",
+    "@typescript-eslint/eslint-plugin": "^8.32.1",
+    "@typescript-eslint/parser": "^8.32.1",
+    "@vitejs/plugin-react": "^4.4.1",
     "eslint": "^8.56.0",
-    "eslint-config-prettier": "^10.1.1",
-    "eslint-plugin-prettier": "^5.2.5",
-    "jsdom": "^26.0.0",
-    "playwright": "^1.41.2",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-react": "^7.37.5",
+    "jsdom": "^26.1.0",
     "prettier": "^3.5.3",
-    "react": "^19.1.0",
-    "rollup": "^4.38.0",
-    "rollup-plugin-terser": "^7.0.2",
-    "terser": "^5.39.0",
+    "react-dom": "^19.1.0",
+    "rimraf": "^5.0.5",
     "typescript": "^5.3.3",
-    "vite": "^5.1.4",
     "vitest": "^1.2.2"
   },
-  "dependencies": {
-    "call-ai": "^0.10.0"
-  },
-  "peerDependencies": {
-    "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
-  },
   "scripts": {
-    "build": "tsc",
-    "build:browser": "node scripts/build-browser.js",
-    "build:browser:test": "node scripts/build-browser-test.js",
-    "build:bookmarklet": "node scripts/generate-bookmarklet.js",
-    "build:all": "npm run build && npm run build:browser && npm run build:bookmarklet",
+    "build": "pnpm clean && tsc && pnpm copy-css",
+    "copy-css": "mkdir -p dist/components && cp src/components/ImgGen.css dist/components/",
+    "build:watch": "tsc --watch",
+    "dev:build": "tsc --watch",
+    "lint": "eslint src --ext .ts,.tsx",
+    "lint:fix": "eslint src --ext .ts,.tsx --fix --rule 'no-unused-vars: 1' --rule 'no-empty: 1' --rule '@typescript-eslint/no-unused-vars: 1'",
+    "format": "prettier --write \"./**/*.{js,jsx,ts,tsx,json,md}\"",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:browser": "npm run build:browser:test && playwright test --reporter=line",
-    "test:browser:headed": "npm run build:browser:test && playwright test --headed --reporter=line",
-    "test:browser:debug": "npm run build:browser:test && playwright test --debug --reporter=line",
-    "lint": "eslint --ext .js,.ts,.tsx src/ tests/ scripts/",
-    "lint:fix": "eslint --ext .js,.ts,.tsx --fix src/ tests/ scripts/",
-    "format": "prettier --write 'src/**/*.{js,ts,tsx}' 'tests/**/*.{js,ts,tsx}' 'scripts/**/*.js'",
+    "clean": "rimraf dist",
     "typecheck": "tsc --noEmit",
-    "validate": "npm run typecheck && npm run test && npm run test:browser && npm run lint",
-    "fix": "npm run lint:fix && npm run format",
-    "check": "npm run validate && npm run fix",
-    "prerelease": "npm run validate",
-    "serve": "vite fixtures --port 3000"
+    "check": "pnpm lint && pnpm format && pnpm typecheck && pnpm test"
   }
 }