mates-devtools 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -0,0 +1,188 @@
+# mates-devtools
+
+In-app developer tools panel for the [Mates](https://www.npmjs.com/package/mates) framework.
+
+Renders a floating FAB button that opens a resizable panel giving you full
+visibility into your running app — components, atoms, hooks, logs, network
+requests, and performance timings — all without leaving the browser.
+
+---
+
+## Installation
+
+```bash
+npm install mates-devtools
+# mates is a required peer dependency
+npm install mates
+```
+
+---
+
+## Quick start
+
+Call `renderMatesDevTools()` **before** `renderX()` so hooks are installed
+before any component mounts.
+
+```ts
+import { renderX } from "mates";
+import { renderMatesDevTools } from "mates-devtools";
+import { App } from "./App";
+
+renderMatesDevTools();          // 👈 must come first
+renderX(App, document.getElementById("app")!);
+```
+
+A ⚙️ FAB appears in the bottom-right corner of the page. Click it to open the
+panel.
+
+---
+
+## API
+
+### `renderMatesDevTools()`
+
+Installs the framework hooks and renders the FAB + panel into `document.body`.
+Safe to call multiple times — subsequent calls are no-ops.
+
+```ts
+import { renderMatesDevTools } from "mates-devtools";
+renderMatesDevTools();
+```
+
+### `destroyMatesDevTools()`
+
+Tears down the FAB, the panel, all subscriptions, and the framework hooks.
+Safe to call even if DevTools was never started.
+
+```ts
+import { destroyMatesDevTools } from "mates-devtools";
+destroyMatesDevTools();
+```
+
+---
+
+## Panel tabs
+
+| Tab | What you see |
+|-----|-------------|
+| **Components** | Live component tree with mount count, render count, and version badges that flash on every re-render. Click any component to inspect its props, scopes, atoms, hooks, and `useState` values. |
+| **Logs** | Timestamped stream of component lifecycle events (mount / render / unmount), atom reads/writes, event triggers, and Fetch requests/responses/errors. |
+| **Performance** | Per-component render timing: total time, average time, slowest render, and a micro bar chart of the last 20 renders. |
+| **Timers** | Active `setInterval` / `setTimeout` calls tracked by the devtools timer interceptor, so you can spot runaway timers. |
+
+---
+
+## Component inspector
+
+Selecting a component in the left-hand list reveals a right-hand inspector with
+five collapsible sections:
+
+- **Props** — current prop values rendered as a collapsible value tree.
+- **Scopes** — reactive scopes owned by the component with their current atom snapshots.
+- **Atoms** — all atoms read by the component and their current values.
+- **Hooks** — lifecycle hooks (`onMount`, `onUnmount`, `onChange`, …) registered by the component.
+- **useState** — local `useState` values.
+
+---
+
+## Low-level exports
+
+Advanced usage only — these are the internal building blocks used by the panel
+itself.
+
+### Registry
+
+```ts
+import {
+  registerComponent, unregisterComponent, notifyRender,
+  getComponentName,  getComponentGroups, getComponentsByView,
+  getComponentDepth, getAllComponents,    getRenderVersion,
+  devToolsEvent,
+} from "mates-devtools";
+```
+
+### Log store
+
+```ts
+import {
+  connectLogStore,    disconnectLogStore,  getLogs,
+  getLogCount,        getUnreadLogCount,   isLogStoreConnected,
+  onLogEntry,         markLogsRead,        clearLogs,
+  logAtomSet,         logAtomUpdate,       logComponentMount,
+  logComponentRender, logComponentUnmount, logEventTrigger,
+  logCleanupEventTrigger,
+} from "mates-devtools";
+import type { LogEntry, LogCategory } from "mates-devtools";
+```
+
+### Perf store
+
+```ts
+import {
+  connectPerfStore,   disconnectPerfStore, isPerfStoreConnected,
+  recordRender,       startRenderTiming,   getPerfSummaries,
+  getRecentTimings,   getSlowestRenders,   clearPerfData,
+  onPerfEntry,
+} from "mates-devtools";
+import type { RenderTiming, ComponentPerfSummary } from "mates-devtools";
+```
+
+### Component fragments
+
+Each panel section is independently exported if you want to embed a single
+viewer in your own UI:
+
+```ts
+import { renderAtomsViewer }       from "mates-devtools";
+import { renderComponentInspector } from "mates-devtools";
+import { renderComponentList }      from "mates-devtools";
+import { renderComponentTree }      from "mates-devtools";
+import { renderHooksViewer }        from "mates-devtools";
+import { renderLogsViewer }         from "mates-devtools";
+import { renderPerfViewer }         from "mates-devtools";
+import { renderPropsViewer }        from "mates-devtools";
+import { renderScopesViewer }       from "mates-devtools";
+import { renderUseStateViewer }     from "mates-devtools";
+```
+
+### Styles
+
+The CSS-in-JS style map used internally — handy if you're theming the panel:
+
+```ts
+import { styles } from "mates-devtools";
+```
+
+---
+
+## Types
+
+```ts
+import type {
+  DevToolsPosition,        // "bottom-right" | "bottom-left" | "top-right" | "top-left"
+  DevToolsTab,             // "components" | "logs" | "perf" | "timers"
+  ComponentInfo,
+  ComponentGroup,
+  LogEntry,
+  LogCategory,
+  RenderTiming,
+  ComponentPerfSummary,
+} from "mates-devtools";
+```
+
+---
+
+## Peer dependencies
+
+| Package | Version |
+|---------|---------|
+| `mates` | `*` (any version) |
+
+`mates-devtools` does **not** bundle mates — it is listed as a peer dependency
+so you always get a single shared copy of the framework at runtime.
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mates-devtools",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "description": "In-app DevTools panel for the Mates framework",
   "type": "module",
   "main": "./dist/mates-devtools.umd.js",
@@ -14,7 +14,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
     "build": "vite build && tsc -p tsconfig.build.json",