gesso-devtools 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1076 @@
+import { ActionCause, ActionEntry, ChannelErrorEntry, ChannelPort, CommandEntry, DevtoolsEvent, DevtoolsRequest, FrameEntry, FrameMetrics, PatchEntry, RuntimeErrorSource, ShellToRuntimeMessage, UiFramePhase, UiNodeReport, UiTreeNode, WorkerHandle } from "gesso-framework";
+//#region src/sourceMap.d.ts
+/**
+ * Enough of Source Map v3 to turn a compiled stack frame back into the
+ * line somebody wrote.
+ *
+ * Written here rather than taken from npm for the reason the rest of
+ * the repository's tooling gives (`scripts/gen-layout-fixtures.ts`,
+ * `scripts/check-webgpu-parity.ts`): the whole of what this package
+ * needs is a VLQ decoder and a binary search, and a dependency that
+ * ships a `SourceMapConsumer` with a WASM payload is a heavier thing to
+ * put in front of a developer trying to read an error than the error
+ * was.
+ *
+ * Two deliberate omissions. Index maps (`sections`) are not read — no
+ * bundler this project builds with emits one. Names are not read
+ * either: a stack frame already carries the function name the engine
+ * knew, and the mapped name is only occasionally better.
+ */
+/** A source map as a bundler writes it. */
+interface SourceMapV3 {
+  version: number;
+  file?: string;
+  sourceRoot?: string;
+  sources: (string | null)[];
+  sourcesContent?: (string | null)[];
+  names?: string[];
+  mappings: string;
+}
+/** Where a generated position came from, with 1-based line and column. */
+interface OriginalPosition {
+  /** The source as the map names it, with `sourceRoot` already applied. */
+  source: string;
+  line: number;
+  column: number;
+  /**
+   * The original text of the source, when the map inlined it.
+   *
+   * Carried on the position rather than fetched from the consumer
+   * afterwards because a chained lookup ends in a consumer the caller
+   * never sees: the map that knows the text is the last one in the
+   * chain, not the one the caller started from. See
+   * `SourceMapStore.originalFor`.
+   */
+  content?: string | null;
+}
+/**
+ * One decoded mapping segment.
+ *
+ * Held as a flat tuple rather than an object because a map for a
+ * medium application has hundreds of thousands of them, and they exist
+ * only to be searched.
+ */
+type Segment = [generatedColumn: number, sourceIndex: number, sourceLine: number, sourceColumn: number];
+/**
+ * Decodes the `mappings` string into one array of segments per
+ * generated line.
+ *
+ * Segments carrying only a generated column — a run of output with no
+ * original position, which is what a bundler emits for code it
+ * synthesised — are dropped rather than kept with nulls. A lookup that
+ * lands in one should fall back to the nearest earlier real mapping,
+ * and dropping them is how that happens without a second case.
+ */
+declare function decodeMappings(mappings: string): Segment[][];
+/**
+ * A decoded map, answering "which line of which source is this?".
+ *
+ * Decoding is done once in the constructor because a page that shows
+ * one error usually shows several from the same file, and each of them
+ * asks about a handful of positions.
+ */
+declare class SourceMapConsumer {
+  private readonly lines;
+  private readonly sources;
+  private readonly contents;
+  constructor(map: SourceMapV3);
+  /**
+   * Maps a generated position — 1-based line and column, as every
+   * engine writes them in a stack — back to an original one.
+   *
+   * Returns the last mapping at or before the column, which is the
+   * definition of a source map's coverage: a mapping holds until the
+   * next one starts. Null when the line has no mappings at all.
+   */
+  lookup(line: number, column: number): OriginalPosition | null;
+  /** The original text of a source, when the map inlined it. */
+  contentFor(source: string): string | null;
+}
+/**
+ * The `sourceMappingURL` a script declares, or null.
+ *
+ * The last one wins, and the search is a `lastIndexOf` over the whole
+ * text rather than a regex over the tail: an inlined map is a single
+ * comment megabytes long, so "near the end" is not where its opening
+ * is.
+ */
+declare function parseSourceMappingUrl(script: string): string | null;
+/**
+ * Fetches and caches the map for each script a stack mentions.
+ *
+ * Every method resolves rather than rejects: this runs while
+ * something has already gone wrong, and an overlay that throws while
+ * explaining a throw is worse than an overlay showing a raw stack.
+ * A script with no map, a map that 404s and a map that is not JSON all
+ * come back as null, and the caller shows what the engine gave it.
+ */
+declare class SourceMapStore {
+  private readonly cache;
+  private readonly load;
+  constructor(load?: (url: string) => Promise<string>);
+  /** The consumer for a script URL, fetched at most once per store. */
+  consumerFor(scriptUrl: string): Promise<SourceMapConsumer | null>;
+  /**
+   * Where a position in a script was written, following the chain of
+   * maps as far as it goes.
+   *
+   * One lookup is not enough, and the reason took a browser to find. A
+   * frame inside `gesso-framework` names Vite's optimised dependency
+   * bundle; that bundle's map points at the package's own
+   * `dist/index.js`, because the optimiser does not chain to the map
+   * the package ships; and it is the package's map that knows about
+   * `src/app/worker/RenderWorkerApp.ts`. Stopping after one step gave
+   * a frame in a bundled file with a five-figure line number, which is
+   * exactly the thing shipping the maps was meant to prevent.
+   *
+   * So each answer is resolved against the map that gave it and asked
+   * again, until a source has no map of its own — which is the source
+   * somebody wrote. `depth` is a guard against a map that names
+   * itself; four is more levels than any real toolchain stacks.
+   */
+  originalFor(scriptUrl: string, line: number, column: number, depth?: number): Promise<OriginalPosition | null>;
+  private resolve;
+}
+//#endregion
+//#region src/ErrorOverlay.d.ts
+/**
+ * Where an error came from.
+ *
+ * The render worker's four sources, plus `window` for the thread the
+ * overlay itself runs on — the single-thread configuration, and
+ * anything the shell does around the app.
+ */
+type ErrorOrigin = RuntimeErrorSource | 'window';
+interface ErrorOverlayOptions {
+  /**
+   * Also write every error to the console (default true).
+   *
+   * On by default because the overlay is a second place to see an
+   * error, not a replacement for the first: the console keeps the live
+   * object, its `cause`, and the "expand to see the real frames" that
+   * no snapshot of a stack can offer.
+   */
+  echoToConsole?: boolean;
+  /** Where source maps are fetched from. Injected by the specs. */
+  sourceMaps?: SourceMapStore;
+}
+/**
+ * The error overlay: what a worker threw, drawn over the app that was
+ * running when it threw.
+ *
+ * A canvas UI has no equivalent of a page that stops rendering. When a
+ * render worker throws, the last good frame stays on screen — pixels
+ * that look exactly like a working application — and the only witness
+ * is a console message on a thread the developer has to know to
+ * select. `WorkerApp` already forwards those errors to `onError`;
+ * this is that callback, with the stack put back through the source
+ * maps and the offending line quoted.
+ *
+ * It is a development tool and it makes a development tool's trade:
+ * it fetches source maps, keeps every distinct error of the session,
+ * and covers the application it is reporting on.
+ */
+declare class ErrorOverlay {
+  private readonly host;
+  /**
+   * The document the host belongs to, rather than the global one.
+   *
+   * The same rule `SemanticsMirror` follows: everything this class
+   * builds hangs off the element it was handed, so it works in a
+   * second window and can be driven by a fake document in a spec —
+   * which is the only way to test it in a suite that runs in Node.
+   */
+  private readonly doc;
+  private readonly view;
+  private readonly container;
+  private readonly root;
+  private readonly panel;
+  private readonly maps;
+  private readonly echo;
+  private readonly entries;
+  private readonly restoreHostPosition;
+  private shown;
+  private disposed;
+  private detachWindow;
+  constructor(host: HTMLElement, options?: ErrorOverlayOptions);
+  /** How many distinct errors have been reported. */
+  get count(): number;
+  /** True while the overlay is covering the app. */
+  get visible(): boolean;
+  /**
+   * Reports an error, in the shape `WorkerApp`'s `onError` hands it
+   * over, so the whole wiring is `onError: overlay.report`.
+   *
+   * Bound as a field rather than a method for exactly that: it is
+   * passed as a callback far more often than it is called.
+   */
+  report: (message: string, stack?: string, origin?: ErrorOrigin) => void;
+  /** Reports a thrown value, which is usually but not always an Error. */
+  reportError: (error: unknown, origin?: ErrorOrigin) => void;
+  /**
+   * Catches what this thread throws, too.
+   *
+   * The single-thread configuration runs components here, and even in
+   * the worker configuration the shell around the app can throw. Returns
+   * a function that stops listening; `dispose` calls it as well.
+   */
+  captureWindowErrors(target?: Window | null): () => void;
+  /** Hides the overlay. The errors are kept and can be shown again. */
+  hide(): void;
+  /** Hides the overlay and forgets every error it was holding. */
+  clear(): void;
+  dispose(): void;
+  private show;
+  private handleKeyDown;
+  /**
+   * Maps the entry's stack and quotes the line it points at.
+   *
+   * Deliberately after the first paint: the raw stack is on screen
+   * within a frame of the error, and the mapped one replaces it when
+   * the network answers. A developer looking at an error should never
+   * be waiting on a fetch to see it.
+   */
+  private resolveSources;
+  /** `element`, bound to this overlay's document. */
+  private el;
+  /** A header button, bound to this overlay's document. */
+  private button;
+  private render;
+  private step;
+  private copy;
+}
+/**
+ * Mounts an error overlay over an application's host element.
+ *
+ *   const overlay = mountErrorOverlay(host);
+ *   createApp({ renderWorker, onError: overlay.report });
+ *   overlay.captureWindowErrors();
+ */
+declare function mountErrorOverlay(host: HTMLElement, options?: ErrorOverlayOptions): ErrorOverlay;
+//#endregion
+//#region src/ActionLog.d.ts
+/**
+ * The store action log: every command a view sent
+ * across the barrier, every patch that came back, on one timeline,
+ * with the view rewindable to any point on it.
+ *
+ * The seam is the port. A channel is two message types over a
+ * `ChannelPort`, so a recorder that sits in the middle of one sees
+ * both directions at their only crossing, needs nothing from the
+ * framework beyond the two type guards the protocol already exports,
+ * and can put a patch back on the wire, which is what makes time
+ * travel a replay rather than a second write path into the replica.
+ *
+ * Nothing here touches the DOM. That is deliberate: the tap belongs
+ * wherever the ports already are, which in the worker configuration is
+ * the render worker, and a recorder that imported a document could not
+ * go there. `ActionLogPanel` is the half that draws.
+ *
+ * **What time travel does.** It rewrites what the *view* holds. The
+ * authoritative state lives on the other thread and is not rewound,
+ * cannot be rewound from here, and does not know this happened. While
+ * the log is pinned to a step, patches still arriving are recorded and
+ * held rather than delivered, so the view stays where it was put;
+ * going live delivers the state the application actually reached. A
+ * command sent from the view while pinned is forwarded like any other,
+ * because the application is still running and pretending otherwise
+ * would be a lie about a button that visibly did something.
+ */
+interface ActionLog {
+  /**
+   * Wraps a worker handle so every channel opened on it is recorded.
+   *
+   * `tokens` is read for one thing: the value both ends of a channel
+   * start from. The first patch a provider sends is a diff against the
+   * token's initial, so a recorder that started from nothing would
+   * reconstruct an early step out of a patch whose base it never had.
+   */
+  tap(handle: WorkerHandle, tokens: readonly ActionLogToken[]): WorkerHandle;
+  /**
+   * Wraps one port, for a channel fed from this thread.
+   *
+   * `createChannelRegistry` makes the pair for a `source` registration
+   * itself and hands out neither end, so a local channel is tapped by
+   * providing it by hand instead: call `provide(token, source, port)`
+   * on one end of a `MessageChannel` and register the other through
+   * this.
+   */
+  tapPort(port: ChannelPort, token: ActionLogToken): ChannelPort;
+  /**
+   * Names what is being answered for as long as the returned function
+   * has not been called, so everything recorded meanwhile carries the
+   * same `ActionCause`.
+   *
+   * Called around the dispatch of one input, which is the only moment
+   * where a cause is known rather than guessed: the command a click's
+   * listener sends is sent synchronously inside it. Nothing is
+   * allocated for an input that records nothing, so wrapping every
+   * pointer move costs a function call and a null check.
+   *
+   * The patches that answer such a command are given the same cause,
+   * which is an inference and the record says so: the barrier carries
+   * no request id, so the recorder ties the next patch batch on that
+   * channel to the command that preceded it, until a frame has drawn
+   * one or another command replaces it.
+   */
+  cause(label: string): () => void;
+  /**
+   * Records the frame that drew whatever has been recorded since the
+   * last one, closing the chain from click to command to patches to
+   * pixels.
+   *
+   * Nothing is recorded for a frame with nothing to close, so an
+   * application drawing sixty frames a second while its channels are
+   * quiet adds nothing to the timeline.
+   */
+  frame(id: number): void;
+  /** The timeline, oldest first. */
+  readonly entries: readonly ActionEntry[];
+  /** The channels this log is tapping, by name, in the order tapped. */
+  readonly channels: readonly string[];
+  /**
+   * The entry the view is pinned to, or null when the view is live.
+   *
+   * A sequence number rather than an index, because entries fall off
+   * the front of a bounded log and an index would then mean a
+   * different entry than it did a moment ago.
+   */
+  readonly pinnedTo: number | null;
+  /**
+   * Rewinds every tapped channel's view to the state it held once
+   * `seq` had been applied, or catches it up to the application when
+   * `seq` is null.
+   *
+   * Each key is posted to the replica as one `{ op: 'set', path: [] }`,
+   * which is the shape a reattaching client is already answered with,
+   * so nothing downstream can tell a replay from a resync.
+   */
+  jumpTo(seq: number | null): void;
+  /** Empties the timeline and goes live. Tapped channels stay tapped. */
+  clear(): void;
+  /** Called whenever the timeline or the pinned step changed. */
+  subscribe(listener: () => void): () => void;
+  /**
+   * Stops recording, leaving every tapped channel working.
+   *
+   * The relay is not removed. A port handed to a replica cannot be
+   * taken back out of the middle of it, so what this does is stop
+   * listening: messages pass through, nothing is written down, and a
+   * held patch could not be stranded by it.
+   */
+  dispose(): void;
+}
+/**
+ * A channel's identity, structurally.
+ *
+ * The same erasure `ChannelRegistration` uses, and for the same
+ * reason: a list of channels has no single generic instantiation, and
+ * the only two things a recorder wants from a token are its name and
+ * the value both ends start from.
+ */
+interface ActionLogToken {
+  readonly name: string;
+  readonly initial: object;
+}
+interface ActionLogOptions {
+  /**
+   * Most entries kept. Default 200.
+   *
+   * A dropped entry is not forgotten, only unaddressable: its patches
+   * are folded into the base state each channel is reconstructed from,
+   * so a jump to a step that survived is still exact.
+   */
+  readonly limit?: number;
+}
+declare function createActionLog(options?: ActionLogOptions): ActionLog;
+/**
+ * Sends each new entry as it is recorded, and returns a function that
+ * stops.
+ *
+ * `subscribe` says only that something changed, so the sequence number
+ * is what tells a new entry from the ones already sent; a `clear`
+ * resets it, and a bounded log retiring old entries does not. Both
+ * routes to a panel need exactly this: the hook, for a log in the
+ * page, and the render worker tap, for one on the other side of a
+ * thread.
+ */
+declare function forwardNewEntries(log: ActionLog, send: (entry: ActionEntry) => void): () => void;
+//#endregion
+//#region src/ActionLogPanel.d.ts
+/**
+ * The action log's panel: the timeline, and a click on any step to put
+ * the view back where it was at that step.
+ *
+ * DOM in a shadow root over the canvas, for the reasons the error
+ * overlay and the node inspector both give: the application owns the
+ * canvas, and a panel drawn into the scene would be part of the scene
+ * it is describing.
+ *
+ * It differs from the node inspector in one way that matters. The
+ * inspector takes no pointer events because the person is hovering the
+ * thing it describes; this panel is operated, so it takes them over
+ * itself and nowhere else. That is also why it is behind a toggle
+ * rather than always up: while it is showing, the canvas underneath it
+ * is not reachable.
+ */
+interface ActionLogPanel {
+  /** Shows or hides the panel. A hidden panel stops rendering. */
+  setVisible(visible: boolean): void;
+  readonly visible: boolean;
+  dispose(): void;
+}
+interface ActionLogPanelOptions {
+  /** Which corner it floats in. Default `'bottom-right'`. */
+  readonly corner?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+}
+declare function mountActionLogPanel(host: HTMLElement, log: ActionLog, options?: ActionLogPanelOptions): ActionLogPanel;
+/**
+ * The direction, as one glyph: up for what the view sent, down for
+ * what came back, a square for the frame that drew it.
+ */
+declare function actionGlyph(entry: ActionEntry): string;
+/** One entry as a line: the command and its payload, the patched keys, the frame, or the error. */
+declare function describeActionEntry(entry: ActionEntry): string;
+//#endregion
+//#region src/RenderWorkerTap.d.ts
+/**
+ * The action log in the worker configuration, and the click at the
+ * head of every chain it records.
+ *
+ * The action log recorded the gap and the reason for it. A channel's
+ * ports are made where the replicas are, which in the worker
+ * configuration is the render worker; the shell holds neither end and
+ * never sees a patch, deliberately. So the recorder was written to run
+ * in a worker — it imports no DOM and its entries are plain data — and
+ * then nothing ran it there, because the two ways to wire it up were
+ * "one line in the render worker's entry" and "route every patch
+ * through the main thread", and the second would falsify the very
+ * thing the route exists to show.
+ *
+ * This is that one line, made general. It stands on the wire the way
+ * the recorder itself does, which is the rule `0047` set: **the tap
+ * goes where the messages already are, never somewhere new.** In a
+ * render worker three kinds of message go past one object, the
+ * worker's global:
+ *
+ *   - the shell's port to the application worker, which arrives with
+ *     `init` and is what a tapped channel has to be opened over;
+ *   - every input the shell forwards, which is where a cause begins;
+ *   - every frame the runtime reports, which is where one ends.
+ *
+ * Nothing here reaches into the runtime, and nothing in the framework
+ * knows it exists. Used after `renderRoot`, whose constructor installs
+ * the handler this wraps:
+ *
+ *   const app = renderRoot(AppRoot).useService(Counter);
+ *   const actions = createActionLog();
+ *   const tap = tapRenderWorker(actions);
+ *   const data = tap.applicationWorker([Catalog, Cart]);
+ *   app.useChannel(Catalog, { worker: data }).useChannel(Cart, { worker: data });
+ *
+ * Guard it with `import.meta.env.DEV` or the equivalent: a tap in a
+ * production bundle is a recorder holding patch batches for a session
+ * nobody is watching.
+ */
+/** The worker global, as far as the tap is concerned. */
+interface RenderWorkerHost {
+  onmessage: ((event: {
+    data: unknown;
+  }) => void) | null;
+  postMessage(message: unknown, transfer?: Transferable[]): void;
+}
+interface RenderWorkerTapOptions {
+  /** Where to stand. Default: the worker's own global. */
+  readonly host?: RenderWorkerHost;
+  /**
+   * Whether entries are posted to the shell as devtools events, so a
+   * panel outside the page shows them. Default true.
+   *
+   * The route a log in the page does not need: there the devtools hook
+   * has the log itself to read.
+   */
+  readonly forward?: boolean;
+}
+interface RenderWorkerTap {
+  /**
+   * A handle on the application worker the shell supplied, with every
+   * channel opened over it recorded.
+   *
+   * Registrations run before `init` and the shell's port arrives with
+   * it, which is why this is a handle rather than a port: it is opened
+   * when the runtime starts, by which time the port is here. Passing
+   * it to `useChannel` is what replaces the `APPLICATION_WORKER`
+   * placeholder the render worker would otherwise swap in.
+   */
+  applicationWorker(tokens: readonly ActionLogToken[]): WorkerHandle;
+  dispose(): void;
+}
+declare function tapRenderWorker(log: ActionLog, options?: RenderWorkerTapOptions): RenderWorkerTap;
+/**
+ * What to call the cause an input starts, or null for a message that
+ * is not an input.
+ *
+ * Position is in the label because two presses in different places are
+ * two different causes to the person who made them, and the ids alone
+ * do not say which was which.
+ */
+declare function inputLabel(message: ShellToRuntimeMessage | undefined): string | null;
+//#endregion
+//#region src/NodePicker.d.ts
+/**
+ * Click a node on the canvas to pin it in the panel
+ * (the first of the two things the node inspector deferred).
+ *
+ * Picking was left out because the panel could not name a node back
+ * to the runtime. The devtools panel built that half: `select` and
+ * `highlight` address a node by id, and the inspector already reports
+ * the node under the pointer while it is on. What was still missing is
+ * the click, and a click is the one part of this that cannot happen in
+ * the render thread. By the time the runtime has an event, the event
+ * has been dispatched; taking it back would mean asking the
+ * application to forget a press it may already have acted on.
+ *
+ * So the pick happens where the click arrives, in the capture phase,
+ * over the element the canvas is in. That is the shell doing what the
+ * shell does — forwarding input, or in this case declining to
+ * — and it costs nothing while picking is off,
+ * because the listeners are attached only then.
+ *
+ * What it pins is whatever the inspector last reported as hovered, so
+ * a picker needs the inspector on; the panel turns it on with the same
+ * toggle.
+ */
+interface NodePickerOptions {
+  /**
+   * The element to take clicks over, in the capture phase. The one the
+   * application is mounted in, so the canvas is inside it.
+   */
+  readonly host: EventTarget;
+  /** The node under the pointer, from the runtime's `hover` reports. */
+  hovered(): string | null;
+}
+/** What a panel drives: arm it, and hear what was picked. */
+interface DevtoolsPicker {
+  /** Whether clicking the canvas pins a node instead of reaching the application. */
+  setEnabled(enabled: boolean): void;
+  readonly enabled: boolean;
+  /** Called with the id of the node picked. Pass null to stop listening. */
+  onPick(listener: ((id: string) => void) | null): void;
+  dispose(): void;
+}
+declare function createNodePicker(options: NodePickerOptions): DevtoolsPicker;
+//#endregion
+//#region src/NodeReportView.d.ts
+interface NodeReportViewOptions {
+  /**
+   * Makes the props editable, calling this with the new value when one
+   * is committed; `null` means "remove it", which puts an inherited
+   * value back.
+   *
+   * Absent for a read-only view. The corner inspector passes nothing,
+   * because it sets `pointer-events: none` and could not be typed into
+   * anyway.
+   */
+  onEditProp?(name: string, value: unknown): void;
+}
+/**
+ * A `UiNodeReport` as DOM: the node inspector's body, shared with the
+ * devtools panel so a node read in a corner of the canvas and a node
+ * picked from a tree are described in the same words.
+ */
+declare function renderNodeReport(doc: Document, report: UiNodeReport, options?: NodeReportViewOptions): HTMLElement[];
+/**
+ * The rules the report's elements use, for any stylesheet that shows one.
+ *
+ * Colours are the devtools panel's custom properties with the dark
+ * palette as fallback, so the corner inspector, which defines none of
+ * them, is unchanged, and the panel recolours the same report by
+ * defining them.
+ */
+declare const NODE_REPORT_STYLES = "\nh1 { margin: 0 0 6px; font-size: 12px; color: var(--gd-accent, #79c0ff); overflow-wrap: anywhere; }\nh2 {\n  margin: 10px 0 4px;\n  font-size: 10px;\n  text-transform: uppercase;\n  letter-spacing: 0.08em;\n  color: var(--gd-muted, #8b949e);\n}\np { margin: 0 0 2px; }\n.label { color: var(--gd-muted, #8b949e); }\n.rows { display: grid; grid-template-columns: auto 1fr; gap: 0 8px; margin: 0; }\ndt { color: var(--gd-muted, #8b949e); overflow-wrap: anywhere; }\ndt.modifier { color: var(--gd-purple, #d2a8ff); }\ndt.binding { color: var(--gd-green, #7ee787); }\ndt.provided { color: var(--gd-orange, #ffa657); }\ndd { margin: 0; overflow-wrap: anywhere; }\ndd.editable { cursor: pointer; border-radius: 3px; }\ndd.editable:hover { background: var(--gd-bg-hover, #21262d); }\n.edit {\n  width: 100%;\n  box-sizing: border-box;\n  border: 1px solid var(--gd-accent, #79c0ff);\n  border-radius: 3px;\n  padding: 0 3px;\n  background: var(--gd-bg, #0d1117);\n  color: var(--gd-text, #e6edf3);\n  font: inherit;\n}\n.note { color: var(--gd-faint, #6e7681); }\n.stream { display: block; color: var(--gd-green, #7ee787); }\n.explanation { margin: 0; white-space: pre-wrap; overflow-wrap: anywhere; color: var(--gd-text-strong, #c9d1d9); }\n";
+//#endregion
+//#region src/PanelProtocol.d.ts
+/**
+ * What a devtools panel and the page it inspects say to each other
+ *.
+ *
+ * The framework's `DevtoolsRequest` and `DevtoolsEvent` are one
+ * application's vocabulary. A page may run several (a documentation
+ * site's examples), and a panel arrives after they started, so this
+ * layer adds the two things the framework's protocol does not have: an
+ * application id on every message, and a greeting that answers with
+ * the list.
+ *
+ * Both sides speak through a `DevtoolsPort`, which is only `post` and
+ * `onMessage`. Two ports are provided here: a pair joined in memory,
+ * for a panel mounted in the same page and for tests, and one over
+ * `window.postMessage`, which is how a browser extension's content
+ * script reaches a page. The extension's own hop, from its content
+ * script to its devtools page, is one more port of the same shape and
+ * lives with the extension.
+ */
+interface DevtoolsAppInfo {
+  readonly id: string;
+  readonly name: string;
+}
+/** Page to panel. */
+type PageMessage =
+/** The applications the page has connected; sent on `hello` and whenever the list changes. */
+{
+  type: 'apps';
+  apps: readonly DevtoolsAppInfo[];
+} | {
+  type: 'event';
+  app: string;
+  event: DevtoolsEvent;
+} |
+/** A store action log entry, from an `ActionLog` the application connected alongside itself. */
+{
+  type: 'action';
+  app: string;
+  entry: ActionEntry;
+} |
+/**
+ * A node the person clicked on the canvas while the panel was
+ * picking. The panel selects it; the click never reaches the
+ * application.
+ */
+{
+  type: 'picked';
+  app: string;
+  id: string;
+};
+/** Panel to page. */
+type PanelMessage =
+/** "Is anyone there": answered with `apps`. */
+{
+  type: 'hello';
+} | {
+  type: 'request';
+  app: string;
+  request: DevtoolsRequest;
+} |
+/**
+ * Turns click-to-pick on or off.
+ *
+ * Not a `DevtoolsRequest`, because it is not a question for the
+ * runtime. Picking is a click that must be taken before the
+ * application sees it, and the only place a click can be taken is
+ * the page, where it arrives; the runtime is a thread away and would
+ * have to be asked to un-dispatch something. So the page answers
+ * this one, and the runtime is asked to `select` the node the page
+ * names, which is a question it already answers.
+ */
+{
+  type: 'pick';
+  app: string;
+  enabled: boolean;
+};
+/** One end of a conversation: what it hears and what it says. */
+interface DevtoolsPort<In, Out> {
+  post(message: Out): void;
+  /** Returns a function that stops listening. */
+  onMessage(listener: (message: In) => void): () => void;
+  /** Drops every listener and stops posting. */
+  close(): void;
+}
+/** The page's end. */
+type PagePort = DevtoolsPort<PanelMessage, PageMessage>;
+/** The panel's end. */
+type PanelPort = DevtoolsPort<PageMessage, PanelMessage>;
+/**
+ * Two ports joined in memory, delivering synchronously.
+ *
+ * For a panel mounted in the page it inspects, and for specs: the
+ * hook and the panel are exercised end to end with nothing between
+ * them but a function call.
+ */
+declare function createDirectPorts(): {
+  page: PagePort;
+  panel: PanelPort;
+};
+/** What a message carries over `window.postMessage`, so both sides can ignore everything else on the window. */
+interface Envelope<T> {
+  readonly source: typeof ENVELOPE_SOURCE;
+  /** Who it is for. A page ignores what it sent, and so does a panel. */
+  readonly to: 'page' | 'panel';
+  readonly message: T;
+}
+declare const ENVELOPE_SOURCE = "gesso-devtools";
+declare function isEnvelope(value: unknown, to: 'page' | 'panel'): value is Envelope<unknown>;
+/** The part of `Window` the transport uses, so a spec can hand it a plain object. */
+interface WindowLike {
+  addEventListener(type: 'message', listener: (event: {
+    data: unknown;
+    source?: unknown;
+  }) => void): void;
+  removeEventListener(type: 'message', listener: (event: {
+    data: unknown;
+    source?: unknown;
+  }) => void): void;
+  postMessage(message: unknown, targetOrigin: string): void;
+  readonly location?: {
+    readonly origin: string;
+  };
+}
+/**
+ * The page's end of a conversation over its own window.
+ *
+ * A content script shares the page's window but not its JavaScript, so
+ * `window.postMessage` to the page's own origin is the one channel
+ * they have. Messages are posted to that origin rather than to `*`,
+ * and the page hears only envelopes addressed to it, so its own posts
+ * come straight back through the same listener and are dropped.
+ */
+declare function windowPagePort(win: WindowLike): PagePort;
+/** The other end, for whatever sits in the page beside it (an extension's content script). */
+declare function windowPanelPort(win: WindowLike): PanelPort;
+//#endregion
+//#region src/DevtoolsHook.d.ts
+/**
+ * The page's side of the devtools panel.
+ *
+ * One object per page, kept on the window under a well-known name the
+ * way React's devtools hook is, so that several bundles (a docs site's
+ * examples, an application and its dependency) connect to the same
+ * hook and a panel sees one list. Applications register with it;
+ * panels attach ports to it; the hook routes requests to the right
+ * application and fans every application's events out to every port.
+ *
+ * `connectDevtools(app)` is the one line an application adds. It also
+ * installs the `window.postMessage` transport the first time, which is
+ * how a browser extension's content script finds the page: nothing is
+ * running in a page that has not connected, and a page that has
+ * connected answers `hello`.
+ */
+/** What an application must offer: both `WorkerApp` and `GessoApp` do. */
+interface DevtoolsApp {
+  devtools(request: DevtoolsRequest): void;
+  /**
+   * Taken over by the hook while connected. An application that was
+   * listening to its own devtools events has to choose: the panel or
+   * itself. In practice the events only exist for panels.
+   */
+  onDevtools(listener: ((event: DevtoolsEvent) => void) | null): void;
+}
+interface ConnectDevtoolsOptions {
+  /** What the panel calls this application. Default: the document title, else `app`. */
+  readonly name?: string;
+  /**
+   * A store action log the panel should show alongside. The log stays
+   * where it is (it taps ports in the page); the panel is sent each
+   * entry as it is recorded.
+   */
+  readonly actions?: ActionLog;
+  /**
+   * Lets the panel pick a node by clicking the canvas.
+   *
+   * The page's half of picking, because a click has to be taken before
+   * the application sees it and only the page has it in time. See
+   * `createNodePicker`.
+   */
+  readonly picker?: DevtoolsPicker;
+  /**
+   * Where the hook lives and where the `postMessage` transport
+   * listens. Default: the global window. `null` keeps the hook off any
+   * window and installs no transport, for a panel mounted directly.
+   */
+  readonly window?: (WindowLike & HookHost) | null;
+}
+interface DevtoolsHook {
+  /** The connected applications, in the order they connected. */
+  readonly apps: readonly DevtoolsAppInfo[];
+  /** Connects an application. Returns a function that disconnects it. */
+  register(app: DevtoolsApp, options?: Omit<ConnectDevtoolsOptions, 'window'>): () => void;
+  /** Attaches a panel's port. Returns a function that detaches it. */
+  attach(port: PagePort): () => void;
+}
+/** The property the hook is kept under. */
+declare const HOOK_PROPERTY = "__GESSO_DEVTOOLS__";
+/** A window, as far as the hook is concerned: somewhere to keep itself. */
+interface HookHost {
+  [HOOK_PROPERTY]?: DevtoolsHook;
+}
+/**
+ * The page's hook, created on first use.
+ *
+ * With a window, the hook is stored on it and the `postMessage`
+ * transport is attached once; without one (`null`), a fresh hook with
+ * no transport, for specs and for a panel in the same page.
+ */
+declare function getDevtoolsHook(win?: (WindowLike & HookHost) | null): DevtoolsHook;
+/**
+ * Connects an application to the page's devtools hook, so a panel can
+ * find it. Returns a function that disconnects it; call it when the
+ * application is disposed.
+ */
+declare function connectDevtools(app: DevtoolsApp, options?: ConnectDevtoolsOptions): () => void;
+//#endregion
+//#region src/DevtoolsPanel.d.ts
+/**
+ * The devtools panel: the tree, a node's
+ * report, the workers' consoles, the frame profiler and the action log,
+ * in one place, docked outside the canvas.
+ *
+ * It is plain DOM against a `PanelPort`, and knows nothing about where
+ * it is mounted: a Chrome extension's devtools page, or a pane in the
+ * page itself. That is what lets the same panel be both, and what lets
+ * a spec drive it through a port joined in memory.
+ *
+ * Unlike the in-page inspector, this panel does not float over the
+ * application, so it takes pointer events and can be as tall as its
+ * host. The trade is that it cannot point at the canvas with the
+ * pointer; it points with `highlight`, and the runtime draws the box.
+ */
+interface DevtoolsPanel {
+  /** The application the panel is showing, or null with none connected. */
+  readonly app: DevtoolsAppInfo | null;
+  /** Shows a different connected application. */
+  show(appId: string): void;
+  /** Changes the theme; see `DevtoolsPanelOptions.theme`. */
+  setTheme(theme: DevtoolsPanelTheme): void;
+  dispose(): void;
+}
+/**
+ * `light` and `dark` are the panel's two palettes; `auto` follows the
+ * viewer's `prefers-color-scheme`. A host that knows better than the
+ * media query says so: Chrome's devtools has its own theme setting,
+ * which the extension reads and passes here, and the playground is
+ * dark whatever the system prefers.
+ */
+type DevtoolsPanelTheme = 'light' | 'dark' | 'auto';
+interface DevtoolsPanelOptions {
+  /** Which palette. Default `auto`. */
+  readonly theme?: DevtoolsPanelTheme;
+  /** How many levels of the tree open on the first snapshot. Default 4. */
+  readonly openDepth?: number;
+  /** How many console entries are kept. Default 500. */
+  readonly consoleLimit?: number;
+  /** How many action entries are kept. Default 300. */
+  readonly actionLimit?: number;
+}
+declare function mountDevtoolsPanel(host: HTMLElement, port: PanelPort, options?: DevtoolsPanelOptions): DevtoolsPanel;
+//#endregion
+//#region src/TreeRows.d.ts
+/**
+ * A tree snapshot as the rows a panel draws.
+ *
+ * The panel keeps a set of expanded ids and asks for the rows; the
+ * tree can be replaced by a new snapshot every frame while the set
+ * stays, so a person's unfolding survives the application changing
+ * under it. Ids are positional, which is what makes that work and also
+ * what makes it approximate: a row that was a button can become a text
+ * when a list reorders. The report says what it is now.
+ */
+interface TreeRow {
+  readonly node: UiTreeNode;
+  readonly depth: number;
+  readonly expandable: boolean;
+  readonly expanded: boolean;
+  /** The nearest component anchor at or above this node, if any. */
+  readonly owner?: string;
+}
+/** The rows of the tree with `expanded` nodes unfolded, in document order. */
+declare function treeRows(root: UiTreeNode, expanded: ReadonlySet<string>): TreeRow[];
+/** The ids of every node with children down to `depth` levels, for a first unfolding. */
+declare function idsToDepth(root: UiTreeNode, depth: number): string[];
+/** The ids of the ancestors of `id`, root first, or null when the tree has no such node. */
+declare function pathTo(root: UiTreeNode, id: string): string[] | null;
+/** One row's label, as the tree prints it. */
+declare function rowLabel(row: TreeRow): string;
+//#endregion
+//#region src/NodeInspector.d.ts
+/**
+ * The node inspector: what the thing under the
+ * pointer is, and where every part of it came from.
+ *
+ * L8 already answered "why is this box that size" and printed it as
+ * text. This is the rest of the question a person actually has, which
+ * turned out to be four more: what did the element declare, what is a
+ * modifier writing over it, what is it inheriting, and which component
+ * rendered it. The layout explanation is still here, at the bottom,
+ * because it is still the answer to the first one.
+ *
+ * It is DOM, in a shadow root, over the canvas, for the same reasons
+ * the error overlay is: the application it is inspecting owns the
+ * canvas, and a panel drawn inside the scene would be part of the
+ * scene it is describing. It takes no pointer events at all, because
+ * the person is hovering the canvas underneath it and a panel that
+ * swallowed the pointer would erase the very thing it is showing.
+ */
+interface NodeInspector {
+  /** Shows the report, or hides the panel when null. */
+  set(report: UiNodeReport | null): void;
+  dispose(): void;
+}
+interface NodeInspectorOptions {
+  /**
+   * Which corner it floats in. Default `'bottom-left'`.
+   *
+   * A corner rather than a docked side, because the panel must not
+   * change the size of the element the application is mounted in: a
+   * readout that resized the canvas would relayout the scene it is
+   * describing, and the boxes it is pointing at would move.
+   */
+  readonly corner?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+}
+declare function mountNodeInspector(host: HTMLElement, options?: NodeInspectorOptions): NodeInspector;
+//#endregion
+//#region src/FrameProfiler.d.ts
+/**
+ * The frame profiler: where a frame's time went, over
+ * the last few seconds, as a picture.
+ *
+ * The timings have existed since L7 and the playground has been showing
+ * them as one clipped line of text, which is enough to read a number
+ * off and not enough to see a shape. A stall, a phase that only wakes
+ * on some frames, a render that grew when a route changed: all three
+ * are obvious in a strip of bars and invisible in a running average.
+ *
+ * It draws into a small canvas rather than a div per bar, because at 60
+ * frames a second a DOM per frame is more main-thread work than the
+ * thing being profiled. For the same reason it redraws on a timer
+ * rather than on every frame: the history is kept per frame, the
+ * picture is repainted a few times a second.
+ */
+interface FrameProfiler {
+  /** Feed it every frame. Cheap: it appends and returns. */
+  report(metrics: FrameMetrics): void;
+  /** Shows or hides the panel. Hidden panels stop redrawing. */
+  setVisible(visible: boolean): void;
+  readonly visible: boolean;
+  dispose(): void;
+}
+interface FrameProfilerOptions {
+  /** How many frames the strip holds. Default 180, about three seconds. */
+  readonly history?: number;
+  /** How often the picture is repainted, in milliseconds. Default 250. */
+  readonly redrawMs?: number;
+  readonly corner?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+  /**
+   * `floating` (the default) sits in a corner over the application;
+   * `docked` fills its host, for a panel that is not over anything.
+   */
+  readonly layout?: 'floating' | 'docked';
+}
+/** One bar's worth of history. */
+interface FrameSample {
+  readonly phases: Readonly<Record<UiFramePhase, number>>;
+  readonly total: number;
+  /** Gap since the previous frame, on the rendering thread's clock. */
+  readonly gap: number;
+  readonly input: number | null;
+}
+declare function mountFrameProfiler(host: HTMLElement, options?: FrameProfilerOptions): FrameProfiler;
+interface FrameSummary {
+  readonly fps: number;
+  readonly meanTotal: number;
+  readonly worstTotal: number;
+  readonly worstGap: number;
+  readonly worstInput: number | null;
+  readonly worstPhase: Record<UiFramePhase, number>;
+}
+/**
+ * The window's numbers.
+ *
+ * Peak rather than mean for the phases, for the reason the playground's
+ * status line already gives: patches and environment run on a small
+ * minority of frames, so a mean would report them as idle on exactly
+ * the frames where they were the cost.
+ */
+declare function summarize(samples: readonly FrameSample[]): FrameSummary;
+//#endregion
+//#region src/codeFrame.d.ts
+/** One line of a code frame, with the offending one marked. */
+interface CodeFrameLine {
+  number: number;
+  text: string;
+  /** True for the line the error was reported on. */
+  target: boolean;
+}
+/** A few lines of original source around a mapped position. */
+interface CodeFrame {
+  lines: CodeFrameLine[];
+  /** 1-based column on the target line, for the caret under it. */
+  column: number;
+}
+/**
+ * Cuts `context` lines either side of a position out of a source file.
+ *
+ * This is the part of an overlay that a stack trace cannot replace: a
+ * file and a line number send a person to their editor, while the line
+ * itself is often the whole answer — a `.length` on something that is
+ * undefined reads as the bug the moment it is on screen.
+ *
+ * Tabs are expanded to two spaces so the caret column below the line
+ * lands where the character does. Nothing else is transformed; the text
+ * reaches the DOM as text, never as markup.
+ */
+declare function codeFrame(source: string, line: number, column: number, context?: number): CodeFrame | null;
+//#endregion
+//#region src/stackTrace.d.ts
+/** A position in a compiled file, 1-based as every engine reports it. */
+interface StackLocation {
+  url: string;
+  line: number;
+  column: number;
+}
+/** One line of a stack, parsed as far as it could be. */
+interface StackFrame {
+  /** The line exactly as the engine wrote it. */
+  raw: string;
+  /** The function name the engine knew, or null for an anonymous frame. */
+  fn: string | null;
+  /** Where it ran, or null when the line named no file. */
+  location: StackLocation | null;
+  /** Where it was written, once a source map has been consulted. */
+  original: OriginalPosition | null;
+}
+/**
+ * Splits a stack string into frames, dropping the message lines an
+ * engine puts above them.
+ *
+ * The message is dropped rather than parsed because the caller already
+ * has it: `onError` reports the message and the stack separately, and
+ * a V8 stack repeats the message in its first line.
+ */
+declare function parseStack(stack: string): StackFrame[];
+/**
+ * Fills in `original` for every frame whose script has a source map.
+ *
+ * Maps are fetched once per script and the frames of one stack usually
+ * name two or three scripts, so this is a couple of requests. It never
+ * rejects: a frame that cannot be mapped keeps its compiled location,
+ * which is what the console would have shown anyway.
+ *
+ * `originalFor` rather than one `lookup`, because a frame inside a
+ * published package is two maps deep: the bundler's map of the
+ * dependency bundle, then the package's own. See its comment.
+ */
+declare function mapStack(frames: StackFrame[], store: SourceMapStore): Promise<StackFrame[]>;
+/**
+ * The first frame worth putting a code frame under.
+ *
+ * Frames inside the framework are skipped while any application frame
+ * remains, because an error thrown from a component surfaces through
+ * several layers of runtime and the runtime is almost never where the
+ * bug is. If every frame is a framework frame, the first one wins —
+ * the framework is then genuinely the answer.
+ */
+declare function primaryFrame(frames: StackFrame[]): StackFrame | null;
+/**
+ * A path short enough to read in a header: same-origin prefix and
+ * query string removed, `node_modules` collapsed to the package.
+ *
+ * The query matters more than it looks. A dev server rewrites imports
+ * with cache-busting parameters — `/src/App.tsx?t=1724965201` — and a
+ * stack full of those is unreadable for a reason that has nothing to
+ * do with the error.
+ */
+declare function shortenPath(url: string, origin?: string): string;
+/** `path:line:column` for a frame, mapped when it could be. */
+declare function formatFrame(frame: StackFrame, origin?: string): string;
+//#endregion
+export { type ActionCause, type ActionEntry, type ActionLog, type ActionLogOptions, type ActionLogPanel, type ActionLogPanelOptions, type ActionLogToken, type ChannelErrorEntry, type CodeFrame, type CodeFrameLine, type CommandEntry, type ConnectDevtoolsOptions, type DevtoolsApp, type DevtoolsAppInfo, type DevtoolsHook, type DevtoolsPanel, type DevtoolsPanelOptions, type DevtoolsPanelTheme, type DevtoolsPicker, type DevtoolsPort, ENVELOPE_SOURCE, type Envelope, type ErrorOrigin, ErrorOverlay, type ErrorOverlayOptions, type FrameEntry, type FrameProfiler, type FrameProfilerOptions, type FrameSample, type FrameSummary, HOOK_PROPERTY, type HookHost, NODE_REPORT_STYLES, type NodeInspector, type NodeInspectorOptions, type NodePickerOptions, type NodeReportViewOptions, type OriginalPosition, type PageMessage, type PagePort, type PanelMessage, type PanelPort, type PatchEntry, type RenderWorkerHost, type RenderWorkerTap, type RenderWorkerTapOptions, SourceMapConsumer, SourceMapStore, type SourceMapV3, type StackFrame, type StackLocation, type TreeRow, type WindowLike, actionGlyph, codeFrame, connectDevtools, createActionLog, createDirectPorts, createNodePicker, decodeMappings, describeActionEntry, formatFrame, forwardNewEntries, getDevtoolsHook, idsToDepth, inputLabel, isEnvelope, mapStack, mountActionLogPanel, mountDevtoolsPanel, mountErrorOverlay, mountFrameProfiler, mountNodeInspector, parseSourceMappingUrl, parseStack, pathTo, primaryFrame, renderNodeReport, rowLabel, shortenPath, summarize, tapRenderWorker, treeRows, windowPagePort, windowPanelPort };
+//# sourceMappingURL=index.d.ts.map