@popmelt.com/core 0.8.17 → 0.9.0

package/README.md

@@ -1,14 +1,57 @@
 <p align="center">
-  <img src="src/assets/bar - popmelt.png" alt="Popmelt" width="360" />
+  <img src="https://raw.githubusercontent.com/popmelt/core/main/src/assets/popmelt-logo.svg" alt="Popmelt" width="72" />
 </p>
 
 # Popmelt
 
-Popmelt is a design collaboration layer for AI coding agents. It gives you a visual toolbar inside your running React app so you can annotate UI, adjust it directly, and hand the result to Claude Code, Codex, or GitHub Copilot without translating every design decision into a written prompt.
+Popmelt is a design collaboration layer that lives inside your local app projects. When your app is running locally, Popmelt appears as a toolbar in the browser.
 
-Popmelt is local-first. Your project, annotations, screenshots, conversations, decisions, and models remain in your development environment.
+Point to any part of your UI, describe what you have in mind, and work through it with Codex or Claude Code in a thread right on the page. You can stack as many threads as you want, so different ideas can move forward without losing their context.
 
-## Install
+As you collaborate, Popmelt builds an **Imprint**: a living project memory of your intent, preferences, and design decisions. Later threads can use that shared understanding instead of starting from scratch.
+
+Popmelt is local-first. Its annotations, screenshots, threads, and Imprint live with your project under `.popmelt/`.
+
+## What you need
+
+- A local React project
+- Node.js 18 or newer
+- React 18 or newer
+- The Codex CLI or Claude Code CLI installed, available in your terminal, and signed in
+
+The Codex and Claude Code desktop apps work too. Open your local app in their built-in browser and use Popmelt there just as you would in any other browser. The corresponding CLI still needs to be installed and signed in because it runs the threads.
+
+## Install with your coding agent
+
+From inside your project, give your coding agent this prompt:
+
+> Let's install `@popmelt.com/core` in this project
+
+Your agent can detect the framework, add the provider and integration, and preserve your existing development command. Restart the development server when it is finished.
+
+## Use Popmelt
+
+1. Run your project locally and open it in a browser
+2. Double-tap Command on macOS or Control on Windows and Linux to open the Popmelt toolbar
+3. Select part of the UI and leave a note about what should change
+4. Press Command+Enter on macOS or Control+Enter on Windows and Linux to send the thread to your coding agent. Review the result and keep iterating from the same thread
+5. To edit text directly, double-tap a text element. Popmelt marks the change so you can send it like any other annotation
+
+Each annotation owns its thread. Status stays attached to the relevant part of the page while work is queued or running, and you can reopen any thread from its badge. Tool and Imprint receipts show what helped the agent reach its result.
+
+## Imprint
+
+As you work, Popmelt recognizes choices that may be useful beyond the current thread and proposes an Imprint update:
+
+- **Yes** adds the learning to the project's shared understanding
+- **This time** keeps it local to the current situation
+- **No** leaves the Imprint unchanged and gives you room to explain what Popmelt misunderstood
+
+Confirmed Imprint knowledge is available to future threads when it is relevant. Popmelt can also search the project's collaboration history when a question depends on earlier discussions, feedback, or the evolution of a part of the UI.
+
+Open the Imprint panel with `I` to inspect the project's current understanding, supporting evidence, relationships, and exceptions.
+
+## Manual setup
 
 Install Popmelt and its icon peer dependency:
 
@@ -16,15 +59,9 @@ Install Popmelt and its icon peer dependency:
 npm install @popmelt.com/core lucide-react
 ```
 
-Popmelt requires React 18+ and Node.js 18+. At least one supported AI CLI must be installed and authenticated:
-
-- Claude Code
-- Codex CLI
-- GitHub Copilot CLI
-
 ### Add the provider
 
-Wrap your application with `PopmeltProvider`. The component that calls `useRouter()` must be a client component in Next.js.
+Wrap your app with `PopmeltProvider`. In Next.js, the component that calls `useRouter()` must be a client component.
 
 ```tsx
 'use client';
@@ -40,13 +77,13 @@ export function Providers({ children }: { children: React.ReactNode }) {
 }
 ```
 
-`navigate` is optional for single-page use. Pass your router's navigation function to support annotations and screenshots across routes.
+`navigate` is optional for single-page use. Pass your router's navigation function when Popmelt needs to restore annotations across routes.
 
 ### Next.js
 
-For Next.js, both steps below are required.
+Next.js needs both the command wrapper and the config wrapper.
 
-1. Run the dev server through the Popmelt wrapper. Update the existing `dev` script while preserving any flags your project already uses:
+Update the existing development script while preserving any flags already in use:
 
 ```json
 {
@@ -56,13 +93,7 @@ For Next.js, both steps below are required.
 }
 ```
 
-For example, a Turbopack project can use:
-
-```json
-"dev": "popmelt wrap -- next dev --turbopack"
-```
-
-2. Wrap the Next config:
+Then wrap the Next config:
 
 ```ts
 // next.config.ts
@@ -73,11 +104,11 @@ const nextConfig = {};
 export default withPopmelt(nextConfig);
 ```
 
-The command wrapper starts the bridge for this project. The Next config wrapper connects the browser UI to that bridge. Using only one of these two pieces is not a complete setup.
+The command wrapper starts the project bridge. The config wrapper connects the browser toolbar to it. Using only one is not a complete setup.
 
 ### Vite
 
-Add the Vite plugin. It starts and connects the bridge with the Vite dev server.
+Add the Vite plugin:
 
 ```ts
 // vite.config.ts
@@ -92,7 +123,7 @@ export default defineConfig({
 
 ### Astro
 
-Add the Astro integration. It starts and connects the bridge with the Astro dev server.
+Add the Astro integration:
 
 ```js
 // astro.config.mjs
@@ -106,7 +137,7 @@ export default defineConfig({
 
 ### Other development servers
 
-The wrapper works with any dev command:
+The wrapper can start Popmelt alongside another development command:
 
 ```json
 {
@@ -116,137 +147,46 @@ The wrapper works with any dev command:
 }
 ```
 
-You can also start the bridge from custom server startup code:
-
-```ts
-import { startPopmelt } from '@popmelt.com/core/server';
-
-await startPopmelt();
-```
-
 ## Verify the installation
 
-Start the app using its normal development command:
+Start the app normally:
 
 ```bash
 npm run dev
 ```
 
-You should see both the bridge URL and the application URL in the terminal. Open the app and double-tap Cmd on macOS or Ctrl on Windows/Linux. The Popmelt toolbar should appear.
+Open the local app in a browser and double-tap Command or Control. The Popmelt toolbar should appear.
 
 If the toolbar opens but cannot reach an AI, check that:
 
-- The dev script includes `popmelt wrap` when using Next.js.
-- The framework plugin or config wrapper is installed.
-- A supported AI CLI is available and authenticated.
-- Another project is not using an old Popmelt bridge. Restart the dev command to reconnect the correct project.
-
-## Installing with an AI
-
-You can hand the following checklist to an AI coding agent:
-
-> Install `@popmelt.com/core` and `lucide-react`. Add `PopmeltProvider` at the application root. Preserve the existing dev command, but for Next.js prefix it with `popmelt wrap --` and wrap `next.config` with `withPopmelt`. For Vite or Astro, add the corresponding Popmelt plugin. Start the app and verify that the toolbar opens after double-tapping Cmd/Ctrl and that the bridge belongs to this project.
-
-The important Next.js detail is that `withPopmelt()` does not start the bridge by itself. The `dev` script must also use the Popmelt wrapper.
-
-## Use Popmelt
-
-Double-tap Cmd/Ctrl to open or collapse the toolbar. Hover any toolbar control to see its guidance panel.
-
-| Tool      | Shortcut | Use it to                                                                             |
-| --------- | -------- | ------------------------------------------------------------------------------------- |
-| Comment   | `C`      | Pin feedback to a specific element and start a conversation with your AI.             |
-| Handle    | `H`      | Adjust layout, spacing, typography, color, borders, and effects directly on the page. |
-| Rectangle | `R`      | Mark a rectangular region.                                                            |
-| Oval      | `O`      | Mark an oval region.                                                                  |
-| Line      | `L`      | Point at or connect parts of the UI.                                                  |
-| Pen       | `P`      | Draw a freehand annotation.                                                           |
-| Text      | `T`      | Add a label or edit existing page text inline.                                        |
-| Model     | `M`      | Review project patterns, components, and design-model suggestions.                    |
-
-### Hand off work
+- The selected AI CLI is installed and signed in
+- A Next.js development script includes `popmelt wrap`
+- The framework plugin or config wrapper is installed
+- The development server was restarted after installation
 
-Create one or more annotations, then press Cmd/Ctrl+Enter. Popmelt sends the visual state, element context, requested edits, and relevant project history to the selected AI.
+## Data and privacy
 
-The conversation opens in a thread beside the page. You can continue working while jobs run, reopen threads from their status badges, answer questions, and send follow-up guidance. Messages sent while an active thread is working are staged and delivered together on its next run.
+Popmelt stores its annotations, screenshots, threads, UI preferences, and Imprint locally under `.popmelt/`. Unsent annotation drafts and preview state also use browser storage.
 
-### Comment on elements
+When you send a thread, the context needed to complete that work is passed to your selected AI provider and is subject to that provider's privacy policy.
 
-Select Comment and click an element. Type what should change, then hand it off with Cmd/Ctrl+Enter. The annotation remains attached to that element as the page scrolls and across supported route changes.
-
-If the AI needs clarification, the annotation shows a Question badge. Open the thread, answer it, and send the reply.
-
-### Adjust UI directly
-
-Select Handle and hover an element. Depending on the element, you can adjust:
-
-- Width, height, padding, and gap
-- Flex and grid alignment
-- Font family, weight, size, line height, letter spacing, and alignment
-- Text and background colors
-- Opacity, radius, borders, and effects
-- Raw CSS for properties not represented by a dedicated control
-
-Right-click the focused element to open the full Handle panel. Values inherited from the page appear as placeholders until you explicitly change them. Hover and scrub numeric field icons to tune values; use modifier keys shown in the panel guidance for snapping and finer control.
-
-Handle changes are previews. They are recorded with the annotation so the AI can implement the corresponding source-code changes.
-
-You can also drag supported elements to propose a new position, and use Cmd/Ctrl+C and Cmd/Ctrl+V in Handle mode to duplicate supported page structures as visual guidance.
-
-### Edit text inline
-
-Select Text and hover page copy. Recognized text elements receive a bounding box. Click to edit the actual visible text in place, then finish the edit to retain it as a pending change.
-
-Clicking outside editable page copy still creates a free-positioned text annotation.
-
-### Draw visual guidance
-
-Rectangle, Oval, Line, and Pen annotations are useful when the desired result is easier to show than describe. Add labels where useful, then submit them with the rest of the page context.
-
-### Work across routes
-
-Pass `navigate` to `PopmeltProvider` to enable route-aware annotations and multi-page capture. Annotation and status badges appear only on their relevant routes. When a handoff includes multiple routes, Popmelt captures each route and sends them together.
-
-## AI providers and models
-
-Popmelt detects supported AI CLIs available in the project environment. Click the provider icon to switch providers. Click the model name, or hover the provider controls, to choose among detected models.
-
-When supported by the selected model, the model guidance panel also exposes:
-
-- Thinking or reasoning effort
-- Standard or faster service tiers
-
-These settings persist per provider and model and apply to annotations, replies, and model work.
-
-## Threads and job status
-
-Each handoff creates or continues a conversation thread. Status badges stay available while work is queued or running and return you to the associated element and conversation.
-
-Use Cancel in the thread to stop the active job associated with that conversation. Closing a thread does not delete it. Delete its annotation to remove that thread, or use Cmd/Ctrl+Backspace to clear all local annotations and pending preview changes.
-
-## Decisions and the project model
-
-Completed annotation threads leave a decision history in the project. Popmelt uses that evidence to identify reusable design patterns rather than treating every edit as an isolated instruction.
-
-When Popmelt finds a model opportunity, it places the proposal in the relevant annotation thread. Expand the proposal to inspect the exact changes, select only the entries you agree with, and apply or dismiss them. Applied changes contribute to the local project model.
-
-Use the Model panel to inspect captured patterns and components or to synthesize model guidance from accumulated project history.
+Popmelt is designed for local development. As with any AI-assisted coding, your agent may edit files or run commands, so review its work, use version control, and run your project tests before you ship.
 
 ## Useful shortcuts
 
-| Shortcut                  | Action                                                          |
-| ------------------------- | --------------------------------------------------------------- |
-| Double-tap Cmd/Ctrl       | Open or collapse Popmelt                                        |
-| Cmd/Ctrl+Enter            | Hand off pending work                                           |
-| Cmd/Ctrl+C                | Copy an annotated screenshot, or copy an element in Handle mode |
-| Cmd/Ctrl+V                | Paste a copied element in Handle mode                           |
-| Cmd/Ctrl+Z                | Undo a pending change                                           |
-| Cmd/Ctrl+Shift+Z          | Redo a pending change                                           |
-| Backspace/Delete          | Delete the selected annotation                                  |
-| Cmd/Ctrl+Backspace/Delete | Clear all annotations and pending changes                       |
-| Escape                    | Cancel the active edit or deselect the current annotation       |
+| Shortcut                         | Action                                                    |
+| -------------------------------- | --------------------------------------------------------- |
+| Double-tap Command or Control    | Open or collapse Popmelt                                  |
+| `C`                              | Enter Comment mode                                        |
+| `I`                              | Enter Imprint mode                                        |
+| Command/Control+Enter            | Send pending work                                         |
+| Command/Control+Z                | Undo a pending change                                     |
+| Command/Control+Shift+Z          | Redo a pending change                                     |
+| Backspace/Delete                 | Delete the selected annotation                            |
+| Command/Control+Backspace/Delete | Clear all annotations and pending changes                 |
+| Escape                           | Cancel the active edit or deselect the current annotation |
 
-## Advanced setup
+## Bridge commands
 
 Run a bridge without wrapping another command:
 
@@ -254,38 +194,16 @@ Run a bridge without wrapping another command:
 npx @popmelt.com/core bridge
 ```
 
-Stop a detached bridge for the current project:
+Stop the bridge for the current project:
 
 ```bash
 npx @popmelt.com/core stop
 ```
 
-Start a configured bridge in server code:
-
-```ts
-await startPopmelt({
-  port: 1111,
-  projectRoot: '.',
-  devOrigin: 'http://localhost:3000',
-  provider: 'codex',
-  timeoutMs: undefined,
-});
-```
-
-`startPopmelt()` returns the selected port, the stable project ID, and a `close()` function.
-
-## Local project data
-
-Popmelt writes project history under `.popmelt/`. Keep this directory when you want decisions, threads, and the local model to survive across sessions. The browser also uses local storage for unsent annotations and preview edits.
-
 ## License
 
 [PolyForm Shield 1.0.0](./LICENSE)
 
 You may use and extend Popmelt for yourself and your team. You may not sell it, offer it as a managed service, or use the code to create a competing product or service. The software is provided as-is.
 
-For custom licensing, contact [reb@popmelt.com](mailto:reb@popmelt.com).
-
-<p align="center">
-  <img src="src/assets/popmelt-logo.svg" alt="Popmelt" width="64" />
-</p>
+For custom licensing, contact **reb@popmelt.com**.