@opetope/devtools 0.1.0

package/dist/protocol.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Executable form of the diagnostic protocol. `docs/devtools.md` §2 sketched it before the
+ * decisions D68–D112 of [`decisions.md`](../../docs/decisions.md); where the two disagree the runtime wins, and it is
+ * recorded in the decision log of document 14 rather than by editing its prose.
+ *
+ * The protocol is data-only by construction: no callbacks, no `FeatureInstance`, no models, resources or repository
+ * objects, no raw `Error`, `AbortSignal` or thenable, no DOM or React instance (§2.6). Failures carry the subject and
+ * the code of the runtime's own error classes and nothing else — never a message, a stack or a cause (§2.6).
+ *
+ * The id brands are *optional* markers, and that is the whole of decision T29. `RuntimeInspectionSession` is a
+ * consumed interface: the runtime produces these ids and declares them `string` and `number`, so a required brand
+ * would have made the producer unable to satisfy the very interface written for it, and every host attaching the
+ * panel would have carried a cast. An optional marker keeps the names — a signature still reads `DiagnosticNodeId`,
+ * not `string` — while a plain string the runtime built is accepted as it is. What it does not do is keep the kinds
+ * apart at compile time; the guarantee that an id is well formed lives where it can be enforced, in the validators
+ * below and in the hostile decoder (§7).
+ */
+declare const conditionIdBrand: unique symbol;
+declare const edgeIdBrand: unique symbol;
+declare const nodeIdBrand: unique symbol;
+declare const planFingerprintBrand: unique symbol;
+declare const sequenceBrand: unique symbol;
+declare const sessionIdBrand: unique symbol;
+declare const stateRevisionBrand: unique symbol;
+declare const topologyRevisionBrand: unique symbol;
+type DiagnosticSessionId = string & {
+    readonly [sessionIdBrand]?: true;
+};
+type DiagnosticNodeId = string & {
+    readonly [nodeIdBrand]?: true;
+};
+type DiagnosticEdgeId = string & {
+    readonly [edgeIdBrand]?: true;
+};
+type DiagnosticConditionId = string & {
+    readonly [conditionIdBrand]?: true;
+};
+type DiagnosticPlanFingerprint = string & {
+    readonly [planFingerprintBrand]?: true;
+};
+type DiagnosticSequence = number & {
+    readonly [sequenceBrand]?: true;
+};
+type DiagnosticStateRevision = number & {
+    readonly [stateRevisionBrand]?: true;
+};
+type DiagnosticTopologyRevision = number & {
+    readonly [topologyRevisionBrand]?: true;
+};
+/**
+ * Non-negative integer epoch milliseconds within Date's range, up to 8_640_000_000_000_000 inclusive.
+ * The protocol has exactly one clock and it belongs to `DiagnosticCauseRef`: it stamps the
+ * trigger of a commit, not the commit itself, and no duration is derived from it. State records therefore carry no
+ * timestamps of their own — a second clock would let the panel invent spans the runtime never measured.
+ */
+type DiagnosticTimestamp = number;
+/**
+ * Human-readable text the compiler derived from declarations. Presentation only: search may index it, control must
+ * never accept it as a target (§2.6).
+ */
+type DiagnosticLabel = string;
+/** Project-relative provenance of a declaration. Never an execution identity (§2.6). */
+type DiagnosticProvenance = string;
+declare class DevtoolsProtocolError extends Error {
+    readonly code: 'invalid-id' | 'invalid-revision' | 'invalid-sequence';
+    constructor(code: 'invalid-id' | 'invalid-revision' | 'invalid-sequence', message: string);
+}
+/**
+ * How long an id may be, derived from the producer's own laws rather than chosen (D200, §2.6).
+ *
+ * An atom is a declaration id: at most 160 characters over `[A-Za-z0-9./:-]`, where a separator always sits between
+ * two alphanumerics, so at most 79 of them. Escaping turns `/` and `:` into two characters each, and that is the
+ * only growth an atom can suffer.
+ *
+ * A node id is a prefix and one escaped atom — `contribution:` is the longest prefix the producer writes. A group is
+ * the exception: its key joins the ids of its conditions, so a set large enough to outgrow one escaped atom is
+ * refused as an oversized id. That is a budget rather than a law, and it is the same kind of refusal `maxNodes` is.
+ *
+ * An edge id is a kind and its two endpoints escaped again, which doubles every escape the endpoints already carry.
+ */
+declare const maxAtomId = 160;
+declare const maxEncodedAtom: number;
+declare const maxNodeId: number;
+declare const maxEdgeId: number;
+declare function diagnosticSessionId(value: string): DiagnosticSessionId;
+declare function diagnosticNodeId(value: string, limit?: number): DiagnosticNodeId;
+declare function diagnosticEdgeId(value: string, limit?: number): DiagnosticEdgeId;
+/**
+ * A condition id is one escaped atom: the producer writes `encodeIdPart(declarationId)` and addresses control by it,
+ * while the readable original stays in the node's label (D200). Escaping is the only growth it can suffer, so it is
+ * bounded by the encoded atom rather than by the declaration id it came from.
+ */
+declare function diagnosticConditionId(value: string): DiagnosticConditionId;
+declare function diagnosticPlanFingerprint(value: string): DiagnosticPlanFingerprint;
+declare function diagnosticSequence(value: number): DiagnosticSequence;
+declare function diagnosticStateRevision(value: number): DiagnosticStateRevision;
+declare function diagnosticTopologyRevision(value: number): DiagnosticTopologyRevision;
+/**
+ * The node kinds of the compiled plan and of the live world, named with the public words of `spec.md` §3: a
+ * feature, one instance of it, the condition group that owns its activation, the port it requires or provides, the
+ * host contract the application binds, the target it contributes to and the contribution itself.
+ *
+ * Projection hides kinds; it never renames them into generic "nodes".
+ */
+type DiagnosticNodeKind = 'absent-provider' | 'application' | 'attachment' | 'condition' | 'condition-group' | 'contribution' | 'contribution-target' | 'feature' | 'feature-instance' | 'host-contract' | 'port';
+/**
+ * A hard edge: the provider opens before the consumer, the consumer closes before the provider, and the compiler
+ * refuses the edge unless the provider's condition set is a subset of the consumer's (`spec.md` §4). These are the
+ * only edges an activation can wait on.
+ */
+type HardEdgeKind = 'hard-import' | 'requires-port';
+/**
+ * A weak edge: one word, `optional`, for features and for ports (D105). The consumer may outlive the provider, reads
+ * a `Lookup` projection instead of a value, and never waits for it. `absent-import` and `absent-port` are the same
+ * edge with no provider in the plan at all — the runtime value is identical, which is exactly D105's point, and only
+ * the plan remembers the difference.
+ */
+type WeakEdgeKind = 'absent-import' | 'absent-port' | 'optional-import' | 'optional-port';
+/**
+ * Edges that carry no state of their own. `provides-port` names the single provider the compiler selected,
+ * `condition-control` names a condition that gates a group, `owns` names the lifetime owner of a feature, and
+ * `on-demand-import` is a host contract whose connection is deferred to the attachment that opens it, so it is
+ * neither a wait nor a `Lookup`.
+ */
+type StructuralEdgeKind = 'condition-control' | 'contributes-to' | 'on-demand-import' | 'owns' | 'provides-port';
+type DiagnosticEdgeKind = HardEdgeKind | StructuralEdgeKind | WeakEdgeKind;
+/** What a weak edge reports to its consumer right now: literally the `Lookup` the projection yields (D105). */
+type WeakEdgeState = 'found' | 'missing';
+type DiagnosticEdgeBase = Readonly<{
+    from: DiagnosticNodeId;
+    id: DiagnosticEdgeId;
+    to: DiagnosticNodeId;
+}>;
+/**
+ * Orientation is fixed: provider, blocker or owner → consumer, waiter or owned node. The panel may print
+ * "B depends on A"; it must not flip the data.
+ *
+ * State lives on the edge kinds that have one, so a weak edge cannot claim to be pending and a hard edge cannot
+ * claim a `Lookup`.
+ */
+type DiagnosticEdge = (DiagnosticEdgeBase & Readonly<{
+    kind: HardEdgeKind;
+    pending: boolean;
+}>) | (DiagnosticEdgeBase & Readonly<{
+    kind: StructuralEdgeKind;
+}>) | (DiagnosticEdgeBase & Readonly<{
+    kind: WeakEdgeKind;
+    lookup: WeakEdgeState;
+}>);
+/** A hard edge is the only thing an activation waits on, so only these can hold up a feature instance. */
+declare function isHardEdge(edge: DiagnosticEdge): edge is DiagnosticEdgeBase & {
+    kind: HardEdgeKind;
+    pending: boolean;
+};
+declare function isWeakEdge(edge: DiagnosticEdge): edge is DiagnosticEdgeBase & {
+    kind: WeakEdgeKind;
+    lookup: WeakEdgeState;
+};
+/** Both kinds of dependency edge, which is what the inspector lists as "blocked by" (weak rows read `missing`). */
+declare function isDependencyEdge(edge: DiagnosticEdge): boolean;
+/** Axis one: what the machine wants, before and after a debug override that no build can set yet (§5.4). */
+type DesiredAxis = 'active' | 'inactive';
+type DiagnosticOverride = 'force-inactive' | 'none';
+/**
+ * Axis two: where the node sits in its own automaton. `declared` is the seventh value: a feature the plan declares
+ * while no instance of it is open is in none of the other six, and calling it `waiting` would claim a blocker that
+ * does not exist.
+ */
+type LifecycleAxis = 'closed' | 'declared' | 'fencing' | 'opening' | 'ready' | 'retiring' | 'waiting';
+/** Axis three: whether that position is a problem. */
+type HealthAxis = 'blocked' | 'cancelled' | 'failed' | 'healthy' | 'quarantined' | 'stale';
+/**
+ * When a host contract is connected: with the instance that owns it, or lazily on first use. The literal is the
+ * runtime's own `ImportDemand` from `runtime/src/feature-contract.ts` and is declared once here, so following the
+ * runtime is one edit rather than three.
+ */
+type HostContractDemand = 'instance' | 'onDemand';
+/** The phase vocabulary of D14, unchanged: one word set for every lifecycle transaction in the runtime. */
+type DiagnosticPhase = 'close' | 'drain' | 'fence' | 'open' | 'retry' | 'rollback';
+/**
+ * The whole vocabulary of failure the protocol exports, and it is the runtime's own: one class per subject of the
+ * author vocabulary with the state in `code` (`spec.md` §4, D69). Subject and code are one discriminated union, so a
+ * `ContributionError` code can never be reported under `FeatureError`. Arbitrary error text stays out (§2.6).
+ */
+type DiagnosticFailureCode = Readonly<{
+    code: 'binding-invalid' | 'duplicate' | 'inactive' | 'missing';
+    subject: 'contribution';
+}> | Readonly<{
+    code: 'cancelled' | 'closed' | 'publication-rejected' | 'unavailable';
+    subject: 'call';
+}> | Readonly<{
+    code: 'cleanup-failed' | 'not-ready' | 'quarantined' | 'retired';
+    subject: 'feature';
+}> | Readonly<{
+    code: 'closed';
+    subject: 'application';
+}> | Readonly<{
+    code: 'closed';
+    subject: 'readable';
+}> | Readonly<{
+    code: 'invalid-id';
+    subject: 'declaration';
+}>;
+type DiagnosticFailure = DiagnosticFailureCode & Readonly<{
+    cause?: DiagnosticCauseRef;
+    phase: DiagnosticPhase;
+}>;
+/**
+ * Why a feature instance has not opened yet. Typed, so the panel never infers a reason from a neighbour's colour.
+ * `awaiting-turn` is the honest name for the canonical order: members of a group open one at a time in
+ * `plan.groups[].order`, so a member can be blocked by nothing but its own position.
+ */
+type DiagnosticWaitReason = 'awaiting-condition' | 'awaiting-hard-import' | 'awaiting-port' | 'awaiting-turn';
+type DiagnosticClosedReason = 'application-closed' | 'condition-inactive' | 'debug-override' | 'plan-replacement' | 'retired';
+type DiagnosticCauseKind = 'activity-change' | 'condition-change' | 'contribution-change' | 'control-command' | 'failure' | 'group-transition' | 'instance-transition' | 'plan-replacement' | 'session-reset';
+/**
+ * A ref, not an explanation: the panel resolves it against the snapshot instead of parsing prose. `at` stamps the
+ * trigger and is the protocol's only clock; a commit with no cause has no time, and the timeline shows that column
+ * empty rather than inventing one.
+ */
+type DiagnosticCauseRef = Readonly<{
+    at?: DiagnosticTimestamp;
+    condition?: DiagnosticConditionId;
+    kind: DiagnosticCauseKind;
+    node?: DiagnosticNodeId;
+    sequence?: DiagnosticSequence;
+}>;
+/**
+ * What a condition group wants. `source` is the conjunction of its conditions, `override` is the debug override no
+ * build can set yet, and `effective` is what the activation machine acts on.
+ */
+type DiagnosticDesiredState = Readonly<{
+    effective: DesiredAxis;
+    override: DiagnosticOverride;
+    source: DesiredAxis;
+}>;
+export { DevtoolsProtocolError, diagnosticConditionId, diagnosticEdgeId, diagnosticNodeId, diagnosticPlanFingerprint, diagnosticSequence, diagnosticSessionId, diagnosticStateRevision, diagnosticTopologyRevision, isDependencyEdge, isHardEdge, isWeakEdge, maxAtomId, maxEdgeId, maxEncodedAtom, maxNodeId, };
+export type { DesiredAxis, DiagnosticCauseKind, DiagnosticCauseRef, DiagnosticClosedReason, DiagnosticConditionId, DiagnosticDesiredState, DiagnosticEdge, DiagnosticEdgeId, DiagnosticEdgeKind, DiagnosticFailure, DiagnosticFailureCode, DiagnosticLabel, DiagnosticNodeId, DiagnosticNodeKind, DiagnosticOverride, DiagnosticPhase, DiagnosticPlanFingerprint, DiagnosticProvenance, DiagnosticSequence, DiagnosticSessionId, DiagnosticStateRevision, DiagnosticTimestamp, DiagnosticTopologyRevision, DiagnosticWaitReason, HardEdgeKind, HealthAxis, HostContractDemand, LifecycleAxis, StructuralEdgeKind, WeakEdgeKind, WeakEdgeState, };

package/dist/react/activity-rows.d.ts

@@ -0,0 +1,12 @@
+import type { ActivityOwner, RuntimeActivitySnapshot } from '../activity.js';
+type ActivityRow = Readonly<{
+    details: readonly (readonly [string, number | string])[];
+    id: string;
+    kind: 'call' | 'feature' | 'resource' | 'stream';
+    label: string;
+    owner: ActivityOwner;
+    state: string;
+}>;
+declare function activityRows(snapshot: RuntimeActivitySnapshot): ActivityRow[];
+export { activityRows };
+export type { ActivityRow };

package/dist/react/activity-view.d.ts

@@ -0,0 +1,9 @@
+import type { ReactElement } from 'react';
+import type { InspectorProjection } from '../inspector.js';
+import type { DiagnosticNodeId } from '../protocol.js';
+type ActivityViewProps = Readonly<{
+    onSelect: (id: DiagnosticNodeId) => void;
+    projection: InspectorProjection;
+}>;
+declare function ActivityView({ onSelect, projection }: ActivityViewProps): ReactElement;
+export { ActivityView };

package/dist/react/control-locale.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The control surface's own dictionary, kept out of the panel's (§5).
+ *
+ * A build that never receives a write port should not ship the words for buttons it will never draw, so these words
+ * live in the lazy chunk with the code that uses them. The discipline is the panel's: English is the source, the
+ * Russian record is typed against it, and a missing key is a type error rather than an English word in a Russian
+ * panel. The protocol's own vocabulary — the command names, `applied`, `rejected`, the rejection reasons and the
+ * override value — is not translated in either.
+ */
+import type { DevtoolsLocale } from './locale.js';
+declare const en: {
+    controlActions: string;
+    controlApplied: (command: string, target: string, sequence: number) => string;
+    controlAudit: string;
+    controlCancel: string;
+    controlConfirm: string;
+    controlConfirmQuestion: (action: string, target: string) => string;
+    controlRejected: (command: string, target: string, reason: string) => string;
+    controlResume: string;
+    controlRetryCleanup: string;
+    controlSuspend: string;
+};
+type ControlStrings = typeof en;
+declare function controlStringsFor(locale: DevtoolsLocale): ControlStrings;
+export { controlStringsFor };

package/dist/react/control-styles.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The control surface's own rules, injected when its chunk lands (§5). They sit here rather than in the panel's
+ * stylesheet for the same reason its dictionary does: a panel installed without a write port should carry neither
+ * the code nor the bytes of a surface it will never draw.
+ */
+declare function ensureControlStylesheet(): void;
+export { ensureControlStylesheet };

package/dist/react/control-ui.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The control surface of `docs/devtools.md` §5, and the only part of the panel that can write to the application.
+ *
+ * It is a chunk of its own, loaded when a host passes a control session and never otherwise. That is not only a size
+ * decision: a build with no write port must not carry the code that would use one, so a panel that never loaded this
+ * module is read-only by construction rather than by a disabled button.
+ *
+ * Every command asks for confirmation first. Suspending a condition stops a real application, so the button that
+ * does it is deliberately two presses away, and the second press names what it is about to do.
+ */
+import type { ReactElement } from 'react';
+import type { ControlAuditEntry, RuntimeControlSession } from '../control.js';
+import type { DevtoolsGraphStore } from '../graph-store.js';
+import type { InspectorProjection } from '../inspector.js';
+type ControlSlotProps = Readonly<{
+    audit: readonly ControlAuditEntry[];
+    onAudit: (entry: ControlAuditEntry) => void;
+    /** The bar over the canvas carries the group's commands; the inspector carries those and the override badge. */
+    place: 'bar' | 'inspector';
+    projection: InspectorProjection | undefined;
+    session: RuntimeControlSession;
+    store: DevtoolsGraphStore;
+}>;
+/**
+ * What may be controlled about the selected node, and nothing else (§5.1): a condition group through its conditions,
+ * and a quarantined instance through the exact frontier its cleanup left. Everything else has no command at all, so
+ * the slot renders nothing rather than a disabled button that would have to explain itself.
+ */
+declare function ControlSlot({ audit, onAudit, place, projection, session, store, }: ControlSlotProps): ReactElement | undefined;
+/**
+ * The panel's own audit trail, above the runtime's timeline and visibly not part of it: an applied command points at
+ * the frame that carries it, and a rejected one has no frame to point at, because nothing was committed.
+ */
+declare function ControlAudit({ entries }: {
+    readonly entries: readonly ControlAuditEntry[];
+}): ReactElement | undefined;
+export { ControlAudit, ControlSlot };

package/dist/react/edge-filter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What the `Graph` tab draws, as the developer decides it: one chip per protocol edge kind, and presets that are
+ * named sets of those chips (`docs/devtools.md` §4.2).
+ *
+ * The five lenses this replaces were five answers to one question — which relations am I looking at — and a
+ * developer who wanted two of them at once had to choose. A chip set is the same choice made additive, so the
+ * presets are shorthand rather than modes: the state is the set of enabled kinds, and a preset is just the name that
+ * set happens to have.
+ */
+import type { DiagnosticEdgeKind } from '../protocol.js';
+/** The two tabs of §4.1. Everything that used to be a tab is a filter inside `graph`. */
+type DevtoolsTab = 'graph' | 'timeline';
+type EdgePresetId = 'conditions' | 'extension-points' | 'imports-and-ports' | 'ownership';
+type EdgePreset = Readonly<{
+    id: EdgePresetId;
+    kinds: readonly DiagnosticEdgeKind[];
+    /** Key into the string dictionary: a preset name is prose, and prose is translated. */
+    label: 'presetConditions' | 'presetExtensionPoints' | 'presetImportsAndPorts' | 'presetOwnership';
+}>;
+/**
+ * Chip order is the protocol's own grouping — imports, then ports, then the structural relations — so a developer
+ * reading the row finds a kind where its neighbours are. The labels are protocol vocabulary and stay untranslated.
+ */
+declare const edgeKinds: readonly DiagnosticEdgeKind[];
+declare const edgePresets: readonly EdgePreset[];
+declare const defaultPreset: EdgePresetId;
+declare function presetKinds(id: EdgePresetId): ReadonlySet<DiagnosticEdgeKind>;
+/**
+ * The name of the current selection, or `undefined` when it has none. Derived rather than stored: a chip toggled
+ * back into a preset's exact set is that preset again, and a panel that remembered otherwise would be lying about
+ * what it draws.
+ */
+declare function presetOf(selected: ReadonlySet<DiagnosticEdgeKind>): EdgePresetId | undefined;
+declare function toggleKind(selected: ReadonlySet<DiagnosticEdgeKind>, kind: DiagnosticEdgeKind): ReadonlySet<DiagnosticEdgeKind>;
+export { defaultPreset, edgeKinds, edgePresets, presetKinds, presetOf, toggleKind };
+export type { DevtoolsTab, EdgePreset, EdgePresetId };

package/dist/react/edge-filters.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The filter row of `docs/devtools.md` §4.2: four presets on the left, one chip per edge kind on the right.
+ *
+ * A preset is a button and not a tab, because pressing it is not a mode switch — it writes the chips and leaves.
+ * The chips are the state, so the pressed preset is whichever one currently matches them, and none is pressed while
+ * the developer holds a set of their own.
+ */
+import type { ReactElement } from 'react';
+import type { DiagnosticEdgeKind } from '../protocol.js';
+import type { EdgePresetId } from './edge-filter.js';
+type EdgeFiltersProps = Readonly<{
+    onPreset: (preset: EdgePresetId) => void;
+    onToggle: (kind: DiagnosticEdgeKind) => void;
+    selected: ReadonlySet<DiagnosticEdgeKind>;
+}>;
+declare function EdgeFilters({ onPreset, onToggle, selected }: EdgeFiltersProps): ReactElement;
+export { EdgeFilters };

package/dist/react/export-delivery.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Delivery of a snapshot export to wherever the host can actually receive it.
+ *
+ * §2.6 allows no network transport, so there are exactly two destinations: the clipboard, and a file the browser saves
+ * locally. Which one is available depends on the host — the clipboard needs a secure context and a permission the
+ * user may refuse — so both are tried in order and the outcome is reported rather than assumed. A button that
+ * silently did nothing is the defect this replaces.
+ */
+type ExportOutcome = Readonly<{
+    detail?: string;
+    kind: 'copied' | 'downloaded' | 'failed' | 'handled';
+}>;
+/**
+ * The capabilities delivery needs, named one by one so a test can offer a host with only some of them, and so no
+ * global is read outside `browserExportHost`.
+ */
+type ExportHost = Readonly<{
+    download?: (text: string, filename: string) => void;
+    writeText?: (text: string) => PromiseLike<void>;
+}>;
+/** Ids carry dots and colons; a filename should carry neither. */
+declare function exportFilename(sessionId: string, sequence: number): string;
+/** What this browser can do, decided by feature detection rather than by a user-agent guess. */
+declare function browserExportHost(): ExportHost;
+/**
+ * Clipboard first, because the developer is usually about to paste it into a report; a saved file second, because a
+ * large graph is easier to keep than to hold. Failure is a reported outcome, never a thrown error: an export that
+ * could not be delivered must not take the panel down with it.
+ */
+declare function deliverExport(text: string, filename: string, host: ExportHost): Promise<ExportOutcome>;
+/** The outcome is reported in the panel's language, so the key is resolved against the dictionary, not hard-coded. */
+export { browserExportHost, deliverExport, exportFilename };
+export type { ExportHost, ExportOutcome };

package/dist/react/export-run.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Running an export, and the words that report where it went (`docs/devtools.md` §2.6).
+ *
+ * The panel keeps the button; this module is what the button loads. Building a redacted snapshot, canonicalising it
+ * and reaching a clipboard is a page of code and four sentences of prose that a session which never exports has no
+ * reason to carry, so both travel behind the click.
+ */
+import type { DevtoolsExport } from '../export-snapshot.js';
+import { exportSnapshot } from '../export-snapshot.js';
+import type { ExportHost } from './export-delivery.js';
+import type { DevtoolsLocale } from './locale.js';
+type ExportRequest = Readonly<{
+    host: ExportHost | undefined;
+    locale: DevtoolsLocale;
+    onExport: ((payload: DevtoolsExport) => void) | undefined;
+    store: Parameters<typeof exportSnapshot>[0];
+}>;
+/** §2.6: no network transport. The clipboard and a local file are the only destinations delivery may use. */
+declare function runExport({ host, locale, onExport, store }: ExportRequest): Promise<string>;
+export { runExport };

package/dist/react/format.d.ts

@@ -0,0 +1,17 @@
+/** Presentation-only formatting. Nothing here decides state; it renders values the projection already resolved. */
+import type { DiagnosticTimestamp } from '../protocol.js';
+import type { Strings } from './locale.js';
+/** `14:02:31` — wall-clock only, for facts where the millisecond adds noise rather than ordering. */
+declare function formatClock(at: DiagnosticTimestamp): string;
+/** `14:02:31.114` — the timestamp column of the causal chain and the timeline, where ordering is the point. */
+declare function formatTime(at: DiagnosticTimestamp): string;
+/**
+ * `3 current · 2 previous` — a feature declaration outlives its instances, so the counter says which life this is.
+ * The number of the previous life carries no time: the protocol's only clock is `cause.at`, and it stamps a trigger,
+ * not a retirement.
+ */
+declare function formatInstance(generation: number, previous: number | undefined, strings: Strings): string;
+/** The time column of a commit that has no cause is empty, because the protocol never stamped one. */
+declare function formatOptionalTime(at: DiagnosticTimestamp | undefined): string;
+declare function formatMilliseconds(value: number): string;
+export { formatClock, formatInstance, formatMilliseconds, formatOptionalTime, formatTime };

package/dist/react/glyph.d.ts

@@ -0,0 +1,20 @@
+/**
+ * State coding per `docs/devtools.md` §4.6: shape, colour and text tag together, never colour alone.
+ *
+ * The glyph itself is `aria-hidden`: it is always rendered next to the state's own text — a tag in the tree and the
+ * inspector, the sub-line on a graph card — so a screen reader gets the state once, as words.
+ */
+import type { ReactElement } from 'react';
+import type { NodeDisplayState } from '../visual-axes.js';
+import type { Strings } from './locale.js';
+declare function stateDescription(state: NodeDisplayState, strings: Strings): string;
+/** Every lifecycle state the panel can draw, in the order the legend lists them. */
+declare const displayStates: readonly NodeDisplayState[];
+declare function StateGlyph({ size, state }: {
+    size?: number;
+    state: NodeDisplayState;
+}): ReactElement;
+declare function StateTag({ state }: {
+    state: NodeDisplayState;
+}): ReactElement;
+export { displayStates, stateDescription, StateGlyph, StateTag };

package/dist/react/graph-layout.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Deterministic three-column layout for the selected node's neighbourhood: blockers on the left, the selection in
+ * the middle, what it owns and publishes on the right — the arrangement `docs/devtools.md` §4 describes.
+ *
+ * Layout is pure and measured in CSS pixels, and the SVG that draws the edges uses the same pixel box as the layer
+ * holding the cards. That is what keeps edges attached to cards at any drawer height (§8 acceptance), and it keeps
+ * the layout testable and cacheable by topology revision (§6) without a DOM.
+ */
+import type { ExtensionPointsProjection } from '../extension-points.js';
+import type { InspectorProjection } from '../inspector.js';
+import type { DiagnosticEdgeKind, DiagnosticLabel, DiagnosticNodeId } from '../protocol.js';
+import type { NodeDisplayState } from '../visual-axes.js';
+import type { Strings } from './locale.js';
+declare const cardWidth = 188;
+type LaidOutNode = Readonly<{
+    /** Third line of the selected card: what its current generation owns. */
+    detail?: string;
+    display: NodeDisplayState;
+    height: number;
+    id: DiagnosticNodeId;
+    /**
+     * React key. It cannot be the node id: one provider can reach the same consumer through two relations — a
+     * candidate admission and a selected-provider wait, say — and then appears in the column twice.
+     */
+    key: string;
+    label: DiagnosticLabel;
+    selected: boolean;
+    /**
+     * The `<relation> · <state>` line under the title, already split so the card does not build strings. Absent on the
+     * selected card, which carries its kind and generation as tags and its state as a state tag instead.
+     */
+    sub?: readonly [string, string];
+    /** Tag chips on the selected card: its kind and its generation. */
+    tags?: readonly string[];
+    /** The full name, for `title`: `label` may have been shortened to fit the card, and this never is (§4.3). */
+    title: DiagnosticLabel;
+    x: number;
+    y: number;
+}>;
+type LaidOutEdge = Readonly<{
+    id: string;
+    kind: DiagnosticEdgeKind;
+    path: string;
+}>;
+type GraphLayout = Readonly<{
+    edges: readonly LaidOutEdge[];
+    height: number;
+    /** Relations the filter leaves out. Shown as a hint, so an empty canvas is never mistaken for an isolated node. */
+    hidden: number;
+    nodes: readonly LaidOutNode[];
+    width: number;
+}>;
+/**
+ * Lays out the neighbourhood the filter is interested in. Nested owned rows are flattened into the right column: the
+ * canvas shows one hop, the inspector shows the ownership tree.
+ */
+declare function layoutNeighbourhood(projection: InspectorProjection, edgeKinds: ReadonlySet<DiagnosticEdgeKind> | undefined, strings: Strings): GraphLayout;
+/**
+ * The `Extension points` picture: the selection on the left, every contribution that reaches the same targets in the
+ * middle, and those targets on the right — inverted into contributors when a target is what was selected.
+ *
+ * Sibling contributions are drawn without an edge back to the selection, because they have none: they compete for
+ * the same target, which is the whole reason they are on the canvas.
+ */
+declare function layoutExtensionPoints(projection: ExtensionPointsProjection): GraphLayout;
+export { cardWidth, layoutExtensionPoints, layoutNeighbourhood };
+export type { GraphLayout, LaidOutEdge, LaidOutNode };

package/dist/react/graph-view.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The graph canvas of `docs/devtools.md` §4, and the list that replaces it on narrow widths (§4.4).
+ *
+ * The SVG shares one pixel box with the layer holding the cards and uses `preserveAspectRatio="xMinYMin meet"`, so
+ * edges stay attached to cards at any zoom — that is the §8 acceptance criterion for this view. The camera moves the
+ * layer, never the coordinates, so the layout stays cacheable and edges never drift.
+ *
+ * The canvas clips its content: a lens may not draw outside itself. Reaching a node that the fit did not cover is
+ * therefore pan and zoom, which is what the surrounding column owns.
+ */
+import type { ReactElement, RefObject } from 'react';
+import type { DiagnosticNodeId } from '../protocol.js';
+import type { GraphLayout } from './graph-layout.js';
+import type { CanvasTransform, ViewportPoint } from './graph-viewport.js';
+type GraphViewProps = Readonly<{
+    canvasRef: RefObject<HTMLDivElement | null>;
+    layout: GraphLayout;
+    onPan: (dx: number, dy: number) => void;
+    onSelect: (id: DiagnosticNodeId) => void;
+    onZoomAt: (point: ViewportPoint, factor: number) => void;
+    transform: CanvasTransform;
+}>;
+declare function GraphView({ canvasRef, layout, onPan, onSelect, onZoomAt, transform }: GraphViewProps): ReactElement;
+type NeighbourListProps = Readonly<{
+    layout: GraphLayout;
+    onSelect: (id: DiagnosticNodeId) => void;
+}>;
+/** The same neighbourhood as a list: the graph's fallback on narrow widths, and a keyboard-first way to walk it. */
+declare function NeighbourList({ layout, onSelect }: NeighbourListProps): ReactElement;
+export { GraphView, NeighbourList };

package/dist/react/graph-viewport.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The camera over the graph canvas: a pan offset and a zoom, kept as plain numbers so the whole of it is testable
+ * without a DOM.
+ *
+ * The canvas clips (`overflow: hidden`), so nothing the lens draws can leave the lens. That makes the camera the only
+ * way to reach a node outside the current view, which is why pan, wheel zoom and fit-to-view are one unit rather than
+ * three loose handlers: they all have to agree on what "the graph is at x, y, scaled by z" means.
+ */
+type Viewport = Readonly<{
+    height: number;
+    width: number;
+}>;
+type CanvasTransform = Readonly<{
+    x: number;
+    y: number;
+    zoom: number;
+}>;
+type ViewportPoint = Readonly<{
+    x: number;
+    y: number;
+}>;
+declare const minZoom = 0.25;
+declare const maxZoom = 2.5;
+/** One press of −/+ is a deliberate, noticeable step. A wheel notch is not: it is whatever the device reported. */
+declare const zoomStep = 1.2;
+/**
+ * The factor one wheel event should apply. Clamped per event so a single coarse notch — a mouse that reports whole
+ * pages — cannot cross the whole zoom range at once.
+ */
+declare function wheelFactor(delta: number, mode?: number): number;
+declare const identityTransform: CanvasTransform;
+declare function clampZoom(zoom: number): number;
+/**
+ * Scales the graph to fit the lens and centres it. An unmeasured viewport — a panel that has not laid out yet, or a
+ * headless test — returns the identity rather than dividing by zero, so opening a node never leaves a blank canvas.
+ */
+declare function fitTransform(layout: Viewport, viewport: Viewport): CanvasTransform;
+declare function panBy(transform: CanvasTransform, dx: number, dy: number): CanvasTransform;
+/**
+ * Zooms around a point given in viewport coordinates, so whatever sits under the cursor stays under it. Without this
+ * the graph slides away as it grows and the developer chases the node they were reading.
+ */
+declare function zoomAround(transform: CanvasTransform, point: ViewportPoint, factor: number): CanvasTransform;
+/** The centre of the lens, used when zoom comes from a button rather than from a cursor. */
+declare function viewportCentre(viewport: Viewport): ViewportPoint;
+declare function transformStyle(transform: CanvasTransform): string;
+export { clampZoom, fitTransform, identityTransform, maxZoom, minZoom, panBy, transformStyle, viewportCentre, wheelFactor, zoomAround, zoomStep, };
+export type { CanvasTransform, Viewport, ViewportPoint };

package/dist/react/icons.d.ts

@@ -0,0 +1,12 @@
+/** The panel's own icon set. Kept local so `@opetope/devtools` needs no icon package to render. */
+import type { ReactElement } from 'react';
+type IconProps = {
+    readonly size?: number;
+};
+declare function SearchIcon({ size }: IconProps): ReactElement;
+declare function CloseIcon({ size }: IconProps): ReactElement;
+declare function CopyIcon({ size }: IconProps): ReactElement;
+declare function ChevronIcon({ open, size }: IconProps & {
+    readonly open: boolean;
+}): ReactElement;
+export { ChevronIcon, CloseIcon, CopyIcon, SearchIcon };