@crowdedkingdoms/crowdyjs 12.0.0 → 12.2.0

package/MIGRATION.md

@@ -1,3 +1,48 @@
+# CrowdyJS v12.1 — Crowdy Studio embed kit (additive)
+
+Version 12.1 ships the reusable game-embed chrome that previously lived only
+in Blocks with Friends. Nothing breaks; games that already hand-roll a shell
+can adopt incrementally.
+
+New from `@crowdedkingdoms/crowdyjs/crowdy-studio`:
+
+- `createCrowdyStudioEmbed(options)` / `CrowdyStudioEmbed` — responsive
+  dock/fullscreen panel with focus trap, Escape/close-key semantics, compact
+  header, on-demand Context drawer (grid bounds, permission cards, optional
+  HUD preview), loading/error/retry chrome, and assembly of the full
+  `mountCrowdyStudio` call (agent block included when the client exposes
+  `crowdyStudioAgent` and the game passes `playerHost`).
+- `CrowdyStudioEmbedDock` — accessible game/studio splitter with persisted
+  width under `ck:crowdy-studio:embed:dock-width:v1`.
+- `CrowdyStudioTextHud` — text-only presentation sink for CLIENT-mod
+  `hud_set` payloads plus the drawer preview mount.
+- `CROWDY_STUDIO_EMBED_STYLES` / `ensureCrowdyStudioEmbedStyles()` — injected
+  `ck-crowdy-studio-embed-*` styling; the docked panel sets
+  `--ck-game-right-inset` on `document.body` for game HUD insets.
+
+New from `@crowdedkingdoms/crowdyjs/player-host`:
+
+- `PlayerControlGate` — the synchronous human-takeover seam (capture-phase
+  keyboard/pointer preemption, offline Stop, page-hide/visibility handling),
+  parameterized on a `clearAgentIntent` hook.
+- `AgentControlBanner` — the always-visible-on-control Pause/Stop safety
+  region with self-injected `ck-agent-control-*` styles.
+
+New package subpath:
+
+- `@crowdedkingdoms/crowdyjs/player-glue-worker` — the self-starting tokenless
+  CLIENT-mod glue worker entry. Bundle it as a same-origin module worker (for
+  example Vite's `?worker&url`) instead of copying a worker wrapper into the
+  game.
+
+Migrating from the Blocks with Friends copies: `CrowdyStudioPanel` →
+`CrowdyStudioEmbed`, `CrowdyStudioDock` → `CrowdyStudioEmbedDock`,
+`ModHudLayer` → `CrowdyStudioTextHud`, `bwf-crowdy-studio-*` CSS →
+`ck-crowdy-studio-embed-*`, `bwf-agent-control-*` → `ck-agent-control-*`,
+`--bwf-game-right-inset` → `--ck-game-right-inset`. The persisted dock width
+key changes from `bwf:crowdy-studio:dock-width:v1` to the `ck:` key above
+(previous widths reset once).
+
 # CrowdyJS v12 — Agentic Crowdy Studio contract (BREAKING)
 
 Version 12 establishes the greenfield public contracts

package/README.md

@@ -39,6 +39,16 @@ CrowdyJS v4 targets browsers by default and uses native `fetch`, `WebSocket`, `c
 > `marketplace.claimGridChunk` / `marketplace.releaseClaimedGrid` require the
 > corresponding 2026-07-22 Game API claim schema. Older servers reject only
 > those operations during GraphQL validation.
+>
+> **App-scoped player-count compatibility:** `gameModel.activePlayerCount(appId)`
+> and `gameModel.activePlayerCountChanged({ appId }, handlers)` require the
+> matching 2026-07-24 Game API schema and an app token scoped to that exact app;
+> the subscription also requires `wsUrl`. They count active gameplay sessions,
+> not distinct users or actors, and an abandoned session can remain counted for
+> approximately 120 seconds. Only `FRESH` snapshots are complete:
+> `PARTIAL`/`UNAVAILABLE` are not authoritative zeroes. The subscription is
+> best-effort and has no initial event; establish it, query the snapshot,
+> deduplicate by `revision`, and requery after reconnects or revision gaps.
 
 > **v8.21.1 Node realtime routing hotfix:** app-routing responses provide a
 > WebSocket base URL. CrowdyJS now normalizes that base to `/graphql` before
@@ -155,7 +165,7 @@ If `managementUrl` is omitted, the SDK falls back to `httpUrl` for backwards-com
 | `client.host` | Game-host election (`get`, `amIHost`) + actor liveness `heartbeat`. `amIHost` is UI convenience only — authoritative host gating uses `gameModelInvoke`'s `is_host` policy. |
 | `client.teleport` | Teleport requests. |
 | `client.channels`, `client.teams` | Messaging channels and app-scoped player teams (membership + roles). |
-| `client.gameModel` | Abstract game model: containers, properties, functions (incl. model-driven `notify_*` effects), sessions, and **automations / NPCs** (`upsertAutomation`, `runAutomation`, `automationRuns`, `automationStats`, …). |
+| `client.gameModel` | Abstract game model: containers, properties, functions (incl. model-driven `notify_*` effects), sessions, **app-scoped active-session counts** (`activePlayerCount`, `activePlayerCountChanged`), and **automations / NPCs** (`upsertAutomation`, `runAutomation`, `automationRuns`, `automationStats`, …). |
 | `client.compute` | **Compute Modules** — server-side Rust/WASM logic: author + deploy source (`upsertModule`, `deployVersion`, `waitForCompile`), triggers + policy, synchronous `invoke`, and monitoring (`moduleRuns`, `moduleStats`, `moduleLogs`, `appDiagnostics`). Modules run server-only; see [Compute Modules docs](https://docs.crowdedkingdoms.com/game-api/compute-modules). |
 | `client.playerCompute` | Player-authored SERVER/CLIENT Rust/WASM bound to player-owned grids: deploy source, activate/deactivate, list modules/versions, and delete self-authored modules. |
 | `client.crowdyStudio` | Cloud project, personal-library, and common-file APIs for Crowdy Studio: target-scoped files, metadata/module names, pairing preference, optimistic revisions, copy-by-value imports, and atomic metadata/file saves. Generated operations are pinned to the committed merged SDL. |
@@ -244,6 +254,65 @@ embedded index remains the byte-identical game export (`schemaVersion: 2`, Rust
 1.97.1, SDK 0.1.5, ABI 0, 725 symbols, content hash
 `3f5f39d4…18ffb`).
 
+### Embed Crowdy Studio in your game (v12.1)
+
+Most games should not hand-roll the window chrome around `mountCrowdyStudio`.
+The embed kit ships the proven Blocks with Friends shell as reusable, game
+-agnostic components (exported from `@crowdedkingdoms/crowdyjs/crowdy-studio`):
+
+- **`createCrowdyStudioEmbed(options)` / `CrowdyStudioEmbed`** — a responsive
+  panel that renders a resizable right dock on desktop and a focus-trapped
+  fullscreen modal below 1000 px. It owns Escape/close-key semantics, the
+  compact header (title, grid pill, on-demand Context drawer, Close), loading
+  and retry chrome, and assembles the `mountCrowdyStudio` call — including the
+  agent block when the client exposes `crowdyStudioAgent` and the game passes a
+  `playerHost`.
+- **`CrowdyStudioEmbedDock`** — the accessible game/studio splitter with
+  persisted width (`ck:crowdy-studio:embed:dock-width:v1`), arrow-key/Home/End
+  resize, and ARIA value text.
+- **`CrowdyStudioTextHud`** — the text-only presentation sink for CLIENT-mod
+  `hud_set` payloads plus the drawer HUD preview. Untrusted payloads render as
+  text, never HTML.
+- **`ensureCrowdyStudioEmbedStyles()`** — injected `ck-crowdy-studio-embed-*`
+  styles; games restyle by overriding classes. While docked, the panel sets
+  `--ck-game-right-inset` on `document.body` so game HUDs can keep clear of
+  the dock.
+
+```ts
+import { createCrowdyStudioEmbed } from '@crowdedkingdoms/crowdyjs/crowdy-studio';
+// Self-starting glue worker for CLIENT mods (Vite shown; any bundler that
+// packages module workers works):
+import workerUrl from '@crowdedkingdoms/crowdyjs/player-glue-worker?worker&url';
+
+const studio = createCrowdyStudioEmbed({
+  client: game, // CrowdyClient: crowdyStudio, playerCompute, playerWallet, crowdyStudioAgent
+  appId,
+  gameName: 'My Game',
+  suppressGameplayInput: () => pauseInput(),
+  onLayoutChange: () => resizeCanvas(),
+});
+
+// Per open (for example after the player claims a grid):
+studio.toggle({
+  gridId,
+  targetPermissions: {
+    SERVER: { canWrite: true, canRun: true },
+    CLIENT: { canWrite: false, canRun: false }, // SERVER-only embeds omit workerUrl
+  },
+});
+```
+
+CLIENT-mod embeds additionally pass `grid`, `workerUrl`, `onHostCall`, an
+optional `hud` sink, and a `playerHost` adapter. Note that CLIENT mods outside
+Blocks with Friends remain gated by program decision D13; new games should
+start SERVER-only exactly as above.
+
+The visible agent safety chrome is exported from
+`@crowdedkingdoms/crowdyjs/player-host`: **`PlayerControlGate`** (capture-phase
+human preemption seam with offline Stop) and **`AgentControlBanner`** (the
+always-visible-on-control Pause/Stop region, self-injected
+`ck-agent-control-*` styles).
+
 ### Game API project contract
 
 `CrowdyStudioAPI` implements the transport-neutral

package/dist/crowdy-studio/agent-dom-shell.d.ts

@@ -1,11 +1,25 @@
 import { type CrowdyStudioAgentController, type CrowdyStudioAgentStateV1 } from '../crowdy-agent/controller.js';
+import type { StudioLayoutController } from './layout.js';
 export interface CrowdyStudioAgentDomShellOptions {
     getPlayLeaseContext?: () => {
         controlledEntityId: string;
         hostCapabilityRevision: string;
     } | null;
+    /**
+     * Optional studio layout controller. When present the dock participates in
+     * the shared pane layout and auto-reveals itself for safety-critical
+     * moments (pending exact approvals, an activating Play lease).
+     */
+    layout?: StudioLayoutController;
 }
-/** Accessible, text-only rendering for the integrated durable agent dock. */
+/**
+ * Accessible, text-only rendering for the integrated durable agent dock.
+ *
+ * The conversation is the primary surface. Play-control, activity, and
+ * change-tracking sections are collapsible disclosures so the dock stays
+ * minimal, with one deliberate exception: pending exact approvals and the
+ * active Play lease countdown always render prominently.
+ */
 export declare class CrowdyStudioAgentDomShell {
     private readonly controller;
     private readonly options;
@@ -20,15 +34,29 @@ export declare class CrowdyStudioAgentDomShell {
     private readonly checkpoints;
     private readonly composer;
     private readonly send;
+    private readonly playDisclosure;
+    private readonly playSummary;
+    private readonly activityDisclosure;
+    private readonly activitySummary;
+    private readonly changesDisclosure;
+    private readonly changesSummary;
     private readonly modeButtons;
     private readonly scopeInputs;
     private readonly unsubscribe;
     private readonly countdownTimer;
     private lastState;
+    private lastPendingApprovals;
+    private lastPlayLeaseActive;
     private disposed;
     constructor(host: HTMLElement, controller: CrowdyStudioAgentController, options?: CrowdyStudioAgentDomShellOptions);
     render(state: CrowdyStudioAgentStateV1): void;
     dispose(): void;
+    /**
+     * Safety-critical auto-reveal: a newly pending exact approval or a Play
+     * lease activation opens the dock and the Play disclosure so the human is
+     * always shown what needs their decision or is acting on their behalf.
+     */
+    private autoReveal;
     private renderBudget;
     private renderLease;
     private renderMessages;

package/dist/crowdy-studio/agent-dom-shell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-dom-shell.d.ts","sourceRoot":"","sources":["../../src/crowdy-studio/agent-dom-shell.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC9B,MAAM,+BAA+B,CAAC;AAavC,MAAM,WAAW,gCAAgC;IAC/C,mBAAmB,CAAC,EAAE,MAAM;QAC1B,kBAAkB,EAAE,MAAM,CAAC;QAC3B,sBAAsB,EAAE,MAAM,CAAC;KAChC,GAAG,IAAI,CAAC;CACV;AAED,6EAA6E;AAC7E,qBAAa,yBAAyB;IAqBlC,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IArB1B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiD;IAC7E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuC;IACnE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiC;IAChE,OAAO,CAAC,SAAS,CAA2B;IAC5C,OAAO,CAAC,QAAQ,CAAS;gBAGvB,IAAI,EAAE,WAAW,EACA,UAAU,EAAE,2BAA2B,EACvC,OAAO,GAAE,gCAAqC;IAkKjE,MAAM,CAAC,KAAK,EAAE,wBAAwB,GAAG,IAAI;IAyB7C,OAAO,IAAI,IAAI;IAQf,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,WAAW;IAoBnB,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,cAAc;IA4DtB,OAAO,CAAC,eAAe;IA+CvB,OAAO,CAAC,iBAAiB;YAkCX,GAAG;CAQlB"}
+{"version":3,"file":"agent-dom-shell.d.ts","sourceRoot":"","sources":["../../src/crowdy-studio/agent-dom-shell.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC9B,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAY1D,MAAM,WAAW,gCAAgC;IAC/C,mBAAmB,CAAC,EAAE,MAAM;QAC1B,kBAAkB,EAAE,MAAM,CAAC;QAC3B,sBAAsB,EAAE,MAAM,CAAC;KAChC,GAAG,IAAI,CAAC;IACT;;;;OAIG;IACH,MAAM,CAAC,EAAE,sBAAsB,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,qBAAa,yBAAyB;IA6BlC,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IA7B1B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAc;IAC9C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqB;IACvD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAc;IAC7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiD;IAC7E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuC;IACnE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiC;IAChE,OAAO,CAAC,SAAS,CAA2B;IAC5C,OAAO,CAAC,oBAAoB,CAAK;IACjC,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAS;gBAGvB,IAAI,EAAE,WAAW,EACA,UAAU,EAAE,2BAA2B,EACvC,OAAO,GAAE,gCAAqC;IAmLjE,MAAM,CAAC,KAAK,EAAE,wBAAwB,GAAG,IAAI;IA0B7C,OAAO,IAAI,IAAI;IAQf;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAqBlB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,WAAW;IAwBnB,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,cAAc;IA8DtB,OAAO,CAAC,eAAe;IAgDvB,OAAO,CAAC,iBAAiB;YA0CX,GAAG;CAQlB"}

package/dist/crowdy-studio/agent-dom-shell.js

@@ -7,13 +7,22 @@ const PLAY_SCOPES = [
     'communicate',
     'travel',
 ];
-/** Accessible, text-only rendering for the integrated durable agent dock. */
+/**
+ * Accessible, text-only rendering for the integrated durable agent dock.
+ *
+ * The conversation is the primary surface. Play-control, activity, and
+ * change-tracking sections are collapsible disclosures so the dock stays
+ * minimal, with one deliberate exception: pending exact approvals and the
+ * active Play lease countdown always render prominently.
+ */
 export class CrowdyStudioAgentDomShell {
     constructor(host, controller, options = {}) {
         this.controller = controller;
         this.options = options;
         this.modeButtons = new Map();
         this.scopeInputs = new Map();
+        this.lastPendingApprovals = 0;
+        this.lastPlayLeaseActive = false;
         this.disposed = false;
         this.lastState = controller.getState();
         this.root = document.createElement('aside');
@@ -27,6 +36,8 @@ export class CrowdyStudioAgentDomShell {
         this.status.setAttribute('role', 'status');
         this.status.setAttribute('aria-live', 'polite');
         header.append(title, this.status);
+        const controlsRow = document.createElement('div');
+        controlsRow.className = 'ck-crowdy-studio-agent-controls-row';
         const modeGroup = document.createElement('div');
         modeGroup.className = 'ck-crowdy-studio-agent-modes';
         modeGroup.setAttribute('role', 'group');
@@ -50,13 +61,52 @@ export class CrowdyStudioAgentDomShell {
         stop.className = 'ck-crowdy-studio-agent-stop';
         stop.addEventListener('click', () => void this.run(() => this.controller.stop()));
         controls.append(pause, resume, stop);
-        this.budget = document.createElement('div');
-        this.budget.className = 'ck-crowdy-studio-agent-budget';
-        this.budget.setAttribute('aria-label', 'Agent budget');
+        controlsRow.append(modeGroup, controls);
+        // Safety surfaces: approvals and the active Play lease stay prominent and
+        // are never hidden behind a disclosure.
+        this.approvals = document.createElement('section');
+        this.approvals.className = 'ck-crowdy-studio-agent-approvals';
+        this.approvals.setAttribute('aria-label', 'Pending exact approvals');
         this.lease = document.createElement('div');
         this.lease.className = 'ck-crowdy-studio-agent-lease';
         this.lease.setAttribute('role', 'status');
         this.lease.setAttribute('aria-label', 'Agent control lease');
+        this.messages = document.createElement('div');
+        this.messages.className = 'ck-crowdy-studio-agent-messages';
+        this.messages.setAttribute('role', 'log');
+        this.messages.setAttribute('aria-live', 'polite');
+        this.messages.setAttribute('aria-relevant', 'additions text');
+        this.stream = document.createElement('div');
+        this.stream.className = 'ck-crowdy-studio-agent-stream';
+        this.stream.setAttribute('aria-label', 'Streaming assistant response');
+        this.messages.append(this.stream);
+        const form = document.createElement('form');
+        form.className = 'ck-crowdy-studio-agent-composer';
+        this.composer = document.createElement('textarea');
+        this.composer.maxLength = 32768;
+        this.composer.rows = 3;
+        this.composer.placeholder = 'Ask, build, or play…';
+        this.composer.setAttribute('aria-label', 'Message Crowdy Agent');
+        this.send = button('Send', 'submit');
+        form.append(this.composer, this.send);
+        form.addEventListener('submit', (event) => {
+            event.preventDefault();
+            const content = this.composer.value;
+            if (!content.trim())
+                return;
+            void this.run(async () => {
+                await this.controller.sendMessage(content);
+                this.composer.value = '';
+            });
+        });
+        this.composer.addEventListener('keydown', (event) => {
+            if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+                event.preventDefault();
+                form.requestSubmit();
+            }
+        });
+        // Collapsible secondary sections.
+        const playBody = document.createElement('div');
         const leaseControls = document.createElement('fieldset');
         leaseControls.className = 'ck-crowdy-studio-agent-lease-controls';
         const leaseLegend = document.createElement('legend');
@@ -92,56 +142,25 @@ export class CrowdyStudioAgentDomShell {
             }));
         });
         leaseControls.append(grant);
-        const conversationTitle = heading('Conversation');
-        this.messages = document.createElement('div');
-        this.messages.className = 'ck-crowdy-studio-agent-messages';
-        this.messages.setAttribute('role', 'log');
-        this.messages.setAttribute('aria-live', 'polite');
-        this.messages.setAttribute('aria-relevant', 'additions text');
-        this.stream = document.createElement('div');
-        this.stream.className = 'ck-crowdy-studio-agent-stream';
-        this.stream.setAttribute('aria-label', 'Streaming assistant response');
-        this.messages.append(this.stream);
-        const activityTitle = heading('Plan and tools');
+        playBody.append(leaseControls);
+        [this.playDisclosure, this.playSummary] = disclosure('Play control', playBody);
         this.timeline = document.createElement('ol');
         this.timeline.className = 'ck-crowdy-studio-agent-timeline';
         this.timeline.setAttribute('aria-label', 'Agent plan and tool timeline');
-        this.approvals = document.createElement('section');
-        this.approvals.className = 'ck-crowdy-studio-agent-approvals';
-        this.approvals.setAttribute('aria-label', 'Pending exact approvals');
+        [this.activityDisclosure, this.activitySummary] = disclosure('Activity', this.timeline);
         this.checkpoints = document.createElement('section');
         this.checkpoints.className = 'ck-crowdy-studio-agent-checkpoints';
         this.checkpoints.setAttribute('aria-label', 'Agent diffs and checkpoints');
-        const form = document.createElement('form');
-        form.className = 'ck-crowdy-studio-agent-composer';
-        this.composer = document.createElement('textarea');
-        this.composer.maxLength = 32768;
-        this.composer.rows = 3;
-        this.composer.placeholder = 'Ask, build, or play…';
-        this.composer.setAttribute('aria-label', 'Message Crowdy Agent');
-        this.send = button('Send', 'submit');
-        form.append(this.composer, this.send);
-        form.addEventListener('submit', (event) => {
-            event.preventDefault();
-            const content = this.composer.value;
-            if (!content.trim())
-                return;
-            void this.run(async () => {
-                await this.controller.sendMessage(content);
-                this.composer.value = '';
-            });
-        });
-        this.composer.addEventListener('keydown', (event) => {
-            if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
-                event.preventDefault();
-                form.requestSubmit();
-            }
-        });
-        this.root.append(header, modeGroup, controls, this.budget, this.lease, leaseControls, conversationTitle, this.messages, activityTitle, this.timeline, this.approvals, this.checkpoints, form);
+        [this.changesDisclosure, this.changesSummary] = disclosure('Changes', this.checkpoints);
+        this.budget = document.createElement('div');
+        this.budget.className = 'ck-crowdy-studio-agent-budget';
+        this.budget.setAttribute('aria-label', 'Agent budget');
+        this.root.append(header, controlsRow, this.approvals, this.lease, this.messages, form, this.playDisclosure, this.activityDisclosure, this.changesDisclosure, this.budget);
         host.dataset.agent = 'true';
         host.append(this.root);
         this.unsubscribe = controller.subscribe((state) => this.render(state));
         this.countdownTimer = setInterval(() => this.renderLease(this.lastState), 1000);
+        this.render(this.lastState);
     }
     render(state) {
         if (this.disposed)
@@ -167,6 +186,7 @@ export class CrowdyStudioAgentDomShell {
         this.renderTimeline(state);
         this.renderApprovals(state);
         this.renderCheckpoints(state);
+        this.autoReveal(state);
     }
     dispose() {
         if (this.disposed)
@@ -176,6 +196,27 @@ export class CrowdyStudioAgentDomShell {
         this.unsubscribe();
         this.root.remove();
     }
+    /**
+     * Safety-critical auto-reveal: a newly pending exact approval or a Play
+     * lease activation opens the dock and the Play disclosure so the human is
+     * always shown what needs their decision or is acting on their behalf.
+     */
+    autoReveal(state) {
+        const pending = state.approvals.filter((approval) => approval.status === 'PENDING').length;
+        const playLeaseActive = state.leases.some((lease) => lease.kind === 'PLAY' && lease.status === 'ACTIVE');
+        if (pending > this.lastPendingApprovals) {
+            this.options.layout?.setVisible('agent', true);
+        }
+        if (playLeaseActive && !this.lastPlayLeaseActive) {
+            this.options.layout?.setVisible('agent', true);
+            this.playDisclosure.open = true;
+        }
+        if (state.session?.mode === 'PLAY' && !playLeaseActive) {
+            this.playDisclosure.open = true;
+        }
+        this.lastPendingApprovals = pending;
+        this.lastPlayLeaseActive = playLeaseActive;
+    }
     renderBudget(state) {
         if (!state.budget) {
             this.budget.textContent = 'Budget unavailable';
@@ -191,15 +232,19 @@ export class CrowdyStudioAgentDomShell {
         const lease = state.leases.find((entry) => entry.kind === 'PLAY' && entry.status === 'ACTIVE');
         if (!lease) {
             this.lease.textContent = 'No active Play lease';
+            this.lease.dataset.active = 'false';
+            this.playSummary.textContent = 'Play control';
             return;
         }
         const remaining = Math.max(0, Math.ceil((Date.parse(lease.expiresAt) - Date.now()) / 1000));
+        this.lease.dataset.active = 'true';
         this.lease.textContent = [
             `Play lease: ${remaining}s`,
             `holder ${lease.holder}`,
             `entity ${lease.controlledEntityId ?? 'none'}`,
             `scopes ${lease.scopes.join(', ')}`,
         ].join(' · ');
+        this.playSummary.textContent = `Play control · lease ${remaining}s`;
     }
     renderMessages(state) {
         const rows = state.messages.map((message) => {
@@ -266,6 +311,8 @@ export class CrowdyStudioAgentDomShell {
         });
         const items = [...runItems, ...toolItems];
         this.timeline.replaceChildren(...items);
+        this.activitySummary.textContent =
+            items.length > 0 ? `Activity (${items.length})` : 'Activity';
         if (items.length === 0) {
             const empty = document.createElement('li');
             empty.textContent = 'No tool activity.';
@@ -301,6 +348,7 @@ export class CrowdyStudioAgentDomShell {
             return card;
         });
         this.approvals.replaceChildren(...cards);
+        this.approvals.hidden = cards.length === 0;
     }
     renderCheckpoints(state) {
         const diffTools = state.tools.filter((tool) => tool.name === 'workspace.file.patch' ||
@@ -327,6 +375,14 @@ export class CrowdyStudioAgentDomShell {
             cards.push(card);
         }
         this.checkpoints.replaceChildren(...cards);
+        this.changesSummary.textContent =
+            cards.length > 0 ? `Changes (${cards.length})` : 'Changes';
+        if (cards.length === 0) {
+            const none = document.createElement('p');
+            none.className = 'ck-crowdy-studio-empty';
+            none.textContent = 'No agent edits or checkpoints yet.';
+            this.checkpoints.append(none);
+        }
     }
     async run(operation) {
         try {
@@ -338,6 +394,14 @@ export class CrowdyStudioAgentDomShell {
         }
     }
 }
+function disclosure(label, body) {
+    const details = document.createElement('details');
+    details.className = 'ck-crowdy-studio-agent-disclosure';
+    const summary = document.createElement('summary');
+    summary.textContent = label;
+    details.append(summary, body);
+    return [details, summary];
+}
 function button(label, type = 'button') {
     const control = document.createElement('button');
     control.type = type;

package/dist/crowdy-studio/dom-shell.d.ts

@@ -1,23 +1,42 @@
 import { type CrowdyStudioController, type CrowdyStudioState } from './controller.js';
 import type { CrowdyStudioAgentController } from '../crowdy-agent/controller.js';
 import { type CrowdyStudioAgentDomShellOptions } from './agent-dom-shell.js';
-/** Modular DOM shell; editor implementations mount into `editorHost`. */
+import { StudioLayoutController } from './layout.js';
+/**
+ * Modular DOM shell; editor implementations mount into `editorHost`.
+ *
+ * Layout is user directed: the editor is always visible while the explorer,
+ * project settings, bottom panel, and agent dock are toggled from the
+ * activity rail, resized with accessible splitters, and persisted through
+ * {@link StudioLayoutController}.
+ */
 export declare class CrowdyStudioDomShell {
     private readonly controller;
     readonly root: HTMLElement;
     readonly editorHost: HTMLElement;
-    private readonly projectSelect;
-    private readonly saveBadge;
+    readonly layout: StudioLayoutController;
+    private readonly workspace;
+    private readonly editorColumn;
+    private readonly projectMenu;
+    private readonly projectMenuList;
+    private readonly saveMenu;
+    private readonly saveActions;
+    private readonly saveMessageText;
     private readonly saveAction;
     private readonly remoteAction;
     private readonly testAction;
+    private readonly runMenu;
     private readonly deployAction;
+    private readonly stopAction;
     private readonly runtimeStatus;
     private readonly budgetStatus;
+    private readonly saveStatus;
     private readonly newForm;
     private readonly newName;
     private readonly newKind;
     private readonly explorer;
+    private readonly settings;
+    private readonly bottom;
     private readonly tabs;
     private readonly settingsName;
     private readonly settingsDescription;
@@ -34,20 +53,44 @@ export declare class CrowdyStudioDomShell {
     private readonly invokeResult;
     private readonly panelButtons;
     private readonly panels;
+    private readonly railButtons;
+    private readonly splitters;
     private readonly agentShell;
+    private readonly unsubscribeLayout;
     private activePanel;
+    private explorerForm;
+    private lastState;
+    private lastPhase;
     private disposed;
     constructor(host: HTMLElement, controller: CrowdyStudioController, agentController?: CrowdyStudioAgentController, agentOptions?: CrowdyStudioAgentDomShellOptions);
     render(state: CrowdyStudioState): void;
     dispose(): void;
+    private railButton;
+    /**
+     * Narrow widths turn side panes into overlays (styles.ts container
+     * queries), where several open panes would stack invisibly on top of each
+     * other. Enforce the "single pane" rule there: opening one side pane
+     * closes the others that overlay at the current width.
+     */
+    private collapseOverlappingPanes;
+    private paneSplitter;
+    private applyLayout;
+    private revealPanel;
+    private autoRevealFailures;
+    private createMenu;
     private createPanel;
     private activatePanel;
+    /** Poll logs/runs only while their panel is both selected and shown. */
+    private syncPanelPolling;
     private renderProjects;
     private renderSaveState;
     private renderExplorer;
     private projectSection;
     private projectFileRow;
+    private projectFileFormRow;
     private referenceSection;
+    private inlineForm;
+    private rerenderExplorer;
     private renderTabs;
     private renderSettings;
     private renderProblems;

package/dist/crowdy-studio/dom-shell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dom-shell.d.ts","sourceRoot":"","sources":["../../src/crowdy-studio/dom-shell.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,sBAAsB,EAE3B,KAAK,iBAAiB,EACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,EAEL,KAAK,gCAAgC,EACtC,MAAM,sBAAsB,CAAC;AAY9B,yEAAyE;AACzE,qBAAa,oBAAoB;IAqC7B,OAAO,CAAC,QAAQ,CAAC,UAAU;IApC7B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoB;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoB;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoB;IACjD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAc;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmB;IAChD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAmB;IACvD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAc;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAc;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmB;IAChD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IACnD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA2C;IACxE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAC5D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmC;IAC9D,OAAO,CAAC,WAAW,CAAyB;IAC5C,OAAO,CAAC,QAAQ,CAAS;gBAGvB,IAAI,EAAE,WAAW,EACA,UAAU,EAAE,sBAAsB,EACnD,eAAe,CAAC,EAAE,2BAA2B,EAC7C,YAAY,GAAE,gCAAqC;IA2MrD,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;IA+BtC,OAAO,IAAI,IAAI;IAUf,OAAO,CAAC,WAAW;IAgBnB,OAAO,CAAC,aAAa;IAiBrB,OAAO,CAAC,cAAc;IAoBtB,OAAO,CAAC,eAAe;IAiBvB,OAAO,CAAC,cAAc;IAyBtB,OAAO,CAAC,cAAc;IAyBtB,OAAO,CAAC,cAAc;IAkDtB,OAAO,CAAC,gBAAgB;IAuCxB,OAAO,CAAC,UAAU;IAwBlB,OAAO,CAAC,cAAc;IAgCtB,OAAO,CAAC,cAAc;IAgCtB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,iBAAiB;YAgBX,GAAG;CAQlB"}
+{"version":3,"file":"dom-shell.d.ts","sourceRoot":"","sources":["../../src/crowdy-studio/dom-shell.ts"],"names":[],"mappings":"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"}