@firsthandjs/devtools 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Firsthand contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @firsthandjs/devtools
+
+> **Experimental.** This package is new and its shape is still moving. The
+> names, the returned structures and the panel will change without a major
+> version while that is true, and nothing else in the framework depends on it.
+
+See which signal updates which DOM node, what depends on what, and why an
+effect ran.
+
+```bash
+npm install --save-dev @firsthandjs/devtools
+```
+
+```ts
+// main.tsx, above everything else
+import { attach } from '@firsthandjs/devtools';
+
+if (import.meta.env.DEV) {
+  attach();
+}
+```
+
+Then, in the browser:
+
+Press **Ctrl+Shift+F**, or:
+
+```js
+__FIRSTHAND__.panel(); // a panel: pick an element, see what writes it and why
+```
+
+Or from the console, on whatever the Elements panel has selected — no import,
+because a console cannot resolve a bare specifier:
+
+```js
+__FIRSTHAND__.chain($0);
+__FIRSTHAND__.causeOf($0);
+__FIRSTHAND__.queries();
+```
+
+And from a test or a module, where the types apply:
+
+```ts
+import { chain, inspect, causeOf } from '@firsthandjs/devtools';
+
+chain(document.querySelector('button'));
+// order.ts:12:19
+//    ↓
+// computed(isEditable)
+//    ↓
+// button.disabled
+
+causeOf(document.querySelector('button'));
+// 'order.ts:12:19' — what changed to make it run
+```
+
+`inspect(node)` returns the same thing as data: each part that writes the node,
+with its dependencies and their dependencies, as far down as you ask.
+`cells()` lists every computed and effect currently alive.
+
+## What it costs
+
+The framework's side of it ships nothing: the hooks this reads live in modules
+the production build replaces with empty functions, so a shipped bundle
+contains neither that code nor its strings, whether or not you use devtools.
+
+This package is not stripped, though — it is an ordinary module, so an
+unconditional import puts it in your production bundle. Guard it if that
+matters:
+
+```ts
+if (import.meta.env.DEV) {
+  const { attach } = await import('@firsthandjs/devtools');
+  attach();
+}
+```
+
+An import pulls in 1.96 kB gzip; the panel is a further 4.83 kB, loaded when it
+is opened.
+
+In development it records nothing until `attach()` is called, because naming
+every cell costs a `WeakMap` write and a hundred thousand rows would feel it.
+
+## How it works
+
+It does not instrument anything. The reactive graph is already there, because
+propagation and disposal need it: every cell carries its dependencies and its
+subscribers, and every owner carries its children. This package attaches names
+to those nodes and reads the structure when asked.
+
+**Documentation:** [guide](../../docs/guide/14-devtools.md) ·
+[API reference](../../docs/reference/devtools.md) ·
+[ADR-0020](../../docs/adr/0020-devtools-without-a-runtime-cost.md) for the
+reasoning.
+
+## Licence
+
+MIT

package/dist/chunk-5XEHZQPH.js

@@ -0,0 +1,7 @@
+var m=new WeakMap,L=new WeakMap,s=new WeakMap,v=new WeakMap,w=new WeakMap,u=[],i=[],T=100,l=null,j=200,p=new Set,a=null,b=null,d=null,f=null,c=null,_=1,y=/@firsthandjs|[\\/]node_modules[\\/]|[\\/]packages[\\/](core|dom|deep|devtools|jsx-runtime|query|router|styled|testing)[\\/]src[\\/]/;function D(){let t=(new Error().stack??"").split(`
+`).slice(1),e=[];for(let n of t){if(y.test(n))continue;let o=n.trim().replace(/^at\s+/,"");if(o!==""&&e.push(o),e.length===6)break}return e}function E(){let e=(new Error().stack??"").split(`
+`).slice(1).find(o=>!y.test(o))??"unknown",n=/\(?([^()\s]+:\d+:\d+)\)?$/.exec(e.trim());return n===null?e.trim():n[1]}function U(){if(c!==null)return;let t={attached:!0,label(e,n,o){m.set(e,{kind:n,name:o===""?E():o})},cause(e){f=e,l={update:{at:Math.round(performance.now()),source:h(e),ran:[],stack:D()},effects:[]},i.push(l),i.length>T&&i.shift()},root(e){p.add(new WeakRef(e))},component(e,n){w.set(e,n)},running(e){a=e,e===null&&b?.(),e!==null&&f!==null&&(v.set(e,f),l?.update.ran.push(h(e)),l?.effects.push(e))},query(e,n,o){u.push({event:e,key:n,tags:o}),u.length>j&&u.shift()},part(e,n){if(a===null)return;L.set(a,{node:e,property:n});let o=s.get(e);o===void 0&&(o=new Set,s.set(e,o)),o.add(a)}};globalThis.__FIRSTHAND_DEVTOOLS__=t,c=t,d=e=>{e.ctrlKey&&e.shiftKey&&e.key.toLowerCase()==="f"&&(e.preventDefault(),import("./chunk-7BUP5FXQ.js").then(n=>{n.toggle()}))},globalThis.addEventListener("keydown",d),console.info("[firsthand] devtools attached \u2014 press Ctrl+Shift+F for the panel, or call __FIRSTHAND__.panel()"),globalThis.__FIRSTHAND__={chain:A,inspect:C,causeOf:K,stack:F,timeline:W,cells:I,queries:M,detach:S,panel:e=>{import("./chunk-7BUP5FXQ.js").then(n=>{e===void 0?n.open():n.show(e)})}}}function S(){c!==null&&(c.attached=!1),globalThis.__FIRSTHAND_DEVTOOLS__=void 0,delete globalThis.__FIRSTHAND__,d!==null&&(globalThis.removeEventListener("keydown",d),d=null),c=null,a=null,f=null,l=null,i.length=0,b=null,u.length=0,p.clear()}function h(t){let e=L.get(t);if(e!==void 0){let o=e.node;return`${(o.tagName??o.nodeName??"node").toLowerCase()}.${e.property}`}let n=m.get(t);return n===void 0?(t.flags&_)===0?"signal":"computed":n.name}function G(t){return L.has(t)?"part":m.get(t)?.kind??((t.flags&_)===0?"signal":"computed")}function g(t,e,n){let o={kind:G(t),name:h(t),value:t.v,dependencies:[],dependents:[]};if(e>0)for(let r=t.deps;r!==void 0;r=r.nextDep)o.dependencies.push(g(r.dep,e-1,0));if(n>0)for(let r=t.subs;r!==void 0;r=r.nextSub)o.dependents.push(g(r.sub,0,n-1));return o}function R(){let t=[];for(let e of p){let n=e.deref();n===void 0?p.delete(e):t.push(n)}return t}function x(t,e){t.cells!==null&&e.push(...t.cells);for(let n=t.head;n!==null;n=n.next)x(n,e)}function I(){let t=[];for(let e of R())x(e,t);return t.map(e=>g(e,1,1))}function C(t,e=8){let n=s.get(t);return n===void 0?[]:[...n].map(o=>g(o,e,0))}function A(t){let e=C(t);return e.length===0?"Nothing reactive writes this node.":e.map(n=>H(O(n)).join(`
+   \u2193
+`)).join(`
+
+`)}function O(t){let e=[];for(let n of t.dependencies){let o=O(n);o.length>e.length&&(e=o)}return[...e,t]}function H(t){return t.map(e=>e.kind==="computed"?`computed(${e.name})`:e.name)}function K(t){let e=s.get(t);if(e===void 0)return null;for(let n of e){let o=v.get(n);if(o!==void 0)return h(o)}return null}function M(){return[...u]}function q(t){b=t}function F(t){let e=s.get(t);if(e===void 0)return[];let n=[];for(let o of e){let r=o.scope??null,k=[];for(;r!==null;){let N=w.get(r);N!==void 0&&k.unshift(N),r=r.parent}k.length>n.length&&(n.length=0,n.push(...k))}return n}function W(t){if(t===void 0)return i.map(n=>n.update);let e=s.get(t);return e===void 0?[]:i.filter(n=>n.effects.some(o=>e.has(o))).map(n=>n.update)}export{U as a,S as b,I as c,C as d,A as e,O as f,K as g,M as h,q as i,F as j,W as k};

package/dist/chunk-7BUP5FXQ.js

@@ -0,0 +1,86 @@
+import{d as $,f as q,g as H,h as C,i as L,j as A,k as T}from"./chunk-5XEHZQPH.js";var J="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";function Q(e){let t=[],r=0,n=0;for(let o of e){let a=J.indexOf(o),i=a&32;if(n+=(a&31)<<r,i===0){let s=n&1;n>>=1,t.push(s===1?-n:n),r=0,n=0}else r+=5}return t}function W(e){let t=[],r=0,n=0,o=0;for(let[a,i]of e.mappings.split(";").entries()){let s=0;for(let u of i.split(",")){if(u==="")continue;let p=Q(u);if(s+=p[0],p.length<4)continue;r+=p[1],n+=p[2],o+=p[3];let m=e.sources[r];m!=null&&t.push({generatedLine:a,generatedColumn:s,source:m,originalLine:n,originalColumn:o})}}return t}var P=new Map,B=/\/\/[#@]\s*sourceMappingURL=data:application\/json;(?:charset=[^;]+;)?base64,([\w+/=]+)/;async function D(e){let t=P.get(e);if(t!==void 0)return t;let r=(async()=>{try{let o=await(await fetch(e)).text(),a=B.exec(o);if(a===null)return null;let i=JSON.parse(atob(a[1]));return W(i)}catch{return null}})();return P.set(e,r),r}function Y(e,t,r){let n=null;for(let o of e){if(o.generatedLine>t||o.generatedLine===t&&o.generatedColumn>r)break;o.generatedLine===t&&(n=o)}return n}async function O(e){let t=/^(.*?)\(?([^\s()]+):(\d+):(\d+)\)?$/.exec(e.trim().replace(/^at\s+/,""));if(t===null)return e;let[,r,n,o,a]=t;if(!/^https?:\/\//.test(n))return e;let i=await D(n);if(i===null)return e;let s=Y(i,Number(o)-1,Number(a)-1);if(s===null)return e;let p=`${s.source.slice(Math.max(s.source.lastIndexOf("/"),s.source.lastIndexOf("\\"))+1)}:${String(s.originalLine+1)}:${String(s.originalColumn+1)}`;return r.trim()===""?p:`${r.trim()} (${p})`}var K=`
+:host { all: initial; }
+.panel {
+  position: fixed; right: 16px; bottom: 16px; z-index: 2147483647;
+  width: 460px; max-height: 78vh; display: flex; flex-direction: column;
+  font: 12px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+  color: #e6e6e6; background: #1c1c1f; border: 1px solid #3a3a40;
+  border-radius: 10px; box-shadow: 0 10px 40px rgb(0 0 0 / 0.45);
+}
+header { display: flex; align-items: center; gap: 6px; padding: 8px 10px;
+  border-bottom: 1px solid #3a3a40; }
+header strong { font-weight: 600; letter-spacing: 0.02em; flex: 1; }
+button { font: inherit; color: inherit; background: #2a2a30; border: 1px solid #45454d;
+  border-radius: 5px; padding: 3px 8px; cursor: pointer; }
+button:hover { background: #34343c; }
+button[aria-pressed='true'] { background: #3d5afe; border-color: #3d5afe; color: #fff; }
+.body { display: flex; flex-direction: column; overflow: hidden; padding: 12px; min-height: 0; }
+/* The list scrolls; the detail stays where it can be read. Without this the
+   call stack sits below everything and is only reachable by scrolling past
+   the whole log \u2014 which is exactly when you least want to. */
+/* Two independent scroll areas: the list above, the detail below. Each gets
+   its own, because a call stack that can only be reached by scrolling past
+   forty rows of log is out of reach exactly when it is wanted. */
+.scroll { overflow-y: auto; overflow-x: hidden; flex: 1 1 auto; min-height: 60px; }
+.pinned { flex: 0 1 auto; min-height: 140px; max-height: 65%; overflow-y: auto;
+  overflow-x: hidden; margin-top: 8px; padding-top: 8px;
+  border-top: 1px solid #3a3a40; }
+.detail-head { display: flex; align-items: center; gap: 8px; }
+.detail-head .hint { margin: 0; flex: 1; }
+.detail-head button { padding: 0 6px; line-height: 1.4; }
+.empty { color: #8a8a94; }
+.hint { color: #7c7c88; margin: 14px 0 6px; font-size: 10px; text-transform: uppercase;
+  letter-spacing: 0.1em; }
+.hint:first-child { margin-top: 0; }
+.section + .section { margin-top: 2px; }
+.stack { margin: 4px 0 0; }
+.stack div { color: #9a9aa6; padding-left: 10px; border-left: 1px solid #3a3a40; }
+.stack div:first-child { color: #e6e6e6; }
+.filters { display: flex; gap: 6px; align-items: center; margin-bottom: 8px; flex-wrap: wrap; }
+.filters .chip { background: #2a2a30; border: 1px solid #45454d; border-radius: 999px;
+  padding: 1px 9px; cursor: pointer; color: #9ecbff; }
+.filters .chip[aria-pressed='true'] { background: #3d5afe; border-color: #3d5afe; color: #fff; }
+.count { color: #7c7c88; }
+
+/* The path, as boxes and arrows rather than as three lines of text. */
+.flow { display: flex; flex-direction: column; align-items: stretch; gap: 0; }
+.box { border: 1px solid #45454d; border-radius: 7px; padding: 6px 9px; background: #232329;
+  display: flex; align-items: baseline; gap: 8px; }
+.box .tag { font-size: 10px; text-transform: uppercase; letter-spacing: 0.07em;
+  padding: 1px 5px; border-radius: 4px; background: #34343c; color: #b9b9c4; }
+.box .label { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.box .val { color: #c3e88d; }
+.box.signal { border-color: #3d5afe; }
+.box.signal .tag { background: #23306b; color: #b6c4ff; }
+.box.computed { border-color: #c792ea; }
+.box.computed .tag { background: #3a2b47; color: #e6c8ff; }
+.box.part { border-color: #ffcb6b; }
+.box.part .tag { background: #4a3a1c; color: #ffdfa1; }
+.box.trigger { box-shadow: 0 0 0 2px #3d5afe66; }
+.arrow { align-self: center; color: #6a6a76; font-size: 14px; line-height: 1; padding: 3px 0; }
+
+/* The component stack, as crumbs. */
+.crumbs { display: flex; flex-wrap: wrap; gap: 4px; margin: 0 0 10px; }
+.crumb { background: #2a2a30; border: 1px solid #45454d; border-radius: 999px;
+  padding: 1px 8px; color: #c792ea; }
+.crumb + .crumb::before { content: '\u203A'; color: #8a8a94; margin-right: 6px; margin-left: -4px; }
+
+/* The timeline: one row per update, a bar for how much it woke. */
+.track { display: flex; flex-direction: column; gap: 4px; }
+.tick { display: grid; grid-template-columns: 52px minmax(0, 1fr) auto auto; gap: 8px;
+  align-items: center; padding: 3px 4px; border-radius: 5px; cursor: pointer; }
+.tick:hover { background: #26262c; }
+.tick[aria-selected='true'] { background: #23306b; }
+.tick .when { color: #8a8a94; text-align: right; }
+.tick .who { color: #9ecbff; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.tick .where { color: #7c7c88; white-space: nowrap; }
+.tick .bar { height: 8px; border-radius: 4px; background: #3d5afe; min-width: 4px; }
+.tick .bar.none { background: #4a4a54; }
+.detail .ran { color: #ffdfa1; }
+.cause { color: #ffcb6b; margin: 10px 0 0; }
+.event { display: grid; grid-template-columns: 84px 1fr; gap: 8px; padding: 2px 0; }
+.event .created { color: #c3e88d; }
+.event .invalidated { color: #ffcb6b; }
+.event .dropped { color: #f07178; }
+.event .tags { color: #9ecbff; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+`,b="firsthand-devtools-outline",d=null,E=null,h=null,v=!1,g="graph",k=null,c=null,M=new Map,w=null;function y(e,t){let r=document.createElement("button");return r.textContent=e,r.setAttribute("aria-pressed","false"),r.addEventListener("click",t),r}function l(e,t,r){let n=document.createElement(e);return n.className=t,n.textContent=r,n}function V(e,t){let r=document.createElement("div");r.className=`box ${e.kind}${t?" trigger":""}`,r.append(l("span","tag",e.kind)),r.append(x("span","label",e.name));let n=e.value;return n!==void 0&&(typeof n!="object"||n===null)&&r.append(l("span","val",JSON.stringify(n))),r}function X(e,t,r){let n=q(e),o=document.createElement("div");o.className="flow";for(let[a,i]of n.entries())o.append(V(i,i.name===t)),a<n.length-1&&o.append(l("div","arrow","\u2193"));r.append(o)}function Z(e){let t=document.createElement("div");if(t.className="scroll",e.append(t),h===null){t.append(l("p","empty","Nothing selected."),l("p","hint","Press \u201CPick\u201D and click an element."));return}let r=A(h);if(r.length>0){t.append(l("p","hint","Component"));let i=document.createElement("div");i.className="crumbs";for(let s of r)i.append(l("span","crumb",s));t.append(i)}let n=$(h);if(n.length===0){t.append(l("p","empty","Nothing reactive writes this node."));return}let o=H(h);t.append(l("p","hint","Path"));for(let i of n)X(i,o,t);t.append(l("p","cause",o===null?"Has not run since anything changed.":`Triggered by ${o}`));let a=T(h).slice(-6).reverse();a.length>0&&(t.append(l("p","hint",`Last ${String(a.length)} updates`)),t.append(F(a))),c!==null&&e.append(N(S(c)))}function F(e){M.clear();let t=Math.max(1,...e.map(n=>n.ran.length)),r=document.createElement("div");r.className="track";for(let n of e){let o=document.createElement("div");o.className="tick",o.setAttribute("aria-selected",String(n===c)),M.set(o,n),o.append(l("span","when",`${String(n.at)}ms`)),o.append(x("span","who",n.source));let a=document.createElement("span");a.className=n.ran.length===0?"bar none":"bar",a.style.width=`${String(Math.round(n.ran.length/t*60)+6)}px`,a.title=`woke ${String(n.ran.length)} of ${String(t)}`,o.append(a);let i=n.stack[0];i!==void 0&&o.append(x("span","where",i,_)),o.addEventListener("click",()=>{I(n)}),r.append(o)}return r}function U(e){let t=/^(.*?)\(?([^()\s]+):(\d+):(\d+)\)?$/.exec(e);if(t===null)return e;let[,r,n,o,a]=t,i=Math.max(n.lastIndexOf("/"),n.lastIndexOf("\\")),s=n.slice(i+1),u=s.indexOf("?"),m=`${(u===-1?s:s.slice(0,u)).trim()}:${o}:${a}`;return r.trim()===""?m:`${r.trim()} (${m})`}function _(e){let t=/\(([^()]+)\)\s*$/.exec(e);return(t===null?e:t[1]).trim()}function x(e,t,r,n=o=>o){let o=l(e,t,n(U(r)));return O(r).then(a=>{o.textContent=n(U(a))}),o}function N(e){return e.classList.add("pinned"),e}function S(e){let t=document.createElement("div");t.className="detail";let r=document.createElement("div");r.className="detail-head",r.append(x("p","hint",e.source,o=>`${o} woke ${String(e.ran.length)}`));let n=y("\xD7",()=>{I(e)});n.setAttribute("aria-label","Close detail"),r.append(n),t.append(r);for(let o of e.ran)t.append(x("div","ran",o));if(e.stack.length>0){t.append(l("p","hint","Written from"));let o=document.createElement("div");o.className="stack";for(let a of e.stack)o.append(x("div","",a));t.append(o)}return t}function I(e){c=c===e?null:e;for(let[r,n]of M)r.setAttribute("aria-selected",String(n===c));let t=E?.body;t!==void 0&&(t.querySelector(".pinned")?.remove(),c!==null&&t.append(N(S(c))))}function ee(e){let t=T();if(t.length===0){e.append(l("p","empty","Nothing has changed yet."));return}let r=document.createElement("div");r.className="scroll",e.append(r);let n=[...new Set(t.map(a=>a.source))];if(n.length>1){let a=document.createElement("div");a.className="filters";for(let i of n){let s=x("span","chip",i);s.setAttribute("aria-pressed",String(w===i)),s.addEventListener("click",()=>{w=w===i?null:i,c=null,f()}),a.append(s)}r.append(a)}let o=w===null?t:t.filter(a=>a.source===w);r.append(l("p","hint",`${String(o.length)} of ${String(t.length)} updates`)),r.append(F([...o].reverse())),c!==null&&e.append(N(S(c)))}function te(e){let t=document.createElement("div");t.className="scroll",e.append(t);let r=C();if(r.length===0){t.append(l("p","empty","The query cache has done nothing yet."));return}for(let n of[...r].reverse()){let o=document.createElement("div");o.className="event",o.append(l("span",n.event,n.event)),o.append(l("span","tags",n.tags.join(", "))),t.append(o)}}function f(){if(E===null)return;let{body:e,pick:t,graphTab:r,queryTab:n,timelineTab:o}=E,a=e.querySelector(".scroll")?.scrollTop??0;r.setAttribute("aria-pressed",String(g==="graph")),n.setAttribute("aria-pressed",String(g==="queries")),o.setAttribute("aria-pressed",String(g==="timeline")),t.setAttribute("aria-pressed",String(v)),e.textContent="",g==="graph"?Z(e):g==="queries"?te(e):ee(e);let i=e.querySelector(".scroll");i!==null&&(i.scrollTop=a)}function G(e){!v||d===null||e.composedPath().includes(d)||(e.preventDefault(),e.stopPropagation(),h=e.target,v=!1,document.querySelector(`.${b}`)?.classList.remove(b),f())}function z(e){if(!v)return;document.querySelector(`.${b}`)?.classList.remove(b);let t=e.target;t!==null&&t!==d&&t.classList.add(b)}function j(){if(d!==null)return;d=document.createElement("div"),d.setAttribute("data-firsthand-devtools","");let e=d.attachShadow({mode:"open"}),t=document.createElement("style");t.textContent=K;let r=document.createElement("style");r.textContent=`.${b} { outline: 2px solid #3d5afe !important; outline-offset: 1px; }`,document.head.append(r);let n=document.createElement("div");n.className="panel";let o=document.createElement("header");o.append(l("strong","","Firsthand"));let a=y("Pick",()=>{v=!v,f()});a.dataset.pick="";let i=y("Graph",()=>{g="graph",f()});i.dataset.tab="graph";let s=y("Queries",()=>{g="queries",f()});s.dataset.tab="queries";let u=y("Timeline",()=>{g="timeline",f()});u.dataset.tab="timeline";let p=y("\xD7",R);p.setAttribute("aria-label","Close"),o.append(a,i,s,u,p);let m=document.createElement("div");m.className="body",n.append(o,m),e.append(t,n),document.body.append(d),E={body:m,pick:a,graphTab:i,queryTab:s,timelineTab:u},document.addEventListener("click",G,!0),document.addEventListener("mouseover",z,!0),L(()=>{c!==null||k!==null||(k=requestAnimationFrame(()=>{k=null,f()}))}),f()}function R(){L(null),k!==null&&(cancelAnimationFrame(k),k=null),document.removeEventListener("click",G,!0),document.removeEventListener("mouseover",z,!0),document.querySelector(`.${b}`)?.classList.remove(b),d?.remove(),d=null,E=null,c=null,w=null,v=!1,h=null,g="graph"}function ae(){d===null?j():R()}function ie(e){j(),h=e,g="graph",f()}function se(){f()}export{R as close,j as open,se as refresh,ie as show,ae as toggle};

package/dist/index.d.ts

@@ -0,0 +1,163 @@
+/** What a node of the graph is. */
+export type NodeKind = 'signal' | 'computed' | 'effect' | 'part';
+/**
+ * One update: a write, and everything that ran because of it.
+ *
+ * This is the thing the graph cannot answer on its own. The graph says what
+ * depends on what; an update says what actually happened, in order, at a time.
+ */
+export interface Update {
+    /** Milliseconds since the page loaded, so entries can be read as a sequence. */
+    at: number;
+    /** What was written. */
+    source: string;
+    /** What ran, in the order it ran. */
+    ran: string[];
+    /**
+     * Where the write came from, application frames only.
+     *
+     * "Which signal changed" is half an answer; the other half is which of your
+     * code changed it, and an event handler three files away is exactly the case
+     * where the graph cannot help.
+     *
+     * Kept exactly as the engine gave them, positions in the *compiled* module
+     * and all — browsers do not apply source maps to `error.stack`. The panel
+     * resolves them through the module's own map before showing them; anything
+     * else reading this should do the same.
+     */
+    stack: string[];
+}
+/** Something the query cache did. */
+export interface QueryEvent {
+    event: 'created' | 'invalidated' | 'dropped';
+    /** The cache key: its tags and variables, as the client derived them. */
+    key: string;
+    /** The tags the entry carries, which is what an invalidation matches on. */
+    tags: readonly string[];
+}
+/** One node of the graph, as devtools describe it. */
+export interface GraphNode {
+    kind: NodeKind;
+    /** `order.status`, `isEditable`, `button.disabled`, or a creation site. */
+    name: string;
+    /** The value the cell currently holds. */
+    value: unknown;
+    /** What this node reads. */
+    dependencies: GraphNode[];
+    /** What reads this node. */
+    dependents: GraphNode[];
+}
+/**
+ * Starts recording.
+ *
+ * Call it before the application creates anything — an import at the top of
+ * the entry module is the usual place — because a cell created earlier has no
+ * name to record. It stays in the graph; it is simply labelled by its
+ * creation site rather than by what it is called.
+ */
+export declare function attach(): void;
+/** What `attach()` puts on `globalThis` for the browser console to use. */
+export interface Console {
+    chain: typeof chain;
+    inspect: typeof inspect;
+    causeOf: typeof causeOf;
+    stack: typeof stack;
+    timeline: typeof timeline;
+    cells: typeof cells;
+    queries: typeof queries;
+    detach: typeof detach;
+    /** Opens the panel, or shows it for a node you already have. */
+    panel: (node?: Node) => void;
+}
+/** Stops recording and forgets everything. Mostly for tests. */
+export declare function detach(): void;
+/** Every computed and effect currently alive, in owner order. */
+export declare function cells(): GraphNode[];
+/**
+ * What feeds a DOM node, all the way up to the signals.
+ *
+ * This is the question the panel exists for: the node is on the screen, the
+ * value is wrong, and what you want to know is where it came from.
+ */
+export declare function inspect(node: Node, depth?: number): GraphNode[];
+/**
+ * The chain from a DOM node up to its sources, as text.
+ *
+ * ```
+ * order.status
+ *    ↓
+ * computed(isEditable)
+ *    ↓
+ * button.disabled
+ * ```
+ *
+ * Only the deepest path is drawn, because a chain is a story and a tree is
+ * not. `inspect` returns the whole shape for anything that wants it.
+ */
+export declare function chain(node: Node): string;
+/**
+ * The longest path through a node's dependencies, sources first.
+ *
+ * One path rather than the whole tree, because a chain is a story: it is what
+ * `chain` prints and what the panel draws as boxes. `inspect` has the shape
+ * for anything that wants all of it.
+ */
+export declare function path(node: GraphNode): GraphNode[];
+/**
+ * Why an effect last ran: the dependency whose change scheduled it.
+ *
+ * The graph does not keep this — nothing needs it once the flush is over — so
+ * it is the one fact devtools record rather than read.
+ */
+export declare function causeOf(node: Node): string | null;
+/**
+ * What the query cache has done, oldest first.
+ *
+ * The cache is the one part of the framework whose behaviour is not in the
+ * reactive graph: a tag match is a decision rather than an edge, and an
+ * invalidation that matched nothing looks exactly like one that was never
+ * sent. Bounded to the last 200 events, because a long session should not
+ * become a memory leak in a debugging tool.
+ *
+ * ```ts
+ * queries().filter((e) => e.event === 'invalidated');
+ * ```
+ */
+export declare function queries(): QueryEvent[];
+/**
+ * Registers something to be told when the graph has settled.
+ *
+ * Used by the panel to redraw itself. Exported because the panel is a separate
+ * module, not because an application should need it.
+ */
+export declare function watch(onSettled: (() => void) | null): void;
+/**
+ * The component stack a DOM node's part lives in, outermost first.
+ *
+ * The owner tree already has the shape — a component's scope is the parent of
+ * everything its setup created — so this is a walk, not a recording. What the
+ * DOM layer contributes is the name, which only it knows and only at the
+ * moment an instance is created.
+ *
+ * ```ts
+ * stack(button); // ['App', 'OrderPage', 'SaveButton']
+ * ```
+ */
+export declare function stack(node: Node): string[];
+/**
+ * Every update, oldest first: what was written, and what ran because of it.
+ *
+ * The graph answers "what depends on this". This answers "what happened", in
+ * order and with a time — which is the question when something updated and
+ * nobody expected it to.
+ *
+ * ```ts
+ * timeline();            // everything
+ * timeline(button);      // only the updates that ran this node's part
+ * ```
+ *
+ * The last 100 updates, so that a page left open overnight is still a
+ * debugging tool rather than a leak.
+ */
+export declare function timeline(node?: Node): Update[];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAeA,mCAAmC;AACnC,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAC;IACX,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,GAAG,EAAE,MAAM,EAAE,CAAC;IACd;;;;;;;;;;;OAWG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,qCAAqC;AACrC,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,SAAS,GAAG,aAAa,GAAG,SAAS,CAAC;IAC7C,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CACzB;AAED,sDAAsD;AACtD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,QAAQ,CAAC;IACf,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,KAAK,EAAE,OAAO,CAAC;IACf,4BAA4B;IAC5B,YAAY,EAAE,SAAS,EAAE,CAAC;IAC1B,4BAA4B;IAC5B,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB;AA0ID;;;;;;;GAOG;AACH,wBAAgB,MAAM,IAAI,IAAI,CAuH7B;AAED,2EAA2E;AAC3E,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,OAAO,EAAE,OAAO,OAAO,CAAC;IACxB,OAAO,EAAE,OAAO,OAAO,CAAC;IACxB,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,OAAO,EAAE,OAAO,OAAO,CAAC;IACxB,MAAM,EAAE,OAAO,MAAM,CAAC;IACtB,gEAAgE;IAChE,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,KAAK,IAAI,CAAC;CAC9B;AAED,gEAAgE;AAChE,wBAAgB,MAAM,IAAI,IAAI,CAkB7B;AA8ED,iEAAiE;AACjE,wBAAgB,KAAK,IAAI,SAAS,EAAE,CAMnC;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,SAAI,GAAG,SAAS,EAAE,CAM1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAMxC;AAED;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,EAAE,CASjD;AAMD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAYjD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,IAAI,UAAU,EAAE,CAEtC;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,SAAS,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAE1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAsB1C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,MAAM,EAAE,CAW9C"}

package/dist/index.js

@@ -0,0 +1 @@
+import{a,b,c,d,e,f,g,h,i,j,k}from"./chunk-5XEHZQPH.js";export{a as attach,g as causeOf,c as cells,e as chain,b as detach,d as inspect,f as path,h as queries,j as stack,k as timeline,i as watch};

package/dist/panel.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Opens the panel.
+ *
+ * In a shadow root with `all: initial`, so the page's stylesheet cannot reach
+ * it and its own cannot reach the page. An inspector that changes what it is
+ * inspecting is worse than no inspector.
+ */
+export declare function open(): void;
+/** Closes the panel and removes everything it added to the page. */
+export declare function close(): void;
+/** Opens the panel, or closes it if it is already open. */
+export declare function toggle(): void;
+/** Shows the panel for a node the caller already has. */
+export declare function show(node: Node): void;
+/** Redraws, for a caller that changed something and wants to see it. */
+export declare function refresh(): void;
+//# sourceMappingURL=panel.d.ts.map

package/dist/panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel.d.ts","sourceRoot":"","sources":["../src/panel.ts"],"names":[],"mappings":"AAgfA;;;;;;GAMG;AACH,wBAAgB,IAAI,IAAI,IAAI,CA2E3B;AAED,oEAAoE;AACpE,wBAAgB,KAAK,IAAI,IAAI,CAiB5B;AAED,2DAA2D;AAC3D,wBAAgB,MAAM,IAAI,IAAI,CAM7B;AAED,yDAAyD;AACzD,wBAAgB,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAKrC;AAED,wEAAwE;AACxE,wBAAgB,OAAO,IAAI,IAAI,CAE9B"}

package/dist/source.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Turning a generated position back into the one that was written.
+ *
+ * `new Error().stack` reports where code is, not where it came from: browsers
+ * do not apply source maps to `error.stack`, so a frame names a line in the
+ * compiled module. In a framework that compiles JSX into templates and thunks,
+ * that line is nothing the author recognises — which makes a call stack in a
+ * panel worse than none, because it looks authoritative.
+ *
+ * So the map is read here. It is already in the served module, as an inline
+ * comment, which is why this needs no build step and no second request beyond
+ * the module itself.
+ */
+/**
+ * Rewrites a stack frame to the position that was written.
+ *
+ * `handleSave (http://host/src/order.ts:31:7)` becomes
+ * `handleSave (order.ts:12:9)` — the line the author would find by opening the
+ * file. A frame that cannot be resolved is handed back unchanged rather than
+ * guessed at.
+ */
+export declare function original(frame: string): Promise<string>;
+/** Forgets what has been fetched. For tests, and for a page that reloaded. */
+export declare function forget(): void;
+//# sourceMappingURL=source.d.ts.map

package/dist/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA8HH;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA6B7D;AAED,8EAA8E;AAC9E,wBAAgB,MAAM,IAAI,IAAI,CAE7B"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@firsthandjs/devtools",
+  "version": "0.4.0",
+  "description": "Experimental devtools for Firsthand: see what updates what, why it ran, and when.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@firsthandjs/core": "0.4.0"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/firsthandjs/firsthand.git",
+    "directory": "packages/devtools"
+  },
+  "bugs": {
+    "url": "https://github.com/firsthandjs/firsthand/issues"
+  },
+  "homepage": "https://github.com/firsthandjs/firsthand#readme",
+  "keywords": [
+    "firsthand",
+    "devtools",
+    "experimental",
+    "reactive",
+    "signals",
+    "debugging"
+  ]
+}