@r-a-i-t-h/viz-protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 r-a-i-t-h
+
+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/dist/contextDeps.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Static context dependency graph shape — shared by host analysis and UI.
+ * The analyzer that builds this lives in `@r-a-i-t-h/viz-host` (needs live XState logic).
+ */
+export type DepEntityKind = 'contextKey' | 'action' | 'guard' | 'invoke';
+export type DepCoverage = 'known' | 'partial' | 'opaque';
+export type DepRelation = 'reads' | 'writes';
+export type DepSite = 'entry' | 'exit' | 'transition' | 'invoke';
+export interface ContextDepNode {
+    id: string;
+    kind: DepEntityKind;
+    label: string;
+    coverage: DepCoverage;
+}
+export interface ContextDepEdge {
+    from: string;
+    to: string;
+    relation: DepRelation;
+    at: {
+        stateId: string;
+        site: DepSite;
+        eventType?: string;
+    };
+}
+export interface ContextDepGraph {
+    nodes: ContextDepNode[];
+    edges: ContextDepEdge[];
+}
+//# sourceMappingURL=contextDeps.d.ts.map

package/dist/contextDeps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextDeps.d.ts","sourceRoot":"","sources":["../src/contextDeps.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEzE,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEzD,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE7C,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,WAAW,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,WAAW,CAAC;IACtB,EAAE,EAAE;QACF,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,OAAO,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB"}

package/dist/contextDeps.js

@@ -0,0 +1,6 @@
+/**
+ * Static context dependency graph shape — shared by host analysis and UI.
+ * The analyzer that builds this lives in `@r-a-i-t-h/viz-host` (needs live XState logic).
+ */
+export {};
+//# sourceMappingURL=contextDeps.js.map

package/dist/contextDeps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextDeps.js","sourceRoot":"","sources":["../src/contextDeps.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/ids.d.ts

@@ -0,0 +1,3 @@
+/** Strip leading `#` from XState state node ids for Viz* id matching. */
+export declare function normalizeStateNodeId(id: string): string;
+//# sourceMappingURL=ids.d.ts.map

package/dist/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/ids.js

@@ -0,0 +1,5 @@
+/** Strip leading `#` from XState state node ids for Viz* id matching. */
+export function normalizeStateNodeId(id) {
+    return id.replace(/^#/, '');
+}
+//# sourceMappingURL=ids.js.map

package/dist/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,MAAM,UAAU,oBAAoB,CAAC,EAAU;IAC7C,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAC9B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared viz presentation model + wire protocol.
+ *
+ * Host projects into Viz*; visualizer renders Viz*. No XState here.
+ */
+export type { ContextDepEdge, ContextDepGraph, ContextDepNode, DepCoverage, DepEntityKind, DepRelation, DepSite, } from './contextDeps.js';
+export type { VizActorRefMarker, VizAnalysis, VizBadge, VizBadgeKind, VizEvent, VizFrame, VizInvoke, VizLogEntry, VizMachine, VizNextEvent, VizNextEventCandidate, VizNode, VizNodeDetails, VizNodeKind, VizSymbol, VizTransition, } from './model.js';
+export { isVizActorRefMarker } from './model.js';
+export type { HostBridgeStatus, VisualizerSnapshot } from './snapshot.js';
+export { VIZ_CHANNEL, VIZ_PROTOCOL_VERSION, VIZ_WINDOW_NAME, isVizMessage, toPortable, type VizDownstreamMessage, type VizMessage, type VizUpstreamMessage, } from './protocol.js';
+export { connectPopupReceiver, type PopupMessageHandler, } from './popupReceiver.js';
+export { normalizeStateNodeId } from './ids.js';
+//# 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;;;;GAIG;AAEH,YAAY,EACV,cAAc,EACd,eAAe,EACf,cAAc,EACd,WAAW,EACX,aAAa,EACb,WAAW,EACX,OAAO,GACR,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,iBAAiB,EACjB,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,WAAW,EACX,UAAU,EACV,YAAY,EACZ,qBAAqB,EACrB,OAAO,EACP,cAAc,EACd,WAAW,EACX,SAAS,EACT,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEjD,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAE1E,OAAO,EACL,WAAW,EACX,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,UAAU,EACV,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,kBAAkB,GACxB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,oBAAoB,EACpB,KAAK,mBAAmB,GACzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * Shared viz presentation model + wire protocol.
+ *
+ * Host projects into Viz*; visualizer renders Viz*. No XState here.
+ */
+export { isVizActorRefMarker } from './model.js';
+export { VIZ_CHANNEL, VIZ_PROTOCOL_VERSION, VIZ_WINDOW_NAME, isVizMessage, toPortable, } from './protocol.js';
+export { connectPopupReceiver, } from './popupReceiver.js';
+export { normalizeStateNodeId } from './ids.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA+BH,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAIjD,OAAO,EACL,WAAW,EACX,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,UAAU,GAIX,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,oBAAoB,GAErB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC"}

package/dist/model.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Shared viz presentation model — spoken by the host projector and the popup UI.
+ * No XState structural types here; those stay behind `projectMachine` / `projectFrame`.
+ */
+import type { ContextDepGraph } from './contextDeps.js';
+export interface VizMachine {
+    sessionId: string;
+    /** Display name (machine id or fallback). */
+    label: string;
+    /** Parent actor session when this machine was invoked/spawned. */
+    parentSessionId?: string;
+    /** Actor input captured at registration (portable / sanitized). */
+    input?: unknown;
+    /** Machine root as a tree. */
+    root: VizNode;
+    /** Static analyses computed against live logic on the host. */
+    analysis: VizAnalysis;
+}
+/**
+ * Portable stand-in for a live ActorRef in scrubbed context.
+ * Host replaces refs before postMessage so sessionId survives JSON.
+ */
+export interface VizActorRefMarker {
+    __viz: 'actorRef';
+    sessionId: string;
+    id: string;
+}
+export declare function isVizActorRefMarker(value: unknown): value is VizActorRefMarker;
+export interface VizNode {
+    id: string;
+    key: string;
+    kind: VizNodeKind;
+    /** Child layout hint — already decided from XState compound vs parallel. */
+    layout: 'sequential' | 'parallel' | 'none';
+    children: VizNode[];
+    /** Which child ids are initial targets (for arrow glyph). */
+    initialChildIds: string[];
+    /** Compact badges — no raw entry/exit arrays. */
+    badges: VizBadge[];
+    /** Ordinary named events (not after/always — those are badges + details). */
+    events: VizEvent[];
+    /** Longer copy for watch cards / hover — still viz vocabulary. */
+    details: VizNodeDetails;
+}
+export type VizNodeKind = 'atomic' | 'compound' | 'parallel' | 'final' | 'history';
+export interface VizBadge {
+    kind: VizBadgeKind;
+    /** Short label on the node chrome. */
+    label: string;
+    /** Lines for hover tip. */
+    lines: string[];
+    /** Node ids to highlight while this badge is hovered. */
+    highlightIds: string[];
+}
+/**
+ * Non-`on` (and lifecycle) markers. Projector maps XState concepts → these.
+ * Popup only switches on VizBadgeKind.
+ */
+export type VizBadgeKind = 'entry' | 'exit' | 'after' | 'always' | 'invoke' | 'history';
+export interface VizEvent {
+    /** Event type string as shown in the UI (`TICK`, not internal keys). */
+    type: string;
+    /** Ordered transition candidates (guard cascade). */
+    transitions: VizTransition[];
+    /** Union of all transition targets — for cheap hover highlight. */
+    highlightIds: string[];
+    /** Lines for hover when guards/actions exist (subset of full transition lines). */
+    hoverLines: string[];
+    /** Full transition lines for watch-card details. */
+    detailLines: string[];
+    /** Wildcard / partial annotation for hover only. */
+    pattern?: 'exact' | 'wildcard' | 'partial';
+}
+export interface VizTransition {
+    /** Target node ids (empty = internal / no target). */
+    targetIds: string[];
+    guard?: VizSymbol;
+    actions: VizSymbol[];
+    reenter?: boolean;
+    /** Delay label for after-transitions. */
+    delayLabel?: string;
+    /** Preformatted one-line summary for lists. */
+    line: string;
+}
+/** Named executable without the function. */
+export interface VizSymbol {
+    kind: 'action' | 'guard' | 'actor' | 'delay';
+    name: string;
+    /** Optional params summary / assign key list, already stringified. */
+    detail?: string;
+}
+export interface VizNodeDetails {
+    /** Dot path from machine root keys (`""` = root, `"a.b"` = nested). */
+    path: string;
+    tags: string[];
+    entry: VizSymbol[];
+    exit: VizSymbol[];
+    after: VizTransition[];
+    always: VizTransition[];
+    invokes: VizInvoke[];
+    history?: 'shallow' | 'deep';
+}
+export interface VizInvoke {
+    id: string;
+    src: string;
+    inputSummary?: string;
+    onDone: VizTransition[];
+    onError: VizTransition[];
+    highlightIds: string[];
+}
+export interface VizAnalysis {
+    contextDeps: ContextDepGraph;
+}
+/** Ordered transition candidate for next-events / cond cascade. */
+export interface VizNextEventCandidate {
+    providerId: string;
+    targetIds: string[];
+    guard?: VizSymbol;
+    actions: VizSymbol[];
+    /** Preformatted one-line summary (`1.` prefix added in UI). */
+    line: string;
+}
+/** An event the active configuration can handle, with providing state ids. */
+export interface VizNextEvent {
+    type: string;
+    /** State node ids that declare a handler (including active ancestors). */
+    providerIds: string[];
+    /** Guard cascade across providers (definition order within each provider). */
+    candidates: VizNextEventCandidate[];
+    /** Providers + candidate targets — for hover highlight. */
+    highlightIds: string[];
+}
+/** Runtime frame — projected from an inspection snapshot. */
+export interface VizFrame {
+    sessionId: string;
+    /**
+     * Active state paths (key segments from the root), same shape as former
+     * `activePaths(value)` — used for graph/watch “you are here” overlay.
+     */
+    activePaths: string[];
+    /** Scrubbed context for the dump panel. */
+    context: unknown;
+    /** Raw state value for the JSON dump panel. */
+    value: unknown;
+    status: 'active' | 'done' | 'error' | 'stopped';
+    output?: unknown;
+    /** Event that produced this frame, if any. */
+    eventType?: string;
+    /**
+     * Events since each top-level context key last changed (0 = changed this
+     * frame). Host-tracked so popup replay stays consistent.
+     */
+    contextKeyAges?: Record<string, number>;
+    /** Named events the active configuration can handle (+ providing states). */
+    nextEvents?: VizNextEvent[];
+}
+/** Debug log entry (still inspection-flavored for the event log panel). */
+export interface VizLogEntry {
+    seq: number;
+    type: string;
+    sessionId: string;
+    eventType?: string;
+    value?: unknown;
+    at: number;
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"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"}

package/dist/model.js

@@ -0,0 +1,11 @@
+/**
+ * Shared viz presentation model — spoken by the host projector and the popup UI.
+ * No XState structural types here; those stay behind `projectMachine` / `projectFrame`.
+ */
+export function isVizActorRefMarker(value) {
+    return (!!value &&
+        typeof value === 'object' &&
+        value.__viz === 'actorRef' &&
+        typeof value.sessionId === 'string');
+}
+//# sourceMappingURL=model.js.map

package/dist/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA4BH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,CACL,CAAC,CAAC,KAAK;QACP,OAAO,KAAK,KAAK,QAAQ;QACxB,KAA2B,CAAC,KAAK,KAAK,UAAU;QACjD,OAAQ,KAA2B,CAAC,SAAS,KAAK,QAAQ,CAC3D,CAAC;AACJ,CAAC"}

package/dist/popupReceiver.d.ts

@@ -0,0 +1,13 @@
+import { type VizDownstreamMessage } from './protocol.js';
+export type PopupMessageHandler = (message: VizDownstreamMessage) => void;
+/**
+ * Runs inside the popup visualizer. Announces readiness to `window.opener`
+ * (the host, which may itself be a nested iframe) and delivers downstream
+ * messages to a handler.
+ *
+ * Does not send `@viz.bye` on React effect cleanup — StrictMode remounts would
+ * otherwise clear the host's popup handle while leaving status "connected".
+ * Teardown uses `pagehide` (actual close / navigate) instead.
+ */
+export declare function connectPopupReceiver(onMessage: PopupMessageHandler): () => void;
+//# sourceMappingURL=popupReceiver.d.ts.map

package/dist/popupReceiver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"popupReceiver.d.ts","sourceRoot":"","sources":["../src/popupReceiver.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,oBAAoB,EAE1B,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAC;AAE1E;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,mBAAmB,GAAG,MAAM,IAAI,CAgD/E"}

package/dist/popupReceiver.js

@@ -0,0 +1,55 @@
+import { isVizMessage, VIZ_CHANNEL, VIZ_PROTOCOL_VERSION, } from './protocol.js';
+/**
+ * Runs inside the popup visualizer. Announces readiness to `window.opener`
+ * (the host, which may itself be a nested iframe) and delivers downstream
+ * messages to a handler.
+ *
+ * Does not send `@viz.bye` on React effect cleanup — StrictMode remounts would
+ * otherwise clear the host's popup handle while leaving status "connected".
+ * Teardown uses `pagehide` (actual close / navigate) instead.
+ */
+export function connectPopupReceiver(onMessage) {
+    const handle = (event) => {
+        if (!isVizMessage(event.data))
+            return;
+        const data = event.data;
+        if (data.type === '@viz.machine' ||
+            data.type === '@viz.frame' ||
+            data.type === '@viz.log' ||
+            data.type === '@viz.closed') {
+            onMessage(data);
+        }
+    };
+    const target = window.opener && !window.opener.closed
+        ? window.opener
+        : window.parent !== window
+            ? window.parent
+            : null;
+    const sendBye = () => {
+        if (!target)
+            return;
+        const bye = { channel: VIZ_CHANNEL, type: '@viz.bye' };
+        try {
+            target.postMessage(bye, '*');
+        }
+        catch {
+            // ignore
+        }
+    };
+    window.addEventListener('message', handle);
+    // pagehide fires on real close/navigation; not on React StrictMode remount.
+    window.addEventListener('pagehide', sendBye);
+    if (target) {
+        const hello = {
+            channel: VIZ_CHANNEL,
+            type: '@viz.hello',
+            version: VIZ_PROTOCOL_VERSION,
+        };
+        target.postMessage(hello, '*');
+    }
+    return () => {
+        window.removeEventListener('message', handle);
+        window.removeEventListener('pagehide', sendBye);
+    };
+}
+//# sourceMappingURL=popupReceiver.js.map

package/dist/popupReceiver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"popupReceiver.js","sourceRoot":"","sources":["../src/popupReceiver.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,WAAW,EACX,oBAAoB,GAGrB,MAAM,eAAe,CAAC;AAIvB;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAA8B;IACjE,MAAM,MAAM,GAAG,CAAC,KAAmB,EAAE,EAAE;QACrC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,OAAO;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACxB,IACE,IAAI,CAAC,IAAI,KAAK,cAAc;YAC5B,IAAI,CAAC,IAAI,KAAK,YAAY;YAC1B,IAAI,CAAC,IAAI,KAAK,UAAU;YACxB,IAAI,CAAC,IAAI,KAAK,aAAa,EAC3B,CAAC;YACD,SAAS,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,MAAM,GACV,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM;QACpC,CAAC,CAAC,MAAM,CAAC,MAAM;QACf,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,MAAM;YACxB,CAAC,CAAC,MAAM,CAAC,MAAM;YACf,CAAC,CAAC,IAAI,CAAC;IAEb,MAAM,OAAO,GAAG,GAAG,EAAE;QACnB,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,MAAM,GAAG,GAAuB,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QAC3E,IAAI,CAAC;YACH,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC3C,4EAA4E;IAC5E,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAE7C,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,KAAK,GAAuB;YAChC,OAAO,EAAE,WAAW;YACpB,IAAI,EAAE,YAAY;YAClB,OAAO,EAAE,oBAAoB;SAC9B,CAAC;QACF,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,GAAG,EAAE;QACV,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAC9C,MAAM,CAAC,mBAAmB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC,CAAC;AACJ,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Cross-window protocol for the visualizer.
+ *
+ * Transport: `window.postMessage` with targetOrigin `"*"`.
+ *
+ * Why postMessage (and not BroadcastChannel / SharedWorker / etc.):
+ * - Works across origins (hidden iframe on host-A, popup from host-B).
+ * - Works when the machine runs inside a sandboxed iframe (given
+ *   `allow-scripts` + `allow-popups` / `allow-popups-to-escape-sandbox`).
+ * - Needs no permissions, service workers, or shared storage.
+ * - Same approach used by `@statelyai/inspect`'s BrowserAdapter.
+ *
+ * Handshake (mirrors Stately's `@statelyai.connected`):
+ * 1. Host opens the popup via `window.open` (must be a user gesture).
+ * 2. Popup loads and posts `@viz.hello` to `window.opener`.
+ * 3. Host marks the link connected and replays deferred payloads
+ *    (VizMachine + latest VizFrame), then streams live updates.
+ *
+ * Payloads are already-projected viz models — not raw XState definitions.
+ */
+import type { VizFrame, VizLogEntry, VizMachine } from './model.js';
+export declare const VIZ_CHANNEL: "viz";
+export declare const VIZ_PROTOCOL_VERSION: 1;
+/** Namespaced window name so a second open focuses the same popup. */
+export declare const VIZ_WINDOW_NAME = "viz-inspector";
+/** Messages the popup sends to the host. */
+export type VizUpstreamMessage = {
+    channel: typeof VIZ_CHANNEL;
+    type: '@viz.hello';
+    version: typeof VIZ_PROTOCOL_VERSION;
+} | {
+    channel: typeof VIZ_CHANNEL;
+    type: '@viz.bye';
+};
+/** Messages the host sends to the popup. */
+export type VizDownstreamMessage = {
+    channel: typeof VIZ_CHANNEL;
+    type: '@viz.machine';
+    payload: VizMachine;
+} | {
+    channel: typeof VIZ_CHANNEL;
+    type: '@viz.frame';
+    payload: VizFrame;
+} | {
+    channel: typeof VIZ_CHANNEL;
+    type: '@viz.log';
+    payload: VizLogEntry;
+} | {
+    channel: typeof VIZ_CHANNEL;
+    type: '@viz.closed';
+};
+export type VizMessage = VizUpstreamMessage | VizDownstreamMessage;
+export declare function isVizMessage(data: unknown): data is VizMessage;
+/**
+ * Structured-clone / postMessage–safe serialization.
+ * Drops functions and other non-JSON values (should already be gone after
+ * projection, but kept as a safety net).
+ */
+export declare function toPortable<T>(value: T): T;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEpE,eAAO,MAAM,WAAW,EAAG,KAAc,CAAC;AAC1C,eAAO,MAAM,oBAAoB,EAAG,CAAU,CAAC;AAE/C,sEAAsE;AACtE,eAAO,MAAM,eAAe,kBAAkB,CAAC;AAE/C,4CAA4C;AAC5C,MAAM,MAAM,kBAAkB,GAC1B;IACE,OAAO,EAAE,OAAO,WAAW,CAAC;IAC5B,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,OAAO,oBAAoB,CAAC;CACtC,GACD;IACE,OAAO,EAAE,OAAO,WAAW,CAAC;IAC5B,IAAI,EAAE,UAAU,CAAC;CAClB,CAAC;AAEN,4CAA4C;AAC5C,MAAM,MAAM,oBAAoB,GAC5B;IACE,OAAO,EAAE,OAAO,WAAW,CAAC;IAC5B,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,UAAU,CAAC;CACrB,GACD;IACE,OAAO,EAAE,OAAO,WAAW,CAAC;IAC5B,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,QAAQ,CAAC;CACnB,GACD;IACE,OAAO,EAAE,OAAO,WAAW,CAAC;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,WAAW,CAAC;CACtB,GACD;IACE,OAAO,EAAE,OAAO,WAAW,CAAC;IAC5B,IAAI,EAAE,aAAa,CAAC;CACrB,CAAC;AAEN,MAAM,MAAM,UAAU,GAAG,kBAAkB,GAAG,oBAAoB,CAAC;AAEnE,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,UAAU,CAS9D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAIzC"}

package/dist/protocol.js

@@ -0,0 +1,41 @@
+/**
+ * Cross-window protocol for the visualizer.
+ *
+ * Transport: `window.postMessage` with targetOrigin `"*"`.
+ *
+ * Why postMessage (and not BroadcastChannel / SharedWorker / etc.):
+ * - Works across origins (hidden iframe on host-A, popup from host-B).
+ * - Works when the machine runs inside a sandboxed iframe (given
+ *   `allow-scripts` + `allow-popups` / `allow-popups-to-escape-sandbox`).
+ * - Needs no permissions, service workers, or shared storage.
+ * - Same approach used by `@statelyai/inspect`'s BrowserAdapter.
+ *
+ * Handshake (mirrors Stately's `@statelyai.connected`):
+ * 1. Host opens the popup via `window.open` (must be a user gesture).
+ * 2. Popup loads and posts `@viz.hello` to `window.opener`.
+ * 3. Host marks the link connected and replays deferred payloads
+ *    (VizMachine + latest VizFrame), then streams live updates.
+ *
+ * Payloads are already-projected viz models — not raw XState definitions.
+ */
+export const VIZ_CHANNEL = 'viz';
+export const VIZ_PROTOCOL_VERSION = 1;
+/** Namespaced window name so a second open focuses the same popup. */
+export const VIZ_WINDOW_NAME = 'viz-inspector';
+export function isVizMessage(data) {
+    return (typeof data === 'object' &&
+        data !== null &&
+        'channel' in data &&
+        data.channel === VIZ_CHANNEL &&
+        'type' in data &&
+        typeof data.type === 'string');
+}
+/**
+ * Structured-clone / postMessage–safe serialization.
+ * Drops functions and other non-JSON values (should already be gone after
+ * projection, but kept as a safety net).
+ */
+export function toPortable(value) {
+    return JSON.parse(JSON.stringify(value, (_key, v) => (typeof v === 'function' ? undefined : v)));
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAc,CAAC;AAC1C,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAU,CAAC;AAE/C,sEAAsE;AACtE,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,CAAC;AAsC/C,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACb,SAAS,IAAI,IAAI;QAChB,IAA6B,CAAC,OAAO,KAAK,WAAW;QACtD,MAAM,IAAI,IAAI;QACd,OAAQ,IAA0B,CAAC,IAAI,KAAK,QAAQ,CACrD,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAI,KAAQ;IACpC,OAAO,IAAI,CAAC,KAAK,CACf,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACzE,CAAC;AACT,CAAC"}

package/dist/snapshot.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Portable snapshot shared by the host store and any visualizer UI.
+ */
+import type { VizFrame, VizLogEntry, VizMachine } from './model.js';
+export type HostBridgeStatus = 'idle' | 'opening' | 'awaiting-hello' | 'connected' | 'blocked';
+/**
+ * Everything a visualizer UI needs for one tick.
+ * Machines and frames are already projected (Viz*), not raw XState shapes.
+ */
+export interface VisualizerSnapshot {
+    /**
+     * Every machine-backed actor observed so far (registration order).
+     * Each `@xstate.actor` inspection event adds one; a UI with more than one
+     * should offer a selector (prefer parent/child tree when links exist).
+     */
+    machines: VizMachine[];
+    /** Latest projected frame per sessionId. */
+    frames: Record<string, VizFrame>;
+    log: VizLogEntry[];
+    /** Whether an in-page visualizer surface should be shown (caller decides how). */
+    inlineVisible: boolean;
+    popupStatus: HostBridgeStatus;
+}
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEpE,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,SAAS,GACT,gBAAgB,GAChB,WAAW,GACX,SAAS,CAAC;AAEd;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACjC,GAAG,EAAE,WAAW,EAAE,CAAC;IACnB,kFAAkF;IAClF,aAAa,EAAE,OAAO,CAAC;IACvB,WAAW,EAAE,gBAAgB,CAAC;CAC/B"}

package/dist/snapshot.js

@@ -0,0 +1,5 @@
+/**
+ * Portable snapshot shared by the host store and any visualizer UI.
+ */
+export {};
+//# sourceMappingURL=snapshot.js.map

package/dist/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@r-a-i-t-h/viz-protocol",
+  "version": "0.1.0",
+  "description": "Shared Viz* model and @viz.* wire types for XState visualizer hosts",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/r-a-i-t-h/viz.git",
+    "directory": "packages/protocol"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "typescript": "~6.0.2"
+  }
+}