@popmelt.com/core 0.12.2 → 0.14.0

package/README.md

@@ -4,13 +4,13 @@
 
 # Popmelt
 
-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 a tiny, powerful design layer for humans and AI. Turn any React repo into a design sandbox with the AI tools you already love.
 
-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.
+Run your app locally and Popmelt appears as a toolbar in the browser. Point to any part of your UI, describe what you have in mind, or steer the design directly. Work through the result with Codex or Claude Code in a thread right on the page. Stack as many threads as you want so different ideas can move forward without losing their context.
 
-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.
+As you collaborate, Popmelt builds an Imprint: a living project memory of your intent, preferences, and design decisions. Later threads 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/`.
+Runs locally, learns naturally. Your annotations, screenshots, threads, and Imprint live with your project under `.popmelt/`.
 
 ## What you need
 
@@ -33,11 +33,61 @@ Your agent can detect the framework, add the provider and integration, and prese
 
 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
+3. Choose Chat (`C`), Steer (`S`), or Imprint (`I`)
+4. Point to the relevant UI to add comments or preview design changes, or use Imprint to review the project's shared understanding
+5. Press Command+Enter on macOS or Control+Enter on Windows and Linux to hand pending work to your coding agent
+6. Review the result in its page-bound thread and keep iterating there
 
-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.
+A handoff can contain several comments and changes, including work on different elements. Popmelt keeps that bundle together as one thread and presents its items separately at the beginning of the conversation. Status stays attached to the relevant parts of the page while work is queued or running, and you can reopen a thread from any of its badges. Tool and Imprint receipts show what helped the agent reach its result.
+
+### Chat
+
+Chat pins a comment to a specific element. Click the element, type the comment, and press Enter to finish the draft. Use Shift+Enter for a new line or Command/Control+Enter to send the full pending bundle.
+
+Double-click visible text to edit it directly. Popmelt records the text change so it can be handed off alongside comments and Steer changes.
+
+### Steer
+
+Steer previews code-native design changes directly on the page. Point to an element, choose a family, narrow to a property, and choose a value. Click the target or press Enter at the value level to stage the preview.
+
+| Keys | Family |
+| --- | --- |
+| `P` / `M` | Padding / margin |
+| `B` / `R` | Borders / radii |
+| `F` / `G` | Flexbox / grid |
+| `FO` / `BG` | Type / background color |
+| `T` / `O` | Transform / opacity and blend mode |
+
+The omnidial can be driven entirely from the keyboard: `Q` and `E` move between properties, `A` and `D` or the arrow keys move between values, `W` or Enter goes deeper or applies, and `S` or Escape goes back. Press Space to search families, properties, colors, and values by name.
+
+At the value level, padding, margin, gap, radius, and transform controls expose drag handles. Hold Shift while dragging to snap or constrain the change. For spacing and radius handles, hold Option/Alt or Control to isolate the touched side, axis, or corner.
+
+### Imprint
+
+Imprint opens the project's shared understanding. Use its filters to review grounded, emerging, and challenged explanations. Expand an explanation to see its rationale, concrete expressions, related understanding, and recent grounding evidence, or reopen its source thread. Changes to the Imprint are proposed and grounded through collaboration in threads rather than authored from this panel.
+
+### Threads and drafts
+
+- Click an annotation or status badge to open its thread
+- Use the left and right chevrons in the thread header to cycle through visible threads
+- Drag a thread header to move the panel; double-click the header to restore its default position
+- Press Escape to close the open thread
+- Press Backspace or Delete with a thread open, or with one of its historical annotations selected, to archive that thread
+- Right-click a draft comment or staged Steer change in its annotation rail to remove only that draft item
+
+Archiving hides a thread from the active canvas without deleting its stored conversation. Delete shortcuts are disabled while a text field is focused.
+
+### Pointer gestures
+
+| Gesture | Action |
+| --- | --- |
+| Shake the pointer quickly | Switch between Chat and Steer |
+| Hold Command/Control while pointing | Pass through the default target to the deepest element under the pointer |
+| Double-click text in Chat | Edit the text directly |
+| Click the toolbar annotation counter | Cycle through annotation bundles, including other routes |
+| Scroll the annotation counter | Change the active annotation color |
+| Hold the annotation counter | Reset the active color |
+| Right-click Popmelt's canvas, then right-click again | Pass through to the page's native context menu |
 
 ## Ambient Popmelt in Codex
 
@@ -68,7 +118,7 @@ As you work, Popmelt recognizes choices that may be useful beyond the current th
 
 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.
+Enter Imprint mode with `I` to inspect the project's current understanding, supporting evidence, relationships, and exceptions.
 
 ## Manual setup
 
@@ -193,17 +243,21 @@ Popmelt is designed for local development. As with any AI-assisted coding, your
 
 ## Useful shortcuts
 
-| 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 |
+| Shortcut | Action |
+| --- | --- |
+| Double-tap Command or Control | Open or collapse Popmelt |
+| `C` | Enter Chat mode |
+| `S` | Enter Steer mode |
+| `I` | Enter Imprint mode |
+| Command/Control+Enter | Send all pending work |
+| Command/Control+C | Capture a screenshot for pending work when no text is selected |
+| Command/Control+Z | Undo a pending change |
+| Command/Control+Shift+Z | Redo a pending change |
+| Backspace/Delete | Archive the open or selected historical thread |
+| Command/Control+Backspace/Delete | Clear all annotations and pending changes |
+| Escape | Go back, cancel, close, discard, or deselect in the current context |
+
+Steer additionally owns the unmodified letter, arrow, Enter, Escape, and Space keys described above while it is active. Popmelt leaves these shortcuts alone while you are typing in an input, textarea, or editable text surface.
 
 ## Bridge commands
 

package/codex-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "popmelt-core",
-  "version": "0.12.2",
+  "version": "0.14.0",
   "description": "Ambient project memory and shared understanding for Codex",
   "author": {
     "name": "Popmelt",