pi-ele-picker 0.4.0 → 0.6.0

package/README.md

@@ -105,6 +105,18 @@ The launcher starts in the **bottom-right** corner and stays out of the way:
    - **写入pi输入框** — pre-fills the current pi input box with the composed prompt; you edit and press Enter.
    - **直接发送** — submits the composed prompt as a real user turn immediately (queued as a follow-up if pi is mid-turn).
 
+### Drafts survive reloads
+
+Vite reloads the page every time you save a file, so the composer is mirrored into `sessionStorage` and re-attached on the next load:
+
+- The description and any attached screenshots come back exactly as they were.
+- The captured element is **snapshotted at pick time and persisted with the draft**, so the element data survives the node being unmounted, an SPA route change, or the reload itself.
+- The captured element is **re-resolved from its selector**, so after an HMR update you land straight back in the panel on the same element — no re-pick.
+- Closing the panel with **✕** also suppresses the automatic reopen; the draft stays reachable through the launcher's hover.
+- **Sending never depends on the element still being on the page.** Pick a button, go copy something from another route, then send — the description goes out with the element as it was when you picked it. A live read is used instead while you are still on the pick-time page, so an HMR swap of the same node is described in its current state; after a route change the snapshot wins, so a lookalike behind the same selector cannot be mistaken for your pick. When a snapshot was used, the status line says so.
+- The draft is per tab and per path (`sessionStorage`, not `localStorage`), and one older than 24h is discarded. A successful send clears it.
+- Screenshots that exceed the ~5MB `sessionStorage` quota are dropped from the draft with a notice rather than silently lost; the description is always kept.
+
 ### Session status
 
 Status polling is **opt-in and off by default**: each cycle opens a loopback request, so it is disabled unless you want it. There are two levels:
@@ -142,6 +154,18 @@ The same payload is available from the bridge directly:
 - If pi restarts while a page is open (new random port + token), the next send re-discovers the bridge and retries once automatically — no page refresh needed. The status poll does the same: a stale port flips to `offline` for one cycle, then rediscovers.
 - The bridge never auto-submits on its own: **写入pi输入框** only fills the editor; **直接发送** is an explicit user action in the page.
 
+## Development
+
+```bash
+npm install
+npm test        # end-to-end suite; starts its own Vite dev server
+npm run typecheck
+```
+
+The suite drives the real browser client inside [`test/fixture`](test/fixture), a throwaway Vite app: it picks elements, types descriptions, attaches screenshots and reloads, then asserts the draft survived. It runs against `src/` and `client/` directly — no build step is needed first, and a broken client fails the tests rather than the published package.
+
+Local runs drive your installed Chrome. To use Playwright's pinned Chromium instead, run `npx playwright install chromium` once and set `PW_BUNDLED=1`; CI always uses the pinned build. `npx playwright test --ui` and `--debug` work as usual, and a failing run keeps a trace in `test-results/`.
+
 ## Releasing
 
 Publishing is token-free: `.github/workflows/release.yml` publishes with **Trusted Publishing (OIDC)**, so `npm publish` authenticates through a short-lived OIDC token minted by GitHub Actions and provenance is attached automatically.

package/client/picker.js

@@ -152,10 +152,22 @@
   // The captured element the panel acts on. Stays put across close/reopen so
   // hovering the launcher can bring the panel back without overwriting it.
   var target = null;
+  // The selector `target` was captured through. Kept so the draft can be
+  // re-attached after a reload replaces the DOM node `target` points at.
+  var targetSelector = null;
+  // Everything about the target captured at pick time. Sending must not depend on
+  // the node still being on the page — see elementPayload().
+  var targetSnapshot = null;
+  // The URL the target was picked on. A selector only identifies an element within
+  // one document: after a route change the same selector may hit a lookalike.
+  var targetUrl = null;
   var shots = [];
   // Set when a pick commits on pointerdown; swallows the follow-up click so the
   // page (links, buttons) never reacts to the click that finished the pick.
   var swallowClick = false;
+  // Set when the user closes the panel themselves, so a reload does not pop it
+  // back open on top of whatever they moved on to.
+  var panelDismissed = false;
 
   document.documentElement.appendChild(host);
 
@@ -485,22 +497,46 @@
     }
   }
 
-  /** Re-show the panel for the element already captured — no re-pick, no overwrite. */
+  /**
+   * Re-show the panel for the element already captured — no re-pick, no overwrite.
+   *
+   * A snapshot is enough to reopen: the developer may have navigated away from the
+   * page that element lives on, and losing access to their own draft over that
+   * would be the wrong trade. The highlight is simply skipped when there is
+   * nothing on screen to outline.
+   */
   function openPanel() {
-    if (!target) return false;
+    var el = resolveTarget();
+    if (!el && !targetSnapshot) return false;
     panel.classList.add('open');
-    showHighlight(target);
+    if (el) showHighlight(el);
+    else hideHighlight();
     positionPanel();
     return true;
   }
 
   function select(el) {
     target = el;
-    metaEl.innerHTML = '<code>' + escapeHtml(cssPath(el)) + '</code>' + vueLine(el);
+    targetSelector = cssPath(el);
+    targetSnapshot = describe(el);
+    targetUrl = location.href;
+    // A new pick re-arms the draft: the user is working again, so a reload must
+    // bring the panel back even if they closed it earlier.
+    panelDismissed = false;
+    metaEl.innerHTML = '<code>' + escapeHtml(targetSelector) + '</code>' + vueLine(el);
     openPanel();
+    saveDraft();
     taEl.focus();
   }
 
+  /**
+   * The element description handed to the bridge is chosen in send(), because the
+   * choice between a live read and the snapshot has to be reported to the user.
+   * Describing a detached node is never an option: `getComputedStyle()` and
+   * `getBoundingClientRect()` return nothing useful once it leaves the document, so
+   * the fallback has to be the captured value, not a fresh read.
+   */
+
   function vueLine(el) {
     var v = vueInfo(el);
     if (v.componentFile) return '<br>组件: <code>' + escapeHtml((v.componentName ? v.componentName + ' ' : '') + v.componentFile) + '</code>';
@@ -593,6 +629,7 @@
   function addShot(dataUrl) {
     shots.push(dataUrl);
     renderShots();
+    saveShots();
   }
 
   function renderShots() {
@@ -609,6 +646,7 @@
       x.addEventListener('click', function () {
         shots.splice(i, 1);
         renderShots();
+        saveShots();
       });
       d1.appendChild(img);
       d1.appendChild(x);
@@ -627,6 +665,234 @@
     });
   }
 
+  /* --- draft persistence ---------------------------------------------------
+   *
+   * Vite reloads the page on every save, and the composer is by far the most
+   * expensive thing in this tool to lose: a couple of hundred words of
+   * description plus a few pasted screenshots. So the draft is mirrored into
+   * `sessionStorage` and re-attached on the next boot.
+   *
+   * `sessionStorage`, not `localStorage`: a draft belongs to the tab that
+   * produced it and must not follow the developer into a fresh window.
+   *
+   * Two keys on purpose. The text changes on every keystroke while the shots
+   * change rarely; re-serialising megabytes of base64 per keypress would both
+   * stutter the panel and hit the ~5MB quota needlessly. The text key stays
+   * tiny so writing it aggressively is cheap, and the shots key is rewritten
+   * only when the shot set actually changes.
+   *
+   * Everything here is best-effort: a storage failure must never break the
+   * editor, only lose the draft.
+   */
+  var DRAFT_PREFIX = 'pi-ele-picker:draft:v1';
+  var SHOTS_PREFIX = 'pi-ele-picker:shots:v1';
+  var SAVE_DEBOUNCE = 250;
+  // A draft left over from a tab that stayed open for days is more confusing than
+  // helpful: it describes an element that has almost certainly moved on.
+  var DRAFT_TTL = 24 * 60 * 60 * 1000;
+  var saveTimer = null;
+  // True while an edit has not reached storage yet, so a page that is going
+  // away flushes exactly once and a delivered draft is not resurrected.
+  var draftDirty = false;
+  var shotsDropped = false;
+
+  function draftKey() {
+    return DRAFT_PREFIX + ':' + location.pathname;
+  }
+
+  function shotsKey() {
+    return SHOTS_PREFIX + ':' + location.pathname;
+  }
+
+  /** Never throws: returns false when storage is full or unavailable. */
+  function writeStorage(key, value) {
+    try {
+      sessionStorage.setItem(key, value);
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+
+  function removeStorage(key) {
+    try {
+      sessionStorage.removeItem(key);
+    } catch (e) {
+      /* storage unavailable — nothing to clear */
+    }
+  }
+
+  function readStorage(key) {
+    try {
+      return sessionStorage.getItem(key);
+    } catch (e) {
+      return null;
+    }
+  }
+
+  function saveShots() {
+    if (!shots.length) {
+      removeStorage(shotsKey());
+      shotsDropped = false;
+      return;
+    }
+    if (writeStorage(shotsKey(), JSON.stringify(shots))) {
+      shotsDropped = false;
+      return;
+    }
+    // The images do not fit. Keep the words and say so once, so a reload does not
+    // silently eat the screenshots that were just pasted.
+    removeStorage(shotsKey());
+    if (!shotsDropped) {
+      shotsDropped = true;
+      setStatus('截图过大，刷新后不会保留（描述仍会保存）', 'err');
+    }
+  }
+
+  function saveDraft() {
+    var rec = {
+      selector: targetSelector,
+      text: taEl.value,
+      // The element as it was when it was picked. Persisted because the reload
+      // that restores the draft is often the same one that removed the node —
+      // without this the send below could only go out with no element at all.
+      element: targetSnapshot,
+      url: targetUrl,
+      dismissed: panelDismissed,
+      savedAt: Date.now(),
+    };
+    if (!rec.text && !rec.selector && !rec.element) {
+      // Nothing worth restoring — do not resurrect an empty panel on reload.
+      clearDraft();
+      return;
+    }
+    // Stay dirty when the write fails, so a page that is going away retries.
+    if (writeStorage(draftKey(), JSON.stringify(rec))) draftDirty = false;
+  }
+
+  /** Debounced text write: the keystroke path must stay cheap. */
+  function scheduleSave() {
+    draftDirty = true;
+    if (saveTimer) clearTimeout(saveTimer);
+    saveTimer = setTimeout(function () {
+      saveTimer = null;
+      saveDraft();
+    }, SAVE_DEBOUNCE);
+  }
+
+  /** Write any pending edit right now — the page is being torn down. */
+  function flushDraft() {
+    if (!draftDirty && !saveTimer) return;
+    if (saveTimer) clearTimeout(saveTimer);
+    saveTimer = null;
+    saveDraft();
+  }
+
+  /** Forget the draft: it has been delivered, or it is stale garbage. */
+  function clearDraft() {
+    if (saveTimer) clearTimeout(saveTimer);
+    saveTimer = null;
+    draftDirty = false;
+    shotsDropped = false;
+    removeStorage(draftKey());
+    removeStorage(shotsKey());
+  }
+
+  /**
+   * The live element the panel acts on.
+   *
+   * `target` is a DOM reference captured at pick time, so an HMR update — or any
+   * re-render that swaps the node — leaves it detached. Re-resolving from the
+   * remembered selector keeps the panel pointed at the right element without
+   * asking the user to pick again, and returns null when the element is really
+   * gone, which is what send() and openPanel() need to know.
+   */
+  function resolveTarget() {
+    if (target && target.isConnected) return target;
+    if (targetSelector) {
+      try {
+        var el = document.querySelector(targetSelector);
+        if (el) {
+          target = el;
+          return el;
+        }
+      } catch (e) {
+        /* not valid CSS (Tailwind-style class names) — cannot re-resolve */
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Re-attach the draft written before this page load.
+   *
+   * The element is re-resolved from its selector rather than trusted blindly:
+   * an HMR update replaces DOM nodes, so a captured `target` reference is dead by
+   * the time the page comes back. If the selector no longer resolves, the text
+   * and screenshots are still restored into the composer, so the next pick
+   * inherits them instead of the user retyping everything.
+   */
+  function restoreDraft() {
+    var raw = readStorage(draftKey());
+    if (!raw) return;
+    var rec;
+    try {
+      rec = JSON.parse(raw);
+    } catch (e) {
+      clearDraft();
+      return;
+    }
+    if (!rec || typeof rec !== 'object') {
+      clearDraft();
+      return;
+    }
+    if (typeof rec.savedAt === 'number' && Date.now() - rec.savedAt > DRAFT_TTL) {
+      clearDraft();
+      return;
+    }
+
+    taEl.value = typeof rec.text === 'string' ? rec.text : '';
+
+    var rawShots = readStorage(shotsKey());
+    if (rawShots) {
+      try {
+        var arr = JSON.parse(rawShots);
+        if (arr instanceof Array) {
+          shots = arr.filter(function (d) {
+            return typeof d === 'string' && d.indexOf('data:image/') === 0;
+          });
+          renderShots();
+        }
+      } catch (e) {
+        removeStorage(shotsKey());
+      }
+    }
+
+    if (rec.selector) targetSelector = String(rec.selector);
+    if (rec.url) targetUrl = String(rec.url);
+    if (rec.element && typeof rec.element === 'object') targetSnapshot = rec.element;
+
+    var el = targetSelector ? resolveTarget() : null;
+    if (el) {
+      metaEl.innerHTML = '<code>' + escapeHtml(targetSelector) + '</code>' + vueLine(el);
+    } else if (targetSnapshot) {
+      // Still sendable: the snapshot carries everything the bridge needs.
+      metaEl.innerHTML =
+        '<code>' + escapeHtml(targetSelector || '') + '</code><br>' +
+        '上次选中的元素已不在页面中，发送时会带上抓取时的快照';
+    }
+
+    if (rec.dismissed) return;
+    if (openPanel()) return;
+    if (!taEl.value && !shots.length) return;
+    // No element at all (not even a snapshot) but there are words: show the
+    // composer so the draft is visibly still there, and let the next pick attach
+    // it to a new element.
+    panel.classList.add('open');
+    metaEl.textContent = '上次选中的元素已不在页面中，请重新点击选择';
+    positionPanel();
+  }
+
   function loadConfig(force) {
     if (!force && cfg.port) return Promise.resolve(cfg);
     return fetch(CFG_URL, { cache: 'no-store' })
@@ -643,14 +909,16 @@
   }
 
   /** POST the payload to the bridge. Never rejects; status 0 means the fetch itself failed. */
-  function deliver(c, submit) {
+  function deliver(c, submit, element) {
     var payload = {
       text: taEl.value,
       images: shots.map(function (d, i) {
         return { name: 'shot-' + i + '.png', dataUrl: d };
       }),
-      element: describe(target),
-      url: location.href,
+      element: element,
+      // The page the element lives on, which is not necessarily the page that is
+      // open right now.
+      url: targetUrl || location.href,
       title: document.title,
       submit: !!submit,
     };
@@ -687,6 +955,32 @@
   }
 
   function send(submit) {
+    // Deliberately NOT gated on the element still being on the page. Picking an
+    // element and then wandering off to another route to copy something is a
+    // normal way to work, and blocking the send there throws away the words the
+    // developer typed.
+    //
+    // Two sources for the element, and the wrong one silently corrupts the payload:
+    // the snapshot captured at pick time (a plain value, so it survives an unmount,
+    // an SPA route change or a reload), and a live read of whatever the selector
+    // resolves to now. A live read wins only while we are still on the pick-time
+    // URL — an HMR swap of the same element is the case that needs it, while a
+    // route change can put an unrelated lookalike behind the same selector.
+    var live = resolveTarget();
+    var samePage = targetUrl === null || location.href === targetUrl;
+    var element = live && samePage ? describe(live) : targetSnapshot;
+    if (element) targetSnapshot = element;
+
+    if (!element && !taEl.value.trim()) {
+      setStatus('请先点击页面元素，或写下要改什么', 'err');
+      return;
+    }
+
+    // Only ever affects the status line, never whether the send happens.
+    var note = '';
+    if (element && !live) note = '（元素已不在页面中，已附抓取时的快照）';
+    else if (element && !samePage) note = '（页面已切换，已附抓取时的元素快照）';
+
     sendBtn.disabled = true;
     sendNowBtn.disabled = true;
     setStatus(submit ? '直接发送中…' : '写入中…');
@@ -694,7 +988,7 @@
     function attempt(forceFresh) {
       return loadConfig(forceFresh).then(function (c) {
         if (!c || !c.port) return { status: 0, body: null, noBridge: true };
-        return deliver(c, submit);
+        return deliver(c, submit, element);
       });
     }
 
@@ -712,14 +1006,22 @@
           return;
         }
         if (out.body && out.body.ok) {
+          // Say which element went out, so a stale pick is visible rather than silent.
           if (out.body.submitted) {
-            setStatus(out.body.queued ? '已发送 ✓（agent 忙碌，已排队为后续任务）' : '已直接发送给 pi 并开始执行 ✓', 'ok');
+            setStatus(
+              (out.body.queued ? '已发送 ✓（agent 忙碌，已排队为后续任务）' : '已直接发送给 pi 并开始执行 ✓') + note,
+              'ok'
+            );
           } else {
-            setStatus(out.body.inserted ? '已写入 pi 输入框 ✓（去终端按回车发送）' : '已发送给 pi ✓', 'ok');
+            setStatus(
+              (out.body.inserted ? '已写入 pi 输入框 ✓（去终端按回车发送）' : '已发送给 pi ✓') + note,
+              'ok'
+            );
           }
           taEl.value = '';
           shots = [];
           renderShots();
+          clearDraft();
         } else {
           setStatus('失败: ' + ((out.body && out.body.error) || out.error || 'HTTP ' + out.status), 'err');
         }
@@ -777,6 +1079,10 @@
     panel.classList.remove('open');
     hideHighlight();
     setStatus('');
+    // Remember the dismissal so a reload does not pop the panel back open, while
+    // the draft stays available through the launcher's hover-to-reopen.
+    panelDismissed = true;
+    saveDraft();
   });
   attachBtn.addEventListener('click', function () {
     fileEl.click();
@@ -791,6 +1097,8 @@
   sendNowBtn.addEventListener('click', function () {
     send(true);
   });
+  taEl.addEventListener('input', scheduleSave);
+  window.addEventListener('pagehide', flushDraft);
   taEl.addEventListener('paste', function (e) {
     var items = e.clipboardData && e.clipboardData.items;
     if (!items) return;
@@ -944,4 +1252,8 @@
     var override = readStatusOverride();
     setStatusEnabled(override !== null ? override : cfg && cfg.statusDefault === true, false);
   });
+
+  // Last: the draft restore depends on state initialised above it (launcher
+  // position, panel offset) and on the draft storage keys being assigned.
+  restoreDraft();
 })();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ele-picker",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Pick an element in your running page, describe the change, and send it to a pi session. Ships a Vite dev plugin (browser picker + discovery endpoint) and the matching pi bridge extension.",
   "type": "module",
   "license": "MIT",
@@ -54,7 +54,8 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "test": "playwright test",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
@@ -70,6 +71,7 @@
     }
   },
   "devDependencies": {
+    "@playwright/test": "^1.64.1",
     "@types/node": "^20.11.0",
     "tsup": "^8.0.0",
     "typescript": "^5.4.0",