@popmelt.com/core 0.20.3 → 0.21.1

package/README.md

@@ -36,6 +36,169 @@ To add local object recognition to an existing Popmelt project, use:
 The integration installs See and adds it to the existing Core provider's
 `extensions` array without replacing Core.
 
+### Experimental standalone browser entry
+
+The first framework-independent integration is available at `@popmelt.com/core/browser`.
+It mounts Popmelt beside the host application, without JSX or a React provider in
+your application code. React still renders Popmelt internally; the package's
+existing React, React DOM, and Lucide React peer dependencies are still required.
+This is an experimental DOM integration, not a claim of Vue/Svelte/Angular feature
+parity. React-specific component hierarchy and library previews are not supplied
+for other frameworks yet.
+
+For a Vite host, keep the existing `@popmelt.com/core/vite` bridge plugin, then use
+this in your browser entry:
+
+```js
+if (import.meta.env.DEV) {
+  const { mountPopmelt } = await import('@popmelt.com/core/browser');
+  const popmelt = await mountPopmelt({ enabled: true });
+  import.meta.hot?.dispose(() => popmelt.unmount());
+}
+```
+
+Enablement is explicit: omitted/false `enabled` or a server-side call is a no-op
+and does not load the renderer. `unmount()` removes the UI and releases its
+subscriptions without deleting saved annotations or cancelling bridge jobs.
+Call it before mounting again; simultaneous integrations on one page are rejected.
+Use either this entry or `PopmeltProvider`, not both. Pass `bridgeUrl`, `projectId`,
+or a host-router `navigate` callback when these are not supplied by your integration.
+Explicit bridge/project options take effect before startup and restore prior
+host bindings when unmounted; no manual browser-global assignment is needed.
+
+For Vue, mount your app normally and mount Popmelt alongside it, not inside the
+Vue component tree. Keep your Vue Vite plugin and add `popmelt()` to that same
+plugin list. Connect the returned `unmount()` to your app's teardown (for example,
+`app.onUnmount(() => popmelt.unmount())` in Vue 3.5+). With Vue Router, pass
+`navigate: (url) => router.push(url)`; no router dependency is required by Core.
+
+The plain HTML/JS fixture at `e2e/fixtures/browser` and Vue fixture at
+`e2e/fixtures/vue` share a browser workflow: author and recover an annotation
+draft through target replacement and page reload, submit it, receive streamed
+and final replies, and continue the same thread after another target replacement.
+Both verify durable thread history, stage a Steer edit, select Chat through the
+toolbar, and recover the exact edited style and completed thread after reload.
+Vanilla replacement creates a fresh DOM node without copying Popmelt attributes
+or inline styles; Vue uses keyed rerenders. Both verify teardown/remount releases
+Popmelt's UI and connection while preserving the host DOM and input state.
+
+Vue additionally exercises real Vite SFC template/script hot updates and Vue
+Router navigation/back. Hot updates must retain the same Popmelt renderer and
+bridge connection, without a full-page reload. The tests edit temporary fixture
+copies, not repository files.
+Only the external provider process is controlled; HTTP, SSE, queue dispatch, and
+durable thread storage use the real bridge. It does not run your installed agent.
+Run both fixtures after building:
+
+```sh
+pnpm run build
+pnpm exec vitest run --config vitest.browser.config.ts e2e/browser-mount.browser.ts
+```
+
+For a fresh tarball installation with the real Vite bridge plugin, run
+`pnpm run vue:smoke`. This opt-in check needs npm registry access and Chrome
+(`CHROME_PATH` can override its location). It installs into a temporary Vue app,
+verifies bridge startup/shutdown and the toolbar, and checks that the
+development-only import is absent from production output. It does not publish
+or replace the separate package-size release gate.
+
+The plain HTML/JS fixture still uses Vite and installed npm peers; this does not
+validate a bundler-free script tag or arbitrary static-server integration.
+The journeys use stable target IDs and Chrome, not a cross-browser or arbitrary
+DOM-identity matrix. They validate the client-side DOM boundary, not Vue component
+metadata. Router guards, nested routes, and hash-history mode are
+not yet covered. Vue and its test tooling are development dependencies only;
+they do not add a second Popmelt UI implementation or become runtime dependencies.
+
+### Experimental Nuxt integration
+
+For Nuxt 4.5.2, install Popmelt and its internal renderer peers as development
+dependencies, then add the module:
+
+```sh
+npm install -D @popmelt.com/core react react-dom lucide-react
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@popmelt.com/core/nuxt'],
+});
+```
+
+No separate Vite plugin, React provider, or manual browser mount is needed.
+The module starts the local bridge in development and mounts Popmelt after Nuxt
+has mounted the client app. It uses Nuxt's router for navigation and releases
+its bridge lease on graceful shutdown. When Nuxt's CLI exits immediately, the
+existing lease-expiry cleanup stops an idle bridge within about a minute.
+Production builds do not register the client
+plugin or start the bridge. Optional `popmelt` settings are `port`, `projectRoot`,
+and `bridge` (set `bridge: false` to disable automatic bridge startup).
+
+Run `pnpm run nuxt:smoke` with a Nuxt-compatible Node version (22.19+, 24.11+,
+or 26+) to check a fresh tarball installation. It requires npm registry access
+and Chrome, like the Vue smoke check. The isolated fixture checks SSR/hydration,
+thread recovery through navigation/back and template/script HMR, and production
+exclusion. It also exercises annotation submission, streaming replies, same-thread
+follow-ups, and staged style recovery through routing and reload. Provider responses
+are controlled in that journey; it never launches your coding agent.
+Nuxt 3, component metadata, and advanced router configurations are not yet tested.
+
+### Experimental Svelte and SvelteKit
+
+Tested with Svelte 5.57.0, SvelteKit 2.70.3, and Vite 8.2.2. Install the same
+development dependencies used by the standalone entry:
+
+```sh
+npm install -D @popmelt.com/core react react-dom lucide-react
+```
+
+Keep your existing Vite configuration and add `popmelt()` alongside `sveltekit()`
+(or `svelte()` for a plain Svelte app):
+
+```js
+import { sveltekit } from '@sveltejs/kit/vite';
+import { popmelt } from '@popmelt.com/core/vite';
+
+export default { plugins: [sveltekit(), popmelt()] };
+```
+
+Mount once in your root `+layout.svelte`, without replacing its existing content:
+
+```svelte
+<script>
+  import { onMount } from 'svelte';
+  import { goto } from '$app/navigation';
+  import { bridgeUrl, projectId } from 'virtual:popmelt/bridge';
+
+  onMount(() => {
+    if (!import.meta.env.DEV || !bridgeUrl || !projectId) return;
+    let disposed = false;
+    const pending = import('@popmelt.com/core/browser').then(({ mountPopmelt }) => {
+      if (!disposed) return mountPopmelt({ enabled: true, bridgeUrl, projectId, navigate: goto });
+    });
+    void pending.catch(console.error);
+    return () => {
+      disposed = true;
+      void pending.then((handle) => handle?.unmount()).catch(() => {});
+    };
+  });
+</script>
+```
+
+For plain Svelte, place this in `App.svelte` and omit the `goto` import and
+`navigate` option, or supply your own router callback. TypeScript projects can
+add `/// <reference types="@popmelt.com/core/vite/client" />` to their app's
+ambient declarations for the virtual module types.
+
+This setup is development-only, including during SSR. It does not provide
+Svelte component metadata or framework-specific library previews. Advanced
+Kit routing, form actions, and deployment adapters beyond Node are not yet tested.
+Run `pnpm run svelte:smoke` with Node 24.11+, npm registry access, and Chrome
+to check fresh Svelte and SvelteKit installs; it does not launch your coding agent.
+The SvelteKit check also runs the shared annotation/reply/style-edit journey,
+including same-thread continuation and recovery after navigation and reload.
+
 ## Use Popmelt
 
 1. Run your project locally and open it in a browser
@@ -83,11 +246,14 @@ Imprint opens the project's shared understanding. Use its filters to review grou
 - 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
+- Right-click a replied rail to dismiss it from the canvas without deleting its history or reverting applied edits. Press **Command/Control+Z** outside a text editor to restore it before reloading. Rails with fresh drafts or active runs are protected.
 - When a reply is queued, use its pencil or trash button to edit or delete that individual message before it starts. Save an edit with the checkmark or Command/Control+Enter; Escape cancels the edit
-- Codex permission requests appear in the thread as a compact action card. Expand it to inspect the exact command or file changes, then choose **Allow once** or **Deny**. Chat text is not a permission grant; Popmelt does not create remembered approvals. Your existing Codex permission rules still apply, so previously allowed commands may run without a new card. Unanswered requests expire after ten minutes, and disconnected runs cannot be approved
+- Codex permission requests appear chronologically in the thread as a compact action card, while the canvas and toolbar show **Approval needed**. Expand the card to inspect the exact command or file changes, then choose **Allow once** or **Deny**. Answered requests become an inline tool icon and label, retained in the thread history. Chat text is not a permission grant; Popmelt does not create remembered approvals. Your existing Codex permission rules still apply, so previously allowed commands may run without a new card. After 10 seconds without a response, a run waiting solely on approval yields to other queued jobs. Approving it while parked moves it to the front of the waiting queue, without interrupting active work. The exact action resumes only after reacquiring a slot; unanswered requests expire on resumption (or at 10 seconds if the run cannot safely yield). Same-thread follow-ups cannot overtake a parked run, and disconnected runs cannot be approved.
 
 Interactive approvals require a Codex CLI that supports the app-server human-approval protocol (verified with 0.153.3). Popmelt checks the effective sandbox and reviewer before starting a coding turn; it does not fall back to unrestricted execution. Background memory review remains read-only and noninteractive. Network-specific and session-wide permission grants are not supported by this first version.
 
+For an opt-in automatic-review trial, start the bridge or wrapped dev server with `POPMELT_CODEX_APPROVALS_REVIEWER=auto_review`. Eligible Codex approvals go to its native reviewer rather than a human; the sandbox and existing permission rules remain in place. This adds model usage and may still deny an action. The default remains human review (`user`); restarting without the variable restores it. Other providers are unchanged.
+
 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
@@ -121,6 +287,8 @@ Ambient capture stays out of toolbar-owned runs, so opening a thread from the in
 
 With your app running and the Popmelt canvas active, point at an element and ask Codex, “What am I pointing at?” You can also ask it to inspect a comment or explain what was discussed in an existing thread, without pointing at that item first.
 
+The prompt hook also supplies a small, timestamped snapshot of bridge-managed runs in the conversation's primary and mounted stores: running, awaiting approval, and queued. This conversation is identified separately; other externally hosted conversations are not counted. Reads are bounded to 500 ms and unavailable bridges are reported as unavailable, not idle. This context is advisory—agents must check live status before restarting or interrupting a bridge.
+
 Popmelt supplies the canvas target and lets Codex read saved threads, unsent drafts, and staged changes as separate kinds of context. A small animated eye appears beside the target or its visible annotation rail during targeted tool access—even if the element itself is offscreen. It indicates access to that item, not the full time the agent spends thinking about it. Reading context does not submit your drafts or start another agent run.
 
 When several copies of the app are open, recent canvas interaction helps select the intended page. If the target is still ambiguous, Codex can ask which page you mean instead of guessing. Focus is a timestamped snapshot, so keep the intended target selected or point again when needed.
@@ -248,9 +416,14 @@ export default defineConfig({
 });
 ```
 
-### Astro
+### Experimental Astro integration
 
-Add the Astro integration:
+For Astro 7.3.1, install Popmelt and its internal renderer peers as development
+dependencies, then add the Astro integration:
+
+```sh
+npm install -D @popmelt.com/core react react-dom lucide-react
+```
 
 ```js
 // astro.config.mjs
@@ -262,6 +435,20 @@ export default defineConfig({
 });
 ```
 
+The integration starts the bridge and mounts Popmelt automatically in development;
+no React island or provider is needed. It supports DOM annotations and style edits,
+with thread recovery through reloads and Astro ClientRouter navigation. Production
+builds and previews do not mount Popmelt or start its bridge.
+
+If your project already mounts a Popmelt provider, use `popmelt({ client: false })`
+to keep that provider in charge of the UI. The existing `port`, `projectRoot`,
+`basePath`, and `bridge` options remain available.
+
+Run `pnpm run astro:smoke` with Node 24.11+, npm registry access, and Chrome for
+the fresh-install browser journey. Provider responses are controlled; it does not
+launch your coding agent. Astro component metadata, framework-specific island
+previews, and deployment adapters are not yet covered.
+
 ### Other development servers
 
 The wrapper can start Popmelt alongside another development command:
@@ -439,7 +626,7 @@ Popmelt is designed for local development. As with any AI-assisted coding, your
 | `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+Z                | Undo a pending change or thread dismissal                            |
 | 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                           |

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

@@ -1,6 +1,6 @@
 {
   "name": "popmelt-core",
-  "version": "0.20.3",
+  "version": "0.21.1",
   "description": "Point out what you mean, talk through changes, and keep your AI on the same page.",
   "author": {
     "name": "Popmelt",