@jay-framework/aiditor 0.16.2

package/README.md

@@ -0,0 +1,58 @@
+# @jay-framework/aiditor
+
+A visual AI-driven code editor plugin for Jay Framework. Annotate live page previews with visual markers, attach short instructions, and let an AI agent edit your source files directly.
+
+## How it works
+
+1. **Preview** — The AIditor loads your project's pages in an iframe
+2. **Annotate** — Place visual markers (points, areas, arrows) on elements you want changed
+3. **Instruct** — Type a short instruction per marker (e.g. "make this blue", "add a close button")
+4. **Run** — The AIditor captures annotated screenshots, sends them to a Claude agent, and streams the agent's file edits back in real-time
+
+The agent receives a triple screenshot (annotated, markers-only, clean) for maximum context, and can also process video recordings of interactions.
+
+## Installation
+
+Add the plugin to your Jay project:
+
+```bash
+yarn add @jay-framework/aiditor
+```
+
+The plugin auto-registers with the Jay dev server — no additional configuration needed. The `/aiditor` route becomes available when you run `yarn dev`.
+
+## Requirements
+
+The AI agent runs server-side via the Claude Agent SDK. Set your API key as an environment variable:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+## Usage
+
+1. Start your dev server (`yarn dev`)
+2. Navigate to `/aiditor`
+3. Select a page route from the dropdown
+4. Choose an annotation tool (point, area, or arrow)
+5. Click on the preview to place a marker
+6. Type your instruction in the popover (Cmd+Enter to run, Escape to cancel)
+7. Watch the agent's output in the bottom panel
+
+## Features
+
+- **Point, area, and arrow annotations** with per-marker instructions
+- **Video recording mode** — record interactions and pin annotations at specific moments
+- **File attachments** — attach reference images or assets to annotations
+- **Page freeze support** — annotate saved page snapshots
+- **Dynamic route params** — automatically discovers and lists route parameter combinations
+- **Streaming output** — real-time agent output with clickable file paths
+- **Keyboard shortcuts** — Cmd+Enter to run, Escape to cancel annotations
+
+## Plugin structure
+
+The plugin provides:
+
+- **Route** `/aiditor` — the editor UI
+- **Actions** — server-side actions for bootstrapping, route discovery, param loading, task submission, and file reading
+- **Contract** `aiditor-shell` — an optional editor chrome banner component

package/dist/actions/get-aiditor-bootstrap.jay-action

@@ -0,0 +1,9 @@
+name: getAiditorBootstrap
+description: One-shot bootstrap returning project directory and dev server base URL
+
+inputSchema:
+  origin: string
+
+outputSchema:
+  projectDir: string
+  httpBaseUrl: string

package/dist/actions/get-aiditor-bootstrap.jay-action.d.ts

@@ -0,0 +1,8 @@
+export interface GetAiditorBootstrapInput {
+  origin: string;
+}
+
+export interface GetAiditorBootstrapOutput {
+  projectDir: string;
+  httpBaseUrl: string;
+}

package/dist/actions/get-page-params.jay-action

@@ -0,0 +1,9 @@
+name: getPageParamsAction
+description: Stream dynamic route parameter combinations from dev server
+streaming: true
+
+inputSchema:
+  route: string
+
+outputSchema:
+  - record(string)

package/dist/actions/get-page-params.jay-action.d.ts

@@ -0,0 +1,5 @@
+export interface GetPageParamsActionInput {
+  route: string;
+}
+
+export type GetPageParamsActionOutput = Array<Record<string, string>>;

package/dist/actions/get-project-info.jay-action

@@ -0,0 +1,12 @@
+name: getProjectInfoAction
+description: List all page routes in the project via dev server
+
+inputSchema:
+  jayDevUrl: string
+
+outputSchema:
+  routes:
+    - path: string
+      jayHtmlPath: string
+      compPath: string
+  httpBaseUrl: string

package/dist/actions/get-project-info.jay-action.d.ts

@@ -0,0 +1,12 @@
+export interface GetProjectInfoActionInput {
+  jayDevUrl: string;
+}
+
+export interface GetProjectInfoActionOutput {
+  routes: Array<{
+      path: string;
+      jayHtmlPath: string;
+      compPath: string;
+    }>;
+  httpBaseUrl: string;
+}

package/dist/actions/list-freezes.jay-action

@@ -0,0 +1,12 @@
+name: listFreezesAction
+description: List frozen page states for a given route
+
+inputSchema:
+  route: string
+
+outputSchema:
+  freezes:
+    - id: string
+      name?: string
+      route: string
+      createdAt: string

package/dist/actions/list-freezes.jay-action.d.ts

@@ -0,0 +1,12 @@
+export interface ListFreezesActionInput {
+  route: string;
+}
+
+export interface ListFreezesActionOutput {
+  freezes: Array<{
+      id: string;
+      name?: string;
+      route: string;
+      createdAt: string;
+    }>;
+}

package/dist/actions/read-file.jay-action

@@ -0,0 +1,11 @@
+name: readFileAction
+description: Read a file from the project filesystem (text or image as base64)
+
+inputSchema:
+  filePath: string
+
+outputSchema:
+  type: string
+  data: string
+  filePath: string
+  mime?: string

package/dist/actions/read-file.jay-action.d.ts

@@ -0,0 +1,10 @@
+export interface ReadFileActionInput {
+  filePath: string;
+}
+
+export interface ReadFileActionOutput {
+  type: string;
+  data: string;
+  filePath: string;
+  mime?: string;
+}

package/dist/actions/submit-task.jay-action

@@ -0,0 +1,24 @@
+name: submitTaskAction
+description: Submit a visual annotation task to the AI agent (Agent SDK) with file uploads
+streaming: true
+
+inputSchema:
+  notes: string
+  pageRoute?: string
+  renderedUrl?: string
+  visualTask?: string
+  videoFramesOnly?: string
+  screenshot_full?: file
+  screenshot_markers_only?: file
+  screenshot_clean?: file
+  video?: file
+  extraFiles?: record(file)
+
+outputSchema:
+  type: string
+  message?: string
+  text?: string
+  name?: string
+  result?: string
+  cost?: number
+  duration?: number

package/dist/actions/submit-task.jay-action.d.ts

@@ -0,0 +1,24 @@
+import { JayFile } from '@jay-framework/fullstack-component';
+
+export interface SubmitTaskActionInput {
+  notes: string;
+  pageRoute?: string;
+  renderedUrl?: string;
+  visualTask?: string;
+  videoFramesOnly?: string;
+  screenshot_full?: JayFile;
+  screenshot_markers_only?: JayFile;
+  screenshot_clean?: JayFile;
+  video?: JayFile;
+  extraFiles?: Record<string, JayFile>;
+}
+
+export interface SubmitTaskActionOutput {
+  type: string;
+  message?: string;
+  text?: string;
+  name?: string;
+  result?: string;
+  cost?: number;
+  duration?: number;
+}

package/dist/aiditor-shell.jay-contract

@@ -0,0 +1,8 @@
+name: AiditorShell
+description: POC shell for AIditor — banner text until full sidebar + iframe UI lands
+tags:
+  - tag: headline
+    type: data
+    dataType: string
+    phase: fast
+    description: Visible title for the AIditor POC shell

package/dist/aiditor-shell.jay-contract.d.ts

@@ -0,0 +1,18 @@
+import {JayContract} from "@jay-framework/runtime";
+
+
+export interface AiditorShellViewState {
+  headline: string
+}
+
+export type AiditorShellSlowViewState = {};
+
+export type AiditorShellFastViewState = Pick<AiditorShellViewState, 'headline'>;
+
+export type AiditorShellInteractiveViewState = {};
+
+export interface AiditorShellRefs {}
+
+export interface AiditorShellRepeatedRefs {}
+
+export type AiditorShellContract = JayContract<AiditorShellViewState, AiditorShellRefs, AiditorShellSlowViewState, AiditorShellFastViewState, AiditorShellInteractiveViewState>