@herbertgao/pi-impeccable 0.0.0-stage → 0.0.0

package/skills/impeccable/scripts/live-browser-dom.js

@@ -0,0 +1,320 @@
+/**
+ * Browser-side DOM helpers for Impeccable live mode.
+ *
+ * Kept separate from live-browser.js so future browser script parts can share
+ * chrome mounting, lookup, focus, and picker helpers without depending on the
+ * full overlay UI bundle.
+ */
+(function (root) {
+  'use strict';
+  if (!root) return;
+
+  function createLiveBrowserDomHelpers({
+    prefix,
+    skipTags,
+    document: doc = root.document,
+    css = root.CSS,
+    crypto = root.crypto,
+  } = {}) {
+    if (!prefix) throw new Error('prefix required');
+    if (!doc) throw new Error('document required');
+    const tagsToSkip = skipTags || new Set();
+
+    function own(el) {
+      return el && (el.id?.startsWith(prefix) || el.closest?.('[id^="' + prefix + '"]'));
+    }
+
+    function pickable(el) {
+      if (!el || el.nodeType !== 1) return false;
+      if (tagsToSkip.has(String(el.tagName || '').toLowerCase())) return false;
+      if (own(el)) return false;
+      const r = el.getBoundingClientRect();
+      return r.width >= 20 && r.height >= 20;
+    }
+
+    function desc(el) {
+      if (!el) return '';
+      let s = el.tagName.toLowerCase();
+      if (el.id) s += '#' + el.id;
+      else if (el.classList.length) s += '.' + [...el.classList].slice(0, 2).join('.');
+      return s;
+    }
+
+    function rectIsUsableAnchor(rect) {
+      return !!rect && rect.width > 0.5 && rect.height > 0.5;
+    }
+
+    function makeFrozenAnchor(el) {
+      if (!el || !el.getBoundingClientRect) return null;
+      const r = el.getBoundingClientRect();
+      if (!rectIsUsableAnchor(r)) return null;
+      const rect = {
+        x: r.x, y: r.y,
+        top: r.top, left: r.left,
+        right: r.right, bottom: r.bottom,
+        width: r.width, height: r.height,
+      };
+      return {
+        __impeccableFrozenAnchor: true,
+        tagName: el.tagName || 'DIV',
+        id: el.id || '',
+        classList: el.classList ? [...el.classList] : [],
+        hasAttribute: () => false,
+        getBoundingClientRect: () => rect,
+      };
+    }
+
+    function hasFrameworkHmrOwnership(el) {
+      for (let node = el; node; node = node.parentElement) {
+        let keys = [];
+        try { keys = Object.getOwnPropertyNames(node); } catch {}
+        if (keys.some((key) => (
+          key.startsWith('__reactFiber$')
+          || key.startsWith('__reactProps$')
+          || key.startsWith('__reactContainer$')
+          || key === '_reactRootContainer'
+          || key === '__vueParentComponent'
+          || key === '__vue_app__'
+          || key === '__vnode'
+          || key === '__svelte_meta'
+        ))) {
+          return true;
+        }
+      }
+      return false;
+    }
+
+    function id8() {
+      // randomUUID is secure-context only (issue #1055); getRandomValues is not.
+      try {
+        if (typeof crypto?.randomUUID === 'function') return crypto.randomUUID().replace(/-/g, '').slice(0, 8);
+      } catch { /* fall through */ }
+      try {
+        if (typeof crypto?.getRandomValues === 'function') {
+          const bytes = crypto.getRandomValues(new Uint8Array(4));
+          return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+        }
+      } catch { /* fall through */ }
+      return (Math.random().toString(16).slice(2) + Date.now().toString(16)).slice(0, 8);
+    }
+
+    function cssId(id) {
+      if (css?.escape) return css.escape(id);
+      return String(id).replace(/([ !"#$%&'()*+,./:;<=>?@[\\\]^`{|}~])/g, '\\$1');
+    }
+
+    function liveUiRoot() {
+      const uiRoot = root.__IMPECCABLE_LIVE_UI_ROOT__;
+      if (uiRoot && typeof uiRoot.appendChild === 'function') return uiRoot;
+      return doc.body;
+    }
+
+    // A modal <dialog> (showModal) paints in the top layer and makes every
+    // node outside its subtree inert, so chrome on <body> can be neither seen
+    // nor clicked while one is open, and no z-index reaches it (issue #879).
+    // While a modal is open the chrome parks inside the topmost one, in one
+    // popover: inside the dialog it is not inert, and a popover shown after
+    // the dialog paints above it. One popover for all of it, because
+    // top-layer entries stack by show order, which would drop the z-index
+    // order between the roots. The detect overlay (browser-bundle/
+    // 40-overlay.js) mounts its outlines here too: it finds the host by this
+    // id and places its outlines again on the event of the same name, fired
+    // on every move.
+    const topLayerHost = doc.createElement('div');
+    topLayerHost.id = prefix + '-top-layer';
+    // Same box as the SvelteKit shadow host: 0x0, fixed, chrome overflows it.
+    // `all: initial` also clears the popover UA box.
+    for (const [name, value] of Object.entries({
+      all: 'initial', position: 'fixed', top: '0', left: '0', width: '0', height: '0', overflow: 'visible',
+    })) topLayerHost.style.setProperty(name, value, 'important');
+    const pageRoots = new WeakSet(); // chrome nodes mounted on the page itself
+    const openModals = [];           // in the order they opened; last is topmost
+
+    // Modals that were open before watching began have no readable top-layer
+    // order, but the topmost one's backdrop covers the viewport, so a hit
+    // test lands in it. Raise that one to the top of the stack.
+    function raiseHitModal() {
+      const i = openModals.indexOf(doc.elementFromPoint(0, 0)?.closest('dialog:modal'));
+      if (i !== -1) openModals.push(...openModals.splice(i, 1));
+    }
+
+    function syncTopLayerHost(records = []) {
+      for (const { type, target, oldValue } of records) {
+        if (type !== 'attributes' || oldValue !== null || !target.matches('dialog:modal')) continue;
+        // Opened, or closed and reopened in one task (the observer sees only
+        // the end state): either way it is back on top of the top layer, so
+        // a host shown inside it earlier has to be shown again. A write to an
+        // `open` that was already set (oldValue not null) moved nothing.
+        const i = openModals.indexOf(target);
+        if (i !== -1) openModals.splice(i, 1);
+        openModals.push(target);
+        if (topLayerHost.parentNode === target) topLayerHost.remove();
+      }
+      // A closed dialog, or one removed from the document while open, stops
+      // matching :modal. Whichever is now on top may predate the watch.
+      const before = openModals.length;
+      for (let i = openModals.length - 1; i >= 0; i--) {
+        if (!openModals[i].matches('dialog:modal')) openModals.splice(i, 1);
+      }
+      if (openModals.length < before && openModals.length > 1) raiseHitModal();
+      const modal = openModals[openModals.length - 1] || null;
+      if (topLayerHost.parentNode === modal) return;
+      if (modal) {
+        modal.appendChild(topLayerHost);
+        for (const el of [...doc.body.children]) if (pageRoots.has(el)) topLayerHost.appendChild(el);
+        topLayerHost.showPopover();
+      } else {
+        doc.body.append(...topLayerHost.childNodes);
+        topLayerHost.remove();
+      }
+      doc.dispatchEvent(new Event(topLayerHost.id));
+    }
+
+    // Returns the function that stops watching and puts the chrome back.
+    function watchModalDialogs() {
+      if (typeof topLayerHost.showPopover !== 'function') return () => {};
+      topLayerHost.popover = 'manual';
+      // Parked in the page's dialog, chrome clicks would bubble into its own
+      // handlers, such as a click-outside-the-box close. Live listens in capture.
+      topLayerHost.addEventListener('click', (e) => e.stopPropagation());
+      openModals.push(...doc.querySelectorAll('dialog:modal'));
+      raiseHitModal();
+      const observer = new MutationObserver(syncTopLayerHost);
+      observer.observe(doc, { subtree: true, childList: true, attributes: true, attributeOldValue: true, attributeFilter: ['open'] });
+      syncTopLayerHost();
+      return () => {
+        observer.disconnect();
+        openModals.length = 0;
+        syncTopLayerHost();
+      };
+    }
+
+    // A copy of a page element without the chrome parked inside it, which a
+    // picked modal dialog contains.
+    function cloneWithoutChrome(el) {
+      const clone = el.cloneNode(true);
+      if (el.contains(topLayerHost)) clone.querySelector('#' + cssId(topLayerHost.id)).remove();
+      return clone;
+    }
+
+    // Mount a chrome node on the page itself: <body>, or the top-layer host
+    // while the chrome is parked in a modal.
+    function uiAppendToPage(el) {
+      pageRoots.add(el);
+      (topLayerHost.parentNode ? topLayerHost : doc.body).appendChild(el);
+      return el;
+    }
+
+    // Copy text through a selected textarea and execCommand, for origins where
+    // navigator.clipboard is missing or refused (plain HTTP, issue #1055).
+    // The textarea mounts like any page-level chrome, so while a modal
+    // <dialog> is open it sits in that dialog's top-layer host: on <body> it
+    // would be inert, and inert text cannot be selected or copied.
+    function copyTextViaSelection(text) {
+      let ta = null;
+      const previous = activeElementDeep();
+      try {
+        ta = doc.createElement('textarea');
+        ta.id = prefix + '-clipboard';
+        ta.value = text;
+        ta.setAttribute('readonly', '');
+        ta.setAttribute('aria-hidden', 'true');
+        ta.tabIndex = -1;
+        ta.style.cssText = 'position:fixed;top:0;left:0;width:1px;height:1px;opacity:0;pointer-events:none;';
+        uiAppendToPage(ta);
+        ta.select();
+        return doc.execCommand('copy');
+      } catch {
+        return false;
+      } finally {
+        ta?.remove();
+        if (previous && previous !== activeElementDeep() && typeof previous.focus === 'function') {
+          try { previous.focus({ preventScroll: true }); } catch { /* best effort */ }
+        }
+      }
+    }
+
+    function uiAppend(el) {
+      const uiRoot = liveUiRoot();
+      if (uiRoot === doc.body) return uiAppendToPage(el);
+      // An adapter shadow root: its host is the node that sits on the page.
+      if (uiRoot.host) pageRoots.add(uiRoot.host);
+      uiRoot.appendChild(el);
+      return el;
+    }
+
+    function uiAppendStyle(styleEl) {
+      const uiRoot = liveUiRoot();
+      if (uiRoot && uiRoot !== doc.body) uiRoot.appendChild(styleEl);
+      else doc.head.appendChild(styleEl);
+      return styleEl;
+    }
+
+    function uiGetById(id) {
+      const uiRoot = liveUiRoot();
+      if (uiRoot?.getElementById) {
+        const found = uiRoot.getElementById(id);
+        if (found) return found;
+      }
+      if (uiRoot?.querySelector) {
+        const found = uiRoot.querySelector('#' + cssId(id));
+        if (found) return found;
+      }
+      return doc.getElementById(id);
+    }
+
+    function activeElementDeep() {
+      let active = doc.activeElement;
+      while (active?.shadowRoot?.activeElement) active = active.shadowRoot.activeElement;
+      return active;
+    }
+
+    function defangOutsideHandlers(rootEl, { setPointerEvents = true } = {}) {
+      if (!rootEl) return;
+      if (setPointerEvents) {
+        rootEl.style.setProperty('pointer-events', 'auto', 'important');
+      }
+      const stop = (e) => e.stopPropagation();
+      rootEl.addEventListener('pointerdown', stop);
+      rootEl.addEventListener('mousedown', stop);
+      rootEl.addEventListener('focusin', stop);
+    }
+
+    // The half of the defang that cannot sit on the chrome: a focus trap (Radix /
+    // Reka FocusScope) also hears the page's own focusout as focus leaves its
+    // modal for our chrome, and pulls it back. Register on the document in
+    // capture, ahead of the trap. The page's own focusout handlers miss that
+    // one transition too; blur still fires.
+    function stopFocusOutIntoChrome(e) {
+      if (own(e.relatedTarget)) e.stopPropagation();
+    }
+
+    return {
+      own,
+      pickable,
+      desc,
+      rectIsUsableAnchor,
+      makeFrozenAnchor,
+      hasFrameworkHmrOwnership,
+      id8,
+      cssId,
+      liveUiRoot,
+      uiAppend,
+      uiAppendToPage,
+      copyTextViaSelection,
+      topLayerHost,
+      watchModalDialogs,
+      cloneWithoutChrome,
+      uiAppendStyle,
+      uiGetById,
+      activeElementDeep,
+      defangOutsideHandlers,
+      stopFocusOutIntoChrome,
+    };
+  }
+
+  root.__IMPECCABLE_LIVE_DOM__ = {
+    version: 1,
+    createLiveBrowserDomHelpers,
+  };
+})(typeof window !== 'undefined' ? window : globalThis);

package/skills/impeccable/scripts/live-browser-ignores.js

@@ -0,0 +1,246 @@
+/**
+ * Browser-side resolution of project detector waivers for Impeccable live mode.
+ *
+ * The live server serializes `.impeccable/config.json` + `config.local.json`
+ * detector ignores (plus the served-root prefixes from the inject config's
+ * `files` globs) into `window.__IMPECCABLE_PROJECT_IGNORES__`. This part
+ * resolves that config against the current page's URL path when a detect scan
+ * starts, so the overlay suppresses the same findings the CLI and the edit
+ * hook do (issue #639).
+ *
+ * Mirrors filterDetectionFindings in cli/lib/impeccable-config.mjs:
+ *   1. `ignoreRules` suppress a rule project-wide.
+ *   2. `ignoreValues` entries with `value: "*"` suppress their rule in the
+ *      files their globs name. The CLI never applies an unscoped wildcard
+ *      (isIgnoredFindingValue returns false for it), so neither does this.
+ *   3. Remaining `ignoreValues` entries match on the finding's own value;
+ *      those are forwarded as `disabledValues` for the detector bundle to
+ *      apply where the findings are assembled.
+ *   4. `ignoreFiles` globs that name the page waive it wholesale: the
+ *      resolver reports `skipScan: true` and the detector answers the scan
+ *      with zero findings, mirroring shouldIgnoreDetectionFile in the CLI
+ *      and the edit hook's own ignoreFiles gate.
+ *
+ * `pageFiles`, when the server could resolve it, lists the real project
+ * files the inject config serves. A URL that suffix-matches exactly one of
+ * them takes that file as its only project identity; an ambiguous or absent
+ * match falls back to the served-root common ancestor below.
+ *
+ * Known gap, unchanged from PR #645: framework apps inject into source files
+ * (src/routes/about/+page.svelte) while scans see route URLs (/about), so
+ * entries scoped to source or asset paths never match a page candidate and
+ * are dropped. That shows the finding, which is the conservative direction.
+ *
+ * Kept separate from live-browser.js so the glob and page-scope logic can be
+ * unit tested in Node (tests/live-browser-ignores.test.mjs) without the full
+ * overlay UI bundle.
+ */
+(function (root) {
+  'use strict';
+  if (!root) return;
+
+  // Keep in step with normalizeIgnoreRule / normalizeIgnoreValue in
+  // cli/lib/impeccable-config.mjs.
+  function normalizeIgnoreRule(rule) {
+    return String(rule || '').trim().toLowerCase();
+  }
+
+  function normalizeIgnoreValue(value) {
+    return String(value || '')
+      .trim()
+      .replace(/^["']|["']$/g, '')
+      .replace(/\+/g, ' ')
+      .replace(/\s+/g, ' ')
+      .toLowerCase();
+  }
+
+  // Glob -> RegExp. Supports `**`, `*`, `?`, and `{a,b}` alternation.
+  // Keep in step with globToRegex in cli/lib/impeccable-config.mjs.
+  function globToRegex(glob) {
+    let re = '^';
+    let i = 0;
+    while (i < glob.length) {
+      const c = glob[i];
+      if (c === '*') {
+        if (glob[i + 1] === '*') {
+          i += 2;
+          if (glob[i] === '/') {
+            re += '(?:.*/)?';
+            i += 1;
+          } else {
+            re += '.*';
+          }
+        } else {
+          re += '[^/]*';
+          i += 1;
+        }
+      } else if (c === '?') {
+        re += '[^/]';
+        i += 1;
+      } else if (c === '{') {
+        const end = glob.indexOf('}', i);
+        if (end === -1) { re += '\\{'; i += 1; continue; }
+        const parts = glob.slice(i + 1, end).split(',').map((p) => p.replace(/[.+^$()|[\]\\]/g, '\\$&'));
+        re += `(?:${parts.join('|')})`;
+        i = end + 1;
+      } else if (/[.+^$()|[\]\\]/.test(c)) {
+        re += `\\${c}`;
+        i += 1;
+      } else {
+        re += c;
+        i += 1;
+      }
+    }
+    re += '$';
+    return new RegExp(re);
+  }
+
+  // The project-relative paths this page could be known as. Ignore globs are
+  // project-relative (prototype/foo.html) and the URL is site-relative
+  // (/foo.html), because a static server's root usually sits inside the
+  // project; `roots` carries that prefix. The server reads it from the inject
+  // config's own `files` globs, which already state where the served pages
+  // are. Do not derive it from the ignore globs: a single entry scoped to
+  // prototype/library/** would then lend prototype/library/ as a candidate
+  // prefix to every page, and that rule would suppress site-wide.
+  //
+  // Each prefixed path also contributes its slash suffixes, mirroring
+  // findingMatchesScopedIgnoreFile in cli/lib/impeccable-config.mjs (which
+  // matches globs against every path suffix of the finding's file).
+  //
+  // One live session is served by one server, so a single document root must
+  // sit at or above every configured page. The only prefix that can safely
+  // be asserted is therefore the deepest common ancestor of the glob roots.
+  // Treating each glob's own prefix as an identity goes wrong in both
+  // directions: disjoint roots (src/ and public/) invent simultaneous
+  // identities for one URL, so a waiver scoped to src/foo.html hides a
+  // finding on a page served from public/foo.html; nested roots (prototype/
+  // and prototype/library/, from globs at two depths in one tree) are not
+  // alternatives at all, and demanding a waiver match under both stops
+  // prototype/index.html from applying anywhere. When the globs share no
+  // common root, no prefix is asserted and only the URL path itself matches.
+  function pageCandidates(pathname, roots, pageFiles) {
+    let pagePath = String(pathname || '');
+    try {
+      pagePath = decodeURIComponent(pagePath);
+    } catch {
+      // Malformed percent-escape: match on the raw path rather than throwing.
+    }
+    pagePath = pagePath.replace(/^\/+/, '');
+    // A directory URL serves that directory's index, and the ignore globs
+    // name files. Without this, /news/ never matches prototype/news/index.html.
+    if (pagePath === '' || pagePath.endsWith('/')) pagePath += 'index.html';
+
+    const candidates = new Set();
+    const addSuffixes = (fullPath) => {
+      const parts = fullPath.split('/').filter(Boolean);
+      for (let i = 0; i < parts.length; i++) {
+        candidates.add(parts.slice(i).join('/'));
+      }
+    };
+    addSuffixes(pagePath);
+
+    // The served page list names the real files the inject config serves.
+    // A URL that suffix-matches exactly one of them has an unambiguous
+    // project identity; assert that identity and stop guessing from roots
+    // (PR #645 review: with src/ and public/ both served, /foo.html must not
+    // borrow src/foo.html's waivers while actually serving public/foo.html).
+    // Zero matches or several fall through to the common-ancestor fallback:
+    // ambiguity resolves toward showing the finding.
+    const knownPages = [];
+    for (const entry of Array.isArray(pageFiles) ? pageFiles : []) {
+      if (typeof entry !== 'string' || !entry) continue;
+      if (entry === pagePath || entry.endsWith('/' + pagePath)) knownPages.push(entry);
+    }
+    if (knownPages.length === 1) {
+      addSuffixes(knownPages[0]);
+      return [...candidates];
+    }
+
+    const prefixes = [];
+    for (const entry of Array.isArray(roots) ? roots : []) {
+      if (typeof entry !== 'string') continue;
+      prefixes.push(entry.split('/').filter(Boolean));
+    }
+    let common = prefixes.length > 0 ? prefixes[0] : [];
+    for (const segments of prefixes.slice(1)) {
+      let i = 0;
+      while (i < common.length && i < segments.length && common[i] === segments[i]) i += 1;
+      common = common.slice(0, i);
+    }
+
+    if (common.length > 0) addSuffixes(common.join('/') + '/' + pagePath);
+    return [...candidates];
+  }
+
+  function matchesScope(globs, candidates) {
+    return globs.some((glob) => {
+      let re;
+      try {
+        re = globToRegex(String(glob));
+      } catch {
+        // Malformed glob: skip it, as matchesAnyGlob does in the CLI.
+        return false;
+      }
+      return candidates.some((candidate) => re.test(candidate));
+    });
+  }
+
+  /**
+   * Resolve the serialized project ignores for one page.
+   *
+   * @param {object} options
+   * @param {object} options.ignores  window.__IMPECCABLE_PROJECT_IGNORES__,
+   *   in whatever state it arrived: absent, null, or hand-edited into the
+   *   wrong shape. Every read tolerates that and degrades to no filtering.
+   * @param {string} options.pathname  location.pathname of the scanned page.
+   * @returns {{ disabledRules: string[], disabledValues: Array<{rule: string, value: string}>, skipScan: boolean }}
+   */
+  function resolveDetectIgnores({ ignores, pathname } = {}) {
+    const config = ignores && typeof ignores === 'object' ? ignores : {};
+    const asArray = (value) => (Array.isArray(value) ? value : []);
+    const candidates = pageCandidates(pathname, config.roots, config.pageFiles);
+
+    // detector.ignoreFiles waives whole files. When any glob names this
+    // page, the scan itself is skipped; rule and value lists are returned
+    // empty because nothing will run.
+    const ignoreFileGlobs = asArray(config.ignoreFiles)
+      .filter((glob) => typeof glob === 'string' && glob.trim());
+    if (ignoreFileGlobs.length > 0 && matchesScope(ignoreFileGlobs, candidates)) {
+      return { disabledRules: [], disabledValues: [], skipScan: true };
+    }
+
+    const disabledRules = new Set(
+      asArray(config.ignoreRules)
+        .filter((rule) => typeof rule === 'string')
+        .map(normalizeIgnoreRule)
+        .filter(Boolean),
+    );
+    const disabledValues = [];
+
+    for (const entry of asArray(config.ignoreValues)) {
+      if (!entry || typeof entry !== 'object') continue;
+      const rule = normalizeIgnoreRule(entry.rule);
+      const value = normalizeIgnoreValue(entry.value);
+      if (!rule || !value) continue;
+      const files = [
+        ...(typeof entry.file === 'string' && entry.file.trim() ? [entry.file.trim()] : []),
+        ...asArray(entry.files).filter((glob) => typeof glob === 'string' && glob.trim()),
+      ];
+      if (value === '*') {
+        // Wildcards suppress their rule only inside the files they name.
+        if (files.length > 0 && matchesScope(files, candidates)) disabledRules.add(rule);
+        continue;
+      }
+      if (files.length > 0 && !matchesScope(files, candidates)) continue;
+      disabledValues.push({ rule, value });
+    }
+
+    return { disabledRules: [...disabledRules], disabledValues, skipScan: false };
+  }
+
+  root.__IMPECCABLE_LIVE_IGNORES__ = {
+    version: 1,
+    resolveDetectIgnores,
+  };
+})(typeof window !== 'undefined' ? window : globalThis);