@antigenic-oss/paint 0.2.7 → 0.2.9

package/README.md

@@ -1,28 +1,35 @@
 # pAInt
 
-[![License](https://img.shields.io/github/license/Antigenic-OSS/pAInt)](https://github.com/Antigenic-OSS/pAInt/blob/main/LICENSE)
-[![Stars](https://img.shields.io/github/stars/Antigenic-OSS/pAInt?style=social)](https://github.com/Antigenic-OSS/pAInt/stargazers)
-[![Issues](https://img.shields.io/github/issues/Antigenic-OSS/pAInt)](https://github.com/Antigenic-OSS/pAInt/issues)
-[![npm version](https://img.shields.io/npm/v/@antigenic-oss/paint)](https://www.npmjs.com/package/@antigenic-oss/paint)
-[![npm downloads](https://img.shields.io/npm/dm/@antigenic-oss/paint)](https://www.npmjs.com/package/@antigenic-oss/paint)
-[![Bun](https://img.shields.io/badge/local%20dev-Bun-000000)](https://bun.sh)
-[![Node.js](https://img.shields.io/badge/runtime-Node.js-5FA04E)](https://nodejs.org)
-[![Next.js](https://img.shields.io/badge/framework-Next.js-000000)](https://nextjs.org)
-[![TypeScript](https://img.shields.io/badge/language-TypeScript-3178C6)](https://www.typescriptlang.org)
+<p>
+  <a href="https://www.npmjs.com/package/@antigenic-oss/paint"><img alt="npm version" src="https://img.shields.io/npm/v/@antigenic-oss/paint" /></a>
+  <a href="https://www.npmjs.com/package/@antigenic-oss/paint"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@antigenic-oss/paint" /></a>
+  <a href="https://github.com/Antigenic-OSS/pAInt/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/Antigenic-OSS/pAInt" /></a>
+  <a href="https://github.com/Antigenic-OSS/pAInt/issues"><img alt="Issues" src="https://img.shields.io/github/issues/Antigenic-OSS/pAInt" /></a>
+  <br />
+  <a href="https://github.com/Antigenic-OSS/pAInt/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/Antigenic-OSS/pAInt?style=social" /></a>
+  <a href="https://bun.sh"><img alt="Bun" src="https://img.shields.io/badge/local%20dev-Bun-000000" /></a>
+  <a href="https://nodejs.org"><img alt="Node.js" src="https://img.shields.io/badge/runtime-Node.js-5FA04E" /></a>
+  <a href="https://nextjs.org"><img alt="Next.js" src="https://img.shields.io/badge/framework-Next.js-000000" /></a>
+  <a href="https://www.typescriptlang.org"><img alt="TypeScript" src="https://img.shields.io/badge/language-TypeScript-3178C6" /></a>
+</p>
 
 pAInt is a visual editor for localhost web projects. It helps you inspect elements, edit styles, manage CSS variables, and export changelogs for [Claude Code](https://claude.ai/claude-code).
 
+Built by [Antigenic](https://antigenic.org).
+
 ## Table of Contents
 
 - [Project Status](#project-status)
 - [Global CLI](#global-cli)
 - [What You Can Do](#what-you-can-do)
+- [Why pAInt Saves AI Tokens](#why-paint-saves-ai-tokens)
 - [Prerequisites](#prerequisites)
 - [Quick Start](#quick-start)
 - [Connection Modes](#connection-modes)
 - [Core Workflow](#core-workflow)
 - [Interface Layout](#interface-layout)
 - [Commands](#commands)
+- [Bridge vs Server vs Terminal](#bridge-vs-server-vs-terminal)
 - [Architecture Summary](#architecture-summary)
 - [Security Notes](#security-notes)
 - [Documentation](#documentation)
@@ -101,6 +108,15 @@ Terminal WS (when started): `ws://localhost:4001/ws`
 - Track every change and export a structured changelog
 - Send changelogs to Claude Code for source-file application
 
+## Why pAInt Saves AI Tokens
+
+pAInt helps you use fewer AI tokens by turning broad prompts into precise, structured change data:
+
+- You edit visually first, so you do not need long back-and-forth prompt iterations
+- Exported changelogs include exact selectors, properties, and before/after values
+- Claude Code receives focused instructions, reducing token-heavy ambiguity
+- You review only real diffs instead of asking the model to rediscover page context each time
+
 ## Prerequisites
 
 - Local repository development: Bun `>=1.3`
@@ -172,6 +188,20 @@ bun run start              # Production server (port 4000)
 bun run lint               # Biome check
 ```
 
+## Bridge vs Server vs Terminal
+
+These three pieces have different jobs:
+
+- `pAInt server` (`paint start`): runs the main pAInt web app UI (default `http://127.0.0.1:4000`)
+- `bridge server` (`paint bridge start`): local HTTP bridge used when pAInt UI is hosted remotely (for example Vercel) but still needs safe local machine access (`http://127.0.0.1:4002` by default)
+- `terminal server` (`paint terminal start`): local WebSocket PTY service for the in-app Terminal tab (`ws://localhost:4001/ws` by default)
+
+When to run each:
+
+- Local-only workflow: run `paint start` (and optionally `paint terminal start` if you want in-app terminal streaming)
+- Hosted UI + local project workflow: run `paint bridge start` so the hosted UI can reach local-only capabilities
+- Claude/CLI visibility workflow: run `paint terminal start` to see command output and progress inside pAInt
+
 ## Architecture Summary
 
 - Next.js App Router frontend (develop locally with Bun, run globally via Node.js CLI)
@@ -201,15 +231,12 @@ See `CONTRIBUTING.md` for setup, workflow, and pull request expectations.
 
 ## Release Automation
 
-- Versioning and release PRs are managed with Changesets.
+- Versioning is manual (update `package.json` before merging to `main`).
 - CI workflow: `.github/workflows/ci.yml`
 - Release workflow: `.github/workflows/release.yml`
 - Publishing uses npm Trusted Publishing (OIDC) from the `release` GitHub Environment.
-- To queue a release, add a changeset:
-
-```bash
-bun run changeset
-```
+- On every push to `main`, the release workflow runs build/lint/smoke checks.
+- Publish happens automatically only when `package.json` version differs from the currently published npm version.
 
 ## License
 

package/bin/paint.js

@@ -22,7 +22,7 @@ const APP_VERSION = (() => {
 const RUNNING_FROM_NODE_MODULES = APP_ROOT.includes(
   `${path.sep}node_modules${path.sep}`,
 )
-const RUNTIME_SCHEMA_VERSION = 2
+const RUNTIME_SCHEMA_VERSION = 4
 const RUNTIME_ROOT = RUNNING_FROM_NODE_MODULES
   ? path.join(STATE_DIR, 'runtime', APP_VERSION)
   : APP_ROOT
@@ -68,11 +68,42 @@ function ensureStateDir() {
   fs.mkdirSync(STATE_DIR, { recursive: true })
 }
 
+function findNodeModulesRootFromResolvedPath(resolvedPath) {
+  const needle = `${path.sep}node_modules${path.sep}`
+  const idx = resolvedPath.lastIndexOf(needle)
+  if (idx === -1) return null
+  // Keep ".../node_modules" (without trailing slash)
+  return resolvedPath.slice(0, idx + needle.length - 1)
+}
+
+function resolveDependencyNodeModulesRoot() {
+  const probes = [
+    'zustand/package.json',
+    '@xterm/xterm/package.json',
+    'react/package.json',
+    'next/package.json',
+  ]
+
+  for (const probe of probes) {
+    try {
+      const resolved = require.resolve(probe, { paths: [APP_ROOT] })
+      const root = findNodeModulesRootFromResolvedPath(resolved)
+      if (root) return root
+    } catch {
+      // keep probing
+    }
+  }
+
+  // Last resort: local node_modules under package root.
+  return path.join(APP_ROOT, 'node_modules')
+}
+
 function ensureRuntimeRoot() {
   if (!RUNNING_FROM_NODE_MODULES) return APP_ROOT
 
   const stampFile = path.join(RUNTIME_ROOT, '.paint-runtime-stamp.json')
   let needsRefresh = true
+  const moduleRoot = resolveDependencyNodeModulesRoot()
 
   if (fs.existsSync(stampFile)) {
     try {
@@ -81,10 +112,18 @@ function ensureRuntimeRoot() {
       const hasLegacyConfigTs = fs.existsSync(
         path.join(RUNTIME_ROOT, 'next.config.ts'),
       )
+      const runtimeNodeModules = path.join(RUNTIME_ROOT, 'node_modules')
+      let linkedToExpectedRoot = false
+      try {
+        linkedToExpectedRoot = fs.realpathSync(runtimeNodeModules) === moduleRoot
+      } catch {
+        linkedToExpectedRoot = false
+      }
       needsRefresh =
         stamp?.schemaVersion !== RUNTIME_SCHEMA_VERSION ||
         !hasConfigMjs ||
-        hasLegacyConfigTs
+        hasLegacyConfigTs ||
+        !linkedToExpectedRoot
     } catch {
       needsRefresh = true
     }
@@ -124,7 +163,7 @@ function ensureRuntimeRoot() {
   }
 
   const runtimeNodeModules = path.join(RUNTIME_ROOT, 'node_modules')
-  fs.symlinkSync(path.join(APP_ROOT, 'node_modules'), runtimeNodeModules, 'dir')
+  fs.symlinkSync(moduleRoot, runtimeNodeModules, 'dir')
 
   fs.writeFileSync(
     stampFile,
@@ -133,6 +172,7 @@ function ensureRuntimeRoot() {
         schemaVersion: RUNTIME_SCHEMA_VERSION,
         version: APP_VERSION,
         sourceRoot: APP_ROOT,
+        moduleRoot,
         preparedAt: now(),
       },
       null,

package/bin/smoke-packed-global.js

@@ -31,9 +31,17 @@ function main() {
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'paint-packed-smoke-'))
   const packDir = path.join(tempRoot, 'pack')
   const extractDir = path.join(tempRoot, 'extract')
+  const globalRoot = path.join(tempRoot, 'global')
+  const globalNodeModules = path.join(globalRoot, 'node_modules')
+  const scopedPackageRoot = path.join(
+    globalNodeModules,
+    '@antigenic-oss',
+    'paint',
+  )
   const fakeHome = path.join(tempRoot, 'home')
   fs.mkdirSync(packDir, { recursive: true })
   fs.mkdirSync(extractDir, { recursive: true })
+  fs.mkdirSync(globalNodeModules, { recursive: true })
   fs.mkdirSync(fakeHome, { recursive: true })
 
   runOrFail('npm', ['pack', '--silent', '--pack-destination', packDir])
@@ -49,9 +57,26 @@ function main() {
   runOrFail('tar', ['-xzf', path.join(packDir, tarball), '-C', extractDir])
 
   const packedRoot = path.join(extractDir, 'package')
-  const packedNodeModules = path.join(packedRoot, 'node_modules')
-  if (!fs.existsSync(packedNodeModules)) {
-    fs.symlinkSync(path.join(APP_ROOT, 'node_modules'), packedNodeModules, 'dir')
+
+  // Emulate global install layout:
+  // <global>/node_modules/@antigenic-oss/paint (package)
+  // <global>/node_modules/<deps> (shared deps), no package-local node_modules.
+  fs.mkdirSync(path.dirname(scopedPackageRoot), { recursive: true })
+  fs.cpSync(packedRoot, scopedPackageRoot, { recursive: true, force: true })
+  fs.rmSync(path.join(scopedPackageRoot, 'node_modules'), {
+    recursive: true,
+    force: true,
+  })
+
+  const sourceNodeModules = path.join(APP_ROOT, 'node_modules')
+  const entries = fs.readdirSync(sourceNodeModules, { withFileTypes: true })
+  for (const entry of entries) {
+    if (entry.name === '.bin') continue
+    if (entry.name === '@antigenic-oss') continue
+    const src = path.join(sourceNodeModules, entry.name)
+    const dst = path.join(globalNodeModules, entry.name)
+    if (fs.existsSync(dst)) continue
+    fs.symlinkSync(src, dst, 'dir')
   }
 
   const env = {
@@ -63,15 +88,15 @@ function main() {
 
   let started = false
   try {
-    runOrFail('node', [path.join(packedRoot, 'bin', 'paint.js'), 'start', '--rebuild', '--port', PORT], {
-      cwd: packedRoot,
+    runOrFail('node', [path.join(scopedPackageRoot, 'bin', 'paint.js'), 'start', '--rebuild', '--port', PORT], {
+      cwd: scopedPackageRoot,
       env,
     })
     started = true
   } finally {
     if (started) {
-      run('node', [path.join(packedRoot, 'bin', 'paint.js'), 'stop'], {
-        cwd: packedRoot,
+      run('node', [path.join(scopedPackageRoot, 'bin', 'paint.js'), 'stop'], {
+        cwd: scopedPackageRoot,
         env,
       })
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antigenic-oss/paint",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Visual editor for localhost web projects with a global paint CLI",
   "license": "Apache-2.0",
   "homepage": "https://github.com/Antigenic-OSS/pAInt",
@@ -13,10 +13,16 @@
   },
   "keywords": [
     "paint",
+    "pAInt",
     "visual-editor",
     "nextjs",
     "css",
-    "localhost"
+    "localhost",
+    "bridge-server",
+    "terminal",
+    "claude-code",
+    "ai-coding",
+    "developer-tools"
   ],
   "bin": {
     "paint": "bin/paint.js"
@@ -53,10 +59,7 @@
     "lint:fix": "biome lint --write .",
     "format": "biome format --write .",
     "smoke:packed-global": "node ./bin/smoke-packed-global.js",
-    "prepublishOnly": "npm run smoke:packed-global",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "changeset publish"
+    "prepublishOnly": "npm run smoke:packed-global"
   },
   "dependencies": {
     "@tailwindcss/postcss": "4.2.1",
@@ -77,7 +80,6 @@
     "zustand": "^5.0.11"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.4.5",
-    "@changesets/cli": "^2.29.7"
+    "@biomejs/biome": "2.4.5"
   }
 }

package/src/app/api/proxy/[[...path]]/route.ts

@@ -1330,6 +1330,11 @@ function getInspectorCode(): string {
                 }
                 var meNewSelector = generateSelectorPath(meEl);
                 var meActualIndex = Array.from(meNewParent.children).indexOf(meEl);
+                var meAttrs = {};
+                for (var mai = 0; mai < meEl.attributes.length; mai++) {
+                  var ma = meEl.attributes[mai];
+                  meAttrs[ma.name] = ma.value;
+                }
                 send({
                   type: 'ELEMENT_MOVED',
                   payload: {
@@ -1338,7 +1343,13 @@ function getInspectorCode(): string {
                     oldParentSelectorPath: meOldParentSelector,
                     newParentSelectorPath: msg.payload.newParentSelectorPath,
                     oldIndex: meOldIndex,
-                    newIndex: meActualIndex
+                    newIndex: meActualIndex,
+                    tagName: meEl.tagName.toLowerCase(),
+                    className: meEl.className && typeof meEl.className === 'string' ? meEl.className : null,
+                    elementId: meEl.id || null,
+                    innerText: (meEl.innerText || '').substring(0, 500) || null,
+                    attributes: meAttrs,
+                    computedStyles: getComputedStylesForElement(meEl)
                   }
                 });
                 if (selectedElement === meEl) {

package/src/app/docs/page.tsx

@@ -10,9 +10,29 @@ import {
 } from './DocsClient'
 
 export const metadata: Metadata = {
-  title: 'pAInt — Setup Guide',
+  title: 'Setup Guide',
   description:
-    'Framework-specific setup instructions for connecting pAInt to your localhost project.',
+    'Framework-specific setup instructions for connecting pAInt to localhost projects, including proxy, bridge, and terminal-assisted workflows.',
+  keywords: [
+    'pAInt setup',
+    'localhost visual editor setup',
+    'bridge server setup',
+    'terminal server setup',
+    'Next.js inspector script',
+    'Claude Code changelog workflow',
+  ],
+  openGraph: {
+    title: 'pAInt Setup Guide',
+    description:
+      'Connect pAInt to your localhost app with framework-specific instructions and efficient AI handoff workflows.',
+    type: 'article',
+  },
+  twitter: {
+    card: 'summary',
+    title: 'pAInt Setup Guide',
+    description:
+      'Configure pAInt quickly for localhost projects and ship cleaner AI-assisted edits.',
+  },
 }
 
 const SCRIPT_TAG =

package/src/app/layout.tsx

@@ -2,8 +2,54 @@ import type { Metadata } from 'next'
 import './globals.css'
 
 export const metadata: Metadata = {
-  title: 'pAInt',
-  description: 'Visual design editor for localhost projects',
+  metadataBase: new URL('https://dev-editor-flow.vercel.app'),
+  title: {
+    default: 'pAInt | Visual Editor for Localhost Projects',
+    template: '%s | pAInt',
+  },
+  description:
+    'pAInt is a visual editor for localhost apps with bridge, server, and terminal workflows. Edit first, export precise changelogs, and save AI tokens with focused Claude Code handoff.',
+  keywords: [
+    'pAInt',
+    'visual editor',
+    'localhost web editor',
+    'bridge server',
+    'terminal server',
+    'Claude Code',
+    'AI token efficiency',
+    'CSS visual editing',
+    'Next.js visual editor',
+    'developer tooling',
+  ],
+  alternates: {
+    canonical: '/',
+  },
+  openGraph: {
+    type: 'website',
+    url: '/',
+    siteName: 'pAInt',
+    title: 'pAInt | Visual Editor for Localhost Projects',
+    description:
+      'Inspect, edit, and export structured UI changes. Use bridge/server/terminal modes to ship faster and reduce AI token usage.',
+  },
+  twitter: {
+    card: 'summary_large_image',
+    title: 'pAInt | Visual Editor for Localhost Projects',
+    description:
+      'Visual-first editing plus focused changelogs for Claude Code means fewer tokens and faster delivery.',
+  },
+  robots: {
+    index: true,
+    follow: true,
+    googleBot: {
+      index: true,
+      follow: true,
+      'max-image-preview': 'large',
+      'max-snippet': -1,
+      'max-video-preview': -1,
+    },
+  },
+  category: 'developer tools',
 }
 
 export default function RootLayout({

package/src/components/right-panel/changes/ChangesPanel.tsx

@@ -1198,7 +1198,12 @@ export function ChangesPanel() {
   ])
 
   const handleAiScan = useCallback(() => {
-    if (!targetUrl || !projectRoot || breakpointChanges.length === 0) return
+    if (!targetUrl || breakpointChanges.length === 0) return
+    if (!projectRoot) {
+      showToast('error', 'Set a project folder first — click the folder icon in the Claude tab')
+      setActiveRightTab('claude')
+      return
+    }
 
     setAiScanStatus('scanning')
     setAiScanError(null)
@@ -1251,6 +1256,7 @@ export function ChangesPanel() {
     setAiScanResult,
     showToast,
     setActiveLeftTab,
+    setActiveRightTab,
   ])
 
   const handleSendToClaudeCode = useCallback(

package/src/hooks/useChangeTracker.ts

@@ -261,6 +261,32 @@ export function performRevertAll() {
   }
 }
 
+// Module-level singletons for auto-persist and load — prevents duplicate
+// subscriptions and stale-data overwrites when multiple components call
+// useChangeTracker() and some of them remount (e.g. LayerNode after tree updates).
+let persistSubscribed = false
+let persistTimeout: ReturnType<typeof setTimeout> | null = null
+let prevChangesRef: unknown = null
+let lastLoadedUrl: string | null = null
+
+function ensurePersistSubscription() {
+  if (persistSubscribed) return
+  persistSubscribed = true
+  useEditorStore.subscribe((state) => {
+    const ref = state.styleChanges
+    if (ref === prevChangesRef) return
+    prevChangesRef = ref
+
+    const url = state.targetUrl
+    if (!url) return
+
+    if (persistTimeout) clearTimeout(persistTimeout)
+    persistTimeout = setTimeout(() => {
+      useEditorStore.getState().persistChanges(url)
+    }, 300)
+  })
+}
+
 /**
  * Hook that tracks style changes, sends PREVIEW_CHANGE to inspector,
  * and auto-persists changes to localStorage.
@@ -273,36 +299,18 @@ export function useChangeTracker() {
   const pushUndo = useEditorStore((s) => s.pushUndo)
   const { sendToInspector } = usePostMessage()
 
-  // Auto-persist changes when they update (count OR content)
-  const persistTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
-  const prevChangesRef = useRef<unknown>(null)
-
+  // Set up singleton auto-persist subscription (once globally, not per component)
   useEffect(() => {
-    const unsubscribe = useEditorStore.subscribe((state) => {
-      // Trigger on any styleChanges or elementSnapshots reference change
-      const ref = state.styleChanges
-      if (ref === prevChangesRef.current) return
-      prevChangesRef.current = ref
-
-      const url = state.targetUrl
-      if (!url) return
-
-      // Debounce persistence
-      if (persistTimeoutRef.current) clearTimeout(persistTimeoutRef.current)
-      persistTimeoutRef.current = setTimeout(() => {
-        useEditorStore.getState().persistChanges(url)
-      }, 300)
-    })
-
-    return () => {
-      unsubscribe()
-      if (persistTimeoutRef.current) clearTimeout(persistTimeoutRef.current)
-    }
+    ensurePersistSubscription()
   }, [])
 
-  // Load persisted changes when target URL changes
+  // Load persisted changes only when target URL actually changes,
+  // not on every component mount. This prevents remounting components
+  // (e.g. LayerNode after tree updates) from overwriting in-memory
+  // changes with stale localStorage data.
   useEffect(() => {
-    if (targetUrl) {
+    if (targetUrl && targetUrl !== lastLoadedUrl) {
+      lastLoadedUrl = targetUrl
       useEditorStore.getState().loadPersistedChanges(targetUrl)
     }
   }, [targetUrl])

package/src/hooks/usePostMessage.ts

@@ -450,6 +450,12 @@ function handleMessage(event: MessageEvent) {
         newParentSelectorPath: mvNewParent,
         oldIndex: mvOldIndex,
         newIndex: mvNewIndex,
+        tagName: mvTag,
+        className: mvClass,
+        elementId: mvId,
+        innerText: mvText,
+        attributes: mvAttrs,
+        computedStyles: mvStyles,
       } = msg.payload
       const mvProperty = '__element_moved__'
 
@@ -464,6 +470,20 @@ function handleMessage(event: MessageEvent) {
         changeScope: store.changeScope,
       })
 
+      // Save element snapshot so move appears in Changes panel
+      store.saveElementSnapshot({
+        selectorPath: mvNewSelector,
+        tagName: mvTag || 'unknown',
+        className: mvClass ?? null,
+        elementId: mvId ?? null,
+        attributes: mvAttrs || {},
+        innerText: mvText,
+        computedStyles: mvStyles ? { ...mvStyles } : {},
+        pagePath: store.currentPagePath,
+        changeScope: store.changeScope,
+        sourceInfo: null,
+      })
+
       // Track the move
       store.addStyleChange({
         id: generateId(),

package/src/types/messages.ts

@@ -337,6 +337,12 @@ export interface ElementMovedMessage {
     newParentSelectorPath: string
     oldIndex: number
     newIndex: number
+    tagName: string
+    className: string | null
+    elementId: string | null
+    innerText: string | null
+    attributes: Record<string, string>
+    computedStyles: Record<string, string>
   }
 }