@design.estate/dees-catalog 12.0.0 → 12.2.0

package/dist_ts_web/elements/00group-harness/dees-harness-sidebar/dees-harness-sidebar.js

@@ -0,0 +1,261 @@
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+import { demoFunc } from './dees-harness-sidebar.demo.js';
+import { DeesElement, html, css, customElement, 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) => `${sectionSlotPrefix}${keyArg}`;
+const sameKeys = (leftArg, rightArg) => leftArg.size === rightArg.size && [...leftArg].every((keyArg) => rightArg.has(keyArg));
+/**
+ * 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.
+ */
+let DeesHarnessSidebar = (() => {
+    let _classDecorators = [customElement('dees-harness-sidebar')];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    let _classSuper = DeesElement;
+    let _sections_decorators;
+    let _sections_initializers = [];
+    let _sections_extraInitializers = [];
+    let _expandedSection_decorators;
+    let _expandedSection_initializers = [];
+    let _expandedSection_extraInitializers = [];
+    let _disabled_decorators;
+    let _disabled_initializers = [];
+    let _disabled_extraInitializers = [];
+    let _populatedSections_decorators;
+    let _populatedSections_initializers = [];
+    let _populatedSections_extraInitializers = [];
+    var DeesHarnessSidebar = class extends _classSuper {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _sections_decorators = [property({ attribute: false })];
+            _expandedSection_decorators = [property()];
+            _disabled_decorators = [property({ type: Boolean })];
+            _populatedSections_decorators = [state()];
+            __esDecorate(this, null, _sections_decorators, { kind: "accessor", name: "sections", static: false, private: false, access: { has: obj => "sections" in obj, get: obj => obj.sections, set: (obj, value) => { obj.sections = value; } }, metadata: _metadata }, _sections_initializers, _sections_extraInitializers);
+            __esDecorate(this, null, _expandedSection_decorators, { kind: "accessor", name: "expandedSection", static: false, private: false, access: { has: obj => "expandedSection" in obj, get: obj => obj.expandedSection, set: (obj, value) => { obj.expandedSection = value; } }, metadata: _metadata }, _expandedSection_initializers, _expandedSection_extraInitializers);
+            __esDecorate(this, null, _disabled_decorators, { kind: "accessor", name: "disabled", static: false, private: false, access: { has: obj => "disabled" in obj, get: obj => obj.disabled, set: (obj, value) => { obj.disabled = value; } }, metadata: _metadata }, _disabled_initializers, _disabled_extraInitializers);
+            __esDecorate(this, null, _populatedSections_decorators, { kind: "accessor", name: "populatedSections", static: false, private: false, access: { has: obj => "populatedSections" in obj, get: obj => obj.populatedSections, set: (obj, value) => { obj.populatedSections = value; } }, metadata: _metadata }, _populatedSections_initializers, _populatedSections_extraInitializers);
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            DeesHarnessSidebar = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        static demo = demoFunc;
+        static demoGroups = ['Agent Chat'];
+        #sections_accessor_storage = __runInitializers(this, _sections_initializers, []);
+        /** Sections in render order; each one's body is slotted as `section-<key>`. */
+        get sections() { return this.#sections_accessor_storage; }
+        set sections(value) { this.#sections_accessor_storage = value; }
+        #expandedSection_accessor_storage = (__runInitializers(this, _sections_extraInitializers), __runInitializers(this, _expandedSection_initializers, undefined));
+        /**
+         * 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.
+         */
+        get expandedSection() { return this.#expandedSection_accessor_storage; }
+        set expandedSection(value) { this.#expandedSection_accessor_storage = value; }
+        #disabled_accessor_storage = (__runInitializers(this, _expandedSection_extraInitializers), __runInitializers(this, _disabled_initializers, false));
+        /** Freezes the accordion: headings stay visible but cannot be toggled. */
+        get disabled() { return this.#disabled_accessor_storage; }
+        set disabled(value) { this.#disabled_accessor_storage = value; }
+        #populatedSections_accessor_storage = (__runInitializers(this, _disabled_extraInitializers), __runInitializers(this, _populatedSections_initializers, new Set()));
+        get populatedSections() { return this.#populatedSections_accessor_storage; }
+        set populatedSections(value) { this.#populatedSections_accessor_storage = value; }
+        sectionStateInitialized = (__runInitializers(this, _populatedSections_extraInitializers), false);
+        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);
+      }
+    `,
+        ];
+        willUpdate(changedPropertiesArg) {
+            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;
+            }
+        }
+        render() {
+            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. */
+        get populatedSectionsInOrder() {
+            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.
+         */
+        renderSection(sectionArg) {
+            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.
+         */
+        handleSectionSlotChange = () => {
+            const populated = new Set();
+            const sectionSlots = this.renderRoot.querySelectorAll(`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;
+        };
+        toggleSection(keyArg) {
+            if (this.disabled)
+                return;
+            const expandedSection = this.expandedSection === keyArg ? undefined : keyArg;
+            this.sectionStateInitialized = true;
+            this.expandedSection = expandedSection;
+            const detail = { expandedSection };
+            this.dispatchEvent(new CustomEvent('harness-sidebar-section-change', { detail, bubbles: true, composed: true }));
+        }
+        static {
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+    };
+    return DeesHarnessSidebar = _classThis;
+})();
+export { DeesHarnessSidebar };
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVlcy1oYXJuZXNzLXNpZGViYXIuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi90c193ZWIvZWxlbWVudHMvMDBncm91cC1oYXJuZXNzL2RlZXMtaGFybmVzcy1zaWRlYmFyL2RlZXMtaGFybmVzcy1zaWRlYmFyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFBQSxPQUFPLEVBQUUsUUFBUSxFQUFFLE1BQU0sZ0NBQWdDLENBQUM7QUFDMUQsT0FBTyxFQUNMLFdBQVcsRUFDWCxJQUFJLEVBQ0osR0FBRyxFQUNILGFBQWEsRUFFYixRQUFRLEVBQ1IsS0FBSyxFQUNMLFVBQVUsRUFDVixVQUFVLEdBQ1gsTUFBTSw2QkFBNkIsQ0FBQztBQUNyQyxPQUFPLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUN0RCxPQUFPLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUM1RCxPQUFPLDhDQUE4QyxDQUFDO0FBRXRELE1BQU0sRUFBRSxNQUFNLEVBQUUsR0FBRyxVQUFVLENBQUM7QUFFOUIsaUVBQWlFO0FBQ2pFLE1BQU0saUJBQWlCLEdBQUcsVUFBVSxDQUFDO0FBQ3JDLE1BQU0sZUFBZSxHQUFHLENBQUMsTUFBYyxFQUFVLEVBQUUsQ0FBQyxHQUFHLGlCQUFpQixHQUFHLE1BQU0sRUFBRSxDQUFDO0FBRXBGLE1BQU0sUUFBUSxHQUFHLENBQUMsT0FBNEIsRUFBRSxRQUE2QixFQUFXLEVBQUUsQ0FDeEYsT0FBTyxDQUFDLElBQUksS0FBSyxRQUFRLENBQUMsSUFBSSxJQUFJLENBQUMsR0FBRyxPQUFPLENBQUMsQ0FBQyxLQUFLLENBQUMsQ0FBQyxNQUFNLEVBQUUsRUFBRSxDQUFDLFFBQVEsQ0FBQyxHQUFHLENBQUMsTUFBTSxDQUFDLENBQUMsQ0FBQztBQStCekY7Ozs7Ozs7R0FPRztJQUVVLGtCQUFrQjs0QkFEOUIsYUFBYSxDQUFD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

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

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

package/dist_ts_web/elements/00group-harness/dees-harness-sidebar/index.js

@@ -0,0 +1,2 @@
+export * from './dees-harness-sidebar.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi90c193ZWIvZWxlbWVudHMvMDBncm91cC1oYXJuZXNzL2RlZXMtaGFybmVzcy1zaWRlYmFyL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsMkJBQTJCLENBQUMifQ==

package/dist_ts_web/elements/00group-harness/dees-terminal-view/dees-terminal-view.d.ts

@@ -8,7 +8,10 @@ declare global {
 export interface ITerminalInputDetail {
     data: string;
 }
-/** Detail of `terminal-resize`, fired after the terminal refits its container. */
+/**
+ * A terminal grid size. It is the detail of `terminal-resize`, fired after the
+ * terminal refits its container, and the size `restore()` paints a snapshot at.
+ */
 export interface ITerminalResizeDetail {
     rows: number;
     cols: number;
@@ -35,9 +38,10 @@ export declare const maxPendingWriteBytes: number;
  * every refit so the host can negotiate a PTY size. Output that arrives while
  * no terminal is live is buffered up to `maxPendingWriteBytes` and replayed in
  * order on the next connection, so a replay may start before the element is
- * ready and survives being detached. xterm loads through DeesServiceLibLoader;
- * CSP-locked hosts can pre-register bundled modules with
- * `provideXtermModules()` to avoid the CDN.
+ * ready and survives being detached. `restore()` paints a serialized snapshot
+ * invisibly at the grid it was taken at, then fits it to the container. xterm
+ * loads through DeesServiceLibLoader; CSP-locked hosts can pre-register
+ * bundled modules with `provideXtermModules()` to avoid the CDN.
  */
 export declare class DeesTerminalView extends DeesElement {
     static demo: () => TemplateResult<1>;
@@ -50,10 +54,21 @@ export declare class DeesTerminalView extends DeesElement {
     private resizeObserver;
     private inputDisposable;
     private lastReportedSize;
+    private pendingRestore;
     private pendingWrites;
     private pendingWriteBytes;
     private pendingWritesDropped;
     private setupPromise;
+    /**
+     * The restore handed to the live terminal whose snapshot is not parsed yet. While it is set the
+     * grid belongs to the snapshot: the terminal stays invisible and nothing refits it.
+     */
+    private activeRestore;
+    /**
+     * Set only by an explicit `focus()` that arrived before the terminal existed. Nothing else sets
+     * it, so a re-render, a write, or a resize can never move the caret into this element.
+     */
+    private focusWhenReady;
     private readyPending;
     private readyResolve;
     private readyReject;
@@ -70,17 +85,96 @@ export declare class DeesTerminalView extends DeesElement {
     connectedCallback(): Promise<void>;
     /** Feed remote output into the terminal; safe to call before setup finishes. */
     write(dataArg: string | Uint8Array): void;
-    /** Reset the screen and scrollback, e.g. before a full replay. */
+    /**
+     * Reset the screen and scrollback, e.g. before a full replay. Before the terminal exists it also
+     * replaces a buffered `restore()`, whose promise then resolves as superseded.
+     */
     clear(): void;
-    focus(): void;
-    /** Current grid size, or undefined while no terminal is live. */
+    /**
+     * Replace the terminal state with a serialized snapshot, e.g. from xterm's serialize addon, and
+     * show it only once it is complete. A snapshot is exact only in a grid of the size it was
+     * serialized at, so the terminal is fully reset (screen, scrollback, modes, alternate buffer),
+     * set to `sizeArg`, fed `dataArg` while invisible, then fitted to its container and revealed.
+     * `terminal-resize` fires at the end when the fitted grid differs from `sizeArg`, which is the
+     * host's cue to resize the PTY so the application redraws at the new size. Until then
+     * `currentSize` reports `sizeArg`, so the closing event, or this promise, is what a host
+     * negotiates a PTY size on.
+     *
+     * The restore is part of the output stream: writes issued after it are applied after the
+     * snapshot, in order, at the fitted size. Like `write()` it is safe before the terminal exists
+     * and while the element is detached; a buffered restore replaces everything buffered before
+     * it. The terminal keeps its focus and keeps forwarding input while the restore runs.
+     *
+     * The promise resolves once the snapshot is on screen, and also, without revealing anything,
+     * when a newer `restore()` supersedes this one or `clear()` replaces it while it is buffered.
+     * It rejects, without ever surfacing as an unhandled rejection, when the element is
+     * disconnected while the snapshot is being parsed (the terminal is disposed with it, as with
+     * any live output), when output buffered after it pushes it out of `maxPendingWriteBytes`, and
+     * when xterm refuses the data (`terminal-error` carries the same error). Buffered output is
+     * dropped oldest first and the restore is the oldest entry, so a buffered snapshot that alone
+     * exceeds the bound is dropped by the next buffered write of any size. An invalid size 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.
+     *
+     * @param dataArg The serialized terminal state.
+     * @param sizeArg The grid the snapshot was serialized at: integer `cols` in [2, 65535] and
+     *   `rows` in [1, 65535].
+     */
+    restore(dataArg: string | Uint8Array, sizeArg: ITerminalResizeDetail): Promise<void>;
+    /**
+     * Moves the caret into the terminal's input surface, so the next keystroke goes to the pty
+     * rather than to whatever the page focused last. This is the call a host makes when the user
+     * selects a terminal in a list.
+     *
+     * The terminal is created asynchronously — the xterm modules are loaded on first connection —
+     * so a call that arrives before it exists is remembered and applied once it is ready, exactly
+     * once. The same applies to an element that is focused while detached and then reattached: the
+     * pending request is dropped on disconnect, because by then the user's intent has expired, and
+     * a fresh `focus()` after the move is what a host should issue.
+     *
+     * Only this method arms that behaviour; re-renders, buffered output and background updates
+     * never steal focus.
+     */
+    focus(optionsArg?: FocusOptions): void;
+    /** True while an explicit `focus()` is waiting for the terminal to come up. */
+    get focusPending(): boolean;
+    /**
+     * Current grid size, or undefined while no terminal is live. While a snapshot is being parsed
+     * this is the grid the snapshot was serialized at; the closing `terminal-resize`, or the promise
+     * `restore()` returned, is the grid to negotiate a PTY size on.
+     */
     get currentSize(): ITerminalResizeDetail | undefined;
     private createReadyPromise;
     private bufferWrite;
+    /** Hands the buffered output over and leaves the buffer empty. */
+    private takePendingOutput;
+    /** Empties the buffer ahead of a reset; a buffered restore is superseded by it. */
+    private discardPendingOutput;
     private flushPendingWrites;
+    /**
+     * Queues a restore into xterm's write stream. Resetting and resizing happen in the callback of
+     * the reset, so they take effect exactly at the restore's position in the stream, and the
+     * restore ends in the callback of its snapshot, before xterm parses the next chunk.
+     */
+    private startRestore;
+    private applyRestoreSize;
+    private finishRestore;
+    /**
+     * Hands the grid back to the container: one refit, then the terminal is revealed. The refit
+     * dispatches `terminal-resize` synchronously, and a restore its listener starts keeps the
+     * terminal hidden.
+     */
+    private endRestore;
     /** xterm throws at its own flow-control watermark; that has to reach the host. */
     private writeToTerminal;
     private reportError;
+    private get terminalHost();
     private ensureTerminal;
     private setupTerminal;
     private createTerminal;

package/dist_ts_web/elements/00group-harness/dees-terminal-view/dees-terminal-view.demo.js

@@ -1,8 +1,34 @@
 import { html } from '@design.estate/dees-element';
 import { demoPage } from '../../../demos/templates.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 = { 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) => {
+    const view = event.currentTarget
+        .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;
@@ -11,17 +37,22 @@ export const demoFunc = () => demoPage('Terminal', 'A terminal surface with loca
       overflow: hidden;
     }
   </style>
-  <div class="terminalDemo">
-    <dees-terminal-view
-      @terminal-input=${(event) => {
+  <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) => {
     const view = event.currentTarget;
     const data = event.detail.data;
     view.write(data === '\r' ? '\r\n' : data);
 }}
-      @terminal-resize=${(event) => {
+        @terminal-resize=${(event) => {
     console.log('terminal size', event.detail);
 }}
-    ></dees-terminal-view>
+      ></dees-terminal-view>
+    </div>
   </div>
 `);
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVlcy10ZXJtaW5hbC12aWV3LmRlbW8uanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi90c193ZWIvZWxlbWVudHMvMDBncm91cC1oYXJuZXNzL2RlZXMtdGVybWluYWwtdmlldy9kZWVzLXRlcm1pbmFsLXZpZXcuZGVtby50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsSUFBSSxFQUFFLE1BQU0sNkJBQTZCLENBQUM7QUFDbkQsT0FBTyxFQUFFLFFBQVEsRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBRXZELDBFQUEwRTtBQUMxRSx3REFBd0Q7QUFDeEQsTUFBTSxDQUFDLE1BQU0sUUFBUSxHQUFHLEdBQUcsRUFBRSxDQUFDLFFBQVEsQ0FBQyxVQUFVLEVBQUUseUZBQXlGLEVBQUUsSUFBSSxDQUFBOzs7Ozs7Ozs7Ozt3QkFXMUgsQ0FBQyxLQUFvQyxFQUFFLEVBQUU7SUFDekQsTUFBTSxJQUFJLEdBQUcsS0FBSyxDQUFDLGFBQTRELENBQUM7SUFDaEYsTUFBTSxJQUFJLEdBQUcsS0FBSyxDQUFDLE1BQU0sQ0FBQyxJQUFJLENBQUM7SUFDL0IsSUFBSSxDQUFDLEtBQUssQ0FBQyxJQUFJLEtBQUssSUFBSSxDQUFDLENBQUMsQ0FBQyxNQUFNLENBQUMsQ0FBQyxDQUFDLElBQUksQ0FBQyxDQUFDO0FBQzVDLENBQUM7eUJBQ2tCLENBQUMsS0FBa0QsRUFBRSxFQUFFO0lBQ3hFLE9BQU8sQ0FBQyxHQUFHLENBQUMsZUFBZSxFQUFFLEtBQUssQ0FBQyxNQUFNLENBQUMsQ0FBQztBQUM3QyxDQUFDOzs7Q0FHTixDQUFDLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVlcy10ZXJtaW5hbC12aWV3LmRlbW8uanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi90c193ZWIvZWxlbWVudHMvMDBncm91cC1oYXJuZXNzL2RlZXMtdGVybWluYWwtdmlldy9kZWVzLXRlcm1pbmFsLXZpZXcuZGVtby50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsSUFBSSxFQUFFLE1BQU0sNkJBQTZCLENBQUM7QUFDbkQsT0FBTyxFQUFFLFFBQVEsRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBR3ZELHdGQUF3RjtBQUN4RiwwRUFBMEU7QUFDMUUsTUFBTSxrQkFBa0IsR0FBMEIsRUFBRSxJQUFJLEVBQUUsRUFBRSxFQUFFLElBQUksRUFBRSxFQUFFLEVBQUUsQ0FBQztBQUN6RSxNQUFNLFlBQVksR0FBRyxpREFBaUQsQ0FBQztBQUN2RSxNQUFNLGNBQWMsR0FBRztJQUNyQixHQUFHLFlBQVksWUFBWTtJQUMzQixnREFBZ0Q7SUFDaEQsb0RBQW9EO0lBQ3BELEVBQUU7SUFDRixHQUFHLFlBQVksV0FBVztJQUMxQiw2REFBNkQ7SUFDN0QsK0RBQStEO0lBQy9ELDJEQUEyRDtJQUMzRCxFQUFFO0lBQ0YsWUFBWTtDQUNiLENBQUMsSUFBSSxDQUFDLE1BQU0sQ0FBQyxDQUFDO0FBRWYsTUFBTSxhQUFhLEdBQUcsQ0FBQyxLQUFZLEVBQVEsRUFBRTtJQUMzQyxNQUFNLElBQUksR0FBSSxLQUFLLENBQUMsYUFBNkI7U0FDOUMsT0FBTyxDQUFDLG9CQUFvQixDQUFDO1FBQzlCLEVBQUUsYUFBYSxDQUFDLG9CQUFvQixDQUFDLENBQUM7SUFDeEMsSUFBSSxDQUFDLElBQUk7UUFBRSxPQUFPO0lBQ2xCLDhGQUE4RjtJQUM5Riw2RUFBNkU7SUFDN0UsSUFBSSxDQUFDLE9BQU8sQ0FBQyxjQUFjLEVBQUUsa0JBQWtCLENBQUMsQ0FBQyxJQUFJLENBQ25ELEdBQUcsRUFBRSxDQUFDLElBQUksQ0FBQyxLQUFLLEVBQUUsRUFDbEIsR0FBRyxFQUFFLENBQUMsU0FBUyxDQUNoQixDQUFDO0FBQ0osQ0FBQyxDQUFDO0FBRUYsMEVBQTBFO0FBQzFFLHdEQUF3RDtBQUN4RCxNQUFNLENBQUMsTUFBTSxRQUFRLEdBQUcsR0FBRyxFQUFFLENBQUMsUUFBUSxDQUFDLFVBQVUsRUFBRSxvTUFBb00sRUFBRSxJQUFJLENBQUE7Ozs7Ozs7Ozs7OzhCQVcvTixhQUFhOzs7OzBCQUlqQixDQUFDLEtBQW9DLEVBQUUsRUFBRTtJQUN6RCxNQUFNLElBQUksR0FBRyxLQUFLLENBQUMsYUFBNEQsQ0FBQztJQUNoRixNQUFNLElBQUksR0FBRyxLQUFLLENBQUMsTUFBTSxDQUFDLElBQUksQ0FBQztJQUMvQixJQUFJLENBQUMsS0FBSyxDQUFDLElBQUksS0FBSyxJQUFJLENBQUMsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxDQUFDLENBQUMsSUFBSSxDQUFDLENBQUM7QUFDNUMsQ0FBQzsyQkFDa0IsQ0FBQyxLQUF5QyxFQUFFLEVBQUU7SUFDL0QsT0FBTyxDQUFDLEdBQUcsQ0FBQyxlQUFlLEVBQUUsS0FBSyxDQUFDLE1BQU0sQ0FBQyxDQUFDO0FBQzdDLENBQUM7Ozs7Q0FJUixDQUFDLENBQUMifQ==