@design.estate/dees-catalog 12.0.0 → 12.2.0

package/readme.md

@@ -174,6 +174,7 @@ task guide and examples deliberately; the generated table does not replace them.
 | `dees-harness-reasoning` | harness | [DeesHarnessReasoning](#deesharnessreasoning) | [Source](ts_web/elements/00group-harness/dees-harness-reasoning/dees-harness-reasoning.ts) |
 | `dees-harness-session-list` | harness | [DeesHarnessSessionList](#deesharnesssessionlist) | [Source](ts_web/elements/00group-harness/dees-harness-session-list/dees-harness-session-list.ts) |
 | `dees-harness-session-sidebar` | harness | [DeesHarnessSessionSidebar](#deesharnesssessionsidebar) | [Source](ts_web/elements/00group-harness/dees-harness-session-sidebar/dees-harness-session-sidebar.ts) |
+| `dees-harness-sidebar` | harness | [DeesHarnessSidebar](#deesharnesssidebar) | [Source](ts_web/elements/00group-harness/dees-harness-sidebar/dees-harness-sidebar.ts) |
 | `dees-harness-status` | harness | [DeesHarnessStatus](#deesharnessstatus) | [Source](ts_web/elements/00group-harness/dees-harness-status/dees-harness-status.ts) |
 | `dees-harness-todos` | harness | [DeesHarnessTodos](#deesharnesstodos) | [Source](ts_web/elements/00group-harness/dees-harness-todos/dees-harness-todos.ts) |
 | `dees-harness-tool-card` | harness | [DeesHarnessToolCard](#deesharnesstoolcard) | [Source](ts_web/elements/00group-harness/dees-harness-tool-card/dees-harness-tool-card.ts) |
@@ -2754,10 +2755,28 @@ Token usage chip (`in · out · total`, `compact` shows the total only); cache r
 
 #### `DeesTerminalView`
 
-Transport-agnostic xterm.js surface. The host pipes remote PTY output in with `write(data)` and receives keystrokes as `terminal-input` (`{ data }`); there is no process, runtime or socket coupling. `terminal-resize` (`{ rows, cols }`) reports the grid after every refit so the host can negotiate a PTY size, and `currentSize` reads it back (`undefined` while no terminal is live). `fontSize` sets the grid font, `disabled` stops `terminal-input` from being emitted, and `focus()` focuses the grid. xterm is loaded through `DeesServiceLibLoader`; CSP-locked or offline hosts call `provideXtermModules()` first to supply their own bundled copy instead of the CDN.
+Transport-agnostic xterm.js surface. The host pipes remote PTY output in with `write(data)` and receives keystrokes as `terminal-input` (`{ data }`); there is no process, runtime or socket coupling. `terminal-resize` (`{ rows, cols }`) reports the grid after every refit so the host can negotiate a PTY size, and `currentSize` reads it back (`undefined` while no terminal is live). `fontSize` sets the grid font, `disabled` stops `terminal-input` from being emitted, and `focus()` moves the caret into the terminal's input surface. xterm is loaded through `DeesServiceLibLoader`; CSP-locked or offline hosts call `provideXtermModules()` first to supply their own bundled copy instead of the CDN.
 
 `write()` is safe before the terminal exists and while the element is detached: output is buffered and replayed in order on the next connection, bounded by the exported `maxPendingWriteBytes` (8 MiB — `Uint8Array` chunks count their `byteLength`, strings their UTF-16 memory). Past that bound the oldest chunks are dropped and the replay emits RIS first, so a truncated prefix is never rendered as if it were contiguous. `clear()` resets screen and scrollback through the write stream (RIS, `ESC c`) rather than around it, so it is ordered against output already queued in xterm — write, `clear()`, write leaves only the later output on screen.
 
+`restore(data, { cols, rows })` shows a serialized terminal state, for example one the host keeps with xterm's serialize addon, in one step, so reattaching to a long-running terminal does not replay its history in front of the user. A snapshot is exact only at the grid it was taken at, so the terminal is fully reset (screen, scrollback, modes, alternate buffer), set to that grid, fed the snapshot while invisible, then fitted to its container and revealed. `terminal-resize` fires at the end when the fitted grid differs from the snapshot's, which is the host's cue to resize the PTY so the application redraws. Until then `currentSize` reports the snapshot's grid, so the closing event, or the resolved promise, is what a host negotiates a PTY size on. The terminal is hidden with `opacity`, so it keeps focus and keeps forwarding input meanwhile. The restore is part of the output stream: `write()` calls issued after it are applied after the snapshot, at the fitted size, so the host does not wait before streaming live output from the snapshot's offset. The resize observer does not refit until the snapshot is parsed. Before the terminal exists, a restore is buffered like `write()`: it replaces everything buffered before it and counts towards `maxPendingWriteBytes`. It is the oldest buffered entry, so it is dropped first, and a snapshot that alone exceeds the bound is dropped by the next buffered write.
+
+The promise resolves once the snapshot is on screen. It also resolves, without revealing anything, when a newer `restore()` supersedes it, or when `clear()` replaces it while it is still buffered. It rejects when the element is disconnected while the snapshot is being parsed (the terminal and the snapshot are disposed together, as with any live output), when output buffered after it pushes it out of the buffer, or when xterm refuses the data (`terminal-error` carries the same error). None of these surfaces as an unhandled rejection. A size that is not an integer `cols` in 2–65535 and `rows` in 1–65535 is a programming error: the promise rejects with a `RangeError` and nothing changes; unlike the reasons above this one is not pre-handled, so a `restore()` nobody observes reports it as an unhandled rejection. There is a fourth outcome: a restore that is still buffered when the element is disconnected stays pending, because the snapshot survives the move like buffered output and is applied on the next connection — a host that discards the element instead of reattaching it must not await that promise.
+
+```typescript
+// Reattach through the host's own transport: paint the snapshot, then keep writing
+// live output from the stream offset the snapshot was taken at.
+const snapshot = await transport.attachTerminal(terminalId);
+// Not awaited, so live output queues behind the snapshot. A rejected restore leaves only
+// the live tail on screen, so take a fresh snapshot rather than ignore the rejection.
+view
+  .restore(snapshot.data, { cols: snapshot.cols, rows: snapshot.rows })
+  .catch(() => transport.reattachTerminal(terminalId));
+transport.streamOutput(terminalId, snapshot.offset, (chunk) => view.write(chunk));
+```
+
+`focus()` is the call a host makes when the user selects a terminal — after a click, or after `Enter`/`Space` on a row — so the next keystroke goes to the pty instead of the page. Because the terminal is created asynchronously on first connection, a `focus()` that arrives before it exists is remembered and applied exactly once when it becomes ready; `focusPending` reads that state back. The request belongs to the connection it was made in and is dropped on disconnect, so an element moved between containers never grabs the caret back from wherever the user went — issue a fresh `focus()` after the move. Nothing else moves focus: re-renders, buffered output and background writes never steal it.
+
 `ready` resolves once the terminal of the current connection is live; a fresh promise is created per connection, so a reattached element can be awaited again. Every connection builds a terminal and every disconnection disposes it, so an element moved between containers, or returned to, is a live surface rather than a dead one; buffered output survives the move. A failed xterm load is not an unhandled rejection: it dispatches the bubbling, composed `terminal-error` (`ITerminalErrorDetail { error }`), rejects `ready` with the same error, leaves the element writable, and is retried on the next connection. xterm's own flow-control refusal is reported the same way. Sizing comes from the host element — give it a bounded height, as the demo does.
 
 #### `DeesHarnessSessionSidebar`
@@ -2768,6 +2787,35 @@ Scratchpad edits emit `harness-scratchpad-save` with `{ text, expectedRevision }
 
 Direct sidebar hosts can set `intelligenceAvailabilityStatus`, `intelligenceUnavailableReason`, and `intelligenceHeading`; `intelligenceEnabled` still controls whether the section exists. The properties default to `available`, an empty reason, and `Session Intelligence`. A blank heading falls back to `Session Intelligence`, and unavailable state without a reason renders `<heading> is unavailable.` Only `available` permits `harness-session-intelligence-ask`; checking and unavailable states retain history and expose accessible status text. The availability union is exported as `THarnessIntelligenceAvailabilityStatus`.
 
+#### `DeesHarnessSidebar`
+
+The sidebar shell behind [DeesHarnessSessionSidebar](#deesharnesssessionsidebar)'s chrome, with host-declared sections instead of session-specific ones: the same paddings, heading rows, chevron affordance, typography and single-open accordion, for a panel the catalog knows nothing about. It owns the accordion and nothing else — every section body is the host's own content, slotted as `slot="section-<key>"`, so the host keeps its state, its updates and its presentation.
+
+Set `.sections` to `IHarnessSidebarSection[]`, where each section is `{ key, label, icon?, badge? }`: `key` is the section's stable identity and names its content slot, `icon` renders before the label (e.g. `lucide:Gauge`), and `badge` is the right-aligned summary the session panel uses for counts. Sections render in array order, and a section whose slot holds no content is not offered at all — no heading row, no expandable region — so the divider follows the last visible section and a panel can declare more sections than the host currently fills.
+
+`expandedSection` is the key of the open section. It is host-settable and reflects what the user opened; it defaults to the first section that has content. A user toggle emits `harness-sidebar-section-change` with `IHarnessSidebarSectionChangeDetail` (`{ expandedSection }`), where `undefined` means the user collapsed the panel — it stays collapsed until something opens a section again. Host writes never echo an event, so a host that binds the property should take the event's value back into its own state to keep the two in step. A section that has no content yet stays collapsed without losing the key and opens the moment its body is slotted, so a body the host renders conditionally costs neither the host nor the user their choice; only withdrawing the open section from `sections` moves the panel on to the first populated section. `disabled` freezes the accordion with its headings still visible.
+
+Section bodies stay mounted while collapsed and keep their identity across renders, so a live panel behaves: updating `sections` for a new badge, or mutating the slotted content itself, neither collapses the open section nor resets its scroll position. The host mounts and unmounts the element to show or hide the panel — there is no toggle button or open animation — and an element that is re-mounted reopens the section it had. Give the panel a bounded height from its container, as the session panel's column does; the element fills it and scrolls the expanded body.
+
+```typescript
+import type { IHarnessSidebarSection, IHarnessSidebarSectionChangeDetail } from '@design.estate/dees-catalog';
+
+const sections: IHarnessSidebarSection[] = [
+  { key: 'screencast', label: 'Screencast', icon: 'lucide:MonitorPlay', badge: '4.4 ms' },
+];
+
+html`
+  <dees-harness-sidebar
+    .sections=${sections}
+    @harness-sidebar-section-change=${(event: CustomEvent<IHarnessSidebarSectionChangeDetail>) => {
+      this.openSection = event.detail.expandedSection;
+    }}
+  >
+    <div slot="section-screencast">${this.renderScreencastStats()}</div>
+  </dees-harness-sidebar>
+`;
+```
+
 #### `DeesHarnessConversationPicker`
 
 Keyboard-first picker for one conversation, or one attachable resource, used wherever a menu would otherwise list every possible target. It is presentation only: it never mutates a session, a resource, or an association — it resolves one choice and leaves the change to the host.

package/ts_web/00_commitinfo_data.ts

@@ -2,7 +2,7 @@
  * autocreated commitinfo by @push.rocks/commitinfo
  */
 export const commitinfo = {
-  name: '@design.estate/dees-catalog',
-  version: '12.0.0',
-  description: 'A comprehensive library that provides dynamic web components for building sophisticated and modern web applications using JavaScript and TypeScript.'
+  name: "@design.estate/dees-catalog",
+  version: "12.2.0",
+  description: "A comprehensive library that provides dynamic web components for building sophisticated and modern web applications using JavaScript and TypeScript."
 }

package/ts_web/elements/00group-harness/dees-harness-session-sidebar/dees-harness-session-sidebar.ts

@@ -11,7 +11,7 @@ import {
   directives,
 } from '@design.estate/dees-element';
 import { themeDefaultStyles } from '../../00theme.js';
-import { harnessControlStyles } from '../harness.styles.js';
+import { harnessControlStyles, harnessSidebarStyles } from '../harness.styles.js';
 import type {
   IHarnessIntelligenceExchange,
   IHarnessMessage,
@@ -135,112 +135,8 @@ export class DeesHarnessSessionSidebar extends DeesElement {
     themeDefaultStyles,
     cssManager.defaultStyles,
     harnessControlStyles,
+    harnessSidebarStyles,
     css`
-      :host {
-        display: flex;
-        flex-direction: column;
-        min-width: 0;
-        min-height: 0;
-        height: 100%;
-        font-family: var(--dees-font-family);
-        color: var(--dees-color-text-primary);
-      }
-
-      .sidebar {
-        display: flex;
-        flex-direction: column;
-        min-height: 0;
-        height: 100%;
-        overflow: hidden;
-      }
-
-      .section {
-        display: flex;
-        flex: 0 0 auto;
-        flex-direction: column;
-        min-height: 0;
-        overflow: hidden;
-        border-bottom: 1px solid var(--dees-color-border-subtle);
-      }
-
-      .section.expanded {
-        flex: 1 1 0;
-      }
-
-      .section:last-child {
-        border-bottom: 0;
-      }
-
-      .sectionHeading {
-        display: flex;
-        flex: 0 0 auto;
-        align-items: center;
-        gap: var(--dees-spacing-xs);
-        width: 100%;
-        min-height: 36px;
-        margin: 0;
-        padding: 6px 12px 6px 8px;
-        border: 0;
-        background: var(--dees-color-bg-canvas);
-        color: var(--dees-color-text-primary);
-        font-family: inherit;
-        font-size: var(--dees-font-control-size-sm, 12px);
-        font-weight: 600;
-        text-align: left;
-        cursor: pointer;
-      }
-
-      .sectionHeading:hover {
-        background: var(--dees-color-badge-default-bg);
-      }
-
-      .sectionHeading:focus-visible {
-        position: relative;
-        z-index: 1;
-        outline: 2px solid var(--dees-color-accent-primary);
-        outline-offset: -2px;
-      }
-
-      .sectionHeading dees-icon {
-        flex: 0 0 auto;
-        color: var(--dees-color-text-secondary);
-      }
-
-      .sectionHeadingText {
-        min-width: 0;
-        flex-shrink: 0;
-        overflow: hidden;
-        text-overflow: ellipsis;
-        white-space: nowrap;
-      }
-
-      .sectionSummary {
-        flex: 0 1 auto;
-        min-width: 0;
-        overflow: hidden;
-        text-overflow: ellipsis;
-        white-space: nowrap;
-        margin-left: auto;
-        color: var(--dees-color-text-muted);
-        font-size: 11px;
-        font-variant-numeric: tabular-nums;
-        font-weight: 500;
-      }
-
-      .sectionContent {
-        flex: 1;
-        min-height: 0;
-        overflow-x: hidden;
-        overflow-y: auto;
-        padding: var(--dees-spacing-sm) var(--dees-spacing-md);
-        scrollbar-width: thin;
-        scrollbar-color: var(--dees-color-scrollbar-thumb) transparent;
-      }
-
-      .sectionContent[hidden] {
-        display: none;
-      }
-
       .sectionContent dees-harness-todos {
         min-width: 0;
       }

package/ts_web/elements/00group-harness/dees-harness-sidebar/dees-harness-sidebar.demo.ts

@@ -0,0 +1,87 @@
+import { html } from '@design.estate/dees-element';
+import { demoPage, demoOutput, showDemoResult } from '../../../demos/templates.js';
+import type {
+  IHarnessSidebarSection,
+  IHarnessSidebarSectionChangeDetail,
+} from './dees-harness-sidebar.js';
+
+// `notes` is declared without slotted content, so the panel does not offer it.
+const sections: IHarnessSidebarSection[] = [
+  { key: 'screencast', label: 'Screencast', icon: 'lucide:MonitorPlay', badge: '4.4 ms' },
+  { key: 'transport', label: 'Transport', icon: 'lucide:Activity', badge: 'webrtc' },
+  { key: 'notes', label: 'Notes', icon: 'lucide:NotebookPen' },
+];
+
+let sampleCount = 0;
+
+/**
+ * A live panel updates its rows and badges in place: the host owns the values,
+ * so nothing collapses and the open section keeps its scroll position.
+ */
+const sampleCounters = (eventArg: Event): void => {
+  const scope = (eventArg.currentTarget as HTMLElement).closest('.harnessSidebarDemo')!;
+  sampleCount += 1;
+  const decodeMs = (4.4 + (sampleCount % 6) * 0.3).toFixed(1);
+  scope.querySelector('[data-metric="frames"]')!.textContent = `${1_440 + sampleCount * 24}`;
+  scope.querySelector('[data-metric="decode"]')!.textContent = `${decodeMs} ms`;
+  scope.querySelector('dees-harness-sidebar')!.sections = sections.map((section) =>
+    section.key === 'screencast' ? { ...section, badge: `${decodeMs} ms` } : section,
+  );
+};
+
+export const demoFunc = () => demoPage('Sidebar', 'A host-composed panel of collapsible sections in the harness sidebar style: the shell owns the accordion, every body is slotted content. One section is declared without content and is therefore not offered.', html`
+  <style>
+    .harnessSidebarPanel {
+      width: min(100%, 300px);
+      height: 420px;
+      overflow: hidden;
+      border: 1px solid var(--dees-color-border-subtle);
+      border-radius: var(--dees-radius-xl);
+    }
+    .sidebarRow {
+      display: flex;
+      align-items: baseline;
+      justify-content: space-between;
+      gap: var(--dees-spacing-md);
+      color: var(--dees-color-text-secondary);
+    }
+    .sidebarRow + .sidebarRow {
+      margin-top: 6px;
+    }
+    .sidebarValue {
+      color: var(--dees-color-text-primary);
+      font-family: var(--dees-font-family-mono);
+      font-variant-numeric: tabular-nums;
+    }
+  </style>
+  <div class="harnessSidebarDemo dees-demo-stack">
+    <div class="dees-demo-row">
+      <dees-button @clicked=${sampleCounters}>Sample the counters</dees-button>
+    </div>
+    <div class="harnessSidebarPanel">
+      <dees-harness-sidebar
+        .sections=${sections}
+        @harness-sidebar-section-change=${(event: CustomEvent<IHarnessSidebarSectionChangeDetail>) => {
+          showDemoResult((event.currentTarget as Element).closest('.harnessSidebarDemo')!, event.detail);
+        }}
+      >
+        <div slot="section-screencast">
+          <div class="sidebarRow"><span>Codec</span><span class="sidebarValue">h264</span></div>
+          <div class="sidebarRow"><span>Encoder</span><span class="sidebarValue">hardware</span></div>
+          <div class="sidebarRow">
+            <span>Decode</span><span class="sidebarValue" data-metric="decode">4.4 ms</span>
+          </div>
+          <div class="sidebarRow">
+            <span>Frames</span><span class="sidebarValue" data-metric="frames">1440</span>
+          </div>
+          <div class="sidebarRow"><span>GPU compositing</span><span class="sidebarValue">on</span></div>
+        </div>
+        <div slot="section-transport">
+          <div class="sidebarRow"><span>Channel</span><span class="sidebarValue">datachannel</span></div>
+          <div class="sidebarRow"><span>Round trip</span><span class="sidebarValue">18 ms</span></div>
+        </div>
+      </dees-harness-sidebar>
+    </div>
+    ${demoOutput()}
+  </div>
+`);

package/ts_web/elements/00group-harness/dees-harness-sidebar/dees-harness-sidebar.ts

@@ -0,0 +1,245 @@
+import { demoFunc } from './dees-harness-sidebar.demo.js';
+import {
+  DeesElement,
+  html,
+  css,
+  customElement,
+  type TemplateResult,
+  property,
+  state,
+  cssManager,
+  directives,
+} from '@design.estate/dees-element';
+import { themeDefaultStyles } from '../../00theme.js';
+import { harnessSidebarStyles } from '../harness.styles.js';
+import '../../00group-utility/dees-icon/dees-icon.js';
+
+const { repeat } = directives;
+
+/** Every section body arrives through `slot="section-<key>"`. */
+const sectionSlotPrefix = 'section-';
+const sectionSlotName = (keyArg: string): string => `${sectionSlotPrefix}${keyArg}`;
+
+const sameKeys = (leftArg: ReadonlySet<string>, rightArg: ReadonlySet<string>): boolean =>
+  leftArg.size === rightArg.size && [...leftArg].every((keyArg) => rightArg.has(keyArg));
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'dees-harness-sidebar': DeesHarnessSidebar;
+  }
+}
+
+/**
+ * One collapsible section of a sidebar panel. The element renders the heading
+ * row; the body is the host's own content, slotted as `slot="section-<key>"`.
+ */
+export interface IHarnessSidebarSection {
+  /** Stable identity, unique within `sections`; also names the content slot. */
+  key: string;
+  label: string;
+  /** Icon shown before the label, e.g. `lucide:Gauge`. */
+  icon?: string;
+  /** Right-aligned summary such as a count, a rate, or a live value. */
+  badge?: string;
+}
+
+/**
+ * Detail of `harness-sidebar-section-change`: the user opened another section
+ * or collapsed the open one.
+ */
+export interface IHarnessSidebarSectionChangeDetail {
+  /** Key of the now-open section, or `undefined` when nothing is open. */
+  expandedSection: string | undefined;
+}
+
+/**
+ * Sidebar shell: the panel chrome of `dees-harness-session-sidebar` with
+ * host-declared sections instead of session-specific ones. It owns the
+ * single-open accordion and nothing else — every section body is slotted
+ * content, so the host keeps its own state, updates, and presentation. A
+ * section whose slot holds no content is not offered at all, and the host
+ * mounts and unmounts the element to show or hide the panel.
+ */
+@customElement('dees-harness-sidebar')
+export class DeesHarnessSidebar extends DeesElement {
+  public static demo = demoFunc;
+  public static demoGroups = ['Agent Chat'];
+
+  /** Sections in render order; each one's body is slotted as `section-<key>`. */
+  @property({ attribute: false })
+  accessor sections: IHarnessSidebarSection[] = [];
+
+  /**
+   * Key of the open section. Host-settable and kept in sync with what the user
+   * opens; it defaults to the first section that has content, and `undefined`
+   * leaves the panel collapsed once a section has been opened. A declared
+   * section without content renders collapsed and opens as soon as its content
+   * arrives, so the key survives an asynchronous body.
+   */
+  @property()
+  accessor expandedSection: string | undefined = undefined;
+
+  /** Freezes the accordion: headings stay visible but cannot be toggled. */
+  @property({ type: Boolean })
+  accessor disabled: boolean = false;
+
+  @state()
+  private accessor populatedSections: ReadonlySet<string> = new Set<string>();
+
+  private sectionStateInitialized = false;
+
+  public static styles = [
+    themeDefaultStyles,
+    cssManager.defaultStyles,
+    harnessSidebarStyles,
+    css`
+      :host {
+        background: var(--dees-color-bg-canvas);
+      }
+
+      /* A section without content is not offered at all: the hidden attribute
+         alone would still be laid out, because the shared chrome's display
+         declaration wins over the user-agent rule. The divider then follows the
+         last visible section instead of the last declared one. */
+      .section[hidden] {
+        display: none;
+      }
+
+      .section:not(:has(~ .section:not([hidden]))) {
+        border-bottom: 0;
+      }
+
+      /* Section bodies stay as compact as the session panel's; slotted content
+         inherits this and can override it per element. */
+      .sectionContent {
+        font-size: var(--dees-font-caption1-size, 11px);
+      }
+
+      .sectionHeading:disabled {
+        opacity: 0.62;
+        cursor: default;
+      }
+
+      .sectionHeading:disabled:hover {
+        background: var(--dees-color-bg-canvas);
+      }
+    `,
+  ];
+
+  protected willUpdate(changedPropertiesArg: Map<PropertyKey, unknown>): void {
+    if (changedPropertiesArg.has('expandedSection')) this.sectionStateInitialized = true;
+    const populated = this.populatedSectionsInOrder;
+    // Slot assignment is only known after the first render, so an empty panel
+    // never overrides a host-set section.
+    if (populated.length === 0) return;
+    if (!this.sectionStateInitialized) {
+      this.expandedSection = populated[0].key;
+      this.sectionStateInitialized = true;
+      return;
+    }
+    const open = this.expandedSection;
+    // A section the host withdrew from `sections` can never open again, so the
+    // panel moves on. A declared section whose content is momentarily missing
+    // keeps the key and renders collapsed until the content is back, so an
+    // asynchronous body never costs the host or the user their choice.
+    if (open !== undefined && !this.sections.some((section) => section.key === open)) {
+      this.expandedSection = populated[0].key;
+    }
+  }
+
+  public render(): TemplateResult {
+    return html`
+      <div class="sidebar">
+        ${repeat(
+          this.sections,
+          (section) => section.key,
+          (section) => this.renderSection(section),
+        )}
+      </div>
+    `;
+  }
+
+  /** Declared sections that currently have slotted content, in render order. */
+  private get populatedSectionsInOrder(): IHarnessSidebarSection[] {
+    return this.sections.filter((section) => this.populatedSections.has(section.key));
+  }
+
+  /**
+   * The heading row is the element's own; the body is the host's, and it stays
+   * mounted while collapsed so it keeps its state and scroll position.
+   */
+  private renderSection(sectionArg: IHarnessSidebarSection): TemplateResult {
+    const populated = this.populatedSections.has(sectionArg.key);
+    const expanded = populated && this.expandedSection === sectionArg.key;
+    const contentId = `harness-sidebar-section-${sectionArg.key}`;
+    return html`
+      <section
+        class=${`section ${expanded ? 'expanded' : ''}`}
+        data-section=${sectionArg.key}
+        ?hidden=${!populated}
+      >
+        ${populated ? html`
+          <button
+            class="sectionHeading"
+            type="button"
+            aria-expanded=${String(expanded)}
+            aria-controls=${contentId}
+            ?disabled=${this.disabled}
+            @click=${() => this.toggleSection(sectionArg.key)}
+          >
+            <dees-icon
+              icon=${expanded ? 'lucide:ChevronDown' : 'lucide:ChevronRight'}
+              iconSize="13"
+            ></dees-icon>
+            ${sectionArg.icon ? html`<dees-icon icon=${sectionArg.icon} iconSize="13"></dees-icon>` : ''}
+            <span class="sectionHeadingText">${sectionArg.label}</span>
+            ${sectionArg.badge ? html`<span class="sectionSummary">${sectionArg.badge}</span>` : ''}
+          </button>
+        ` : ''}
+        <div
+          id=${contentId}
+          class="sectionContent"
+          role="region"
+          aria-label=${sectionArg.label}
+          aria-hidden=${String(!expanded)}
+          ?hidden=${!expanded}
+        >
+          <slot
+            name=${sectionSlotName(sectionArg.key)}
+            @slotchange=${this.handleSectionSlotChange}
+          ></slot>
+        </div>
+      </section>
+    `;
+  }
+
+  /**
+   * A section is offered only while its slot holds content, so the panel
+   * recomputes from its live slots whenever the host fills or empties one.
+   */
+  private readonly handleSectionSlotChange = (): void => {
+    const populated = new Set<string>();
+    const sectionSlots = this.renderRoot.querySelectorAll<HTMLSlotElement>(
+      `slot[name^="${sectionSlotPrefix}"]`,
+    );
+    for (const slot of sectionSlots) {
+      if (slot.assignedElements({ flatten: true }).length > 0) {
+        populated.add(slot.name.slice(sectionSlotPrefix.length));
+      }
+    }
+    if (sameKeys(this.populatedSections, populated)) return;
+    this.populatedSections = populated;
+  };
+
+  private toggleSection(keyArg: string): void {
+    if (this.disabled) return;
+    const expandedSection = this.expandedSection === keyArg ? undefined : keyArg;
+    this.sectionStateInitialized = true;
+    this.expandedSection = expandedSection;
+    const detail: IHarnessSidebarSectionChangeDetail = { expandedSection };
+    this.dispatchEvent(new CustomEvent<IHarnessSidebarSectionChangeDetail>(
+      'harness-sidebar-section-change',
+      { detail, bubbles: true, composed: true },
+    ));
+  }
+}

package/ts_web/elements/00group-harness/dees-harness-sidebar/index.ts

@@ -0,0 +1 @@
+export * from './dees-harness-sidebar.js';

package/ts_web/elements/00group-harness/dees-terminal-view/dees-terminal-view.demo.ts

@@ -1,9 +1,40 @@
 import { html } from '@design.estate/dees-element';
 import { demoPage } from '../../../demos/templates.js';
+import type { ITerminalResizeDetail } from './dees-terminal-view.js';
+
+// A serialized terminal state as a host would receive it on reattach, e.g. from xterm's
+// serialize addon: styled rows at the grid the PTY had when it was taken.
+const sampleSnapshotSize: ITerminalResizeDetail = { cols: 64, rows: 12 };
+const samplePrompt = '\x1b[1;32m➜\x1b[0m \x1b[36mdees-catalog\x1b[0m ';
+const sampleSnapshot = [
+  `${samplePrompt}pnpm build`,
+  '\x1b[2mtsbuild \x1b[0m compiled the web folder',
+  '\x1b[2mtsbundle\x1b[0m wrote dist_bundle/bundle.js',
+  '',
+  `${samplePrompt}pnpm test`,
+  ' \x1b[32m✔\x1b[0m restore() sizes, parses, fits and reveals',
+  ' \x1b[32m✔\x1b[0m writes during a restore follow the snapshot',
+  ' \x1b[32m✔\x1b[0m a newer restore supersedes an older one',
+  '',
+  samplePrompt,
+].join('\r\n');
+
+const restoreSample = (event: Event): void => {
+  const view = (event.currentTarget as HTMLElement)
+    .closest('.terminalDemoStack')
+    ?.querySelector('dees-terminal-view');
+  if (!view) return;
+  // A click handler's promise is dropped by the DOM, so both outcomes are settled here: leaving
+  // the demo page mid-restore rejects, and nobody would be left to observe it.
+  view.restore(sampleSnapshot, sampleSnapshotSize).then(
+    () => view.focus(),
+    () => undefined,
+  );
+};
 
 // A loopback demo: keystrokes echo straight back into the terminal so the
 // component is explorable without a live PTY behind it.
-export const demoFunc = () => demoPage('Terminal', 'A terminal surface with local keyboard echo. Type to try the input and resize behavior.', html`
+export const demoFunc = () => demoPage('Terminal', 'A terminal surface with local keyboard echo. Type to try the input and resize behavior, or restore a serialized snapshot: it is painted invisibly at its own grid and appears fitted, in one step.', html`
   <style>
     .terminalDemo {
       height: 380px;
@@ -12,16 +43,21 @@ export const demoFunc = () => demoPage('Terminal', 'A terminal surface with loca
       overflow: hidden;
     }
   </style>
-  <div class="terminalDemo">
-    <dees-terminal-view
-      @terminal-input=${(event: CustomEvent<{ data: string }>) => {
-        const view = event.currentTarget as HTMLElementTagNameMap['dees-terminal-view'];
-        const data = event.detail.data;
-        view.write(data === '\r' ? '\r\n' : data);
-      }}
-      @terminal-resize=${(event: CustomEvent<{ rows: number; cols: number }>) => {
-        console.log('terminal size', event.detail);
-      }}
-    ></dees-terminal-view>
+  <div class="terminalDemoStack dees-demo-stack">
+    <div class="dees-demo-row">
+      <dees-button @clicked=${restoreSample}>Restore a snapshot</dees-button>
+    </div>
+    <div class="terminalDemo">
+      <dees-terminal-view
+        @terminal-input=${(event: CustomEvent<{ data: string }>) => {
+          const view = event.currentTarget as HTMLElementTagNameMap['dees-terminal-view'];
+          const data = event.detail.data;
+          view.write(data === '\r' ? '\r\n' : data);
+        }}
+        @terminal-resize=${(event: CustomEvent<ITerminalResizeDetail>) => {
+          console.log('terminal size', event.detail);
+        }}
+      ></dees-terminal-view>
+    </div>
   </div>
 `);