morph-embed 0.1.0 → 0.2.0

package/dist/morph-embed.js

@@ -1,4 +1,4 @@
-/*! Morph Embed SDK v0.1.0 — https://usemorph.xyz — MIT */
+/*! Morph Embed SDK v0.2.0 — https://usemorph.xyz — MIT */
 
 /* ---- shared/dsl.js ---- */
 /*
@@ -1320,151 +1320,255 @@
 
 
 /* ---- sdk/src/storage.js ---- */
-/*
- * Morph SDK — recipe store. Persists one recipe per page path so generated
- * widgets/reshapes reapply on every visit. Default backing is localStorage
- * (per-browser); a vendor may pass a custom adapter {get,set,remove} (sync or
- * Promise) to store recipes in their own backend so a user's generated
- * features follow them across devices. Storage failures NEVER throw — a
- * broken store must never break the host page.
- * UMD: Node module in tests, browser global `MorphStorage` in the SDK bundle.
- */
-(function (global, factory) {
-  const api = factory();
-  if (typeof module !== 'undefined' && module.exports) module.exports = api;
-  else global.MorphStorage = api;
-})(typeof self !== 'undefined' ? self : this, function () {
-  'use strict';
-
-  const PREFIX = 'morph:sdk:recipe:';
-  const SCHEMA_VERSION = 1;
-  const MAX_PROMPT_LABEL = 300;
-
-  // Default adapter: window.localStorage, JSON values, fully guarded.
-  function localAdapter() {
-    function ls() {
-      try {
-        return (typeof window !== 'undefined' && window.localStorage) ? window.localStorage : null;
-      } catch (_) { return null; } // SecurityError in sandboxed frames
-    }
-    return {
-      get(key) {
-        const s = ls();
-        if (!s) return undefined;
-        const raw = s.getItem(key);
-        if (raw == null) return undefined;
-        try { return JSON.parse(raw); } catch (_) { return undefined; }
-      },
-      set(key, value) {
-        const s = ls();
-        if (!s) return;
-        s.setItem(key, JSON.stringify(value));
-      },
-      remove(key) {
-        const s = ls();
-        if (!s) return;
-        s.removeItem(key);
-      },
-    };
-  }
-
-  // mergeTransforms concats; recipes must UNION. Drop structurally identical
-  // ops (first occurrence wins) so repeating a prompt can't bloat the recipe.
-  function dedupeOps(transform) {
-    if (!transform || !Array.isArray(transform.ops)) return transform;
-    const seen = new Set();
-    const ops = transform.ops.filter((op) => {
-      let key;
-      try { key = JSON.stringify(op); } catch (_) { return true; }
-      if (seen.has(key)) return false;
-      seen.add(key);
-      return true;
-    });
-    return Object.assign({}, transform, { ops });
-  }
-
-  // Dedupe prompt-label segments exactly like extension/src/recipes.js
-  // appendTransform: never re-append a segment that is already present.
-  function mergePrompt(existingPrompt, incoming) {
-    if (existingPrompt && incoming) {
-      const dup = existingPrompt.split(' + ')
-        .some((s) => s.trim().toLowerCase() === incoming.trim().toLowerCase());
-      return dup ? existingPrompt : String(existingPrompt + ' + ' + incoming).slice(0, MAX_PROMPT_LABEL);
-    }
-    return incoming || existingPrompt || '';
-  }
-
-  function createStore(adapter) {
-    const backing = (adapter && typeof adapter === 'object') ? adapter : localAdapter();
-    const keyOf = (pathKey) => PREFIX + String(pathKey || '/');
-
-    // Serialize read-modify-write so rapid appends can't lose ops (same
-    // pattern as extension/src/recipes.js).
-    let writeChain = Promise.resolve();
-    function serialize(fn) {
-      const run = writeChain.then(fn, fn);
-      writeChain = run.then(() => {}, () => {});
-      return run;
-    }
-
-    async function loadRecipe(pathKey) {
-      try {
-        const v = await backing.get(keyOf(pathKey));
-        return (v && typeof v === 'object') ? v : null;
-      } catch (_) { return null; }
-    }
-
-    function saveRecipe(pathKey, recipe) {
-      return serialize(async () => {
-        try {
-          const merged = Object.assign(
-            { path: String(pathKey || '/'), enabled: true, createdAt: Date.now() },
-            recipe,
-            { schemaVersion: SCHEMA_VERSION, path: String(pathKey || '/') }
-          );
-          await backing.set(keyOf(pathKey), merged);
-          return merged;
-        } catch (_) { return null; }
-      });
-    }
-
-    function appendTransform(pathKey, transform, meta, mergeFn) {
-      return serialize(async () => {
-        try {
-          let existing = null;
-          try { existing = await backing.get(keyOf(pathKey)); } catch (_) { /* treat as none */ }
-          if (!existing || typeof existing !== 'object') existing = null;
-          const mergedTransform = dedupeOps(
-            (existing && existing.transform && typeof mergeFn === 'function')
-              ? mergeFn(existing.transform, transform)
-              : transform
-          );
-          const prompt = mergePrompt(existing && existing.prompt, (meta && meta.prompt) || '');
-          const merged = Object.assign(
-            { path: String(pathKey || '/'), createdAt: Date.now() },
-            existing || {},
-            {
-              path: String(pathKey || '/'), prompt, transform: mergedTransform,
-              enabled: true, schemaVersion: SCHEMA_VERSION,
-            }
-          );
-          await backing.set(keyOf(pathKey), merged);
-          return merged;
-        } catch (_) { return null; }
-      });
-    }
-
-    function removeRecipe(pathKey) {
-      return serialize(async () => {
-        try { await backing.remove(keyOf(pathKey)); } catch (_) { /* never throws */ }
-      });
-    }
-
-    return { loadRecipe, saveRecipe, appendTransform, removeRecipe };
-  }
-
-  return { createStore, SCHEMA_VERSION };
-});
+/*
+ * Morph SDK — recipe store. SCHEMA v2: a recipe is a LIST OF EDITS
+ * ({id, prompt, ts, enabled, transform}) per page path, which is what makes
+ * per-edit undo, history, and toggling possible in the SDK UI (Nielsen #3,
+ * user control and freedom). v1 recipes (one merged blob) migrate on read.
+ *
+ * Default backing is localStorage (per-browser); a vendor may pass a custom
+ * adapter {get,set,remove} (sync or Promise) to store recipes in their own
+ * backend so a user's generated features follow them across devices.
+ * Storage failures NEVER throw — a broken store must never break the host page.
+ * UMD: Node module in tests, browser global `MorphStorage` in the SDK bundle.
+ */
+(function (global, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else global.MorphStorage = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+  'use strict';
+
+  const PREFIX = 'morph:sdk:recipe:';
+  const SCHEMA_VERSION = 2;
+  const MAX_PROMPT_LABEL = 300;
+  const MAX_EDITS = 20;
+
+  // Default adapter: window.localStorage, JSON values, fully guarded.
+  function localAdapter() {
+    function ls() {
+      try {
+        return (typeof window !== 'undefined' && window.localStorage) ? window.localStorage : null;
+      } catch (_) { return null; } // SecurityError in sandboxed frames
+    }
+    return {
+      get(key) {
+        const s = ls();
+        if (!s) return undefined;
+        const raw = s.getItem(key);
+        if (raw == null) return undefined;
+        try { return JSON.parse(raw); } catch (_) { return undefined; }
+      },
+      set(key, value) {
+        const s = ls();
+        if (!s) return;
+        s.setItem(key, JSON.stringify(value));
+      },
+      remove(key) {
+        const s = ls();
+        if (!s) return;
+        s.removeItem(key);
+      },
+    };
+  }
+
+  function genId() {
+    return 'e_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+  }
+
+  // mergeTransforms concats; recipes must UNION. Drop structurally identical
+  // ops (first occurrence wins) so repeating a prompt can't bloat the recipe.
+  function dedupeOps(transform) {
+    if (!transform || !Array.isArray(transform.ops)) return transform;
+    const seen = new Set();
+    const ops = transform.ops.filter((op) => {
+      let key;
+      try { key = JSON.stringify(op); } catch (_) { return true; }
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+    return Object.assign({}, transform, { ops });
+  }
+
+  // Merge the ENABLED edits, in order, into one transform (deduped). Returns
+  // null when nothing is enabled. mergeFn is DSL.mergeTransforms when the
+  // caller has the DSL; the concat fallback keeps this module dependency-free.
+  function composeEdits(edits, mergeFn) {
+    const enabled = (Array.isArray(edits) ? edits : []).filter((e) => e && e.enabled !== false && e.transform);
+    if (!enabled.length) return null;
+    let merged = enabled[0].transform;
+    for (let i = 1; i < enabled.length; i++) {
+      merged = (typeof mergeFn === 'function')
+        ? mergeFn(merged, enabled[i].transform)
+        : Object.assign({}, merged, { ops: (merged.ops || []).concat(enabled[i].transform.ops || []) });
+    }
+    return dedupeOps(merged);
+  }
+
+  // Human label for the whole recipe: unique enabled-edit prompts, in order.
+  function promptLabel(edits) {
+    const seen = new Set();
+    const parts = [];
+    for (const e of Array.isArray(edits) ? edits : []) {
+      if (!e || e.enabled === false) continue;
+      const p = String(e.prompt || '').trim();
+      const k = p.toLowerCase();
+      if (!p || seen.has(k)) continue;
+      seen.add(k);
+      parts.push(p);
+    }
+    return parts.join(' + ').slice(0, MAX_PROMPT_LABEL);
+  }
+
+  // Any stored shape -> v2. v1 recipes (single merged transform) become one
+  // edit so nothing a user saved before the redesign is lost.
+  function migrate(raw, pathKey) {
+    const base = { path: String(pathKey || '/'), enabled: true, schemaVersion: SCHEMA_VERSION, createdAt: (raw && raw.createdAt) || Date.now(), edits: [] };
+    if (!raw || typeof raw !== 'object') return base;
+    if (Array.isArray(raw.edits)) {
+      base.edits = raw.edits.filter((e) => e && typeof e === 'object' && e.transform);
+      return base;
+    }
+    if (raw.transform) {
+      base.edits = [{
+        id: genId(),
+        prompt: String(raw.prompt || 'Earlier changes').slice(0, MAX_PROMPT_LABEL),
+        ts: raw.createdAt || Date.now(),
+        enabled: raw.enabled !== false,
+        transform: raw.transform,
+      }];
+    }
+    return base;
+  }
+
+  function createStore(adapter) {
+    const backing = (adapter && typeof adapter === 'object') ? adapter : localAdapter();
+    const keyOf = (pathKey) => PREFIX + String(pathKey || '/');
+
+    // Serialize read-modify-write so rapid appends can't lose edits (same
+    // pattern as extension/src/recipes.js).
+    let writeChain = Promise.resolve();
+    function serialize(fn) {
+      const run = writeChain.then(fn, fn);
+      writeChain = run.then(() => {}, () => {});
+      return run;
+    }
+
+    async function readMigrated(pathKey) {
+      let raw;
+      try { raw = await backing.get(keyOf(pathKey)); } catch (_) { raw = undefined; }
+      if (!raw || typeof raw !== 'object') return null;
+      return migrate(raw, pathKey);
+    }
+
+    async function persist(pathKey, recipe) {
+      await backing.set(keyOf(pathKey), recipe);
+      return recipe;
+    }
+
+    // Back-compat read shape: composed transform + merged prompt + the edits.
+    async function loadRecipe(pathKey) {
+      try {
+        const r = await readMigrated(pathKey);
+        if (!r) return null;
+        return {
+          path: r.path,
+          enabled: r.edits.some((e) => e.enabled !== false),
+          prompt: promptLabel(r.edits),
+          transform: composeEdits(r.edits),
+          edits: r.edits,
+          schemaVersion: SCHEMA_VERSION,
+          createdAt: r.createdAt,
+        };
+      } catch (_) { return null; }
+    }
+
+    function saveRecipe(pathKey, recipe) {
+      return serialize(async () => {
+        try {
+          const merged = Object.assign(
+            { path: String(pathKey || '/'), enabled: true, createdAt: Date.now() },
+            recipe,
+            { schemaVersion: SCHEMA_VERSION, path: String(pathKey || '/') }
+          );
+          await persist(pathKey, merged);
+          return merged;
+        } catch (_) { return null; }
+      });
+    }
+
+    // Add one edit (the unit of undo/history). Returns the new edit or null.
+    function appendEdit(pathKey, transform, meta) {
+      return serialize(async () => {
+        try {
+          const r = (await readMigrated(pathKey)) || migrate(null, pathKey);
+          const edit = {
+            id: genId(),
+            prompt: String((meta && meta.prompt) || '').slice(0, MAX_PROMPT_LABEL),
+            ts: Date.now(),
+            enabled: true,
+            transform,
+          };
+          r.edits.push(edit);
+          if (r.edits.length > MAX_EDITS) r.edits.splice(0, r.edits.length - MAX_EDITS);
+          await persist(pathKey, r);
+          return edit;
+        } catch (_) { return null; }
+      });
+    }
+
+    async function listEdits(pathKey) {
+      try {
+        const r = await readMigrated(pathKey);
+        return r ? r.edits : [];
+      } catch (_) { return []; }
+    }
+
+    function setEditEnabled(pathKey, id, enabled) {
+      return serialize(async () => {
+        try {
+          const r = await readMigrated(pathKey);
+          if (!r) return false;
+          const edit = r.edits.find((e) => e.id === id);
+          if (!edit) return false;
+          edit.enabled = enabled !== false;
+          await persist(pathKey, r);
+          return true;
+        } catch (_) { return false; }
+      });
+    }
+
+    function removeEdit(pathKey, id) {
+      return serialize(async () => {
+        try {
+          const r = await readMigrated(pathKey);
+          if (!r) return false;
+          const i = r.edits.findIndex((e) => e.id === id);
+          if (i < 0) return false;
+          r.edits.splice(i, 1);
+          await persist(pathKey, r);
+          return true;
+        } catch (_) { return false; }
+      });
+    }
+
+    // v1 API kept for existing callers: appends as an edit under the hood.
+    function appendTransform(pathKey, transform, meta, mergeFn) {
+      return appendEdit(pathKey, transform, meta).then((edit) => (edit ? loadRecipe(pathKey) : null), () => null);
+    }
+
+    function removeRecipe(pathKey) {
+      return serialize(async () => {
+        try { await backing.remove(keyOf(pathKey)); } catch (_) { /* never throws */ }
+      });
+    }
+
+    return { loadRecipe, saveRecipe, appendTransform, appendEdit, listEdits, setEditEnabled, removeEdit, removeRecipe };
+  }
+
+  return { createStore, composeEdits, SCHEMA_VERSION };
+});
 
 
 /* ---- extension/src/context.js ---- */
@@ -2185,6 +2289,301 @@
 })();
 
 
+/* ---- sdk/src/ui.js ---- */
+/*
+ * Morph SDK — UI layer: launcher + edits panel + undo toast, isolated in a
+ * closed-over Shadow DOM so host-page CSS can't leak in either direction.
+ *
+ * Every behavior here is deliberate, from the sprint's research pass:
+ *  - The launcher is small, corner-pinned, and NEVER auto-opens (Baymard's
+ *    live-chat testing: sticky elements that act on their own are "highly
+ *    disruptive"; everything is user-initiated).
+ *  - First-run pulse fires exactly once (persisted flag) and not at all under
+ *    prefers-reduced-motion (NN/g animation-usability).
+ *  - Edits apply immediately and the toast offers Undo afterwards — the Gmail
+ *    pattern; confirmation-first dialogs habituate and fail (NN/g).
+ *  - The panel gives per-edit visibility, toggle, and delete — HAX G17
+ *    "provide global controls", Nielsen #3 "user control and freedom".
+ *  - The launcher menu never has more than two options (Hick's law), and the
+ *    whole surface is at most two disclosure levels deep (NN/g progressive
+ *    disclosure).
+ * UMD: Node module in tests, browser global `MorphUI` in the SDK bundle.
+ */
+(function (global, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else global.MorphUI = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+  'use strict';
+
+  const HOST_ID = 'morph-sdk-ui';
+  const NUDGE_FLAG = 'morph:sdk:nudged';
+
+  const CSS = `
+    :host { all: initial; }
+    * { box-sizing: border-box; font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; }
+    .morph-ui-root { position: fixed; z-index: 2147483600; bottom: 20px; right: 20px;
+      display: flex; flex-direction: column; align-items: flex-end; gap: 10px; }
+    .morph-ui-root.pos-bottom-left { right: auto; left: 20px; align-items: flex-start; }
+
+    .morph-fab { width: 46px; height: 46px; border-radius: 50%; border: none; cursor: pointer;
+      background: var(--morph-accent, #111114); color: #fff; font-size: 20px; line-height: 1;
+      box-shadow: 0 4px 18px rgba(0,0,0,.28); display: flex; align-items: center; justify-content: center;
+      position: relative; transition: transform .12s ease; }
+    .morph-fab:hover { transform: scale(1.06); }
+    .morph-fab:focus-visible { outline: 2px solid #4c8dff; outline-offset: 2px; }
+    .morph-fab.pulse { animation: morphPulse 1.6s ease-out 2; }
+    @keyframes morphPulse {
+      0% { box-shadow: 0 0 0 0 rgba(76,141,255,.55), 0 4px 18px rgba(0,0,0,.28); }
+      100% { box-shadow: 0 0 0 16px rgba(76,141,255,0), 0 4px 18px rgba(0,0,0,.28); }
+    }
+    @media (prefers-reduced-motion: reduce) { .morph-fab.pulse { animation: none; } }
+
+    .morph-badge { position: absolute; top: -4px; right: -4px; min-width: 18px; height: 18px;
+      border-radius: 9px; background: #e8554d; color: #fff; font-size: 11px; font-weight: 700;
+      display: none; align-items: center; justify-content: center; padding: 0 5px; }
+    .morph-badge.show { display: flex; }
+
+    .morph-menu { display: none; flex-direction: column; background: #fff; border-radius: 10px;
+      box-shadow: 0 8px 30px rgba(0,0,0,.22); overflow: hidden; min-width: 200px; }
+    .morph-menu.open { display: flex; }
+    .morph-menu-item { border: none; background: none; text-align: left; padding: 12px 16px;
+      font-size: 13.5px; color: #17171c; cursor: pointer; display: flex; gap: 9px; align-items: center; }
+    .morph-menu-item:hover { background: #f2f3f7; }
+
+    .morph-panel { display: none; width: 320px; max-height: 420px; overflow: auto; background: #fff;
+      border-radius: 12px; box-shadow: 0 10px 38px rgba(0,0,0,.26); padding: 14px 14px 10px; }
+    .morph-panel.open { display: block; }
+    .morph-panel h3 { margin: 0 0 2px; font-size: 13px; color: #17171c; }
+    .morph-panel .morph-panel-sub { margin: 0 0 10px; font-size: 11px; color: #7a7a85; }
+    .morph-edit-row { display: flex; align-items: center; gap: 8px; padding: 8px 4px;
+      border-top: 1px solid #eef0f4; }
+    .morph-edit-label { flex: 1; min-width: 0; }
+    .morph-edit-label .p { font-size: 12.5px; color: #17171c; overflow: hidden; text-overflow: ellipsis;
+      white-space: nowrap; }
+    .morph-edit-label .t { font-size: 10.5px; color: #9a9aa5; }
+    .morph-edit-row.off .morph-edit-label .p { color: #9a9aa5; text-decoration: line-through; }
+    .morph-edit-toggle { width: 32px; height: 18px; border-radius: 9px; border: none; cursor: pointer;
+      background: #cfd3dc; position: relative; flex: none; }
+    .morph-edit-toggle::after { content: ""; position: absolute; top: 2px; left: 2px; width: 14px; height: 14px;
+      border-radius: 50%; background: #fff; transition: left .12s ease; }
+    .morph-edit-toggle[aria-checked="true"] { background: var(--morph-accent, #2f9e63); }
+    .morph-edit-toggle[aria-checked="true"]::after { left: 16px; }
+    .morph-edit-delete { border: none; background: none; color: #b9bcc6; cursor: pointer; font-size: 15px;
+      padding: 4px; flex: none; }
+    .morph-edit-delete:hover { color: #e8554d; }
+    .morph-panel-empty { padding: 14px 4px 10px; font-size: 12.5px; color: #6f6f7a; line-height: 1.5; }
+    .morph-panel-foot { display: flex; justify-content: space-between; align-items: center; margin-top: 10px;
+      padding-top: 8px; border-top: 1px solid #eef0f4; }
+    .morph-panel-reset { border: none; background: none; color: #e8554d; font-size: 12px; cursor: pointer; padding: 4px; }
+    .morph-panel-close { border: none; background: none; color: #7a7a85; font-size: 12px; cursor: pointer; padding: 4px; }
+
+    .morph-toast { position: fixed; left: 50%; transform: translateX(-50%) translateY(8px); bottom: 24px;
+      display: none; align-items: center; gap: 12px; background: #17171c; color: #fff; border-radius: 10px;
+      padding: 11px 16px; font-size: 13px; box-shadow: 0 8px 30px rgba(0,0,0,.32); opacity: 0;
+      transition: opacity .15s ease, transform .15s ease; max-width: min(92vw, 460px); }
+    .morph-toast.show { display: flex; opacity: 1; transform: translateX(-50%) translateY(0); }
+    .morph-toast-action { border: none; background: none; color: #7db4ff; font-weight: 700; font-size: 13px;
+      cursor: pointer; padding: 2px 4px; flex: none; }
+  `;
+
+  function createUI(opts) {
+    opts = opts || {};
+    const win = opts.win;
+    const position = opts.position === undefined ? 'bottom-right' : opts.position;
+    const getFlag = opts.getFlag || defaultGetFlag(win);
+    const setFlag = opts.setFlag || defaultSetFlag(win);
+    const reducedMotion = opts.reducedMotion !== undefined ? !!opts.reducedMotion : prefersReducedMotion(win);
+
+    // Vendor opted out of the launcher entirely -> inert API (they drive
+    // everything through Morph.open() and the bar).
+    if (position === false) {
+      const noop = () => {};
+      return { mount: noop, setCount: noop, showToast: noop, renderPanel: noop, showPanel: noop, hidePanel: noop };
+    }
+
+    let root = null, fab = null, badge = null, menu = null, panel = null, toast = null;
+    let toastTimer = null;
+    let handlers = { onPrimary: null, onPanel: null };
+    let panelHandlers = null;
+    let count = 0;
+
+    function el(tag, cls, text) {
+      const n = win.document.createElement(tag);
+      if (cls) n.className = cls;
+      if (text !== undefined) n.textContent = text;
+      return n;
+    }
+
+    function mount(h) {
+      handlers = h || handlers;
+      if (win.document.getElementById(HOST_ID)) return;
+      const host = el('div');
+      host.id = HOST_ID;
+      const shadow = host.attachShadow({ mode: 'open' });
+      const style = el('style'); style.textContent = CSS;
+      shadow.appendChild(style);
+
+      root = el('div', 'morph-ui-root' + (position === 'bottom-left' ? ' pos-bottom-left' : ''));
+      if (opts.accent) root.style.setProperty('--morph-accent', String(opts.accent));
+
+      panel = el('div', 'morph-panel');
+      menu = el('div', 'morph-menu');
+      fab = el('button', 'morph-fab', '✦');
+      fab.setAttribute('aria-label', 'Customize this page with Morph (Alt+M)');
+      fab.setAttribute('title', 'Customize this page (Alt+M)');
+      badge = el('span', 'morph-badge');
+      badge.setAttribute('aria-hidden', 'true');
+      fab.appendChild(badge);
+
+      toast = el('div', 'morph-toast');
+      toast.setAttribute('role', 'status');
+      toast.setAttribute('aria-live', 'polite');
+
+      fab.addEventListener('click', () => {
+        hidePanel();
+        if (count > 0) { menu.classList.toggle('open'); renderMenu(); return; }
+        menu.classList.remove('open');
+        if (handlers.onPrimary) handlers.onPrimary();
+      });
+
+      // One escape hatch for everything floating (Nielsen #3).
+      win.document.addEventListener('keydown', (e) => {
+        if (e.key === 'Escape') { hidePanel(); menu.classList.remove('open'); }
+      });
+
+      root.appendChild(panel);
+      root.appendChild(menu);
+      root.appendChild(fab);
+      shadow.appendChild(root);
+      shadow.appendChild(toast);
+      win.document.documentElement.appendChild(host);
+
+      // First-run nudge: one pulse, ever, and none under reduced motion.
+      let seen;
+      try { seen = getFlag(NUDGE_FLAG); } catch (_) { seen = true; }
+      if (!seen && !reducedMotion) {
+        fab.classList.add('pulse');
+        try { setFlag(NUDGE_FLAG, '1'); } catch (_) { /* private mode */ }
+      } else if (!seen) {
+        try { setFlag(NUDGE_FLAG, '1'); } catch (_) { /* private mode */ }
+      }
+    }
+
+    function renderMenu() {
+      if (!menu) return;
+      menu.textContent = '';
+      const make = el('button', 'morph-menu-item', '✦  Make a change');
+      make.addEventListener('click', () => { menu.classList.remove('open'); if (handlers.onPrimary) handlers.onPrimary(); });
+      const edits = el('button', 'morph-menu-item', '☰  Your edits (' + count + ')');
+      edits.addEventListener('click', () => { menu.classList.remove('open'); if (handlers.onPanel) handlers.onPanel(); });
+      menu.appendChild(make);
+      menu.appendChild(edits);
+    }
+
+    function setCount(n) {
+      count = Number(n) || 0;
+      if (!badge) return;
+      badge.textContent = String(count);
+      badge.classList.toggle('show', count > 0);
+    }
+
+    // Act-then-undo toast (the Gmail pattern). One at a time; new replaces old.
+    function showToast(t) {
+      if (!toast) return;
+      t = t || {};
+      if (toastTimer) { clearTimeout(toastTimer); toastTimer = null; }
+      toast.textContent = '';
+      const txt = el('span', 'morph-toast-text', String(t.text || ''));
+      toast.appendChild(txt);
+      if (t.actionLabel) {
+        const act = el('button', 'morph-toast-action', String(t.actionLabel));
+        act.addEventListener('click', () => { hideToast(); if (t.onAction) t.onAction(); });
+        toast.appendChild(act);
+      }
+      toast.classList.add('show');
+      const ttl = typeof t.ttlMs === 'number' ? t.ttlMs : 10000;
+      toastTimer = setTimeout(hideToast, ttl);
+      if (toastTimer && toastTimer.unref) toastTimer.unref();
+    }
+    function hideToast() {
+      if (toast) toast.classList.remove('show');
+      if (toastTimer) { clearTimeout(toastTimer); toastTimer = null; }
+    }
+
+    function fmtWhen(ts) {
+      try {
+        const d = new Date(ts);
+        return d.toLocaleDateString(undefined, { month: 'short', day: 'numeric' }) + ', ' +
+               d.toLocaleTimeString(undefined, { hour: 'numeric', minute: '2-digit' });
+      } catch (_) { return ''; }
+    }
+
+    // "Your edits on this page": visibility + per-edit control (HAX G17).
+    function renderPanel(edits, h) {
+      panelHandlers = h || panelHandlers || {};
+      if (!panel) return;
+      panel.textContent = '';
+      panel.appendChild(el('h3', '', 'Your edits on this page'));
+      panel.appendChild(el('p', 'morph-panel-sub', 'These re-apply every time you visit. Toggle one off to preview the page without it.'));
+
+      if (!edits || !edits.length) {
+        panel.appendChild(el('div', 'morph-panel-empty',
+          'Nothing yet. Click the ✦ button and describe a change — “make this easier to read”, “add a box totaling this table” — and it will live here.'));
+      } else {
+        edits.forEach((e) => {
+          const row = el('div', 'morph-edit-row' + (e.enabled === false ? ' off' : ''));
+          const label = el('div', 'morph-edit-label');
+          label.appendChild(el('div', 'p', e.prompt || 'Untitled edit'));
+          label.appendChild(el('div', 't', fmtWhen(e.ts)));
+          const toggle = el('button', 'morph-edit-toggle');
+          toggle.setAttribute('role', 'switch');
+          toggle.setAttribute('aria-checked', e.enabled === false ? 'false' : 'true');
+          toggle.setAttribute('aria-label', 'Toggle edit: ' + (e.prompt || 'untitled'));
+          toggle.addEventListener('click', () => {
+            if (panelHandlers.onToggle) panelHandlers.onToggle(e.id, e.enabled === false);
+          });
+          const del = el('button', 'morph-edit-delete', '✕');
+          del.setAttribute('aria-label', 'Remove edit: ' + (e.prompt || 'untitled'));
+          del.addEventListener('click', () => { if (panelHandlers.onDelete) panelHandlers.onDelete(e.id); });
+          row.appendChild(label);
+          row.appendChild(toggle);
+          row.appendChild(del);
+          panel.appendChild(row);
+        });
+      }
+
+      const foot = el('div', 'morph-panel-foot');
+      const reset = el('button', 'morph-panel-reset', 'Reset this page');
+      reset.addEventListener('click', () => { if (panelHandlers.onReset) panelHandlers.onReset(); });
+      const close = el('button', 'morph-panel-close', 'Close');
+      close.addEventListener('click', () => { hidePanel(); if (panelHandlers.onClose) panelHandlers.onClose(); });
+      foot.appendChild(reset);
+      foot.appendChild(close);
+      panel.appendChild(foot);
+    }
+
+    function showPanel() { if (panel) { menu && menu.classList.remove('open'); panel.classList.add('open'); } }
+    function hidePanel() { if (panel) panel.classList.remove('open'); }
+
+    return { mount, setCount, showToast, renderPanel, showPanel, hidePanel };
+  }
+
+  function defaultGetFlag(win) {
+    return (k) => { try { return win.localStorage.getItem(k); } catch (_) { return '1'; } };
+  }
+  function defaultSetFlag(win) {
+    return (k, v) => { try { win.localStorage.setItem(k, v); } catch (_) { /* noop */ } };
+  }
+  function prefersReducedMotion(win) {
+    try { return !!(win.matchMedia && win.matchMedia('(prefers-reduced-motion: reduce)').matches); }
+    catch (_) { return false; }
+  }
+
+  return { createUI };
+});
+
+
 /* ---- sdk/src/embed.js ---- */
 /*
  * Morph SDK — embed entry. Wires the engine (MorphDSL), the vendor registry,
@@ -2209,6 +2608,56 @@
 
   const DEFAULT_BACKEND = 'https://morph-api-234584917638.us-central1.run.app';
 
+  // Hotkey matching on the PHYSICAL key (e.code), not the produced character:
+  // on macOS Option acts as a character modifier (Option+M types 'µ'), so an
+  // e.key comparison never fires there. Modifier state must match EXACTLY —
+  // that also keeps AltGr (reported as ctrl+alt on Windows) from triggering
+  // an alt-only shortcut while someone types accented characters.
+  function matchesTrigger(e, trigger) {
+    if (!e || typeof trigger !== 'string' || !trigger) return false;
+    // IME guard: isComposing can be false on the first/last composition
+    // keystroke while keyCode is still the spec-mandated 229 — check both.
+    if (e.isComposing || e.keyCode === 229) return false;
+    const parts = trigger.toLowerCase().split('+').map((s) => s.trim()).filter(Boolean);
+    if (!parts.length) return false;
+    const key = parts[parts.length - 1];
+    const mods = new Set(parts.slice(0, -1));
+    const want = {
+      alt: mods.has('alt') || mods.has('option'),
+      ctrl: mods.has('ctrl') || mods.has('control'),
+      shift: mods.has('shift'),
+      meta: mods.has('meta') || mods.has('cmd') || mods.has('command'),
+    };
+    if (!!e.altKey !== want.alt || !!e.ctrlKey !== want.ctrl ||
+        !!e.shiftKey !== want.shift || !!e.metaKey !== want.meta) return false;
+    if (typeof e.code === 'string' && e.code) {
+      if (/^[a-z]$/.test(key)) return e.code === 'Key' + key.toUpperCase();
+      if (/^[0-9]$/.test(key)) return e.code === 'Digit' + key;
+    }
+    return typeof e.key === 'string' && e.key.toLowerCase() === key;
+  }
+
+  // Don't hijack keys while the user is typing in the host app (Mousetrap /
+  // github-hotkey convention). composedPath()[0] sees the REAL target even
+  // when the event comes from inside a shadow root (retargeting would
+  // otherwise hide the input element from us).
+  function isTypingTarget(e) {
+    let t = e && e.target;
+    try { if (e && typeof e.composedPath === 'function') t = e.composedPath()[0] || t; } catch (_) { /* keep target */ }
+    if (!t) return false;
+    const tag = String(t.tagName || '').toUpperCase();
+    return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || t.isContentEditable === true;
+  }
+
+  // Wait narration (NN/g response-time bands: acknowledge <100ms, actively
+  // manage the 2-10s AI band; a moving/staged indicator triples patience).
+  const STAGE_MESSAGES = [
+    'Reading this page…',
+    'Designing your change…',
+    'Still working — bigger changes can take a few seconds…',
+  ];
+  const STAGE_DELAYS = [1500, 6000];
+
   function createEmbed(deps) {
     const config = (deps && deps.config) || {};
     const win = deps.win;
@@ -2216,8 +2665,17 @@
     const registry = deps.registry;
     const store = deps.store;
     const bar = deps.bar;
+    const ui = deps.ui || null;
     const extractContext = deps.extractContext;
     const fetchFn = deps.fetchFn;
+    const stageDelays = deps.stageDelays || STAGE_DELAYS;
+    // Merge enabled edits into one transform (storage exports the canonical
+    // deduping composer; the fallback keeps createEmbed usable without it).
+    const compose = deps.compose || function (edits) {
+      const on = (edits || []).filter((e) => e && e.enabled !== false && e.transform);
+      if (!on.length) return null;
+      return on.slice(1).reduce((m, e) => DSL.mergeTransforms(m, e.transform), on[0].transform);
+    };
 
     let backend = DEFAULT_BACKEND;
     let currentHandle = null;   // live undo handle for everything applied this session
@@ -2227,6 +2685,14 @@
       try { return win.location.pathname || '/'; } catch (_) { return '/'; }
     }
 
+    async function refreshCount() {
+      if (!ui) return;
+      try {
+        const edits = await store.listEdits(pathKey());
+        ui.setCount(edits.filter((e) => e.enabled !== false).length);
+      } catch (_) { /* badge is best-effort */ }
+    }
+
     function init() {
       if (typeof config.key !== 'string' || !config.key) {
         throw new TypeError('Morph: init requires a publishable key (config.key)');
@@ -2279,19 +2745,52 @@
       return { transform: Object.assign({}, transform, { ops }), data, failedCount: failedSources.size };
     }
 
+    // Replace whatever this session applied with `transform` (fresh handle).
+    function applyFresh(transform, data) {
+      if (currentHandle) DSL.undoTransform(currentHandle);
+      const handle = DSL.applyTransform(transform, win.document, { groupId: 'morph-sdk', data, onAction });
+      currentHandle = handle;
+      activeTransform = transform;
+      return handle;
+    }
+
     async function applyMerged(incoming, data) {
       // Stack on top of anything already applied this session (additive), so
       // successive prompts accumulate instead of replacing each other.
       const merged = activeTransform ? DSL.mergeTransforms(activeTransform, incoming) : incoming;
-      if (currentHandle) DSL.undoTransform(currentHandle);
-      const handle = DSL.applyTransform(merged, win.document, { groupId: 'morph-sdk', data, onAction });
-      currentHandle = handle;
-      activeTransform = merged;
-      return handle;
+      return applyFresh(merged, data);
+    }
+
+    // Rebuild the applied state from the store (after per-edit remove/toggle).
+    async function reapplyFromStore() {
+      const edits = await store.listEdits(pathKey());
+      const merged = compose(edits);
+      if (!merged || !merged.ops || !merged.ops.length) {
+        if (currentHandle) { DSL.undoTransform(currentHandle); currentHandle = null; }
+        activeTransform = null;
+        return;
+      }
+      const gated = dropUnknownSourceOps(merged);
+      const { transform, data } = await resolveAllData(gated);
+      if (!transform.ops.length) {
+        if (currentHandle) { DSL.undoTransform(currentHandle); currentHandle = null; }
+        activeTransform = null;
+        return;
+      }
+      applyFresh(transform, data);
     }
 
     async function onSubmit(prompt) {
       try { bar.setBusy(true); bar.showActions(false); } catch (_) { /* bar optional in tests */ }
+      // Acknowledge instantly, then narrate the wait in stages.
+      const stageTimers = [];
+      try {
+        bar.setStatus(STAGE_MESSAGES[0], '');
+        stageTimers.push(setTimeout(() => { try { bar.setStatus(STAGE_MESSAGES[1], ''); } catch (_) { /* noop */ } }, stageDelays[0]));
+        stageTimers.push(setTimeout(() => { try { bar.setStatus(STAGE_MESSAGES[2], ''); } catch (_) { /* noop */ } }, stageDelays[1]));
+      } catch (_) { /* noop */ }
+      const clearStages = () => { while (stageTimers.length) clearTimeout(stageTimers.pop()); };
+
       let context = '';
       try { context = extractContext() || ''; } catch (_) { /* snapshot is best-effort */ }
 
@@ -2310,9 +2809,11 @@
         }
         resp = await r.json();
       } catch (e) {
+        clearStages();
         try { bar.setBusy(false); bar.setStatus('Could not reach Morph: ' + String((e && e.message) || e), 'err'); } catch (_) { /* noop */ }
         return;
       }
+      clearStages();
 
       try {
         const v = DSL.validateTransform(resp && resp.transform);
@@ -2335,23 +2836,79 @@
           return;
         }
         const anchored = DSL.withAnchors ? DSL.withAnchors(transform, win.document) : transform;
-        await store.appendTransform(pathKey(), anchored, { prompt }, DSL.mergeTransforms);
+        const edit = await store.appendEdit(pathKey(), anchored, { prompt });
         const note = handle.failed ? ' (' + handle.failed + ' op(s) skipped)' : '';
-        bar.setStatus('✓ ' + ((resp.transform && resp.transform.explanation) || 'Done.') + ' Saved for this page.' + note, 'ok');
+        const explanation = (resp.transform && resp.transform.explanation) || 'Done.';
+        bar.setStatus('✓ ' + explanation + ' Saved for this page.' + note, 'ok');
         bar.showActions(true);
         try { bar.clearInput(); } catch (_) { /* noop */ }
+        await refreshCount();
+        // Act-then-undo (the Gmail pattern): the change is already saved;
+        // the toast is the low-cost escape hatch — never a confirm dialog.
+        if (ui && edit) {
+          ui.showToast({
+            text: '✓ ' + explanation + ' Saved for this page.',
+            actionLabel: 'Undo',
+            onAction: () => removeEdit(edit.id),
+          });
+        }
       } catch (e) {
         try { bar.setBusy(false); bar.setStatus('Something went wrong applying that change.', 'err'); } catch (_) { /* noop */ }
       }
     }
 
-    async function onUndo() {
+    // Per-edit dismissal (HAX G8/G9): drop ONE edit, keep the rest.
+    async function removeEdit(id) {
+      await store.removeEdit(pathKey(), id);
+      await reapplyFromStore();
+      await refreshCount();
+      try { bar.setStatus('Change removed.', ''); } catch (_) { /* noop */ }
+      if (ui) await openPanelIfRendered();
+    }
+
+    async function toggleEdit(id, enabled) {
+      await store.setEditEnabled(pathKey(), id, enabled);
+      await reapplyFromStore();
+      await refreshCount();
+      if (ui) await openPanelIfRendered();
+    }
+
+    // Full reset — the "emergency exit" (Nielsen #3). Bar's Undo maps here.
+    async function resetPage() {
       if (currentHandle) { DSL.undoTransform(currentHandle); currentHandle = null; }
       activeTransform = null;
       await store.removeRecipe(pathKey());
+      await refreshCount();
+      if (ui) await openPanelIfRendered();
       try { bar.setStatus('Reverted this page to its original look.', ''); bar.showActions(false); } catch (_) { /* noop */ }
     }
 
+    async function onUndo() { return resetPage(); }
+
+    // "Your edits on this page" — visibility + per-edit control (HAX G17).
+    let panelRendered = false;
+    async function renderPanel() {
+      if (!ui) return;
+      const edits = await store.listEdits(pathKey());
+      ui.renderPanel(edits, {
+        onToggle: (id, enabled) => toggleEdit(id, enabled),
+        onDelete: (id) => removeEdit(id),
+        onReset: () => {
+          // Destroying ALL edits is the one legitimately confirm-worthy act.
+          let ok = true;
+          try { ok = win.confirm('Remove all your edits on this page?'); } catch (_) { /* headless */ }
+          if (ok) resetPage();
+        },
+        onClose: () => {},
+      });
+      panelRendered = true;
+    }
+    async function openPanelIfRendered() { if (panelRendered) await renderPanel(); }
+    async function openPanel() {
+      await renderPanel();
+      if (ui) ui.showPanel();
+    }
+
     // Reapply the saved recipe: CSS immediately (FOUC kill), the full
     // transform (with fresh data) once the DOM is ready.
     async function applySaved() {
@@ -2378,9 +2935,10 @@
       } else {
         await full();
       }
+      await refreshCount();
     }
 
-    const api = { init, onSubmit, onUndo, applySaved };
+    const api = { init, onSubmit, onUndo, applySaved, removeEdit, toggleEdit, resetPage, openPanel };
     return api;
   }
 
@@ -2396,19 +2954,36 @@
       const doFetch = typeof window.fetch === 'function'
         ? window.fetch.bind(window)
         : () => Promise.reject(new Error('Morph: fetch unavailable'));
+      // Visible launcher (discoverability: HAX G7 — an invisible hotkey is
+      // not an entry point). config.launcher: false to hide, or
+      // { position: 'bottom-left', accent: '#hex' } to theme.
+      const launcherCfg = config.launcher === false ? { position: false } : (config.launcher || {});
+      const ui = window.MorphUI.createUI({
+        win: window,
+        position: launcherCfg.position === undefined ? 'bottom-right' : launcherCfg.position,
+        accent: launcherCfg.accent,
+      });
       const embed = createEmbed({
         config, win: window, DSL: window.MorphDSL, registry, store,
-        bar: window.Morph.bar, extractContext: window.Morph.extractContext,
-        fetchFn: doFetch,
+        bar: window.Morph.bar, ui, extractContext: window.Morph.extractContext,
+        fetchFn: doFetch, compose: window.MorphStorage.composeEdits,
       });
       embed.init();
+      ui.mount({
+        onPrimary: () => window.Morph.bar.show(),
+        onPanel: () => { embed.openPanel().catch(() => {}); },
+      });
       // Hotkey (default alt+m) + a programmatic opener for vendor-built buttons.
+      // Physical-key matching (e.code) so macOS Option+M — which types 'µ' —
+      // still fires; see matchesTrigger above.
       const trigger = typeof config.trigger === 'string' ? config.trigger.toLowerCase() : 'alt+m';
       if (trigger !== 'none') {
-        const key = trigger.split('+').pop();
+        // capture:true so host-page handlers can't swallow the shortcut;
+        // typing guard so we never steal keystrokes from the host's inputs.
         window.addEventListener('keydown', (e) => {
-          if (e.altKey && String(e.key).toLowerCase() === key) { e.preventDefault(); window.Morph.bar.toggle(); }
-        });
+          if (isTypingTarget(e)) return;
+          if (matchesTrigger(e, trigger)) { e.preventDefault(); e.stopPropagation(); window.Morph.bar.toggle(); }
+        }, { capture: true });
       }
       window.Morph.open = () => window.Morph.bar.show();
       embed.applySaved().catch(() => {});
@@ -2416,5 +2991,5 @@
     };
   }
 
-  return { createEmbed };
+  return { createEmbed, matchesTrigger, isTypingTarget };
 });