@oddkin/workbench 0.0.0-stage → 1.0.0-beta.0

package/dist/panels/theme-studio.js

@@ -0,0 +1,312 @@
+/**
+ * Theme Studio content (workbench.md §6, workbench-pages.md §8): one draft of the library's theme
+ * configuration, edited through a form and a JSON editor; generated in a Worker by the library's
+ * own generator; applied to light and dark specimen frames as a preview-owned stylesheet, so the
+ * real components update in place (no remount). An invalid draft keeps the last valid theme and
+ * lists the generator's diagnostics with their configuration paths.
+ */
+import { OddkinElement, prop } from '@oddkin/core/element';
+import { styleMap } from '@oddkin/core/helpers/style-map';
+import { signal, untracked } from '@oddkin/core/reactive';
+import { createScope } from '@oddkin/core/scope';
+import { html, nothing, repeat } from '@oddkin/core/template';
+import { createIsolatedPreview } from '../preview/frame.js';
+import { createThemeGeneration, } from '../preview/theme-generation.js';
+import { contentStyles, panelHostStyles } from './styles.js';
+import { fieldValue, parseDraft, pathText, setPath, themeFields, } from './theme-model.js';
+const MODES = ['light', 'dark'];
+export class ThemeStudioElement extends OddkinElement.with({
+    page: prop.object({ description: 'The Theme Studio page data.' }),
+    frameUrl: prop.string({
+        default: '',
+        description: 'Same-origin URL of the generated preview frame document.',
+    }),
+}) {
+    static styles = [panelHostStyles, contentStyles];
+    #draft = signal(undefined);
+    #json = signal('');
+    #jsonError = signal('');
+    #result = signal(undefined);
+    #status = signal({
+        text: '',
+        alert: false,
+    });
+    #hosts;
+    #previews = [];
+    #generation;
+    #studioScope;
+    #css;
+    #key;
+    constructor() {
+        super();
+        this.#hosts = [document.createElement('div'), document.createElement('div')];
+    }
+    /** The current draft (for tests and embedding); read-only snapshot. */
+    get draft() {
+        return this.#draft.peek();
+    }
+    /** Light and dark specimen frames, in that order. */
+    get previews() {
+        return this.#previews;
+    }
+    /** Generation counters: requests sent, superseded, and results applied. */
+    get generation() {
+        return this.#generation?.stats;
+    }
+    connected(scope) {
+        scope.effect(() => {
+            const page = this.page;
+            const frameUrl = this.frameUrl;
+            untracked(() => {
+                if (page === this.#key)
+                    return;
+                this.#key = page;
+                this.#start(page, frameUrl);
+            });
+        });
+        scope.add(() => {
+            this.#key = undefined;
+            this.#stop();
+        });
+    }
+    #stop() {
+        this.#studioScope?.dispose();
+        this.#studioScope = undefined;
+        this.#previews = [];
+        this.#generation = undefined;
+        this.#css = undefined;
+        for (const host of this.#hosts)
+            host.replaceChildren();
+    }
+    #start(page, frameUrl) {
+        this.#stop();
+        const studio = page?.studio;
+        this.#draft.value = studio?.config;
+        this.#json.value = studio?.config ? JSON.stringify(studio.config, null, 2) : '';
+        this.#jsonError.value = '';
+        this.#result.value = undefined;
+        this.#status.value = { text: '', alert: false };
+        if (!page || !studio?.config || !studio.worker)
+            return;
+        const scope = createScope({ name: 'workbench-theme-studio' });
+        this.#studioScope = scope;
+        this.#generation = createThemeGeneration(studio.worker, scope, (result) => this.#apply(result), (message) => {
+            this.#status.value = { text: `Generation unavailable: ${message}`, alert: true };
+        });
+        if (frameUrl && studio.roles.length)
+            this.#specimens(scope, page, frameUrl);
+        this.#generation.request(studio.config);
+    }
+    #specimens(scope, page, frameUrl) {
+        const items = page.studio.roles.map((role) => ({
+            role: role.role,
+            label: role.label,
+            tag: role.tag,
+            registration: role.registration,
+            example: role.example,
+            properties: role.properties,
+            attributes: role.attributes,
+            slots: role.slots,
+        }));
+        MODES.forEach((mode, i) => {
+            const preview = createIsolatedPreview({
+                document: this.ownerDocument,
+                container: this.#hosts[i],
+                frameUrl,
+                title: `Theme specimen (${mode})`,
+            });
+            preview.iframe.style.blockSize = '40rem';
+            scope.add(() => preview.dispose(), 'specimen frame');
+            this.#previews.push(preview);
+            void preview.ready
+                .then(() => preview.request('specimen', { items, settings: { mode } }))
+                .then(() => (this.#css === undefined ? undefined : this.#theme(preview, this.#css)))
+                .catch((error) => {
+                if (!scope.disposed)
+                    this.#status.value = {
+                        text: `Specimen unavailable: ${error instanceof Error ? error.message : String(error)}`,
+                        alert: true,
+                    };
+            });
+        });
+    }
+    #theme(preview, css) {
+        return preview.request('theme', { cssText: css });
+    }
+    /** A valid result replaces the specimens' theme sheet; an invalid one keeps the last valid. */
+    #apply(result) {
+        this.#result.value = result;
+        if (!result.ok || result.css === undefined)
+            return;
+        this.#css = result.css;
+        for (const preview of this.#previews)
+            void this.#theme(preview, result.css).catch(() => {
+                // Not connected yet: the sheet is applied once its specimen has mounted.
+            });
+    }
+    #setDraft(draft, fromJson = false) {
+        this.#draft.value = draft;
+        if (!fromJson) {
+            this.#json.value = JSON.stringify(draft, null, 2);
+            this.#jsonError.value = '';
+        }
+        this.#generation?.request(draft);
+    }
+    #field(field) {
+        const id = `ts-${field.path.join('-')}`;
+        const swatch = field.kind === 'color' &&
+            typeof field.value === 'string' &&
+            globalThis.CSS?.supports('color', field.value)
+            ? html `<span
+            class="wb-swatch"
+            aria-hidden="true"
+            style=${styleMap({ background: field.value })}
+          ></span>`
+            : nothing;
+        return html `<div class="wb-field">
+      <label for=${id}>${field.label}</label>
+      <span class="wb-cell-controls"
+        >${swatch}<input
+          id=${id}
+          type=${field.kind === 'number' || field.kind === 'integer' ? 'number' : 'text'}
+          step=${field.kind === 'integer' ? '1' : 'any'}
+          .value=${field.value === undefined ? '' : String(field.value)}
+          placeholder="Not set (generated)"
+          data-path=${pathText(field.path)}
+          aria-describedby=${`${id}-origin`}
+          @change=${(event) => this.#setDraft(setPath(this.#draft.peek(), field.path, fieldValue(field, event.target.value)))}
+      /></span>
+      <span id=${`${id}-origin`} class="wb-muted">${field.origin}</span>
+    </div>`;
+    }
+    render() {
+        const studio = this.page?.studio;
+        if (!studio)
+            return html `<div class="wb-content"></div>`;
+        const draft = this.#draft.value;
+        const result = this.#result.value;
+        const status = this.#status.value;
+        const groups = draft === undefined ? [] : themeFields(draft);
+        const problems = result?.diagnostics ?? [];
+        return html `<div class="wb-content">
+      <section id="generate" aria-labelledby="generate-title">
+        <h2 id="generate-title">Generate</h2>
+        ${studio.source
+            ? html `<p class="wb-muted">
+                Draft of <code>${studio.source}</code>. Edits stay in this page until exported.
+              </p>`
+            : nothing}
+        ${repeat(groups, (group) => group.id, (group) => html `<fieldset class="wb-group" data-group=${group.id}>
+              <legend>${group.title}</legend>
+              ${group.note ? html `<p class="wb-muted">${group.note}</p>` : nothing}
+              ${repeat(group.fields, (field) => pathText(field.path), (field) => this.#field(field))}
+              ${group.rows?.length
+            ? html `<div class="wb-table-wrap">
+                      <table>
+                        <caption class="wb-visually-hidden">
+                          ${group.title}, one column per mode
+                        </caption>
+                        <thead>
+                          <tr>
+                            <th scope="col">Token</th>
+                            ${(group.modes ?? []).map((mode) => html `<th scope="col">${mode}</th>`)}
+                          </tr>
+                        </thead>
+                        <tbody>
+                          ${repeat(group.rows, (row) => row.token, (row) => html `<tr>
+                                <th scope="row"><code>${row.token}</code></th>
+                                ${row.cells.map((cell) => html `<td>
+                                      <input
+                                        aria-label=${cell.label}
+                                        .value=${cell.value === undefined ? '' : String(cell.value)}
+                                        data-path=${pathText(cell.path)}
+                                        @change=${(event) => this.#setDraft(setPath(this.#draft.peek(), cell.path, fieldValue(cell, event.target.value)))}
+                                      />
+                                    </td>`)}
+                              </tr>`)}
+                        </tbody>
+                      </table>
+                    </div>`
+            : nothing}
+            </fieldset>`)}
+        ${draft === undefined
+            ? nothing
+            : html `<div class="wb-field wb-json">
+                <label for="ts-json">Configuration (JSON)</label>
+                <textarea
+                  id="ts-json"
+                  class="wb-code"
+                  rows="16"
+                  spellcheck="false"
+                  aria-describedby="ts-json-error"
+                  .value=${this.#json.value}
+                  @input=${(event) => {
+                const text = event.target.value;
+                this.#json.value = text;
+                const parsed = parseDraft(text);
+                this.#jsonError.value = parsed.ok ? '' : (parsed.message ?? '');
+                if (parsed.ok)
+                    this.#setDraft(parsed.value, true);
+            }}
+                ></textarea>
+                <p id="ts-json-error" class="wb-error" ?hidden=${!this.#jsonError.value}>
+                  ${this.#jsonError.value
+                ? `Not applied: ${this.#jsonError.value} The preview keeps the last valid draft.`
+                : ''}
+                </p>
+              </div>`}
+      </section>
+      <section id="live-preview" aria-labelledby="live-preview-title">
+        <h2 id="live-preview-title">Live preview</h2>
+        <p class="wb-status" role=${status.alert || (result && !result.ok) ? 'alert' : 'status'}>
+          ${status.text ||
+            (result
+                ? result.ok
+                    ? `Generated in ${Math.round(result.ms)} ms.`
+                    : 'This draft is invalid: the preview keeps the last valid theme.'
+                : '')}
+        </p>
+        ${problems.length
+            ? html `<ul class="wb-list" aria-label="Generator diagnostics">
+                ${problems.map((d) => html `<li data-severity=${d.severity ?? 'error'}>
+                      <code>${d.path || '/'}</code> ${d.message ?? d.code ?? ''}
+                    </li>`)}
+              </ul>`
+            : nothing}
+        <div class="wb-previews wb-pair">
+          ${MODES.map((mode, i) => html `<div class="wb-preview">
+                <p>${mode === 'light' ? 'Light' : 'Dark'}</p>
+                ${this.#hosts[i]}
+              </div>`)}
+        </div>
+        ${studio.roles.length
+            ? html `<p class="wb-muted">
+                Roles:
+                ${studio.roles.map((r) => `${r.label} (<${r.tag}>, ${r.source === 'config' ? 'configured' : 'claimed by its example'})`).join(' · ')}.
+              </p>`
+            : nothing}
+      </section>
+      <section id="method" aria-labelledby="method-title">
+        <h2 id="method-title">Method and limits</h2>
+        <p>
+          The draft is generated by the library's own theme generator in a Worker; the newest edit
+          wins and older results are discarded. Generated CSS replaces one stylesheet in each
+          specimen frame, so the components keep their state.
+        </p>
+        ${studio.missing.length
+            ? html `<ul class="wb-list" aria-label="Not available">
+                ${studio.missing.map((m) => html `<li class="wb-not-documented" data-missing=${m.item}>
+                      ${m.item.startsWith('role:')
+                ? `No specimen for the ${m.item.slice(5)} role.`
+                : m.item === 'config'
+                    ? 'No theme configuration to edit.'
+                    : 'No theme generator.'}
+                      Supplied by ${m.supply}.
+                    </li>`)}
+              </ul>`
+            : nothing}
+      </section>
+    </div>`;
+    }
+}
+//# sourceMappingURL=theme-studio.js.map

package/dist/panels/theme-studio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-studio.js","sourceRoot":"","sources":["../../src/panels/theme-studio.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAc,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAG9D,OAAO,EAAE,qBAAqB,EAAwB,MAAM,qBAAqB,CAAC;AAClF,OAAO,EACL,qBAAqB,GAGtB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EACL,UAAU,EACV,UAAU,EACV,QAAQ,EACR,OAAO,EACP,WAAW,GAEZ,MAAM,kBAAkB,CAAC;AAE1B,MAAM,KAAK,GAAG,CAAC,OAAO,EAAE,MAAM,CAAU,CAAC;AAEzC,MAAM,OAAO,kBAAmB,SAAQ,aAAa,CAAC,IAAI,CAAC;IACzD,IAAI,EAAE,IAAI,CAAC,MAAM,CAAsB,EAAE,WAAW,EAAE,6BAA6B,EAAE,CAAC;IACtF,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC;QACpB,OAAO,EAAE,EAAE;QACX,WAAW,EAAE,0DAA0D;KACxE,CAAC;CACH,CAAC;IACA,MAAM,CAAU,MAAM,GAAe,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC;IAE7D,MAAM,GAAG,MAAM,CAAU,SAAS,CAAC,CAAC;IACpC,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;IACnB,UAAU,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;IACxB,OAAO,GAAG,MAAM,CAA+B,SAAS,CAAC,CAAC;IAC1D,OAAO,GAAG,MAAM,CAAqD;QAC5E,IAAI,EAAE,EAAE;QACR,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;IACM,MAAM,CAA4C;IAC3D,SAAS,GAAsB,EAAE,CAAC;IAClC,WAAW,CAA8B;IACzC,YAAY,CAAoB;IAChC,IAAI,CAAqB;IACzB,IAAI,CAAkC;IAEtC;QACE,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,MAAM,GAAG,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/E,CAAC;IAED,uEAAuE;IACvE,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC5B,CAAC;IAED,qDAAqD;IACrD,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,2EAA2E;IAC3E,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC;IACjC,CAAC;IAEkB,SAAS,CAAC,KAAY;QACvC,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE;YAChB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;YACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC/B,SAAS,CAAC,GAAG,EAAE;gBACb,IAAI,IAAI,KAAK,IAAI,CAAC,IAAI;oBAAE,OAAO;gBAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;gBACjB,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YAC9B,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YACb,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC;YACtB,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK;QACH,IAAI,CAAC,YAAY,EAAE,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;QAC9B,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;QACpB,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC;QACtB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,MAAM;YAAE,IAAI,CAAC,eAAe,EAAE,CAAC;IACzD,CAAC;IAED,MAAM,CAAC,IAAqC,EAAE,QAAgB;QAC5D,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC;QAC5B,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,MAAM,EAAE,MAAM,CAAC;QACnC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,IAAI,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC;QAC3B,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC;QAC/B,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAChD,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM;YAAE,OAAO;QACvD,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,IAAI,EAAE,wBAAwB,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;QAC1B,IAAI,CAAC,WAAW,GAAG,qBAAqB,CACtC,MAAM,CAAC,MAAM,EACb,KAAK,EACL,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAC/B,CAAC,OAAO,EAAE,EAAE;YACV,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,EAAE,IAAI,EAAE,2BAA2B,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACnF,CAAC,CACF,CAAC;QACF,IAAI,QAAQ,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM;YAAE,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC5E,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;IAED,UAAU,CAAC,KAAY,EAAE,IAAyB,EAAE,QAAgB;QAClE,MAAM,KAAK,GAAwB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAClE,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB,CAAC,CAAC,CAAC;QACJ,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;YACxB,MAAM,OAAO,GAAG,qBAAqB,CAAC;gBACpC,QAAQ,EAAE,IAAI,CAAC,aAAa;gBAC5B,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAmB;gBAC3C,QAAQ;gBACR,KAAK,EAAE,mBAAmB,IAAI,GAAG;aAClC,CAAC,CAAC;YACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,GAAG,OAAO,CAAC;YACzC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,gBAAgB,CAAC,CAAC;YACrD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC7B,KAAK,OAAO,CAAC,KAAK;iBACf,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;iBACtE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;iBACnF,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBACxB,IAAI,CAAC,KAAK,CAAC,QAAQ;oBACjB,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG;wBACnB,IAAI,EAAE,yBAAyB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;wBACvF,KAAK,EAAE,IAAI;qBACZ,CAAC;YACN,CAAC,CAAC,CAAC;QACP,CAAC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,OAAwB,EAAE,GAAW;QAC1C,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,+FAA+F;IAC/F,MAAM,CAAC,MAAwB;QAC7B,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC;QAC5B,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS;YAAE,OAAO;QACnD,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC;QACvB,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,SAAS;YAClC,KAAK,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;gBAC/C,yEAAyE;YAC3E,CAAC,CAAC,CAAC;IACP,CAAC;IAED,SAAS,CAAC,KAAc,EAAE,QAAQ,GAAG,KAAK;QACxC,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;QAC1B,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YAClD,IAAI,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC;QAC7B,CAAC;QACD,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC;IAED,MAAM,CAAC,KAAiB;QACtB,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACxC,MAAM,MAAM,GACV,KAAK,CAAC,IAAI,KAAK,OAAO;YACtB,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;YAC/B,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC;YAC5C,CAAC,CAAC,IAAI,CAAA;;;oBAGM,QAAQ,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;mBACtC;YACX,CAAC,CAAC,OAAO,CAAC;QACd,OAAO,IAAI,CAAA;mBACI,EAAE,IAAI,KAAK,CAAC,KAAK;;WAEzB,MAAM;eACF,EAAE;iBACA,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM;iBACvE,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK;mBACpC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;;sBAEjD,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;6BACb,GAAG,EAAE,SAAS;oBACvB,CAAC,KAAY,EAAE,EAAE,CACzB,IAAI,CAAC,SAAS,CACZ,OAAO,CACL,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAClB,KAAK,CAAC,IAAI,EACV,UAAU,CAAC,KAAK,EAAG,KAAK,CAAC,MAA2B,CAAC,KAAK,CAAC,CAC5D,CACF;;iBAEI,GAAG,EAAE,SAAS,qBAAqB,KAAK,CAAC,MAAM;WACrD,CAAC;IACV,CAAC;IAEkB,MAAM;QACvB,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC;QACjC,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAA,gCAAgC,CAAC;QACzD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;QAClC,MAAM,MAAM,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAC7D,MAAM,QAAQ,GAAG,MAAM,EAAE,WAAW,IAAI,EAAE,CAAC;QAC3C,OAAO,IAAI,CAAA;;;UAIL,MAAM,CAAC,MAAM;YACX,CAAC,CAAC,IAAI,CAAA;iCACe,MAAM,CAAC,MAAM;mBAC3B;YACP,CAAC,CAAC,OACN;UACE,MAAM,CACN,MAAM,EACN,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,EACnB,CAAC,KAAK,EAAE,EAAE,CACR,IAAI,CAAA,yCAAyC,KAAK,CAAC,EAAE;wBACzC,KAAK,CAAC,KAAK;gBACnB,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAA,uBAAuB,KAAK,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,OAAO;gBAClE,MAAM,CACN,KAAK,CAAC,MAAM,EACZ,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAC/B,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAC9B;gBAEC,KAAK,CAAC,IAAI,EAAE,MAAM;YAChB,CAAC,CAAC,IAAI,CAAA;;;4BAGI,KAAK,CAAC,KAAK;;;;;8BAKT,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAA,mBAAmB,IAAI,OAAO,CAAC;;;;4BAIvE,MAAM,CACN,KAAK,CAAC,IAAI,EACV,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,EAClB,CAAC,GAAG,EAAE,EAAE,CACN,IAAI,CAAA;wDACsB,GAAG,CAAC,KAAK;kCAC/B,GAAG,CAAC,KAAK,CAAC,GAAG,CACb,CAAC,IAAI,EAAE,EAAE,CACP,IAAI,CAAA;;qDAEa,IAAI,CAAC,KAAK;iDACd,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;oDAC/C,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;kDACrB,CAAC,KAAY,EAAE,EAAE,CACzB,IAAI,CAAC,SAAS,CACZ,OAAO,CACL,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAClB,IAAI,CAAC,IAAI,EACT,UAAU,CACR,IAAI,EACH,KAAK,CAAC,MAA2B,CAAC,KAAK,CACzC,CACF,CACF;;0CAED,CACT;oCACG,CACT;;;2BAGA;YACT,CAAC,CAAC,OACN;wBACU,CACf;UAEC,KAAK,KAAK,SAAS;YACjB,CAAC,CAAC,OAAO;YACT,CAAC,CAAC,IAAI,CAAA;;;;;;;;2BAQS,IAAI,CAAC,KAAK,CAAC,KAAK;2BAChB,CAAC,KAAY,EAAE,EAAE;gBACxB,MAAM,IAAI,GAAI,KAAK,CAAC,MAA8B,CAAC,KAAK,CAAC;gBACzD,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;gBACxB,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;gBAChC,IAAI,CAAC,UAAU,CAAC,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;gBAChE,IAAI,MAAM,CAAC,EAAE;oBAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YACpD,CAAC;;iEAE8C,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK;oBAEnE,IAAI,CAAC,UAAU,CAAC,KAAK;gBACnB,CAAC,CAAC,gBAAgB,IAAI,CAAC,UAAU,CAAC,KAAK,0CAA0C;gBACjF,CAAC,CAAC,EACN;;qBAGV;;;;oCAI4B,MAAM,CAAC,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ;YAEnF,MAAM,CAAC,IAAI;YACX,CAAC,MAAM;gBACL,CAAC,CAAC,MAAM,CAAC,EAAE;oBACT,CAAC,CAAC,gBAAgB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM;oBAC7C,CAAC,CAAC,gEAAgE;gBACpE,CAAC,CAAC,EAAE,CACR;;UAGA,QAAQ,CAAC,MAAM;YACb,CAAC,CAAC,IAAI,CAAA;kBACA,QAAQ,CAAC,GAAG,CACZ,CAAC,CAAC,EAAE,EAAE,CACJ,IAAI,CAAA,qBAAqB,CAAC,CAAC,QAAQ,IAAI,OAAO;8BACpC,CAAC,CAAC,IAAI,IAAI,GAAG,WAAW,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,IAAI,EAAE;0BACrD,CACT;oBACG;YACR,CAAC,CAAC,OACN;;YAEI,KAAK,CAAC,GAAG,CACT,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CACV,IAAI,CAAA;qBACG,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;kBACtC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;qBACX,CACV;;UAGD,MAAM,CAAC,KAAK,CAAC,MAAM;YACjB,CAAC,CAAC,IAAI,CAAA;;kBAEA,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,wBAAwB,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;mBACjI;YACP,CAAC,CAAC,OACN;;;;;;;;;UAUE,MAAM,CAAC,OAAO,CAAC,MAAM;YACnB,CAAC,CAAC,IAAI,CAAA;kBACA,MAAM,CAAC,OAAO,CAAC,GAAG,CAClB,CAAC,CAAC,EAAE,EAAE,CACJ,IAAI,CAAA,8CAA8C,CAAC,CAAC,IAAI;wBAEpD,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;gBACxB,CAAC,CAAC,uBAAuB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ;gBAChD,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ;oBACnB,CAAC,CAAC,iCAAiC;oBACnC,CAAC,CAAC,qBACR;oCACc,CAAC,CAAC,MAAM;0BAClB,CACT;oBACG;YACR,CAAC,CAAC,OACN;;WAEG,CAAC;IACV,CAAC;CACF"}

package/dist/preview/frame.d.ts

@@ -0,0 +1,44 @@
+import { type FrameIdentity, type FrameNotification, type FrameRequest, type FrameRequestPayload, type JsonValue } from '../protocol/index.js';
+declare const protocolStats: {
+    liveFrames: number;
+    rejectedMessages: number;
+    staleMessages: number;
+    disposedMessages: number;
+};
+/** Counts protocol rejections and live host frames; resource ownership is also measured by `scopeStats()`. */
+export declare function previewProtocolStats(): Readonly<typeof protocolStats>;
+export interface IsolatedPreviewOptions {
+    readonly document: Document;
+    readonly container: Element;
+    /** Same-origin URL of the generated frame document. */
+    readonly frameUrl: string;
+    readonly title: string;
+    readonly generation?: number;
+    /** How long the handshake and each request may wait for the frame (default 10 000 ms). */
+    readonly timeoutMs?: number;
+    /**
+     * How long a `mount` or `specimen` request may wait (default 60 000 ms). Both import component
+     * module graphs, which a cold, unbundled load can take seconds to fetch; a failed import is
+     * reported by the frame, so this only bounds a fetch that never settles.
+     */
+    readonly mountTimeoutMs?: number;
+    readonly onMessage?: (message: FrameNotification) => void;
+}
+export interface IsolatedPreview {
+    readonly iframe: HTMLIFrameElement;
+    readonly identity: FrameIdentity;
+    readonly ready: Promise<void>;
+    request(kind: FrameRequest['kind'], payload?: FrameRequestPayload): Promise<JsonValue | undefined>;
+    setViewport(width: number, height: number): void;
+    /** Replace the frame document and advance its generation. */
+    reload(): Promise<void>;
+    dispose(): void;
+}
+export declare class PreviewFrameError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Create one same-origin, independently registered preview frame. */
+export declare function createIsolatedPreview(options: IsolatedPreviewOptions): IsolatedPreview;
+export {};
+//# sourceMappingURL=frame.d.ts.map

package/dist/preview/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../src/preview/frame.ts"],"names":[],"mappings":"AACA,OAAO,EAOL,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACf,MAAM,sBAAsB,CAAC;AAE9B,QAAA,MAAM,aAAa;IAAK,UAAU;IAAK,gBAAgB;IAAK,aAAa;IAAK,gBAAgB;CAAK,CAAC;AAOpG,8GAA8G;AAC9G,wBAAgB,oBAAoB,IAAI,QAAQ,CAAC,OAAO,aAAa,CAAC,CAErE;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,0FAA0F;IAC1F,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC3D;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,CACL,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAC1B,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;IAClC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACjD,6DAA6D;IAC7D,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAExC,QAAQ,CAAC,IAAI,EAAE,MAAM;IADvB,YACW,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EAIhB;CACF;AAED,sEAAsE;AACtE,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,eAAe,CAuQtF"}

package/dist/preview/frame.js

@@ -0,0 +1,250 @@
+import { createScope } from '@oddkin/core/scope';
+import { FRAME_PROTOCOL_VERSION, frameEnvelope, isCompatibleFrameMessage, isFrameMessage, isFrameReply, isFrameRequest, } from '../protocol/index.js';
+const protocolStats = { liveFrames: 0, rejectedMessages: 0, staleMessages: 0, disposedMessages: 0 };
+let nextFrameId = 0;
+const isObjectPayload = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** Counts protocol rejections and live host frames; resource ownership is also measured by `scopeStats()`. */
+export function previewProtocolStats() {
+    return { ...protocolStats };
+}
+export class PreviewFrameError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'PreviewFrameError';
+    }
+}
+/** Create one same-origin, independently registered preview frame. */
+export function createIsolatedPreview(options) {
+    const { document: doc, container } = options;
+    const win = doc.defaultView;
+    if (!win)
+        throw new Error('A preview frame needs a live owner document.');
+    const frameUrl = new URL(options.frameUrl, doc.baseURI);
+    if (frameUrl.origin !== win.location.origin)
+        throw new TypeError('Preview frames must use the Workbench origin.');
+    const frame = `preview-${++nextFrameId}`;
+    let generation = options.generation ?? 1;
+    if (!Number.isSafeInteger(generation) || generation < 1)
+        throw new TypeError('Preview generation must be a positive integer.');
+    const scope = createScope({
+        name: `preview-host:${frame}:${generation}`,
+    });
+    const iframe = doc.createElement('iframe');
+    iframe.title = options.title;
+    iframe.style.cssText = 'display:block;inline-size:100%;block-size:24rem;border:0;';
+    container.append(iframe);
+    protocolStats.liveFrames++;
+    scope.add(() => {
+        protocolStats.liveFrames--;
+        iframe.remove();
+    }, 'preview frame');
+    let port;
+    let generationScope;
+    let nextRequestId = 0;
+    let connected = false;
+    let ready;
+    let finishReady = () => { };
+    let cancelHandshake = () => { };
+    const pending = new Map();
+    const expectedOrigin = frameUrl.origin;
+    const identity = () => ({ frame, generation });
+    const rejectPending = (error) => {
+        for (const request of pending.values())
+            request.reject(error);
+        pending.clear();
+    };
+    scope.add(() => {
+        const error = new PreviewFrameError('frame.disposed', 'The preview frame was disposed.');
+        finishReady(error);
+        rejectPending(error);
+        generationScope?.dispose(error);
+    }, 'pending frame requests');
+    const fail = (error) => {
+        finishReady(error);
+        scope.dispose(error);
+    };
+    const startGeneration = () => {
+        const current = identity();
+        const currentScope = scope.child({
+            name: `preview-host:${current.frame}:${current.generation}`,
+        });
+        generationScope = currentScope;
+        connected = false;
+        ready = new Promise((resolve, reject) => {
+            let settled = false;
+            finishReady = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+        });
+        const url = new URL(frameUrl);
+        url.searchParams.set('frame', current.frame);
+        url.searchParams.set('generation', String(current.generation));
+        cancelHandshake = currentScope.timeout(() => fail(new PreviewFrameError('frame.handshake.timeout', `Frame did not connect within ${timeoutMs} ms.`)), timeoutMs);
+        currentScope.add(() => cancelHandshake(), 'handshake timeout');
+        iframe.src = url.href;
+    };
+    scope.listen(win, 'message', (event) => {
+        const currentScope = generationScope;
+        const currentIdentity = identity();
+        if (scope.disposed || !currentScope || currentScope.disposed) {
+            protocolStats.disposedMessages++;
+            return;
+        }
+        if (event.source !== iframe.contentWindow || event.origin !== expectedOrigin) {
+            protocolStats.rejectedMessages++;
+            return;
+        }
+        const message = event.data;
+        if (!isFrameMessage(message) || message.kind !== 'hello') {
+            protocolStats.rejectedMessages++;
+            return;
+        }
+        if (message.version !== FRAME_PROTOCOL_VERSION) {
+            fail(new PreviewFrameError('frame.version.incompatible', `Frame protocol ${message.version} is incompatible with host protocol ${FRAME_PROTOCOL_VERSION}.`));
+            return;
+        }
+        if (message.frame !== currentIdentity.frame ||
+            message.generation !== currentIdentity.generation) {
+            protocolStats.staleMessages++;
+            return;
+        }
+        if (connected) {
+            protocolStats.rejectedMessages++;
+            return;
+        }
+        const Channel = win.MessageChannel;
+        if (!Channel) {
+            fail(new PreviewFrameError('frame.channel.unavailable', 'MessageChannel is unavailable.'));
+            return;
+        }
+        const channel = new Channel();
+        port = channel.port1;
+        connected = true;
+        currentScope.add(() => channel.port1.close(), 'preview message port');
+        currentScope.listen(port, 'message', (portEvent) => {
+            if (scope.disposed || currentScope.disposed) {
+                protocolStats.disposedMessages++;
+                return;
+            }
+            const incoming = portEvent.data;
+            if (!isCompatibleFrameMessage(incoming) ||
+                incoming.frame !== currentIdentity.frame ||
+                incoming.generation !== currentIdentity.generation) {
+                protocolStats.staleMessages++;
+                return;
+            }
+            if (isFrameReply(incoming)) {
+                const request = pending.get(incoming.replyTo);
+                if (!request) {
+                    protocolStats.rejectedMessages++;
+                    return;
+                }
+                pending.delete(incoming.replyTo);
+                if (incoming.error)
+                    request.reject(new PreviewFrameError(incoming.error.code, incoming.error.message));
+                else
+                    request.resolve(incoming.payload);
+            }
+            else if (incoming.kind === 'event' ||
+                incoming.kind === 'error' ||
+                incoming.kind === 'state' ||
+                incoming.kind === 'size') {
+                if (incoming.kind === 'state' &&
+                    isObjectPayload(incoming.payload) &&
+                    incoming.payload['connected'] === true) {
+                    finishReady();
+                    cancelHandshake();
+                }
+                options.onMessage?.(incoming);
+            }
+            else
+                protocolStats.rejectedMessages++;
+        });
+        port.start();
+        const connect = frameEnvelope(currentIdentity, 'connect');
+        iframe.contentWindow?.postMessage(connect, expectedOrigin, [channel.port2]);
+    });
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const mountTimeoutMs = options.mountTimeoutMs ?? 60_000;
+    startGeneration();
+    return {
+        iframe,
+        get identity() {
+            return identity();
+        },
+        get ready() {
+            return ready;
+        },
+        async request(kind, payload) {
+            const requestIdentity = identity();
+            const requestReady = ready;
+            await requestReady;
+            if (identity().generation !== requestIdentity.generation)
+                throw new PreviewFrameError('frame.generation.superseded', 'The preview frame was replaced.');
+            if (scope.disposed || !port)
+                throw new PreviewFrameError('frame.disposed', 'The preview frame is not connected.');
+            const id = ++nextRequestId;
+            const limit = kind === 'mount' || kind === 'specimen' ? mountTimeoutMs : timeoutMs;
+            return new Promise((resolve, reject) => {
+                const releaseTimer = scope.timeout(() => {
+                    pending.delete(id);
+                    reject(new PreviewFrameError('frame.request.timeout', `Frame request ${id} timed out.`));
+                }, limit);
+                pending.set(id, {
+                    resolve: (value) => {
+                        releaseTimer();
+                        resolve(value);
+                    },
+                    reject: (error) => {
+                        releaseTimer();
+                        reject(error);
+                    },
+                });
+                const request = {
+                    ...frameEnvelope(requestIdentity, kind),
+                    id,
+                    ...(payload === undefined ? {} : { payload }),
+                };
+                if (!isFrameRequest(request)) {
+                    pending.delete(id);
+                    releaseTimer();
+                    reject(new TypeError(`Invalid ${kind} frame request payload.`));
+                    return;
+                }
+                port?.postMessage(request);
+            });
+        },
+        setViewport(width, height) {
+            if (!Number.isFinite(width) || width <= 0 || !Number.isFinite(height) || height <= 0)
+                throw new RangeError('Preview viewport dimensions must be positive finite numbers.');
+            iframe.style.inlineSize = `${width}px`;
+            iframe.style.blockSize = `${height}px`;
+            iframe.width = String(Math.round(width));
+            iframe.height = String(Math.round(height));
+        },
+        reload() {
+            if (scope.disposed)
+                return Promise.reject(new PreviewFrameError('frame.disposed', 'The preview frame is not connected.'));
+            const error = new PreviewFrameError('frame.generation.superseded', 'The preview frame was replaced by a new generation.');
+            finishReady(error);
+            rejectPending(error);
+            generationScope?.dispose(error);
+            port = undefined;
+            generation++;
+            startGeneration();
+            return ready;
+        },
+        dispose() {
+            scope.dispose();
+        },
+    };
+}
+//# sourceMappingURL=frame.js.map

package/dist/preview/frame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.js","sourceRoot":"","sources":["../../src/preview/frame.ts"],"names":[],"mappings":"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"}