@weasel-js/devtools 0.0.0-stage → 1.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 orochi235
+
+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

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# @weasel-js/devtools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A devtools panel for weasel canvases. It connects to the devtools hook every
+`<SceneCanvas>` registers with (`@weasel-js/core/devtools`), and reads and
+steers each canvas on the page: it never edits a scene.
+
+Part of [weasel](https://github.com/orochi235/weasel), a domain-agnostic 2D
+scene-graph canvas kit for React. See the
+[API reference](https://orochi235.github.io/weasel/#pkg/devtools).
+
+```sh
+npm install @weasel-js/devtools
+```
+
+```tsx
+import { DevtoolsPanel, createInPagePanelTransport } from '@weasel-js/devtools';
+import '@weasel-js/devtools/style.css';
+
+const transport = createInPagePanelTransport();
+
+<div className="devtools-dock">
+  <DevtoolsPanel transport={transport} />
+</div>;
+```
+
+The panel fills its container, so give the container a size.
+
+| Tab | Shows | Steers |
+|---|---|---|
+| Scene | the node tree, loaded a level at a time; a node's parent, pose and data | `select` the picked node; hovering a row outlines it on the canvas |
+| State | selection, view, active tool, overlay flags, probes | the active tool; each debug overlay flag |
+| Dispatch | every resolved input and mode switch, newest first, under what a press at the pointer would do; coord records behind a toggle | — |
+| Frame | the last paint's CPU time and draw calls, per render layer, while the `fps` overlay is on | the `fps` overlay |
+
+`tabs={['dispatch']}` shows only the tabs named, and drops the tab bar when
+one is left.
+
+## Transports
+
+`DevtoolsPanel` takes any `PanelTransport` (`{ send, onMessage }`).
+`createInPagePanelTransport()` reaches this page's own hook, opening a fresh
+session on each `yo`, so a panel that remounts reconnects. An extension passes
+the panel end of whatever bridge carries messages to the page.
+
+## Without React
+
+`connectDevtools(transport)` is the protocol client the panel is built on: the
+handshake, numbered requests and their replies, the roots the page reports, and
+its change notices. `followTrace(client, rootId)` reads a canvas's dispatch
+trace a slice at a time through its cursors.

package/dist/DevtoolsPanel.d.ts

@@ -0,0 +1,20 @@
+import { type ReactElement } from 'react';
+import type { PanelTransport } from '@weasel-js/core/devtools-protocol';
+import { type DevtoolsTabId } from './tabs';
+/** Props for {@link DevtoolsPanel}. */
+export interface DevtoolsPanelProps {
+    /** The panel's end of a connection to a page's devtools hook. */
+    transport: PanelTransport;
+    /** The tabs to show, in the panel's own order. Default: every tab. With one, the tab bar is left out. */
+    tabs?: readonly DevtoolsTabId[];
+    /** The tab open first. Default: the first shown. */
+    defaultTab?: DevtoolsTabId;
+    className?: string;
+}
+/**
+ * Reads and steers the canvases of the page `transport` reaches: pick a canvas,
+ * then walk its scene, read its state, follow its dispatch trace, or watch its
+ * frame stats. It fills its container; give that a size.
+ */
+export declare function DevtoolsPanel({ transport, tabs, defaultTab, className }: DevtoolsPanelProps): ReactElement;
+//# sourceMappingURL=DevtoolsPanel.d.ts.map

package/dist/DevtoolsPanel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DevtoolsPanel.d.ts","sourceRoot":"","sources":["../src/DevtoolsPanel.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,YAAY,EAAE,MAAM,OAAO,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAKxE,OAAO,EAAmC,KAAK,aAAa,EAAE,MAAM,QAAQ,CAAC;AAG7E,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,SAAS,EAAE,cAAc,CAAC;IAC1B,yGAAyG;IACzG,IAAI,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC,oDAAoD;IACpD,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,EAAE,kBAAkB,GAAG,YAAY,CA+B1G"}

package/dist/RootPicker.d.ts

@@ -0,0 +1,10 @@
+import type { ReactElement } from 'react';
+import type { DevtoolsRootInfo } from '@weasel-js/core/devtools-protocol';
+export interface RootPickerProps {
+    roots: readonly DevtoolsRootInfo[];
+    value: string | null;
+    onChange(rootId: string): void;
+}
+/** Which canvas the panel reads, each named by its label and dimension. */
+export declare function RootPicker({ roots, value, onChange }: RootPickerProps): ReactElement;
+//# sourceMappingURL=RootPicker.d.ts.map

package/dist/RootPicker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RootPicker.d.ts","sourceRoot":"","sources":["../src/RootPicker.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAC1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAI1E,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACnC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,eAAe,GAAG,YAAY,CAiBpF"}

package/dist/client.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The panel's side of the devtools protocol, free of any framework: the
+ * handshake, request ids and their replies, the roots the page reports, and
+ * its change notices. The views, the extension and tests all drive this.
+ */
+import { type DevtoolsArea, type DevtoolsHistorySlice, type DevtoolsNodeDetail, type DevtoolsNodeSummary, type DevtoolsRegistry, type DevtoolsRequest, type DevtoolsRootInfo, type DevtoolsRootState, type DevtoolsTraceSlice, type PanelTransport, type SerializedValue } from '@weasel-js/core/devtools-protocol';
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/** A request as a caller writes it: the client adds the protocol, the request id and the root. */
+export type DevtoolsRequestBody = DistributiveOmit<DevtoolsRequest, 'protocol' | 'requestId' | 'rootId'>;
+/** What each request resolves to. */
+export interface DevtoolsResultMap {
+    'get-children': DevtoolsNodeSummary[];
+    'get-node': DevtoolsNodeDetail;
+    'get-state': DevtoolsRootState;
+    'get-trace': DevtoolsTraceSlice;
+    'get-frame': SerializedValue;
+    'get-registry': DevtoolsRegistry;
+    'get-history': DevtoolsHistorySlice;
+    select: null;
+    highlight: null;
+    'set-tool': null;
+    'set-overlays': null;
+}
+/** Where a connection stands. `error` holds a message the page sent about no request, such as a protocol mismatch. */
+export interface DevtoolsClientState {
+    status: 'connecting' | 'connected' | 'error' | 'closed';
+    kitVersion: string | null;
+    roots: readonly DevtoolsRootInfo[];
+    error: string | null;
+}
+/** One open connection to a page's devtools hook, from the panel's side. */
+export interface DevtoolsClient {
+    state(): DevtoolsClientState;
+    /** Hear every change to {@link DevtoolsClient.state}. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** Hear a root's `changed` notices, with the areas each names. Returns the unsubscribe. */
+    onChanged(listener: (rootId: string, areas: DevtoolsArea[]) => void): () => void;
+    /** Send `body` about `rootId`. Rejects with the page's message when it refuses. */
+    request<B extends DevtoolsRequestBody>(rootId: string, body: B): Promise<DevtoolsResultMap[B['type']]>;
+    /** Say `yo` and start listening. Called again after {@link DevtoolsClient.close}, it reconnects. */
+    open(): void;
+    /** Say `bye` and stop listening. Pending requests reject. */
+    close(): void;
+}
+/** A connection over `transport`, sending nothing until it is opened. It is connected once the page says `sup`. */
+export declare function createDevtoolsClient(transport: PanelTransport): DevtoolsClient;
+/** {@link createDevtoolsClient}, opened: it says `yo` at once. */
+export declare function connectDevtools(transport: PanelTransport): DevtoolsClient;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACc,KAAK,YAAY,EAAE,KAAK,oBAAoB,EAAE,KAAK,kBAAkB,EAAE,KAAK,mBAAmB,EAClH,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,KAAK,kBAAkB,EACjG,KAAK,cAAc,EAAE,KAAK,eAAe,EAC5D,MAAM,mCAAmC,CAAC;AAE3C,KAAK,gBAAgB,CAAC,CAAC,EAAE,CAAC,SAAS,WAAW,IAAI,CAAC,SAAS,OAAO,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC;AAEzF,kGAAkG;AAClG,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,eAAe,EAAE,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC,CAAC;AAEzG,qCAAqC;AACrC,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,mBAAmB,EAAE,CAAC;IACtC,UAAU,EAAE,kBAAkB,CAAC;IAC/B,WAAW,EAAE,iBAAiB,CAAC;IAC/B,WAAW,EAAE,kBAAkB,CAAC;IAChC,WAAW,EAAE,eAAe,CAAC;IAC7B,cAAc,EAAE,gBAAgB,CAAC;IACjC,aAAa,EAAE,oBAAoB,CAAC;IACpC,MAAM,EAAE,IAAI,CAAC;IACb,SAAS,EAAE,IAAI,CAAC;IAChB,UAAU,EAAE,IAAI,CAAC;IACjB,cAAc,EAAE,IAAI,CAAC;CACtB;AAED,sHAAsH;AACtH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,YAAY,GAAG,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAC;IACxD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACnC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,KAAK,IAAI,mBAAmB,CAAC;IAC7B,kFAAkF;IAClF,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5C,2FAA2F;IAC3F,SAAS,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACjF,mFAAmF;IACnF,OAAO,CAAC,CAAC,SAAS,mBAAmB,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACvG,oGAAoG;IACpG,IAAI,IAAI,IAAI,CAAC;IACb,6DAA6D;IAC7D,KAAK,IAAI,IAAI,CAAC;CACf;AAOD,mHAAmH;AACnH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,cAAc,GAAG,cAAc,CAiF9E;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,SAAS,EAAE,cAAc,GAAG,cAAc,CAIzE"}

package/dist/history.d.ts

@@ -0,0 +1,13 @@
+/** A root's history steps read a slice at a time through their cursor, the stack's entries along with them on request. */
+import type { DevtoolsHistorySlice } from '@weasel-js/core/devtools-protocol';
+import type { DevtoolsClient } from './client';
+/** A cursor over one root's history steps. */
+export interface HistoryFollower {
+    /** The steps recorded since the last read, and where the history stands now. Reads run one after another. */
+    read(): Promise<DevtoolsHistorySlice>;
+    /** Ask for the stack's entries with every read from the next on. */
+    setCheckpoints(on: boolean): void;
+}
+/** Follow `rootId`'s history steps through `client`, from the oldest step the canvas still holds. */
+export declare function followHistory(client: DevtoolsClient, rootId: string): HistoryFollower;
+//# sourceMappingURL=history.d.ts.map

package/dist/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"AAAA,0HAA0H;AAC1H,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,8CAA8C;AAC9C,MAAM,WAAW,eAAe;IAC9B,6GAA6G;IAC7G,IAAI,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACtC,oEAAoE;IACpE,cAAc,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;CACnC;AAED,qGAAqG;AACrG,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe,CAqBrF"}

package/dist/hooks.d.ts

@@ -0,0 +1,22 @@
+import type { DevtoolsArea, PanelTransport } from '@weasel-js/core/devtools-protocol';
+import { type DevtoolsClient, type DevtoolsClientState } from './client';
+/** A connection over `transport` for as long as the component is mounted: `yo` on mount, `bye` on unmount. */
+export declare function useDevtoolsClient(transport: PanelTransport): {
+    client: DevtoolsClient;
+    state: DevtoolsClientState;
+};
+/** What a view reads about one root: the last answer, or the page's refusal. */
+export interface RootQuery<T> {
+    data: T | undefined;
+    error: string | null;
+    /** Ask again now, as after a steering request whose effect no notice reports. */
+    refresh(): void;
+}
+/**
+ * `read`'s answer about `rootId`, asked again whenever a `changed` notice for
+ * that root names one of `areas`, or a dependency in `deps` changes.
+ */
+export declare function useRootQuery<T>(client: DevtoolsClient, rootId: string, areas: readonly DevtoolsArea[], read: () => Promise<T>, deps?: readonly unknown[]): RootQuery<T>;
+/** Call `tick` every `ms` while `enabled` and the page is visible, and once at the start. */
+export declare function usePoll(tick: () => void, ms: number, enabled: boolean): void;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAEtF,OAAO,EAAwB,KAAK,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAE/F,8GAA8G;AAC9G,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,cAAc,GAAG;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAQnH;AAED,gFAAgF;AAChF,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,iFAAiF;IACjF,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,IAAI,GAAE,SAAS,OAAO,EAAO,GAC5B,SAAS,CAAC,CAAC,CAAC,CAuBd;AAED,6FAA6F;AAC7F,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAgB5E"}

package/dist/inPageTransport.d.ts

@@ -0,0 +1,9 @@
+import { type PanelTransport, type WeaselDevtoolsHook } from '@weasel-js/core/devtools-protocol';
+/**
+ * A panel's end of a connection to this page's own hook. Each `yo` opens a
+ * fresh session and each `bye` ends it, the way a `yo` posted to the window
+ * does, so a panel that unmounts and mounts again reconnects. Installs the
+ * hook when the page has none.
+ */
+export declare function createInPagePanelTransport(hook?: WeaselDevtoolsHook | null): PanelTransport;
+//# sourceMappingURL=inPageTransport.d.ts.map

package/dist/inPageTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inPageTransport.d.ts","sourceRoot":"","sources":["../src/inPageTransport.ts"],"names":[],"mappings":"AAAA,OAAO,EACwC,KAAK,cAAc,EAAE,KAAK,kBAAkB,EAC1F,MAAM,mCAAmC,CAAC;AAE3C;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,GAAE,kBAAkB,GAAG,IAA4B,GAAG,cAAc,CAiBlH"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @weasel-js/devtools — a panel that reads and steers every `<SceneCanvas>` on
+ * a page through the devtools hook (`@weasel-js/core/devtools`). Mount
+ * `DevtoolsPanel` over any transport; `connectDevtools` is the same protocol
+ * client without React.
+ */
+export { connectDevtools, createDevtoolsClient } from './client';
+export type { DevtoolsClient, DevtoolsClientState, DevtoolsRequestBody, DevtoolsResultMap } from './client';
+export { followTrace } from './trace';
+export type { TraceFollower, TraceRead } from './trace';
+export { followHistory } from './history';
+export type { HistoryFollower } from './history';
+export { DevtoolsPanel } from './DevtoolsPanel';
+export type { DevtoolsPanelProps } from './DevtoolsPanel';
+export type { DevtoolsTabId } from './tabs';
+export { createInPagePanelTransport } from './inPageTransport';
+//# 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":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACjE,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC5G,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,YAAY,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC"}