diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9a75c8e..49695b7 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,8 +1,8 @@ name: CI build check -# Fast per-push sanity gate: install deps, parse-check every JS file, run the -# node self-checks. Catches a broken commit immediately. The heavy installer -# build lives in build.yml (tags only) — this stays light. +# Fast per-push sanity gate: install deps, type-check + compile the TypeScript +# tree, run the node self-checks. Catches a broken commit immediately. The +# heavy installer build lives in build.yml (tags only) — this stays light. on: push: @@ -21,7 +21,9 @@ jobs: node-version: '20' cache: 'npm' - run: npm install - - name: Parse-check every JS file - run: git ls-files '*.js' | xargs -P4 -n1 node --check + - name: Type-check + compile TypeScript + # The whole tree is .ts (in-place sibling emit) — tsc strict is the + # parse+type gate; there are no tracked runtime .js files left to check. + run: npm run build:ts - name: Run self-checks run: npm test diff --git a/.gitignore b/.gitignore index ee79da5..b737eae 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,12 @@ config.json # Claude Code agent worktrees (transient) .claude/worktrees/ + +# TypeScript: ALL runtime .js is compiled output of a sibling .ts source +# (in-place emit) — sources are the .ts files, never commit emitted .js. +/main.js +src/**/*.js +preload/**/*.js +renderer/**/*.js +scripts/**/*.js +*.tsbuildinfo diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e0e24a1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,189 @@ +# Screenchart + +Screenshot anything on screen → press a hotkey → Screenchart analyzes the content in plain +English and can draw the right chart or map from it. Local-first, model-agnostic, open source (MIT). + +**Core principle:** the intelligence is in the prompt, not the plumbing — invest in prompt +quality before adding code. The model *extracts and classifies*; the app *does the math* +(deterministic, auditable — the model never writes a computed number). + +## Project Overview +- **What:** drag a box around on-screen content; a vision model reads it and answers. +- **One mode — analysis.** The model returns plain-language analysis PLUS structured data; the + app then computes metrics, writes a number-accurate headline, and offers charts/maps + export. +- **Follow-ups:** each capture is a conversation. The model is stateless, so follow-ups replay + the full thread (system prompt + original prompt + screenshot + every prior turn) each turn. +- **Audience:** developers / local-AI users (fast, private, no-key); benefits non-technical + people living in dashboards and spreadsheets most. + +## Tech Stack +- **Runtime:** Electron 42 (macOS-first; darwin + win32 build targets, linux eventually). +- **Language/UI:** TypeScript, **incremental migration** from plain JS (no bundler — `tsc` only); + vanilla HTML/CSS, no framework. Mixed tree: converted files are `.ts`, the rest still `.js`. +- **Screenshot/hotkey:** `desktopCapturer` + `globalShortcut` (default `CommandOrControl+Alt+S` + → `⌘⌥S` on macOS; user-configurable). +- **Charts:** Chart.js 4 + plugins (treemap, sankey, matrix, financial, `@sgratzl` boxplot). + **Maps:** Leaflet (OSM tiles — the one planned external network call). +- **Export:** `pdfmake` (PDF), `docx` (Word), `pptxgenjs` (PPT). **Logos:** `simple-icons`. +- **Key storage:** plaintext in `userData/config.json` (gitignored, **not** encrypted). **Config:** JSON at `userData/config.json` (v2). + **History:** threads + crops on disk under `userData` (`src/history.js`). + +### Two execution modes (`config.executionMode`) +- **`local`** (default) — a **Local CLI** the user already installed. Runnable: Claude Code, + Antigravity, Codex, Grok, OpenCode, Cursor. The app **detects and runs only — never installs** + (the "Install" button just opens a vendor URL). Gemini CLI is retired (honest disabled entry). +- **`byok`** — Bring Your Own Key to a cloud API. Families: **anthropic, openai, gemini, gateway** + (any OpenAI-compatible endpoint — OpenRouter/custom/local servers). Keys stored plaintext per-provider. + +## Architecture + +### The capture loop +Hotkey (or "New capture") → gate on `config.executionReady()` → `startCapture()` → frozen frame +via `desktopCapturer` on the **display under the cursor** → full-screen overlay dims that screen → +drag a box → `capture:commit` → main crops the frozen frame → the crop (base64 PNG data URL) is +saved to history, shown as a thumbnail, and sent to `analyze()`. If not ready (no CLI/key), the +hub opens to **Execution settings** instead — capture never starts. + +### Image delivery +- **BYOK:** crop sent **inline as base64** in the HTTPS body (Anthropic `image` / OpenAI + `image_url` / Gemini `inline_data`). +- **Local CLI:** crop written to a **temp file** under `userData/tmp/…`; its path is handed to the + CLI via a prompt hint or a flag (`--add-dir`, `-i`). + +### analyze → compute → display (`src/analyze.js`, `calc.js`, `headline.js`) +`analyze(dataUrl)` sends `buildSystemPrompt()` + image, expects ONLY a JSON envelope → +`parseReply()` validates against controlled vocabularies (drops off-list) into `extractedTable` +(raw numbers verbatim), `dataShape`, `columnRoles`, `suggestedCalculations`, number-free +`headline.angle`, `visualizations`, `geo`, `followups` → `calc.js` does the arithmetic → +`headline.js` composes the headline and inserts figures (model forbidden from writing numbers). + +### Windows (all inline panels live in the hub; no extra BrowserWindow for settings) +| Window | Renderer | Preload → bridge | Factory (`src/windows/`) | +|--------|----------|------------------|--------------------------| +| Hub | `renderer/hub/` | `hubPreload` → `window.hub` | `hubWindow.js` | +| Overlay | `renderer/overlay/` | `overlayPreload` → `window.overlay` | `overlayWindow.js` | +| Status | `renderer/status/` | `statusPreload` → `window.screenchart` | `statusWindow.js` | +| About | `renderer/about/` | `aboutPreload` → `window.about` | `aboutWindow.js` | +| Permission | `renderer/permission/` | `permissionPreload` → `window.permission` | `permissionWindow.js` | + +Settings/About/Permission are fixed full-window overlay panels inside the hub (`#settings-panel` +with `#ex-local-panel`/`#ex-byok-panel`, `#about-panel`, `#permission-panel`), shown via +`hub:open-settings`; back returns to the hub view. + +### Result surface +Thumbnail (→ lightbox), headline + analysis, a chart or Leaflet map with a `⋯` menu +(Values/Periods/customize), follow-up chips + input, and report export (PDF/Word/PPT — charts +and maps). A disk-persisted history rail lists captures (newest first); clicking restores its thread. + +### Code layout +- **Main:** `main.js` = entry/lifecycle/hotkey/capture loop/windows. Logic in `src/` modules + (`analyze, calc, headline, capture, config, history, hotkey, localCli, localCliRun, models, + icons, userPath`). **IPC** split into `src/ipc/*.js`, each exporting `register(deps)`, wired in + `main.js`. Add new IPC to the matching `src/ipc` module, not `main.js`. +- **Renderer (hub):** many `