gesso-devtools 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# gesso-devtools
+
+## 0.1.0
+
+First public release.
+
+**The error overlay.** A canvas application that throws leaves its last good
+frame on screen, looking exactly like one that works. `mountErrorOverlay(host)`
+returns a `report` matching `WorkerAppOptions.onError`, so wiring it is one
+line. It draws the message over the application, says which of five sources it
+came from and what that costs the running app, quotes the original source line
+with a caret under the column, and maps every stack frame back through the
+source maps -- decoded in this package, with no dependency. A repeat counts
+instead of stacking up, and a dismissal survives an error that throws every
+frame.
+
+**The panels**, each written against a port and hosted either by the Chrome
+devtools extension or by a pane in the page: the node tree with owners, a
+node's report (props with their sources, `listens`, `beneath`, and the layout
+explanation), the frame profiler, the action log, and the render and
+application workers' consoles with the thread named.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Baker
+
+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,34 @@
+# gesso-devtools
+
+See what a Gesso application is doing, and what it threw.
+
+```bash
+npm install --save-dev gesso-devtools
+```
+
+## The error overlay
+
+A canvas application that throws leaves its last good frame on screen, looking exactly like one that works. This draws the failure over it:
+
+```ts
+import { mountErrorOverlay } from 'gesso-devtools';
+
+createApp({ onError: mountErrorOverlay(document.body) }).mount('#app');
+```
+
+`mountErrorOverlay(host)` returns a `report` matching `WorkerAppOptions.onError`, so wiring it is one line. It names which of five sources the failure came from and decodes the source maps of the scripts the stack names, so a frame points at the file somebody wrote rather than at a bundled line and column.
+
+## The panels
+
+- **Node inspector** -- the tree with owners, and a node's report: props with their sources, `listens`, `beneath`, and the layout explanation
+- **Frame profiler** -- where a frame's milliseconds went, by phase
+- **Action log** -- what crossed the barrier, with the cause that started it
+- **Worker consoles** -- `console.*` from the render and application workers, with the thread named
+
+`connectDevtools()` in your render worker is the one line that makes an application answer a panel. The same panel is hosted two ways: a Chrome devtools extension, and a pane inside the page.
+
+## Documentation
+
+[Devtools](https://github.com/kevinpbaker/gesso/blob/main/apps/docs/tooling/devtools.md) | [Errors and the overlay](https://github.com/kevinpbaker/gesso/blob/main/apps/docs/structure/errors-and-the-overlay.md) | [Frames and phases](https://github.com/kevinpbaker/gesso/blob/main/apps/docs/tooling/frames-and-phases.md)
+
+MIT (c) Kevin Baker