dsh-realtime-audio-ws 0.2.2 → 0.2.4

package/README.md

@@ -43,8 +43,27 @@ first — which is the only reason to trust it.
 
 ## The wire
 
-Binary frames only, both directions, in the session's declared input/output format (PCM16, 24 kHz, mono, for
-the shipped adapter). A text frame is ignored rather than fatal: nothing on this wire is JSON.
+Binary frames carry audio, both directions, in the session's declared input/output format (PCM16, 24 kHz,
+mono, for the shipped adapter). **Text frames carry control:**
+
+| Frame | Answer |
+|---|---|
+| `status` | this route, the live voice, every setting, the journal's last entry |
+| `start` | the session that opened — an outcome, not an acknowledgement |
+| `stop` | the state afterwards |
+| `steer <sessionId>` | the setting that declares a live `sessionId`, changed |
+| `set <key>=<value>` | the setting named by its `<owner>.<field>` key, changed |
+
+One frame in, exactly one frame out, and **every** frame is answered — a verb it does not have, an argument
+where none belongs, a field frozen by its class, a value the setting's own rules reject. The reply is JSON:
+`{"ok":true,…}` with the fields for that verb, or `{"ok":false,"verb":…,"code":…,"reason":…}` with a reason
+written to be relayed verbatim. `set realtime-agent.autoStart=true` answers with the *restart* it needs
+rather than a silence that reads as a broken control.
+
+This was a deliberate widening of a contract that used to say the opposite — a text frame was ignored,
+because nothing on this wire was JSON. The socket is the only duplex connection the client already holds,
+one text frame in / one text frame out is smaller than a second route with its own authentication, and the
+audio path is untouched: the two are told apart by the frame's own type.
 
 Frames are forwarded, never queued. A client that cannot keep up drops audio instead of accumulating it,
 which matches the `realtime-agent/audio` contract — a queue that grows while nothing drains it presents
@@ -60,6 +79,14 @@ A frame larger than `maxFrameBytes` closes the connection with 1009 rather than
 | `maxFrameBytes` | `480000` | Ten seconds of 24 kHz mono PCM16. Above this the connection is closed with 1009. |
 | `maxConnections` | `1` | A second connection is closed with 1013 rather than queued. One microphone is the honest default. |
 
+`openSessionOnConnect` (default `true`) is **live**: read at the moment an authenticated client connects
+and at the moment the last one leaves, so the seam's settings surface turns it off and on without a
+restart — `set realtime-audio-ws.openSessionOnConnect=false`. Freezing it was the failure this plugin's
+own docs describe: with it off and no way to change it, a working microphone produces silence that looks
+like a fault anywhere but in the config. The rest of this row's fields (`path`, `maxFrameBytes`,
+`maxConnections`, `diagnosticsPath`) are claimed against the web server's registry or enforced by the
+socket at load, so they are restart-bound and get no control.
+
 ## Where it waits
 
 This row appears **unloaded** in a composition without the web server and connection services, and that is
@@ -70,20 +97,41 @@ visibly waits rather than one that loads and silently claims nothing. The bundle
 ## The client half
 
 `dsh-realtime-audio-ws/client` is the browser face: it opens this socket, captures the microphone into it at
-24 kHz PCM16, and plays what comes back. No client services, one file, and it injects nothing — a client
-face that needs nothing cannot be broken by another plugin's absence.
+24 kHz PCM16, plays what comes back, and drives the strip. No client services, one file.
+
+**How it runs.** The strip in the app's own page is the way in — it is mounted by the injected row and by
+the bundle itself, whichever lands second finding the panel already there:
+
+```
+[ microphone: idle ] [ Connect microphone ] [ Refresh ]
+voice: open · fake/gpt-live-1
+realtime-responder.sessionId   [ sess-1 ▾ ] [ Steer ]      applied
+realtime-responder.answerTimeoutMs  [ 45000 ] [ Set ]
+realtime-agent.model           fixed when the session opens — reconnect to apply
+```
+
+A live field gets a control, a session-bound field gets the value it will take plus the words "reconnect to
+apply", and a restart-bound field gets no row at all — a control the protocol cannot honour is worse than no
+control. Every `set` reports its outcome beside the field it belongs to, and a refusal is relayed verbatim
+with the host's own code: `FROZEN_SETTING: "…" is claimed when the plugin loads — restart to change it`.
 
-**How it runs.** There is no UI surface yet, so it publishes itself on a global:
+The same handle stays published on `globalThis[GLOBAL_KEY]` for the injected bootstrap and for anything else
+that holds it — `start`, `stop`, `state`, `request`, `mount` — but it is no longer the on-switch:
 
 ```js
-await __dshRealtimeAudio.start()   // asks for the microphone, then connects
-__dshRealtimeAudio.state()         // { kind: 'idle' | 'live' | 'failed' }
-__dshRealtimeAudio.stop()
+__dshRealtimeAudio.start()            // asks for the microphone, then connects
+__dshRealtimeAudio.state()            // { kind: 'idle' | 'live' | 'failed' }
+__dshRealtimeAudio.request('status')  // one text frame in, exactly one reply out
 ```
 
 `start()` **reports rather than throws**, so a refused permission or a missing API arrives as
 `{ kind: 'failed', reason }` — the reason is what tells someone whether to grant something or to look
-somewhere else. A settings card is its own increment.
+somewhere else.
+
+**Requests are serialised.** One frame is in flight at a time: the host answers in arrival order, and two
+frames out at once would make pairing a reply with its request a guess the moment anything on the host
+slowed down. A request with no socket is a rejection — reporting `{ok: false}` there would be
+indistinguishable from the host refusing.
 
 **Two decisions inside it worth knowing.**
 
@@ -99,6 +147,10 @@ will not open at 24 kHz the client fails and says which rate it got.
 
 ## What it does not do yet
 
-**No format negotiation, and no reconnect.** A `ready` frame carrying sample rate and channel count would be
-the natural first control message; a dropped socket currently ends the conversation rather than being
-rejoined. Both are deliberately absent rather than half-built.
+**No format negotiation, and no reconnect.** A `ready` frame carrying sample rate and channel count is the
+obvious next control *frame* — the control channel is now there to carry one — and a dropped socket still
+ends the conversation rather than being rejoined. Both are deliberately absent rather than half-built.
+
+**The panel has no keyboard path and no permissions row.** The strip is clickable controls and text, so a
+screen reader gets it, but nothing focuses it and the microphone's permission state is reported rather than
+requested ahead of time. Both are increments, not gaps in the channel.

package/lib/bridge.d.ts

@@ -12,6 +12,20 @@ export interface AudioSocketBridgeDeps {
     readonly subscribeAudio: (listener: (pcm16: Uint8Array) => void) => () => void;
     /** Longest inbound frame accepted, in bytes. */
     readonly maxFrameBytes: number;
+    /**
+     * Handle one **control frame** — a text frame on this socket.
+     *
+     * Until S2 story 2 a text frame was not part of this contract, and the comment that said so was right
+     * about the wire as it was: the socket carried PCM16 in both directions and nothing else. It now
+     * carries a channel too, because it is the only duplex connection the client already holds, and one
+     * text frame in / one text frame out is a smaller contract than a second route with its own
+     * authentication would have been.
+     *
+     * `reply` writes exactly one text frame back, and silently drops it once the socket is gone: a control
+     * handler is asynchronous, and a reply to a closed socket would throw from inside a promise nobody
+     * awaits.
+     */
+    readonly onControl: (frame: string, reply: (text: string) => void) => void;
     /** Called exactly once when the bridge stops, however it stops. */
     readonly onDetach: () => void;
 }
@@ -26,6 +40,16 @@ export interface AudioSocketBridgeDeps {
  * @returns the payload as bytes.
  */
 export declare function toBytes(data: unknown): Uint8Array;
+/**
+ * Normalise a `ws` message payload to text.
+ *
+ * The same three shapes {@link toBytes} handles, decoded as UTF-8 — a control frame arrives as a Buffer
+ * whichever way it was framed, and a fragmented one as an array of them.
+ *
+ * @param data - the payload as `ws` delivered it.
+ * @returns the payload as text.
+ */
+export declare function toText(data: unknown): string;
 /**
  * Wire one accepted socket to the agent's audio events.
  *

package/lib/bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;IAC7C,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;IAC9E,gDAAgD;IAChD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAA;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAKjD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,qBAAqB,GAAG,MAAM,IAAI,CAwC9F"}
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;IAC7C,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;IAC9E,gDAAgD;IAChD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,KAAK,IAAI,CAAA;IAC1E,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAA;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAKjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAK5C;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,qBAAqB,GAAG,MAAM,IAAI,CAkE9F"}

package/lib/bridge.js

@@ -23,6 +23,24 @@ export function toBytes(data) {
         return new Uint8Array(data);
     return new Uint8Array(Buffer.from(data));
 }
+/**
+ * Normalise a `ws` message payload to text.
+ *
+ * The same three shapes {@link toBytes} handles, decoded as UTF-8 — a control frame arrives as a Buffer
+ * whichever way it was framed, and a fragmented one as an array of them.
+ *
+ * @param data - the payload as `ws` delivered it.
+ * @returns the payload as text.
+ */
+export function toText(data) {
+    if (typeof data === 'string')
+        return data;
+    if (Array.isArray(data))
+        return Buffer.concat(data).toString('utf8');
+    if (data instanceof Uint8Array)
+        return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString('utf8');
+    return Buffer.from(data).toString('utf8');
+}
 /**
  * Wire one accepted socket to the agent's audio events.
  *
@@ -48,11 +66,37 @@ export function attachAudioSocket(client, deps) {
         unsubscribe();
         deps.onDetach();
     };
+    /**
+     * Answer one control frame, if the socket is still there.
+     *
+     * The guard is here rather than at the call site because this is the only place that knows whether the
+     * bridge is still live, and because a control handler settles asynchronously: a reply that arrives after
+     * the socket went away must be dropped, not thrown.
+     *
+     * **Total**, including the write: a socket can die between the check above and the send, and a throw here
+     * would escape into a promise nobody awaits — and, in the plugin, would break the reply queue for every
+     * frame behind it.
+     * @param text - the reply frame.
+     */
+    const reply = (text) => {
+        if (stopped)
+            return;
+        try {
+            client.send(text);
+        }
+        catch {
+            stop();
+        }
+    };
     client.on('message', (data, isBinary) => {
-        // A text frame is not part of this contract. Ignoring one is cheaper than closing the connection and
-        // no less correct: nothing on this wire is JSON.
-        if (!isBinary)
+        // A **text** frame is a control frame. This is the deliberate widening of the contract that used to
+        // say the opposite: the socket is the one duplex connection the client already holds, and a control
+        // plane that needs a second route with a second authentication is a control plane nobody builds.
+        // Checked before the audio path, because a text frame is never audio whatever it contains.
+        if (!isBinary) {
+            deps.onControl(toText(data), reply);
             return;
+        }
         const pcm16 = toBytes(data);
         if (pcm16.byteLength > deps.maxFrameBytes) {
             // 1009 = message too big. `ws` enforces its own `maxPayload` first, so reaching this means the bound

package/lib/bridge.js.map

@@ -1 +1 @@
-{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAeH;;;;;;;;;GASG;AACH,MAAM,UAAU,OAAO,CAAC,IAAa;IACnC,IAAI,IAAI,YAAY,UAAU;QAAE,OAAO,IAAI,CAAA;IAC3C,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,IAA6B,CAAC,CAAC,CAAA;IAC5F,IAAI,IAAI,YAAY,WAAW;QAAE,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,CAAA;IAC5D,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,IAAuB,CAAC,CAAC,CAAA;AAC7D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAmB,EAAE,IAA2B;IAChF,IAAI,OAAO,GAAG,KAAK,CAAA;IAEnB,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC,KAAK,EAAE,EAAE;QAChD,qGAAqG;QACrG,gGAAgG;QAChG,IAAI,OAAO;YAAE,OAAM;QACnB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACpB,CAAC,CAAC,CAAA;IAEF,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,sGAAsG;QACtG,qDAAqD;QACrD,IAAI,OAAO;YAAE,OAAM;QACnB,OAAO,GAAG,IAAI,CAAA;QACd,WAAW,EAAE,CAAA;QACb,IAAI,CAAC,QAAQ,EAAE,CAAA;IACjB,CAAC,CAAA;IAED,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE;QACtC,qGAAqG;QACrG,iDAAiD;QACjD,IAAI,CAAC,QAAQ;YAAE,OAAM;QACrB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;QAC3B,IAAI,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YAC1C,qGAAqG;YACrG,mGAAmG;YACnG,IAAI,EAAE,CAAA;YACN,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAA;YACrC,OAAM;QACR,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IACrB,CAAC,CAAC,CAAA;IACF,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IACxB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IAExB,OAAO,GAAG,EAAE;QACV,IAAI,EAAE,CAAA;QACN,MAAM,CAAC,SAAS,EAAE,CAAA;IACpB,CAAC,CAAA;AACH,CAAC"}
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"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"}

package/lib/client/bundle.js

@@ -28,7 +28,7 @@ window.__ModuleLoader__.load({ id: "dsh-realtime-audio-ws",
      * actually been read, rather than shipping a capture path that a policy might silently kill.
      */
     Object.defineProperty(exports, "__esModule", { value: true });
-    exports.INJECTED_KEY = exports.GLOBAL_KEY = exports.MAX_BACKLOG_SECONDS = exports.CAPTURE_BUFFER = exports.SAMPLE_RATE = exports.DEFAULT_PATH = exports.inject = exports.name = void 0;
+    exports.STRIP_ELEMENT_ID = exports.INJECTED_KEY = exports.GLOBAL_KEY = exports.MAX_BACKLOG_SECONDS = exports.CAPTURE_BUFFER = exports.SAMPLE_RATE = exports.DEFAULT_PATH = exports.inject = exports.name = void 0;
     exports.socketUrl = socketUrl;
     exports.pageAuthority = pageAuthority;
     exports.withToken = withToken;
@@ -36,6 +36,9 @@ window.__ModuleLoader__.load({ id: "dsh-realtime-audio-ws",
     exports.float32FromPcm16 = float32FromPcm16;
     exports.defaultDeps = defaultDeps;
     exports.createAudioClient = createAudioClient;
+    exports.stripRoot = stripRoot;
+    exports.renderStrip = renderStrip;
+    exports.mountStrip = mountStrip;
     exports.apply = apply;
     /** Browser-side plugin name. */
     exports.name = 'realtime-audio-client';
@@ -170,12 +173,20 @@ window.__ModuleLoader__.load({ id: "dsh-realtime-audio-ws",
         let processor;
         let silence;
         let playsAt = 0;
+        /** The control request waiting for its reply, if any. The host answers one frame with one frame. */
+        let pending;
+        /** The tail of the request chain, so two frames are never in flight at once. */
+        let chain = Promise.resolve();
         const fail = (reason) => {
             current = { kind: 'failed', reason };
             return current;
         };
         /** Release everything held. Idempotent, because stop, an error and a close all reach it. */
         const release = () => {
+            // A request whose socket is going away must fail rather than hang: the panel disables half of itself
+            // while one is in flight, and a promise that never settles would leave it disabled for ever.
+            pending?.reject(new Error('the audio socket closed before the host answered'));
+            pending = undefined;
             socket?.close();
             socket = undefined;
             processor?.disconnect();
@@ -220,6 +231,12 @@ window.__ModuleLoader__.load({ id: "dsh-realtime-audio-ws",
             const source = context.createMediaStreamSource(stream);
             const node = context.createScriptProcessor(exports.CAPTURE_BUFFER, 1, 1);
             node.onaudioprocess = (event) => {
+                // Every quantum ships, **silent ones included, and that is load-bearing rather than incidental**: the
+                // provider's session timeline advances with the audio this client sends, and a context append is
+                // placed only while that timeline is advancing — so a client that skipped silent blocks (an
+                // obvious-looking saving) would silently freeze the session and lose every append after it. Measured,
+                // with the mechanism, in `docs/usable-window.md`; guarded by the capture-continuity case in
+                // `tests/client.spec.ts`.
                 const pcm16 = pcm16FromFloat32(event.inputBuffer.getChannelData(0));
                 socket?.send(new Uint8Array(pcm16.buffer));
             };
@@ -276,8 +293,26 @@ window.__ModuleLoader__.load({ id: "dsh-realtime-audio-ws",
             socket = opened;
             opened.binaryType = 'arraybuffer';
             opened.onmessage = (event) => {
-                if (event.data instanceof ArrayBuffer)
+                // Binary frames are audio; a string is the answer to a control frame. The frame's own type is what
+                // tells them apart, which is why the control channel cost this path nothing.
+                if (event.data instanceof ArrayBuffer) {
                     play(new Uint8Array(event.data));
+                    return;
+                }
+                if (typeof event.data !== 'string')
+                    return;
+                const waiting = pending;
+                pending = undefined;
+                if (waiting === undefined)
+                    return;
+                try {
+                    waiting.resolve(JSON.parse(event.data));
+                }
+                catch {
+                    // A reply that is not JSON is a host fault, and the caller has to hear about it rather than be left
+                    // waiting: the same rule the channel itself follows, one side out.
+                    waiting.reject(new Error('the host answered a control frame with something that is not a reply'));
+                }
             };
             opened.onclose = () => {
                 release();
@@ -288,23 +323,329 @@ window.__ModuleLoader__.load({ id: "dsh-realtime-audio-ws",
                 opened.onerror = () => { resolve(fail('the host refused the audio socket')); };
             });
         };
-        return { start, stop, state: () => current };
+        /**
+         * Send one frame and wait for its reply.
+         *
+         * The socket is looked up at the moment of use rather than closed over, so a request made after a
+         * reconnect goes out on the socket that exists now — the same rule every other live value in this
+         * project follows.
+         * @param frame - the control frame.
+         * @returns the parsed reply.
+         */
+        const sendFrame = (frame) => {
+            const current = socket;
+            if (current === undefined) {
+                return Promise.reject(new Error('not connected: connect the microphone first'));
+            }
+            return new Promise((resolve, reject) => {
+                pending = { resolve, reject };
+                current.send(frame);
+            });
+        };
+        const request = (frame) => {
+            // Chained, not concurrent: the host answers in arrival order, and a client that pipelined would be
+            // pairing replies with frames by guesswork. The chain is kept alive across a failure, because one
+            // refused frame must not silently stop every frame behind it.
+            const next = chain.then(() => sendFrame(frame));
+            chain = next.catch(() => undefined);
+            return next;
+        };
+        return { start, stop, state: () => current, request };
+    }
+    // ---- the strip: the panel this plugin puts in the app ---------------------------------------------------
+    /** The element the injected markup provides. Duplicated in the host half, which mints the row. */
+    exports.STRIP_ELEMENT_ID = 'dsh-realtime-strip';
+    /**
+     * Where the injected markup puts the panel, or `null` when this page does not carry it.
+     * @param scope - the page scope, injectable so both cases are testable without a DOM.
+     * @returns the panel's element, or `null`.
+     */
+    function stripRoot(scope) {
+        return scope.document?.getElementById(exports.STRIP_ELEMENT_ID) ?? null;
+    }
+    /**
+     * Escape text for an element's body and for a quoted attribute at once.
+     *
+     * One function rather than two because the two contexts differ only in which characters break out, and
+     * every value a panel renders came from a plugin's own configuration — a session id, a model name, or
+     * `instructions` somebody typed.
+     * @param text - the text to escape.
+     * @returns the text, safe in either position.
+     */
+    function escapeHtml(text) {
+        return text
+            .replaceAll('&', '&')
+            .replaceAll('<', '&lt;')
+            .replaceAll('>', '&gt;')
+            .replaceAll('"', '&quot;');
+    }
+    /**
+     * Show one value as text.
+     * @param value - a setting's value as `status` reported it.
+     * @returns the text to render.
+     */
+    function show(value) {
+        if (value === undefined || value === null)
+            return '—';
+        return typeof value === 'string' ? value : JSON.stringify(value);
+    }
+    /**
+     * Render the whole panel.
+     *
+     * A pure function of the state, because that is what makes the panel testable at all: the injected script
+     * is three lines and the DOM is one assignment, so everything worth checking lives here.
+     * @param state - what the panel is showing.
+     * @returns the markup for the panel's element.
+     */
+    function renderStrip(state) {
+        const reply = state.reply;
+        const lines = [`<p data-dsh-strip-voice>${escapeHtml(summariseVoice(reply, state.audio))}</p>`];
+        if (reply !== null)
+            lines.push(`<p data-dsh-strip-route>${escapeHtml(summariseRoute(reply))}</p>`);
+        if (state.notice !== '')
+            lines.push(`<p data-dsh-strip-notice>${escapeHtml(state.notice)}</p>`);
+        lines.push(`<p data-dsh-strip-buttons>${buttons(state.audio)}</p>`);
+        // Restart-bound settings are omitted rather than shown read-only: the gate says no control at all, and a
+        // row that cannot be changed is a row a reader will try to change.
+        const settings = (reply?.settings ?? []).filter(entry => entry.scope !== 'restart');
+        lines.push(settings.length === 0
+            ? '<p data-dsh-strip-empty>no settings to show</p>'
+            : `<ul>${settings.map(entry => settingRow(entry, state.notes)).join('')}</ul>`);
+        return lines.join('');
+    }
+    /**
+     * The voice line: whether a session is live, and what it is.
+     * @param reply - the last status, if any.
+     * @param audio - what the microphone is doing.
+     * @returns one line of plain text.
+     */
+    function summariseVoice(reply, audio) {
+        const microphone = audio.kind === 'failed' ? `microphone: failed — ${audio.reason}` : `microphone: ${audio.kind}`;
+        if (reply === null)
+            return `no answer yet · ${microphone}`;
+        const voice = reply.voice;
+        // `null` is "nobody answered the question", which is a composition without an agent row — deliberately
+        // not the same statement as a session that is merely closed.
+        if (voice === null || voice === undefined)
+            return `voice: no agent is mounted in this profile · ${microphone}`;
+        const where = voice.provider === undefined ? '' : ` · ${voice.provider}/${voice.model ?? '?'}`;
+        const which = voice.sessionId === undefined ? '' : ` · ${voice.sessionId}`;
+        return `voice: ${voice.open ? 'open' : 'closed'}${where}${which} · ${microphone}`;
     }
     /**
-     * The client plugin. Publishes the client on a global and releases it with the plugin.
+     * The route line: what this socket is, and the last thing the journal recorded.
+     * @param reply - the last status.
+     * @returns one line of plain text.
+     */
+    function summariseRoute(reply) {
+        const last = reply.journal?.last?.kind;
+        return [
+            reply.audio?.path ?? 'the audio route',
+            `${String(reply.audio?.clients ?? 0)} socket(s)`,
+            `journal ${String(reply.journal?.size ?? 0)}`,
+            ...last === undefined ? [] : [`last ${last}`],
+        ].join(' · ');
+    }
+    /**
+     * The buttons above the settings.
      *
-     * There is no UI surface yet, so a global is how it is driven — a settings card is its own increment and a
-     * bigger one than this. `inject` is empty for the same reason: nothing here needs another plugin.
+     * The microphone's own button is the on-switch this sprint exists to provide: what used to be a
+     * `globalThis` call in a devtools console is now the first control in the panel.
+     * @param audio - what the microphone is doing.
+     * @returns the markup.
+     */
+    function buttons(audio) {
+        const live = audio.kind === 'live';
+        return [
+            `<button data-action="${live ? 'disconnect' : 'connect'}">${live ? 'Disconnect microphone' : 'Connect microphone'}</button>`,
+            '<button data-action="voice-start">Start voice</button>',
+            '<button data-action="voice-stop">Stop voice</button>',
+            '<button data-action="refresh">Refresh</button>',
+        ].join(' ');
+    }
+    /**
+     * One setting's row.
+     *
+     * Three classes, three treatments, and the gate's rule is the reason: a live field gets a control, a
+     * session-bound field says what it would take to change it, and a restart-bound field is not rendered.
+     * @param entry - the setting as `status` reported it.
+     * @param notes - what the last change to each setting produced.
+     * @returns the markup for one row.
+     */
+    function settingRow(entry, notes) {
+        const key = escapeHtml(entry.key);
+        const label = `<span data-dsh-strip-label>${escapeHtml(entry.describe ?? entry.field)}</span>`;
+        const note = notes[entry.key] === undefined
+            ? ''
+            : `<em data-note="${key}">${escapeHtml(notes[entry.key])}</em>`;
+        if (entry.scope !== 'live') {
+            return `<li data-key="${key}" data-scope="session">${label}<b>${escapeHtml(show(entry.value))}</b>`
+                + `<em>fixed when the session opens — reconnect to apply</em>${note}</li>`;
+        }
+        // The channel has a verb for exactly one purpose — steering at a session — and this is the field it
+        // means. Everything else goes through `set <key>=<value>`.
+        const action = entry.field === 'sessionId' && entry.kind === 'string' ? 'steer' : 'set';
+        const control = entry.choices !== undefined && entry.choices.length > 0
+            ? `<select data-input="${key}">${choiceOptions(entry, entry.choices)}</select>`
+            : `<input data-input="${key}" value="${escapeHtml(show(entry.value))}">`;
+        const name = action === 'steer' ? 'Steer' : 'Set';
+        return `<li data-key="${key}" data-scope="live">${label}${control}`
+            + `<button data-action="${action}" data-key="${key}">${name}</button>${note}</li>`;
+    }
+    /**
+     * A picker's options, with the value in force always among them.
+     * @param entry - the setting, for its value.
+     * @param candidates - the values it declared. Passed in rather than read here: this is only ever called
+     *   for a setting that has a non-empty list, and a fallback for the case that cannot happen is a branch
+     *   the coverage gate rightly flags as dead.
+     * @returns the markup for each option.
+     */
+    function choiceOptions(entry, candidates) {
+        const current = show(entry.value);
+        // A value that is not among the candidates is offered anyway. A select that silently showed the first
+        // candidate instead of the value actually in force would be lying about the state, which is the one
+        // thing a control plane must not do.
+        const all = candidates.includes(current) ? candidates : [current, ...candidates];
+        return all.map(choice => `<option value="${escapeHtml(choice)}"${choice === current ? ' selected' : ''}>${escapeHtml(choice)}</option>`).join('');
+    }
+    /**
+     * Mount the panel on its element.
+     *
+     * Reads `status` once, then renders — and renders again after every action, because a control that
+     * reported an outcome without showing the state it produced would leave the reader unsure which of the two
+     * they are looking at.
+     * @param deps - the element, the transport and the microphone's own controls.
+     * @returns the panel's handle.
+     */
+    function mountStrip(deps) {
+        let reply = null;
+        const notes = {};
+        let notice = '';
+        const paint = () => {
+            deps.root.innerHTML = renderStrip({ reply, notes, notice, audio: deps.audio() });
+        };
+        const refresh = async () => {
+            try {
+                reply = await deps.request('status');
+            }
+            catch (error) {
+                // Nothing was sent, or nothing came back: the panel says which, rather than showing a stale state as
+                // if it were current.
+                notice = error instanceof Error ? error.message : String(error);
+            }
+            paint();
+        };
+        /**
+         * Send one frame and report what came back, then re-render.
+         * @param frame - the control frame.
+         * @param fieldKey - the setting the change was about, when it was about one.
+         * @param done - what to say when it worked.
+         */
+        const send = async (frame, fieldKey, done) => {
+            let line;
+            try {
+                const answer = await deps.request(frame);
+                // A refusal carries the reason written to be relayed verbatim, so it is relayed rather than
+                // translated — including for a field frozen by its class.
+                line = answer.ok ? done : `${answer.code ?? 'refused'}: ${answer.reason ?? 'no reason given'}`;
+            }
+            catch (error) {
+                line = error instanceof Error ? error.message : String(error);
+            }
+            if (fieldKey === undefined)
+                notice = line;
+            else
+                notes[fieldKey] = line;
+            await refresh();
+        };
+        const onClick = (event) => {
+            const action = event.target?.dataset?.action;
+            if (action === undefined)
+                return;
+            const key = event.target?.dataset?.key;
+            const value = key === undefined ? undefined : deps.root.querySelector(`[data-input="${key}"]`)?.value;
+            const act = async () => {
+                // Cleared per action: a notice from the last one is about the last one, and leaving it up would make
+                // a successful reconnect read as a failed one.
+                notice = '';
+                switch (action) {
+                    case 'refresh':
+                        await refresh();
+                        return;
+                    case 'disconnect':
+                        deps.disconnect();
+                        await refresh();
+                        return;
+                    case 'connect': {
+                        const reached = await deps.connect();
+                        if (reached.kind === 'failed')
+                            notice = reached.reason;
+                        await refresh();
+                        return;
+                    }
+                    case 'voice-start':
+                        await send('start', undefined, 'voice started');
+                        return;
+                    case 'voice-stop':
+                        await send('stop', undefined, 'voice stopped');
+                        return;
+                    case 'steer':
+                        await send(`steer ${value ?? ''}`, key, 'steered');
+                        return;
+                    case 'set': await send(`set ${key ?? ''}=${value ?? ''}`, key, 'applied');
+                }
+            };
+            void act();
+        };
+        deps.root.addEventListener('click', onClick);
+        return { refresh, state: () => ({ reply, notes, notice, audio: deps.audio() }) };
+    }
+    /**
+     * The client plugin. Publishes the client and the strip on a global, and releases them with the plugin.
+     *
+     * `inject` is empty on purpose: nothing here needs another plugin, and a client face that needs nothing
+     * cannot be broken by another plugin's absence.
+     *
+     * The global is **no longer the on-switch**. S2 story 3 put a panel in the app, and the panel's buttons
+     * are how anyone starts a microphone; the global is now the seam between the injected markup and this
+     * bundle, which is a different thing from a user interface that only exists in a devtools console.
      *
      * @param ctx - the client context, used only to own the lifetime.
      */
     function apply(ctx) {
         const client = createAudioClient(defaultDeps());
+        let mounted = false;
+        /**
+         * Render the panel into the element the injected markup provides.
+         *
+         * Called twice on purpose — once here, and once by the injected bootstrap script — because the two
+         * orders are both possible: this bundle is materialised by the module table, and the markup arrives with
+         * the body rows. Whichever runs second finds the panel already there and does nothing.
+         */
+        const mount = () => {
+            if (mounted)
+                return;
+            const root = stripRoot(globalThis);
+            if (root === null)
+                return;
+            mounted = true;
+            const strip = mountStrip({
+                root,
+                request: (frame) => client.request(frame),
+                connect: () => client.start(),
+                disconnect: () => { client.stop(); },
+                audio: () => client.state(),
+            });
+            void strip.refresh();
+        };
         globalThis[exports.GLOBAL_KEY] = {
             start: () => client.start(),
             stop: () => { client.stop(); },
             state: () => client.state(),
+            request: (frame) => client.request(frame),
+            mount,
         };
+        mount();
         // A held microphone and a live audio graph must not outlive the plugin that opened them.
         ctx.effect(() => () => { client.stop(); }, 'realtime-audio-client');
     }