@crowdedkingdoms/crowdyjs 12.0.0 → 12.1.0

package/dist/player-host/control-banner.d.ts

@@ -0,0 +1,40 @@
+import type { CrowdyStudioAgentStateV1 } from '../crowdy-agent/controller.js';
+import type { PlayerControlGate } from './control-gate.js';
+export interface AgentControlBannerController {
+    getState(): CrowdyStudioAgentStateV1;
+    subscribe(listener: (state: CrowdyStudioAgentStateV1) => void): () => void;
+}
+/**
+ * Always-visible-on-control safety surface outside the Studio dock. Text,
+ * status, Pause, and Stop remain keyboard/screen-reader accessible over the
+ * game canvas; Stop clears locally before any transport promise is attempted.
+ */
+export declare class AgentControlBanner {
+    private readonly gate;
+    readonly root: HTMLElement;
+    private readonly summary;
+    private readonly expiry;
+    private readonly pauseButton;
+    private readonly stopButton;
+    private controller;
+    private agentState;
+    private gateState;
+    private unsubscribeAgent;
+    private unsubscribeGate;
+    private readonly countdown;
+    constructor(parent: HTMLElement, gate: PlayerControlGate);
+    bind(controller: AgentControlBannerController): () => void;
+    showUnavailable(message: string): void;
+    unbind(): void;
+    destroy(): void;
+    private render;
+}
+export declare function ensureAgentControlBannerStyles(doc?: Document | null): void;
+/**
+ * Injected presentation for the visible lease safety surface. Games that
+ * dock a studio can set `--ck-game-right-inset` on `document.body` so the
+ * banner keeps clear of the dock (the Crowdy Studio embed kit does this
+ * automatically).
+ */
+export declare const AGENT_CONTROL_BANNER_STYLES = "\n.ck-agent-control-banner {\n  position: fixed;\n  top: 12px;\n  right: calc(12px + var(--ck-game-right-inset, 0px));\n  z-index: 65;\n  display: grid;\n  grid-template-columns: auto minmax(180px, 1fr) auto auto;\n  align-items: center;\n  gap: 10px;\n  max-width: min(760px, calc(100vw - var(--ck-game-right-inset, 0px) - 24px));\n  padding: 9px 10px;\n  border: 1px solid rgba(110, 231, 183, 0.65);\n  border-radius: 10px;\n  color: #ecfdf5;\n  background: rgba(2, 44, 34, 0.94);\n  box-shadow: 0 12px 30px rgba(2, 6, 23, 0.45);\n  pointer-events: auto;\n}\n\n.ck-agent-control-banner[hidden] {\n  display: none;\n}\n\n.ck-agent-control-banner[data-state=\"unavailable\"] {\n  border-color: rgba(251, 191, 36, 0.65);\n  background: rgba(69, 26, 3, 0.94);\n}\n\n.ck-agent-control-summary,\n.ck-agent-control-expiry {\n  overflow: hidden;\n  color: #d1fae5;\n  font-size: 12px;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n}\n\n.ck-agent-control-expiry {\n  color: #a7f3d0;\n}\n\n.ck-agent-control-actions {\n  display: flex;\n  gap: 6px;\n}\n\n.ck-agent-control-actions button {\n  padding: 6px 9px;\n  border: 1px solid rgba(167, 243, 208, 0.5);\n  border-radius: 7px;\n  color: #ecfdf5;\n  background: rgba(6, 78, 59, 0.85);\n  cursor: pointer;\n}\n\n.ck-agent-control-actions .ck-agent-control-stop {\n  border-color: rgba(254, 202, 202, 0.75);\n  background: rgba(153, 27, 27, 0.9);\n}\n\n.ck-agent-control-actions button:focus-visible {\n  outline: 2px solid #fef3c7;\n  outline-offset: 2px;\n}\n\n@media (max-width: 900px) {\n  .ck-agent-control-banner {\n    right: 8px;\n    left: 8px;\n    grid-template-columns: auto minmax(0, 1fr) auto;\n    max-width: none;\n  }\n\n  .ck-agent-control-expiry {\n    display: none;\n  }\n}\n\n@media (max-width: 620px) {\n  .ck-agent-control-banner {\n    grid-template-columns: minmax(0, 1fr) auto;\n  }\n\n  .ck-agent-control-banner > strong {\n    display: none;\n  }\n}\n";
+//# sourceMappingURL=control-banner.d.ts.map

package/dist/player-host/control-banner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-banner.d.ts","sourceRoot":"","sources":["../../src/player-host/control-banner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAC9E,OAAO,KAAK,EACV,iBAAiB,EAElB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,IAAI,wBAAwB,CAAC;IACrC,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC5E;AAED;;;;GAIG;AACH,qBAAa,kBAAkB;IAe3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IAdvB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,UAAU,CAA6C;IAC/D,OAAO,CAAC,UAAU,CAAyC;IAC3D,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;gBAGzD,MAAM,EAAE,WAAW,EACF,IAAI,EAAE,iBAAiB;IAqC1C,IAAI,CAAC,UAAU,EAAE,4BAA4B,GAAG,MAAM,IAAI;IAc1D,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAUtC,MAAM,IAAI,IAAI;IASd,OAAO,IAAI,IAAI;IAQf,OAAO,CAAC,MAAM;CAuDf;AA2BD,wBAAgB,8BAA8B,CAC5C,GAAG,GAAE,QAAQ,GAAG,IAAwD,GACvE,IAAI,CAMN;AAED;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,+4DAwFvC,CAAC"}

package/dist/player-host/control-banner.js

@@ -0,0 +1,252 @@
+/**
+ * Always-visible-on-control safety surface outside the Studio dock. Text,
+ * status, Pause, and Stop remain keyboard/screen-reader accessible over the
+ * game canvas; Stop clears locally before any transport promise is attempted.
+ */
+export class AgentControlBanner {
+    constructor(parent, gate) {
+        this.gate = gate;
+        this.controller = null;
+        this.agentState = null;
+        this.unsubscribeAgent = null;
+        this.unsubscribeGate = null;
+        ensureAgentControlBannerStyles(parent.ownerDocument);
+        const root = document.createElement('aside');
+        root.className = 'ck-agent-control-banner';
+        root.setAttribute('role', 'region');
+        root.setAttribute('aria-label', 'Agent player control');
+        root.hidden = true;
+        const title = document.createElement('strong');
+        title.textContent = 'Crowdy Agent';
+        this.summary = document.createElement('span');
+        this.summary.className = 'ck-agent-control-summary';
+        this.summary.setAttribute('role', 'status');
+        this.summary.setAttribute('aria-live', 'polite');
+        this.expiry = document.createElement('span');
+        this.expiry.className = 'ck-agent-control-expiry';
+        const controls = document.createElement('div');
+        controls.className = 'ck-agent-control-actions';
+        this.pauseButton = button('Pause agent');
+        this.pauseButton.addEventListener('click', () => this.gate.pause());
+        this.stopButton = button('Stop agent');
+        this.stopButton.className = 'ck-agent-control-stop';
+        this.stopButton.addEventListener('click', () => this.gate.stop());
+        controls.append(this.pauseButton, this.stopButton);
+        root.append(title, this.summary, this.expiry, controls);
+        parent.append(root);
+        this.root = root;
+        this.gateState = gate.snapshot();
+        this.unsubscribeGate = gate.subscribe((state) => {
+            this.gateState = state;
+            this.render();
+        });
+        this.countdown = setInterval(() => this.render(), 500);
+    }
+    bind(controller) {
+        this.unbind();
+        this.controller = controller;
+        this.agentState = controller.getState();
+        this.unsubscribeAgent = controller.subscribe((state) => {
+            this.agentState = state;
+            this.render();
+        });
+        this.render();
+        return () => {
+            if (this.controller === controller)
+                this.unbind();
+        };
+    }
+    showUnavailable(message) {
+        this.unbind();
+        this.root.hidden = false;
+        this.root.dataset.state = 'unavailable';
+        this.summary.textContent = `Agent unavailable · ${message.slice(0, 240)}`;
+        this.expiry.textContent = 'Gameplay remains under human control.';
+        this.pauseButton.disabled = true;
+        this.stopButton.disabled = false;
+    }
+    unbind() {
+        this.unsubscribeAgent?.();
+        this.unsubscribeAgent = null;
+        this.controller = null;
+        this.agentState = null;
+        this.root.hidden = true;
+        this.root.removeAttribute('data-state');
+    }
+    destroy() {
+        this.unbind();
+        this.unsubscribeGate?.();
+        this.unsubscribeGate = null;
+        clearInterval(this.countdown);
+        this.root.remove();
+    }
+    render() {
+        const state = this.agentState;
+        if (!state || !this.controller)
+            return;
+        this.gateState = this.gate.snapshot();
+        const lease = activePlayLease(state.leases, this.gateState.activeLease, this.gateState.bound);
+        const mode = state.session?.mode ?? 'ASK';
+        const unavailable = state.connection === 'ERROR' ||
+            (state.lastError !== null && state.connection !== 'CONNECTED');
+        this.root.hidden =
+            !unavailable &&
+                !lease &&
+                mode !== 'PLAY' &&
+                state.connection === 'DISCONNECTED';
+        this.root.dataset.state = unavailable
+            ? 'unavailable'
+            : lease
+                ? 'active'
+                : 'idle';
+        this.summary.textContent = unavailable
+            ? `Agent disabled · ${state.lastError?.code ?? 'backend unavailable'}`
+            : [
+                `Mode ${mode}`,
+                lease
+                    ? `entity ${lease.controlledEntityId ?? 'unknown'}`
+                    : 'human control',
+                lease
+                    ? `scopes ${lease.scopes.join(', ') || 'none'}`
+                    : 'no Play lease',
+            ].join(' · ');
+        if (lease) {
+            const remaining = Math.max(0, Math.ceil((Date.parse(lease.expiresAt) - Date.now()) / 1000));
+            this.expiry.textContent = `Control expires in ${remaining} seconds`;
+        }
+        else if (this.gateState.offlineStop) {
+            this.expiry.textContent =
+                'Stopped locally; server acknowledgement is not required.';
+        }
+        else if (state.reconnectRequired) {
+            this.expiry.textContent =
+                'Explicit resume and a new Play lease are required.';
+        }
+        else {
+            this.expiry.textContent = state.connection
+                .toLowerCase()
+                .replace(/_/gu, ' ');
+        }
+        this.pauseButton.disabled = !lease && state.session?.status !== 'ACTIVE';
+        // Stop is a local safety action and intentionally never disabled.
+        this.stopButton.disabled = false;
+    }
+}
+function activePlayLease(leases, localLease, gateBound) {
+    if (localLease?.kind === 'PLAY' && localLease.status === 'ACTIVE') {
+        return localLease;
+    }
+    if (gateBound)
+        return null;
+    return (leases.find((lease) => lease.kind === 'PLAY' && lease.status === 'ACTIVE') ?? null);
+}
+function button(label) {
+    const control = document.createElement('button');
+    control.type = 'button';
+    control.textContent = label;
+    return control;
+}
+const STYLE_ELEMENT_ID = 'ck-agent-control-banner-styles';
+export function ensureAgentControlBannerStyles(doc = typeof document === 'undefined' ? null : document) {
+    if (!doc || doc.getElementById(STYLE_ELEMENT_ID))
+        return;
+    const style = doc.createElement('style');
+    style.id = STYLE_ELEMENT_ID;
+    style.textContent = AGENT_CONTROL_BANNER_STYLES;
+    doc.head.appendChild(style);
+}
+/**
+ * Injected presentation for the visible lease safety surface. Games that
+ * dock a studio can set `--ck-game-right-inset` on `document.body` so the
+ * banner keeps clear of the dock (the Crowdy Studio embed kit does this
+ * automatically).
+ */
+export const AGENT_CONTROL_BANNER_STYLES = `
+.ck-agent-control-banner {
+  position: fixed;
+  top: 12px;
+  right: calc(12px + var(--ck-game-right-inset, 0px));
+  z-index: 65;
+  display: grid;
+  grid-template-columns: auto minmax(180px, 1fr) auto auto;
+  align-items: center;
+  gap: 10px;
+  max-width: min(760px, calc(100vw - var(--ck-game-right-inset, 0px) - 24px));
+  padding: 9px 10px;
+  border: 1px solid rgba(110, 231, 183, 0.65);
+  border-radius: 10px;
+  color: #ecfdf5;
+  background: rgba(2, 44, 34, 0.94);
+  box-shadow: 0 12px 30px rgba(2, 6, 23, 0.45);
+  pointer-events: auto;
+}
+
+.ck-agent-control-banner[hidden] {
+  display: none;
+}
+
+.ck-agent-control-banner[data-state="unavailable"] {
+  border-color: rgba(251, 191, 36, 0.65);
+  background: rgba(69, 26, 3, 0.94);
+}
+
+.ck-agent-control-summary,
+.ck-agent-control-expiry {
+  overflow: hidden;
+  color: #d1fae5;
+  font-size: 12px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.ck-agent-control-expiry {
+  color: #a7f3d0;
+}
+
+.ck-agent-control-actions {
+  display: flex;
+  gap: 6px;
+}
+
+.ck-agent-control-actions button {
+  padding: 6px 9px;
+  border: 1px solid rgba(167, 243, 208, 0.5);
+  border-radius: 7px;
+  color: #ecfdf5;
+  background: rgba(6, 78, 59, 0.85);
+  cursor: pointer;
+}
+
+.ck-agent-control-actions .ck-agent-control-stop {
+  border-color: rgba(254, 202, 202, 0.75);
+  background: rgba(153, 27, 27, 0.9);
+}
+
+.ck-agent-control-actions button:focus-visible {
+  outline: 2px solid #fef3c7;
+  outline-offset: 2px;
+}
+
+@media (max-width: 900px) {
+  .ck-agent-control-banner {
+    right: 8px;
+    left: 8px;
+    grid-template-columns: auto minmax(0, 1fr) auto;
+    max-width: none;
+  }
+
+  .ck-agent-control-expiry {
+    display: none;
+  }
+}
+
+@media (max-width: 620px) {
+  .ck-agent-control-banner {
+    grid-template-columns: minmax(0, 1fr) auto;
+  }
+
+  .ck-agent-control-banner > strong {
+    display: none;
+  }
+}
+`;

package/dist/player-host/control-gate.d.ts

@@ -0,0 +1,77 @@
+import type { CrowdyAgentLeaseV1, CrowdyAgentPreemptionReason } from '../crowdy-agent/types.js';
+import type { AgentControlLeaseManager } from './lease-manager.js';
+/**
+ * The slice of the studio agent controller the gate needs to observe and
+ * revoke leases. `CrowdyStudioAgentController` satisfies this structurally.
+ */
+export interface PlayerControlGateAgentControl {
+    getState(): {
+        readonly leases: readonly CrowdyAgentLeaseV1[];
+    };
+    revokeLease(leaseId: string, reason?: CrowdyAgentPreemptionReason): Promise<void>;
+    pause(): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface PlayerControlGateSnapshot {
+    readonly bound: boolean;
+    readonly activeLease: CrowdyAgentLeaseV1 | null;
+    readonly lastPreemption?: CrowdyAgentPreemptionReason;
+    readonly humanInputActive: boolean;
+    readonly offlineStop: boolean;
+}
+export interface PlayerControlGateOptions {
+    readonly window?: Window;
+    readonly document?: Document;
+    readonly now?: () => number;
+    readonly humanInputActiveMs?: number;
+    readonly onPreempt?: (reason: CrowdyAgentPreemptionReason) => void;
+}
+/**
+ * The game's synchronous takeover seam around CrowdyJS's lease manager.
+ * Capture listeners revoke before the game's own gameplay listeners run, but
+ * never cancel or synthesize the human event. Offline Stop stays effective
+ * with no GraphQL connection.
+ */
+export declare class PlayerControlGate {
+    private readonly clearAgentIntent;
+    private readonly options;
+    private readonly windowValue;
+    private readonly documentValue;
+    private readonly now;
+    private readonly listeners;
+    private leaseManager;
+    private controller;
+    private readonly locallyRevokedLeaseIds;
+    private started;
+    private lastHumanInputAt;
+    private lastPreemption?;
+    private offlineStop;
+    constructor(clearAgentIntent: (reason: CrowdyAgentPreemptionReason) => void, options?: PlayerControlGateOptions);
+    start(): void;
+    destroy(): void;
+    bind(leaseManager: AgentControlLeaseManager, controller: PlayerControlGateAgentControl): () => void;
+    subscribe(listener: (snapshot: PlayerControlGateSnapshot) => void): () => void;
+    snapshot(): PlayerControlGateSnapshot;
+    humanInputActive(): boolean;
+    preempt(reason: CrowdyAgentPreemptionReason, notifyServer?: boolean): void;
+    /** Immediate local Pause; remote persistence is best effort. */
+    pause(): void;
+    /** Immediate local Stop remains effective with no GraphQL connection. */
+    stop(): void;
+    death(): void;
+    contextChanged(): void;
+    permissionChanged(): void;
+    controlTargetChanged(): void;
+    disconnected(): void;
+    private activeLease;
+    private unbind;
+    private takeHumanInput;
+    private readonly keyboardInput;
+    private readonly pointerInput;
+    private readonly mouseMove;
+    private readonly pageHide;
+    private readonly offline;
+    private readonly visibilityChange;
+    private emit;
+}
+//# sourceMappingURL=control-gate.d.ts.map

package/dist/player-host/control-gate.d.ts.map

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

package/dist/player-host/control-gate.js

@@ -0,0 +1,197 @@
+/**
+ * The game's synchronous takeover seam around CrowdyJS's lease manager.
+ * Capture listeners revoke before the game's own gameplay listeners run, but
+ * never cancel or synthesize the human event. Offline Stop stays effective
+ * with no GraphQL connection.
+ */
+export class PlayerControlGate {
+    constructor(clearAgentIntent, options = {}) {
+        this.clearAgentIntent = clearAgentIntent;
+        this.options = options;
+        this.listeners = new Set();
+        this.leaseManager = null;
+        this.controller = null;
+        this.locallyRevokedLeaseIds = new Set();
+        this.started = false;
+        this.lastHumanInputAt = Number.NEGATIVE_INFINITY;
+        this.offlineStop = false;
+        this.keyboardInput = (event) => {
+            this.takeHumanInput(event.code === 'Escape' ? 'ESCAPE' : 'HUMAN_INPUT');
+        };
+        this.pointerInput = () => {
+            this.takeHumanInput('HUMAN_INPUT');
+        };
+        this.mouseMove = (event) => {
+            if (event.movementX !== 0 || event.movementY !== 0 || event.buttons !== 0) {
+                this.takeHumanInput('HUMAN_INPUT');
+            }
+        };
+        this.pageHide = () => {
+            this.disconnected();
+        };
+        this.offline = () => {
+            this.disconnected();
+        };
+        this.visibilityChange = () => {
+            if (this.documentValue?.visibilityState === 'hidden')
+                this.disconnected();
+        };
+        this.windowValue =
+            options.window ?? (typeof window === 'undefined' ? null : window);
+        this.documentValue =
+            options.document ?? (typeof document === 'undefined' ? null : document);
+        this.now = options.now ?? Date.now;
+    }
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        const win = this.windowValue;
+        const doc = this.documentValue;
+        win?.addEventListener('keydown', this.keyboardInput, true);
+        win?.addEventListener('mousedown', this.pointerInput, true);
+        win?.addEventListener('pointerdown', this.pointerInput, true);
+        win?.addEventListener('mousemove', this.mouseMove, true);
+        win?.addEventListener('wheel', this.pointerInput, true);
+        win?.addEventListener('touchstart', this.pointerInput, true);
+        win?.addEventListener('pagehide', this.pageHide, true);
+        win?.addEventListener('offline', this.offline, true);
+        doc?.addEventListener('visibilitychange', this.visibilityChange, true);
+    }
+    destroy() {
+        if (this.started) {
+            this.started = false;
+            const win = this.windowValue;
+            const doc = this.documentValue;
+            win?.removeEventListener('keydown', this.keyboardInput, true);
+            win?.removeEventListener('mousedown', this.pointerInput, true);
+            win?.removeEventListener('pointerdown', this.pointerInput, true);
+            win?.removeEventListener('mousemove', this.mouseMove, true);
+            win?.removeEventListener('wheel', this.pointerInput, true);
+            win?.removeEventListener('touchstart', this.pointerInput, true);
+            win?.removeEventListener('pagehide', this.pageHide, true);
+            win?.removeEventListener('offline', this.offline, true);
+            doc?.removeEventListener('visibilitychange', this.visibilityChange, true);
+        }
+        this.preempt('DISCONNECTED', false);
+        this.unbind();
+        this.listeners.clear();
+    }
+    bind(leaseManager, controller) {
+        if (this.leaseManager &&
+            (this.leaseManager !== leaseManager || this.controller !== controller)) {
+            this.preempt('CLIENT_REATTACHED', false);
+        }
+        this.leaseManager = leaseManager;
+        this.controller = controller;
+        this.offlineStop = false;
+        this.emit();
+        return () => {
+            if (this.leaseManager === leaseManager &&
+                this.controller === controller) {
+                this.preempt('DISCONNECTED', false);
+                this.unbind();
+            }
+        };
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        listener(this.snapshot());
+        return () => this.listeners.delete(listener);
+    }
+    snapshot() {
+        return {
+            bound: Boolean(this.leaseManager && this.controller),
+            activeLease: this.activeLease(),
+            ...(this.lastPreemption ? { lastPreemption: this.lastPreemption } : {}),
+            humanInputActive: this.humanInputActive(),
+            offlineStop: this.offlineStop,
+        };
+    }
+    humanInputActive() {
+        return (this.now() - this.lastHumanInputAt <
+            (this.options.humanInputActiveMs ?? 150));
+    }
+    preempt(reason, notifyServer = true) {
+        const lease = this.activeLease();
+        if (lease)
+            this.locallyRevokedLeaseIds.add(lease.leaseId);
+        try {
+            if (this.leaseManager)
+                this.leaseManager.preempt(reason);
+            else
+                this.clearAgentIntent(reason);
+        }
+        catch {
+            // CrowdyJS still clears the lease in its own finally block. A host
+            // cleanup bug must not interrupt the human event or offline Stop.
+        }
+        finally {
+            this.lastPreemption = reason;
+            this.options.onPreempt?.(reason);
+            this.emit();
+        }
+        if (notifyServer && lease && this.controller) {
+            void this.controller
+                .revokeLease(lease.leaseId, reason)
+                .catch(() => undefined);
+        }
+    }
+    /** Immediate local Pause; remote persistence is best effort. */
+    pause() {
+        this.preempt('HUMAN_STOP', false);
+        void this.controller?.pause().catch(() => undefined);
+    }
+    /** Immediate local Stop remains effective with no GraphQL connection. */
+    stop() {
+        this.offlineStop = true;
+        this.preempt('HUMAN_STOP', false);
+        void this.controller?.stop().catch(() => undefined);
+        this.emit();
+    }
+    death() {
+        this.preempt('DEATH');
+    }
+    contextChanged() {
+        this.preempt('CONTEXT_CHANGED');
+    }
+    permissionChanged() {
+        this.preempt('PERMISSION_CHANGED');
+    }
+    controlTargetChanged() {
+        this.preempt('CONTROL_TARGET_CHANGED');
+    }
+    disconnected() {
+        this.preempt('DISCONNECTED', false);
+    }
+    activeLease() {
+        const local = this.leaseManager?.snapshot().lease;
+        if (local?.status === 'ACTIVE' &&
+            !this.locallyRevokedLeaseIds.has(local.leaseId)) {
+            return local;
+        }
+        return (this.controller
+            ?.getState()
+            .leases.find((lease) => lease.kind === 'PLAY' &&
+            lease.status === 'ACTIVE' &&
+            !this.locallyRevokedLeaseIds.has(lease.leaseId)) ?? null);
+    }
+    unbind() {
+        this.leaseManager = null;
+        this.controller = null;
+        this.locallyRevokedLeaseIds.clear();
+        this.emit();
+    }
+    takeHumanInput(reason) {
+        this.lastHumanInputAt = this.now();
+        if (this.activeLease())
+            this.preempt(reason);
+        else
+            this.emit();
+    }
+    emit() {
+        const snapshot = this.snapshot();
+        for (const listener of [...this.listeners])
+            listener(snapshot);
+    }
+}

package/dist/player-host/index.d.ts

@@ -1,5 +1,7 @@
 export { AgentControlLeaseManager, type AgentControlDispatchV1, type AgentControlLeaseManagerOptionsV1, type AgentControlLeaseSnapshotV1, type AgentObservationDispatchV1, } from './lease-manager.js';
 export { GAME_COMMAND_RESULT_SCHEMA_V1, GAME_COMMAND_SCHEMAS_V1, GAME_COMMAND_SCHEMA_V1, GAME_OBSERVATION_SCHEMA_V1, OBSERVE_REQUEST_SCHEMA_V1, PLAYER_HOST_CAPABILITIES_SCHEMA_V1, } from './schemas.js';
 export { createPlayerHostAgentTools, type PlayerHostAgentToolsV1, } from './tools.js';
+export { PlayerControlGate, type PlayerControlGateAgentControl, type PlayerControlGateOptions, type PlayerControlGateSnapshot, } from './control-gate.js';
+export { AGENT_CONTROL_BANNER_STYLES, AgentControlBanner, ensureAgentControlBannerStyles, type AgentControlBannerController, } from './control-banner.js';
 export type { GameChatSendCommandV1, GameCombatAttackCommandV1, GameCommandResultV1, GameCommandV1, GameCraftCommandV1, GameInteractCommandV1, GameInventoryConsumeCommandV1, GameInventorySelectCommandV1, GameInventoryTransferCommandV1, GameLookCommandV1, GameMountCommandV1, GameMoveCommandV1, GameObservationActorV1, GameObservationInventoryV1, GameObservationV1, GameStopCommandV1, GameTravelTeleportCommandV1, ObserveRequestV1, PlayerHostAdapterV1, PlayerHostCapabilitiesV1, PlayerHostCommandCapabilityV1, PlayerHostCommandKind, PlayerHostLeaseScope, PlayerHostLookV1, PlayerHostVector3V1, ValidatedGateV1, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/player-host/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/player-host/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,iCAAiC,EACtC,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,GAChC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,6BAA6B,EAC7B,uBAAuB,EACvB,sBAAsB,EACtB,0BAA0B,EAC1B,yBAAyB,EACzB,kCAAkC,GACnC,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,0BAA0B,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,qBAAqB,EACrB,yBAAyB,EACzB,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EAClB,qBAAqB,EACrB,6BAA6B,EAC7B,4BAA4B,EAC5B,8BAA8B,EAC9B,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,0BAA0B,EAC1B,iBAAiB,EACjB,iBAAiB,EACjB,2BAA2B,EAC3B,gBAAgB,EAChB,mBAAmB,EACnB,wBAAwB,EACxB,6BAA6B,EAC7B,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,GAChB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/player-host/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,iCAAiC,EACtC,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,GAChC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,6BAA6B,EAC7B,uBAAuB,EACvB,sBAAsB,EACtB,0BAA0B,EAC1B,yBAAyB,EACzB,kCAAkC,GACnC,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,0BAA0B,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,KAAK,6BAA6B,EAClC,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,8BAA8B,EAC9B,KAAK,4BAA4B,GAClC,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,qBAAqB,EACrB,yBAAyB,EACzB,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EAClB,qBAAqB,EACrB,6BAA6B,EAC7B,4BAA4B,EAC5B,8BAA8B,EAC9B,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,0BAA0B,EAC1B,iBAAiB,EACjB,iBAAiB,EACjB,2BAA2B,EAC3B,gBAAgB,EAChB,mBAAmB,EACnB,wBAAwB,EACxB,6BAA6B,EAC7B,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,GAChB,MAAM,YAAY,CAAC"}

package/dist/player-host/index.js

@@ -1,3 +1,5 @@
 export { AgentControlLeaseManager, } from './lease-manager.js';
 export { GAME_COMMAND_RESULT_SCHEMA_V1, GAME_COMMAND_SCHEMAS_V1, GAME_COMMAND_SCHEMA_V1, GAME_OBSERVATION_SCHEMA_V1, OBSERVE_REQUEST_SCHEMA_V1, PLAYER_HOST_CAPABILITIES_SCHEMA_V1, } from './schemas.js';
 export { createPlayerHostAgentTools, } from './tools.js';
+export { PlayerControlGate, } from './control-gate.js';
+export { AGENT_CONTROL_BANNER_STYLES, AgentControlBanner, ensureAgentControlBannerStyles, } from './control-banner.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowdedkingdoms/crowdyjs",
-  "version": "12.0.0",
+  "version": "12.1.0",
   "description": "Browser-first Crowded Kingdoms SDK with GraphQL, realtime, and local Rust authoring support",
   "type": "module",
   "main": "dist/index.js",
@@ -29,6 +29,10 @@
     "./player-host": {
       "import": "./dist/player-host/index.js",
       "types": "./dist/player-host/index.d.ts"
+    },
+    "./player-glue-worker": {
+      "import": "./dist/player-runtime/player-glue-worker.js",
+      "types": "./dist/player-runtime/player-glue-worker.d.ts"
     }
   },
   "sideEffects": false,
@@ -88,6 +92,7 @@
     "@graphql-codegen/typescript-operations": "^5.1.0",
     "@graphql-tools/merge": "^9.1.10",
     "@types/node": "^22.10.7",
+    "happy-dom": "^20.11.1",
     "typescript": "^5.7.3",
     "ws": "^8.21.1"
   },