@gratiaos/pad-core 1.0.0

package/dist/realtime/sim-adapter.js

@@ -0,0 +1,79 @@
+import { decodeJson, envelope, ns } from './port';
+/**
+ * SimAdapter — in-memory realtime port for local testing and playground use.
+ * --------------------------------------------------------------------------
+ * Behaves like a broadcast bus in a single browser tab. If multiple adapters
+ * exist in the same window, they share an EventTarget. This allows presence,
+ * scene, and pad messages to circulate during development without a network.
+ */
+const GLOBAL_BUS = globalThis.__GARDEN_SIM_BUS__ ?? new EventTarget();
+globalThis.__GARDEN_SIM_BUS__ = GLOBAL_BUS;
+let COUNTER = 0;
+function newPeerId() {
+    COUNTER += 1;
+    return `peer:sim-${COUNTER.toString(36)}-${Math.random().toString(36).slice(2, 7)}`;
+}
+export class SimAdapter {
+    constructor() {
+        this._circleId = null;
+        this._status = 'disconnected';
+        this._peerId = newPeerId();
+    }
+    status() {
+        return this._status;
+    }
+    myPeerId() {
+        return this._peerId;
+    }
+    async joinCircle(circleId) {
+        this._circleId = circleId;
+        this._status = 'connecting';
+        // Simulate async join delay
+        await new Promise((r) => setTimeout(r, 120));
+        this._status = 'connected';
+        this._emitSystem(`joined circle ${circleId}`);
+    }
+    async leaveCircle() {
+        if (this._circleId) {
+            this._emitSystem(`left circle ${this._circleId}`);
+        }
+        this._circleId = null;
+        this._status = 'disconnected';
+    }
+    publish(topic, payload) {
+        if (!this._circleId)
+            return;
+        const body = payload instanceof Uint8Array ? decodeJson(payload) : payload;
+        const msg = envelope(this._circleId, this._peerId, topic, body);
+        const eventName = ns(this._circleId, topic);
+        const evt = new CustomEvent(eventName, { detail: msg });
+        GLOBAL_BUS.dispatchEvent(evt);
+    }
+    subscribe(topic, handler) {
+        const circleId = this._circleId;
+        if (!circleId)
+            return () => { };
+        const eventName = ns(circleId, topic);
+        const fn = (e) => {
+            const ce = e;
+            if (ce.detail.sender === this._peerId)
+                return; // don't echo self
+            const decoded = decodeJson(ce.detail.body);
+            handler(decoded, ce.detail);
+        };
+        GLOBAL_BUS.addEventListener(eventName, fn);
+        return () => GLOBAL_BUS.removeEventListener(eventName, fn);
+    }
+    _emitSystem(msg) {
+        if (!this._circleId)
+            return;
+        const evt = new CustomEvent(ns(this._circleId, 'presence'), {
+            detail: envelope(this._circleId, this._peerId, 'presence', { system: msg }),
+        });
+        GLOBAL_BUS.dispatchEvent(evt);
+    }
+}
+/** Factory to create a new SimAdapter easily */
+export function createSimAdapter() {
+    return new SimAdapter();
+}

package/dist/realtime/webrtc-adapter.d.ts

@@ -0,0 +1,44 @@
+import { type CircleId, type PeerId, type Topic, type MessageEnvelope, type RealtimePort } from './port';
+/**
+ * WebRtcAdapter — hybrid P2P realtime adapter (signaling + DataChannels)
+ * ---------------------------------------------------------------------
+ * This is a scaffold for the full peer-to-peer implementation.
+ * It connects peers via a lightweight signaling WebSocket and uses
+ * WebRTC DataChannels for encrypted, low-latency message exchange.
+ *
+ * For now, this adapter only logs connection flow and mirrors the API.
+ * You can expand it to full WebRTC mesh or hub-spoke topology later.
+ */
+export interface WebRtcConfig {
+    signalUrl: string;
+    circleId: CircleId;
+    peerId?: PeerId;
+    iceServers?: RTCIceServer[];
+}
+export declare class WebRtcAdapter implements RealtimePort {
+    private cfg;
+    private _peerId;
+    private _circleId;
+    private _status;
+    private _ws;
+    private _peers;
+    private _channels;
+    private _handlers;
+    constructor(cfg: WebRtcConfig);
+    status(): "disconnected" | "connecting" | "connected";
+    myPeerId(): string;
+    joinCircle(circleId: CircleId): Promise<void>;
+    leaveCircle(): Promise<void>;
+    publish<T = unknown>(topic: Topic, payload: T | Uint8Array): void;
+    subscribe<T = unknown>(topic: Topic, handler: (payload: T, envelope: MessageEnvelope<T>) => void): () => void;
+    private _connectSignal;
+    private _sendSignal;
+    private _handleSignal;
+    private _createConnection;
+    private _handleOffer;
+    private _handleAnswer;
+    private _handleIce;
+    private _attachChannel;
+}
+/** Factory helper */
+export declare function createWebRtcAdapter(cfg: WebRtcConfig): RealtimePort;

package/dist/realtime/webrtc-adapter.js

@@ -0,0 +1,177 @@
+import { decodeJson, envelope } from './port';
+export class WebRtcAdapter {
+    constructor(cfg) {
+        this.cfg = cfg;
+        this._circleId = null;
+        this._status = 'disconnected';
+        this._ws = null;
+        this._peers = new Map();
+        this._channels = new Map();
+        this._handlers = new Map();
+        this._peerId = cfg.peerId || `peer:rtc-${Math.random().toString(36).slice(2, 8)}`;
+    }
+    status() {
+        return this._status;
+    }
+    myPeerId() {
+        return this._peerId;
+    }
+    async joinCircle(circleId) {
+        this._circleId = circleId;
+        this._status = 'connecting';
+        try {
+            await this._connectSignal();
+            this._status = 'connected';
+            console.info('[webrtc] connected to signaling hub');
+        }
+        catch (err) {
+            console.error('[webrtc] signaling failed', err);
+            this._status = 'disconnected';
+        }
+    }
+    async leaveCircle() {
+        for (const ch of this._channels.values())
+            ch.close();
+        for (const pc of this._peers.values())
+            pc.close();
+        this._channels.clear();
+        this._peers.clear();
+        if (this._ws) {
+            this._ws.close();
+            this._ws = null;
+        }
+        this._status = 'disconnected';
+        console.info('[webrtc] left circle');
+    }
+    publish(topic, payload) {
+        if (!this._circleId)
+            return;
+        const body = payload instanceof Uint8Array ? decodeJson(payload) : payload;
+        const msg = envelope(this._circleId, this._peerId, topic, body);
+        const json = JSON.stringify(msg);
+        // Broadcast to all open DataChannels
+        for (const [pid, ch] of this._channels.entries()) {
+            if (ch.readyState === 'open') {
+                ch.send(json);
+            }
+        }
+    }
+    subscribe(topic, handler) {
+        const key = topic;
+        const set = this._handlers.get(key) || new Set();
+        set.add(handler);
+        this._handlers.set(key, set);
+        return () => set.delete(handler);
+    }
+    // ---------------------------------------------------------------------------
+    // Signaling logic (simplified placeholder)
+    // ---------------------------------------------------------------------------
+    async _connectSignal() {
+        const { signalUrl } = this.cfg;
+        this._ws = new WebSocket(signalUrl);
+        this._ws.addEventListener('open', () => {
+            this._sendSignal({ type: 'join', circleId: this._circleId, peerId: this._peerId });
+        });
+        this._ws.addEventListener('message', (e) => this._handleSignal(JSON.parse(e.data)));
+        this._ws.addEventListener('close', () => {
+            this._status = 'disconnected';
+        });
+    }
+    _sendSignal(obj) {
+        if (this._ws && this._ws.readyState === WebSocket.OPEN) {
+            this._ws.send(JSON.stringify(obj));
+        }
+    }
+    async _handleSignal(msg) {
+        const { type, from, data } = msg;
+        if (from === this._peerId)
+            return;
+        switch (type) {
+            case 'offer':
+                await this._handleOffer(from, data);
+                break;
+            case 'answer':
+                await this._handleAnswer(from, data);
+                break;
+            case 'ice':
+                await this._handleIce(from, data);
+                break;
+            case 'peers':
+                for (const p of data) {
+                    if (p !== this._peerId)
+                        this._createConnection(p, true);
+                }
+                break;
+            default:
+                console.debug('[webrtc] unknown signal', msg);
+        }
+    }
+    async _createConnection(peerId, initiator) {
+        const pc = new RTCPeerConnection({ iceServers: this.cfg.iceServers || [{ urls: 'stun:stun.l.google.com:19302' }] });
+        this._peers.set(peerId, pc);
+        const channel = initiator ? pc.createDataChannel('garden') : null;
+        if (channel)
+            this._attachChannel(peerId, channel);
+        pc.ondatachannel = (e) => {
+            this._attachChannel(peerId, e.channel);
+        };
+        pc.onicecandidate = (e) => {
+            if (e.candidate)
+                this._sendSignal({ type: 'ice', from: this._peerId, to: peerId, data: e.candidate });
+        };
+        if (initiator) {
+            const offer = await pc.createOffer();
+            await pc.setLocalDescription(offer);
+            this._sendSignal({ type: 'offer', from: this._peerId, to: peerId, data: offer });
+        }
+    }
+    async _handleOffer(from, offer) {
+        const pc = new RTCPeerConnection({ iceServers: this.cfg.iceServers || [{ urls: 'stun:stun.l.google.com:19302' }] });
+        this._peers.set(from, pc);
+        pc.ondatachannel = (e) => this._attachChannel(from, e.channel);
+        pc.onicecandidate = (e) => {
+            if (e.candidate)
+                this._sendSignal({ type: 'ice', from: this._peerId, to: from, data: e.candidate });
+        };
+        await pc.setRemoteDescription(new RTCSessionDescription(offer));
+        const answer = await pc.createAnswer();
+        await pc.setLocalDescription(answer);
+        this._sendSignal({ type: 'answer', from: this._peerId, to: from, data: answer });
+    }
+    async _handleAnswer(from, answer) {
+        const pc = this._peers.get(from);
+        if (!pc)
+            return;
+        await pc.setRemoteDescription(new RTCSessionDescription(answer));
+    }
+    async _handleIce(from, candidate) {
+        const pc = this._peers.get(from);
+        if (!pc)
+            return;
+        await pc.addIceCandidate(new RTCIceCandidate(candidate));
+    }
+    _attachChannel(peerId, ch) {
+        this._channels.set(peerId, ch);
+        ch.onopen = () => console.debug('[webrtc] channel open', peerId);
+        ch.onclose = () => console.debug('[webrtc] channel closed', peerId);
+        ch.onmessage = (e) => {
+            try {
+                const msg = JSON.parse(e.data);
+                const handlers = this._handlers.get(msg.type);
+                if (!handlers)
+                    return;
+                for (const h of handlers) {
+                    const decoded = decodeJson(msg.body);
+                    h(decoded, msg);
+                }
+            }
+            catch (err) {
+                console.warn('[webrtc] bad message', err);
+            }
+        };
+    }
+}
+/** Factory helper */
+export function createWebRtcAdapter(cfg) {
+    return new WebRtcAdapter(cfg);
+}

package/dist/registry.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Pad registry: a tiny in-memory catalog of pads.
+ *
+ * - Keeps a map of PadManifest by id.
+ * - Agnostic to React/runtime; safe for SSR and tests.
+ * - Does not enforce ordering; use `sortPads` for stable sort when rendering.
+ *
+ * Typical usage
+ * ```ts
+ * import { createRegistry, sortPads, globalRegistry } from '@gratiaos/pad-core';
+ *
+ * // 1) Local registry
+ * const reg = createRegistry();
+ * reg.register({ id: 'town', title: 'Town', icon: '🌆', mount });
+ * const padsForUi = sortPads(reg.list());
+ *
+ * // 2) Or use the shared global registry (opt-in)
+ * globalRegistry.register({ id: 'value', title: 'Value Bridge', icon: '💱', mount });
+ * ```
+ */
+import type { PadId, PadManifest } from './types.js';
+export interface PadRegistry {
+    /** Insert or replace a pad manifest by id. */
+    register(manifest: PadManifest): void;
+    /** Fetch a manifest by id (undefined if absent). */
+    get(id: PadId): PadManifest | undefined;
+    /** Return all manifests (unsorted). */
+    list(): PadManifest[];
+    /** True if a manifest with this id exists. */
+    has(id: PadId): boolean;
+    /** Remove all manifests. */
+    clear(): void;
+}
+/**
+ * Create a fresh registry with optional initial manifests.
+ * This is a pure, in-memory structure – no I/O, no global state.
+ */
+export declare function createRegistry(initial?: ReadonlyArray<PadManifest>): PadRegistry;
+/** Convenience: stable sorting by title (case-insensitive), then id. */
+export declare function sortPads(pads: PadManifest[]): PadManifest[];
+/** Batch helper to register multiple manifests at once. */
+export declare function registerAll(registry: PadRegistry, manifests: ReadonlyArray<PadManifest>): void;
+/**
+ * Shared global registry (optional).
+ * Useful for apps that prefer a singleton catalog.
+ * Tests can import and call `globalRegistry.clear()` to isolate cases.
+ */
+export declare const globalRegistry: PadRegistry;

package/dist/registry.js

@@ -0,0 +1,41 @@
+/**
+ * Create a fresh registry with optional initial manifests.
+ * This is a pure, in-memory structure – no I/O, no global state.
+ */
+export function createRegistry(initial) {
+    const map = new Map();
+    for (const m of initial ?? [])
+        map.set(m.id, m);
+    return {
+        register(m) {
+            map.set(m.id, m);
+        },
+        get(id) {
+            return map.get(id);
+        },
+        list() {
+            return Array.from(map.values());
+        },
+        has(id) {
+            return map.has(id);
+        },
+        clear() {
+            map.clear();
+        },
+    };
+}
+/** Convenience: stable sorting by title (case-insensitive), then id. */
+export function sortPads(pads) {
+    return [...pads].sort((a, b) => (a.title || '').localeCompare(b.title || '', undefined, { sensitivity: 'base' }) || a.id.localeCompare(b.id));
+}
+/** Batch helper to register multiple manifests at once. */
+export function registerAll(registry, manifests) {
+    for (const m of manifests)
+        registry.register(m);
+}
+/**
+ * Shared global registry (optional).
+ * Useful for apps that prefer a singleton catalog.
+ * Tests can import and call `globalRegistry.clear()` to isolate cases.
+ */
+export const globalRegistry = createRegistry();

package/dist/route.d.ts

@@ -0,0 +1,39 @@
+import type { PadId, PadManifest, PadRouteOptions } from './types.js';
+/**
+ * Garden Pads — routing helpers (hash | query | path)
+ * ---------------------------------------------------
+ * Framework-agnostic utilities for reading/writing the current pad id from
+ * the URL using one of three strategies:
+ *   - hash  : /page#pad=town
+ *   - query : /page?pad=town
+ *   - path  : /pads/town   (with a `pathPrefix`, e.g. "/pads")
+ *
+ * The default strategy is `"auto"` which *reads* from whichever location
+ * already contains a value (hash → query → path), and *writes* to `hash`
+ * unless a manifest/opts overrides it.
+ *
+ * All functions are SSR-safe: if `window` is absent they no-op or return
+ * best-effort strings.
+ */
+export declare const DEFAULT_HASH_KEY: "pad";
+/** Read current pad id according to route options (defaults to auto). */
+export declare function getActivePadId(manifest?: PadManifest, opts?: PadRouteOptions): PadId | null;
+/** Set or clear current pad id (uses replaceState by default). */
+export declare function setActivePadId(id: PadId | null, manifest?: PadManifest, opts?: PadRouteOptions & {
+    replace?: boolean;
+}): void;
+/** Remove any active pad indicator. */
+export declare function clearActivePadId(manifest?: PadManifest, opts?: PadRouteOptions & {
+    replace?: boolean;
+}): void;
+/** Build an href that would navigate to a given pad id. */
+export declare function hrefForPad(manifest: PadManifest, opts?: PadRouteOptions & {
+    basePath?: string;
+}): string;
+/**
+ * Subscribe to route changes (hashchange/popstate) and receive the current pad id.
+ * Returns an unsubscribe function.
+ */
+export declare function onPadRouteChange(fn: (id: PadId | null) => void, manifest?: PadManifest, opts?: PadRouteOptions & {
+    fireNow?: boolean;
+}): () => void;

package/dist/route.js

@@ -0,0 +1,207 @@
+import { DEFAULT_ROUTE_MODE, DEFAULT_QUERY_KEY } from './types.js';
+/**
+ * Garden Pads — routing helpers (hash | query | path)
+ * ---------------------------------------------------
+ * Framework-agnostic utilities for reading/writing the current pad id from
+ * the URL using one of three strategies:
+ *   - hash  : /page#pad=town
+ *   - query : /page?pad=town
+ *   - path  : /pads/town   (with a `pathPrefix`, e.g. "/pads")
+ *
+ * The default strategy is `"auto"` which *reads* from whichever location
+ * already contains a value (hash → query → path), and *writes* to `hash`
+ * unless a manifest/opts overrides it.
+ *
+ * All functions are SSR-safe: if `window` is absent they no-op or return
+ * best-effort strings.
+ */
+// Defaults
+export const DEFAULT_HASH_KEY = DEFAULT_QUERY_KEY; // default hash key (mirrors query key)
+// ── internals ────────────────────────────────────────────────────────────────
+function safeWindow() {
+    try {
+        return window;
+    }
+    catch {
+        return null;
+    }
+}
+function ensureLeadingSlash(s) {
+    if (!s)
+        return '/';
+    return s.startsWith('/') ? s : `/${s}`;
+}
+function readHashParams(w = safeWindow()) {
+    const hash = w?.location?.hash ?? '';
+    return new URLSearchParams(String(hash).replace(/^#/, ''));
+}
+function writeHash(params, basePath, replace, w = safeWindow()) {
+    if (!w)
+        return;
+    const next = params.toString();
+    const newHash = next ? `#${next}` : '';
+    const base = basePath ?? w.location.pathname;
+    const href = `${base}${newHash}`;
+    if (replace)
+        w.history.replaceState(null, '', href);
+    else
+        w.history.pushState(null, '', href);
+}
+function readQueryParams(w = safeWindow()) {
+    const search = w?.location?.search ?? '';
+    return new URLSearchParams(String(search).replace(/^\?/, ''));
+}
+function writeQuery(params, basePath, replace, w = safeWindow()) {
+    if (!w)
+        return;
+    const next = params.toString();
+    const href = `${basePath ?? w.location.pathname}${next ? `?${next}` : ''}${w.location.hash ?? ''}`;
+    if (replace)
+        w.history.replaceState(null, '', href);
+    else
+        w.history.pushState(null, '', href);
+}
+function readPathId(prefix, w = safeWindow()) {
+    if (!w || !prefix)
+        return null;
+    const base = ensureLeadingSlash(prefix);
+    const p = w.location.pathname;
+    if (p === base)
+        return null;
+    if (p.startsWith(base + '/')) {
+        const rest = p.slice((base + '/').length);
+        const seg = rest.split('/')[0];
+        return decodeURIComponent(seg);
+    }
+    return null;
+}
+function writePathId(id, prefix, replace, w = safeWindow()) {
+    if (!w || !prefix)
+        return;
+    const base = ensureLeadingSlash(prefix);
+    const path = id ? `${base}/${encodeURIComponent(id)}` : base;
+    const href = `${path}${w.location.search ?? ''}${w.location.hash ?? ''}`;
+    if (replace)
+        w.history.replaceState(null, '', href);
+    else
+        w.history.pushState(null, '', href);
+}
+function resolveRoute(manifest, opts) {
+    const mode = opts?.mode ?? manifest?.route?.mode ?? DEFAULT_ROUTE_MODE;
+    // Back-compat: support legacy `route.hashKey` and `route.path` from manifests.
+    const hashKey = opts?.hashKey ?? manifest?.route?.hashKey ?? DEFAULT_HASH_KEY;
+    const queryKey = opts?.queryKey ?? DEFAULT_QUERY_KEY;
+    const pathPrefix = opts?.pathPrefix ?? manifest?.route?.pathPrefix;
+    const basePath = opts?.path ??
+        manifest?.route?.path ?? // legacy base path for hash/query hrefs
+        undefined;
+    return { mode, hashKey, queryKey, pathPrefix, basePath };
+}
+function detectAutoMode(route, w = safeWindow()) {
+    if (!w)
+        return 'hash';
+    const hashParams = readHashParams(w);
+    if (hashParams.has(route.hashKey))
+        return 'hash';
+    const queryParams = readQueryParams(w);
+    if (queryParams.has(route.queryKey))
+        return 'query';
+    if (route.pathPrefix && readPathId(route.pathPrefix, w))
+        return 'path';
+    return 'hash';
+}
+// ── public: get/set/clear/href/subscribe (multi-mode) ───────────────────────
+/** Read current pad id according to route options (defaults to auto). */
+export function getActivePadId(manifest, opts) {
+    const route = resolveRoute(manifest, opts);
+    const mode = route.mode === 'auto' ? detectAutoMode(route) : route.mode;
+    if (mode === 'hash') {
+        const v = readHashParams().get(route.hashKey);
+        return v ?? null;
+    }
+    if (mode === 'query') {
+        const v = readQueryParams().get(route.queryKey);
+        return v ?? null;
+    }
+    // path
+    return readPathId(route.pathPrefix);
+}
+/** Set or clear current pad id (uses replaceState by default). */
+export function setActivePadId(id, manifest, opts) {
+    const route = resolveRoute(manifest, opts);
+    const w = safeWindow();
+    if (!w)
+        return;
+    const replace = opts?.replace ?? true;
+    const mode = route.mode === 'auto' ? detectAutoMode(route, w) : route.mode;
+    if (mode === 'hash') {
+        const params = readHashParams(w);
+        if (id)
+            params.set(route.hashKey, id);
+        else
+            params.delete(route.hashKey);
+        writeHash(params, route.basePath, replace, w);
+        return;
+    }
+    if (mode === 'query') {
+        const params = readQueryParams(w);
+        if (id)
+            params.set(route.queryKey, id);
+        else
+            params.delete(route.queryKey);
+        writeQuery(params, route.basePath, replace, w);
+        return;
+    }
+    writePathId(id, route.pathPrefix, replace, w);
+}
+/** Remove any active pad indicator. */
+export function clearActivePadId(manifest, opts) {
+    setActivePadId(null, manifest, opts);
+}
+/** Build an href that would navigate to a given pad id. */
+export function hrefForPad(manifest, opts) {
+    const route = resolveRoute(manifest, opts);
+    const w = safeWindow();
+    const base = opts?.basePath ?? route.basePath ?? w?.location?.pathname ?? '/';
+    const mode = route.mode === 'auto' ? 'hash' : route.mode; // default hrefs to hash when auto
+    if (mode === 'hash') {
+        const params = w ? readHashParams(w) : new URLSearchParams();
+        params.set(route.hashKey, manifest.id);
+        const q = params.toString();
+        return q ? `${base}#${q}` : base;
+    }
+    if (mode === 'query') {
+        const params = w ? readQueryParams(w) : new URLSearchParams();
+        params.set(route.queryKey, manifest.id);
+        const q = params.toString();
+        const hash = w?.location?.hash ?? '';
+        return `${base}${q ? `?${q}` : ''}${hash}`;
+    }
+    // path
+    const prefix = ensureLeadingSlash(route.pathPrefix ?? '/pads');
+    return `${prefix}/${encodeURIComponent(manifest.id)}`;
+}
+/**
+ * Subscribe to route changes (hashchange/popstate) and receive the current pad id.
+ * Returns an unsubscribe function.
+ */
+export function onPadRouteChange(fn, manifest, opts) {
+    const route = resolveRoute(manifest, opts);
+    const w = safeWindow();
+    if (!w)
+        return () => { };
+    const handler = () => fn(getActivePadId(manifest, opts));
+    const mode = route.mode === 'auto' ? 'auto' : route.mode;
+    const unsubs = [];
+    if (mode === 'hash' || mode === 'auto') {
+        w.addEventListener('hashchange', handler);
+        unsubs.push(() => w.removeEventListener('hashchange', handler));
+    }
+    if (mode === 'query' || mode === 'path' || mode === 'auto') {
+        w.addEventListener('popstate', handler);
+        unsubs.push(() => w.removeEventListener('popstate', handler));
+    }
+    if (opts?.fireNow)
+        handler();
+    return () => unsubs.forEach((u) => u());
+}

package/dist/scene-events.d.ts

@@ -0,0 +1,48 @@
+import type { PadId, SceneId } from './types';
+/**
+ * Scene Events (Pad Core)
+ * -------------------------------------------------------
+ * Typed CustomEvent helpers for entering and completing Scenes.
+ * Mirrors the pad events API shape (dispatch/on/... with unsubscribe).
+ */
+export declare const SCENE_ENTER: "scene:enter";
+export declare const SCENE_COMPLETE: "scene:complete";
+/** Who triggered the event and how the user got here */
+export type SceneVia = 'diagram' | 'inspector' | 'deeplink' | 'system' | 'other';
+export type SceneEnterDetail = {
+    padId: PadId | string;
+    sceneId: SceneId | string;
+    via?: SceneVia;
+    actorId?: string;
+    timestamp?: number;
+};
+export type SceneCompleteDetail = {
+    padId: PadId | string;
+    sceneId: SceneId | string;
+    result?: unknown;
+    success?: boolean;
+    actorId?: string;
+    timestamp?: number;
+};
+type SceneEnterEvent = CustomEvent<SceneEnterDetail>;
+type SceneCompleteEvent = CustomEvent<SceneCompleteDetail>;
+type DispatchOptions = {
+    skipRealtime?: boolean;
+};
+/**
+ * Dispatchers
+ * -------------------------------------------------------
+ */
+export declare function dispatchSceneEnter(detail: SceneEnterDetail, target?: EventTarget | null, options?: DispatchOptions): void;
+export declare function dispatchSceneComplete(detail: SceneCompleteDetail, target?: EventTarget | null, options?: DispatchOptions): void;
+/**
+ * Listeners
+ * -------------------------------------------------------
+ * Returns an unsubscribe function for convenience.
+ */
+export declare function onSceneEnter(handler: (e: SceneEnterEvent) => void, target?: EventTarget | null): () => void;
+export declare function onSceneComplete(handler: (e: SceneCompleteEvent) => void, target?: EventTarget | null): () => void;
+/**
+ * Type re-exports (handy for consumers)
+ */
+export type { SceneEnterEvent, SceneCompleteEvent };