@antigenic-oss/paint 0.2.8 → 0.3.0

package/LICENSE

@@ -175,4 +175,4 @@ of your accepting any such warranty or additional liability.
 
 END OF TERMS AND CONDITIONS
 
-Copyright 2026 Antigenic Research Institute
+Copyright 2026 Antigenic Technologies Inc.

package/NOTICE

@@ -1,4 +1,4 @@
 pAInt
-Copyright 2026 Antigenic Research Institute
+Copyright 2026 Antigenic Technologies Inc.
 
-This product includes software developed at Antigenic Research Institute.
+This product includes software developed at Antigenic Technologies Inc.

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

@@ -491,6 +491,8 @@ async function startApp(options) {
   console.log(`pAInt started at http://${options.host}:${options.port}`)
   console.log(`Web pid: ${webChild.pid}`)
   console.log(`Web logs: ${WEB_LOG_FILE}`)
+
+  checkForUpdate()
 }
 
 function stopApp() {
@@ -529,6 +531,8 @@ function appStatus() {
   console.log(`URL: http://${existing.host}:${existing.port}`)
   console.log(`Started: ${existing.startedAt}`)
   if (existing.logs?.web) console.log(`Web logs: ${existing.logs.web}`)
+
+  checkForUpdate()
 }
 
 function appLogs() {
@@ -747,6 +751,34 @@ function bridgeLogs() {
   process.stdout.write(fs.readFileSync(BRIDGE_LOG_FILE, 'utf8'))
 }
 
+function checkForUpdate() {
+  const pkg = JSON.parse(fs.readFileSync(APP_PACKAGE_JSON, 'utf8'))
+  const name = pkg.name
+  const registryUrl = `https://registry.npmjs.org/${name}/latest`
+
+  const req = https.get(registryUrl, { timeout: 3000 }, (res) => {
+    if (res.statusCode !== 200) return
+    const chunks = []
+    res.on('data', (chunk) => chunks.push(chunk))
+    res.on('end', () => {
+      try {
+        const data = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+        const latest = data.version
+        if (latest && latest !== APP_VERSION) {
+          console.log(
+            `\nUpdate available: ${APP_VERSION} → ${latest}\nRun: npm install -g ${name}\n`,
+          )
+        }
+      } catch {
+        // ignore parse errors
+      }
+    })
+  })
+
+  req.on('error', () => {})
+  req.on('timeout', () => req.destroy())
+}
+
 function showHelp() {
   console.log(`paint - pAInt server manager
 

package/next.config.mjs

@@ -20,6 +20,14 @@ const nextConfig = {
           { key: 'Cross-Origin-Resource-Policy', value: 'cross-origin' },
         ],
       },
+      {
+        // Allow the SW to control /sw-proxy/ scope even though the script
+        // lives at /sw-proxy/sw.js (scope matches script directory)
+        source: '/sw-proxy/sw.js',
+        headers: [
+          { key: 'Service-Worker-Allowed', value: '/sw-proxy/' },
+        ],
+      },
     ]
   },
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antigenic-oss/paint",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "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/public/dev-editor-inspector.js

@@ -429,6 +429,13 @@
       'position:absolute;top:-18px;left:-1px;padding:1px 6px;font-size:10px;font-family:-apple-system,BlinkMacSystemFont,sans-serif;line-height:14px;color:#fff;background:#1D3F23;border-radius:3px 3px 0 0;white-space:nowrap;pointer-events:none;'
     hoverOverlay.appendChild(hoverLabel)
 
+    // Watch for framework hydration removing our overlays from the DOM.
+    // When detected, re-append them to the current document.body.
+    new MutationObserver(function () {
+      if (!selectionOverlay.isConnected) document.body.appendChild(selectionOverlay)
+      if (!hoverOverlay.isConnected) document.body.appendChild(hoverOverlay)
+    }).observe(document.documentElement, { childList: true, subtree: true })
+
     var hoveredElement = null
 
     function getElementLabel(el) {
@@ -447,6 +454,7 @@
     }
 
     document.addEventListener('mousemove', (e) => {
+
       if (!selectionModeEnabled) {
         hoverOverlay.style.display = 'none'
         return
@@ -524,6 +532,7 @@
     function selectElement(el) {
       // Don't select elements when selection mode is disabled (preview mode)
       if (!selectionModeEnabled) return
+
       selectedElement = el
       var rect = el.getBoundingClientRect()
       selectionOverlay.style.display = 'block'
@@ -575,6 +584,7 @@
     }
 
     function updateSelectionOverlay() {
+
       if (!selectedElement || selectionOverlay.style.display === 'none') return
       var rect = selectedElement.getBoundingClientRect()
       selectionOverlay.style.top = `${rect.top}px`
@@ -1439,6 +1449,10 @@
             }
             if (resolved.origin !== window.location.origin) continue
             var linkPath = resolved.pathname
+            // Strip /sw-proxy/ prefix added by SW proxy URL rewriting
+            if (linkPath.indexOf('/sw-proxy/') === 0) {
+              linkPath = linkPath.substring('/sw-proxy'.length) || '/'
+            }
             if (linkPath.indexOf('/api/') === 0 || linkPath === '') continue
             if (!linkPath.startsWith('/')) continue
             if (seen[linkPath]) continue