@design.estate/wcctools 5.1.0 → 6.1.0

package/ts_web/elements/wcc-standalone-notice.ts

@@ -0,0 +1,65 @@
+import { DeesElement, html, customElement, type TemplateResult, css } from '@design.estate/dees-element';
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'wcc-standalone-notice': WccStandaloneNotice;
+  }
+}
+
+/**
+ * Shown when a catalog bundle is opened outside `wcctools dev`: the catalog UI lives in the
+ * wcctools shell, which loads this document into its preview frame.
+ */
+@customElement('wcc-standalone-notice')
+export class WccStandaloneNotice extends DeesElement {
+  public static styles = [
+    css`
+      :host {
+        position: fixed;
+        inset: 0;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        padding: 24px;
+        background: #0a0a0a;
+        color: #e5e5e5;
+        font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif;
+      }
+      .card {
+        max-width: 480px;
+        padding: 24px 28px;
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        border-radius: 8px;
+        background: #0f0f0f;
+      }
+      h1 {
+        margin: 0 0 8px;
+        font-size: 16px;
+        font-weight: 600;
+      }
+      p {
+        margin: 0 0 12px;
+        font-size: 13px;
+        line-height: 1.5;
+        color: #a3a3a3;
+      }
+      code {
+        padding: 2px 6px;
+        border-radius: 4px;
+        background: #1a1a1a;
+        color: #e5e5e5;
+        font-size: 12px;
+      }
+    `,
+  ];
+
+  public render(): TemplateResult {
+    return html`
+      <div class="card" role="status">
+        <h1>This catalog runs in wcctools dev</h1>
+        <p>The page you opened is the catalog's preview document. The catalog UI loads it into its preview frame.</p>
+        <p>Start it with <code>pnpm exec wcctools dev</code> and open the address it prints.</p>
+      </div>
+    `;
+  }
+}

package/ts_web/elements/wcctools.helpers.ts

@@ -1,4 +1,5 @@
 import type { TemplateResult } from 'lit';
+import type * as plugins from '../wcctools.plugins.js';
 
 export type TTemplateFactory = () => TemplateResult | Promise<TemplateResult>;
 
@@ -77,8 +78,6 @@ export const getElementDemoGroups = (itemArg: unknown): string[] => {
   return list.filter((groupArg): groupArg is string => typeof groupArg === 'string' && groupArg.length > 0);
 };
 
-export type TPropertyType = 'String' | 'Number' | 'Boolean' | 'Object' | 'Enum' | 'Array';
-
 export interface IReactivePropertyDeclaration {
   state?: boolean;
   type?: unknown;
@@ -97,7 +96,7 @@ const isEnumerationType = (typeArg: unknown): boolean => {
 
 export const determinePropertyType = (
   propertyArg: IReactivePropertyDeclaration
-): TPropertyType | null => {
+): plugins.interfaces.TWccPropertyKind | null => {
   if (!propertyArg || typeof propertyArg !== 'object' || propertyArg.state) {
     return null;
   }
@@ -144,10 +143,3 @@ export const getDemoAtIndex = (demo: TDemoDefinition, index: number): TTemplateF
   // Single demo - only index 0 is valid
   return index === 0 ? demo : null;
 };
-
-/**
- * Check if an element has multiple demos
- */
-export const hasMultipleDemos = (demo: TDemoDefinition): boolean => {
-  return Array.isArray(demo) && demo.length > 1;
-};

package/ts_web/index.ts

@@ -1,16 +1,35 @@
-import { WccDashboard } from './elements/wcc-dashboard.js';
-import type { IWccConfig, IWccSection } from './wcctools.interfaces.js';
+import * as plugins from './wcctools.plugins.js';
+import { WccCatalog } from './catalog.js';
+import { WccPreview } from './elements/wcc-preview.js';
+import { WccStandaloneNotice } from './elements/wcc-standalone-notice.js';
+import { WccPreviewBridge } from './previewbridge.js';
+import type { IWccConfig } from './wcctools.interfaces.js';
 
-// Export recording components and service
-export { RecorderService, type IRecorderEvents, type IRecordingOptions, type TOutputFormat } from './services/recorder.service.js';
-export { WccRecordButton } from './elements/wcc-record-button.js';
-export { WccRecordingPanel } from './elements/wcc-recording-panel.js';
-
-// Export types for external use
 export type { IWccConfig, IWccSection } from './wcctools.interfaces.js';
 
 /**
- * Set up the WCC Tools dashboard:
+ * Start the preview document of a catalog. `wcctools dev` loads this document into the shell's
+ * preview frame; opened on the preview route it renders the one demo the route names.
+ * Opened anywhere else it shows how to start the catalog.
+ */
+const startPreview = async (configArg: IWccConfig) => {
+  const isFramed = window.parent !== window;
+  if (!isFramed && window.location.pathname !== plugins.shared.previewRoutePath) {
+    document.body.append(new WccStandaloneNotice());
+    return;
+  }
+  const preview = new WccPreview();
+  document.body.append(preview);
+  const bridge = new WccPreviewBridge(new WccCatalog(configArg), preview);
+  await bridge.renderRoute(plugins.shared.parsePreviewQuery(window.location.search));
+  window.wccPreview = bridge;
+  if (isFramed) {
+    window.parent.postMessage(plugins.shared.previewReadyMessage, window.location.origin);
+  }
+};
+
+/**
+ * Set up the catalog's preview document:
  * ```typescript
  * setupWccTools({
  *   sections: [
@@ -20,17 +39,17 @@ export type { IWccConfig, IWccSection } from './wcctools.interfaces.js';
  * });
  * ```
  */
-const setupWccTools = (config: IWccConfig) => {
-  let hasRun = false;
-  const runWccToolsSetup = async () => {
-    if (document.readyState === 'complete' && !hasRun) {
-      hasRun = true;
-      const wccTools = new WccDashboard(config);
-      document.querySelector('body').append(wccTools);
-    }
+const setupWccTools = (configArg: IWccConfig) => {
+  const start = () => {
+    startPreview(configArg).catch((error) => {
+      console.error('wcctools: the preview failed to start', error);
+    });
   };
-  document.addEventListener('readystatechange', runWccToolsSetup);
-  runWccToolsSetup();
+  if (document.readyState === 'complete') {
+    start();
+  } else {
+    window.addEventListener('load', start, { once: true });
+  }
 };
 
 export {

package/ts_web/previewbridge.ts

@@ -0,0 +1,189 @@
+import { html, render } from '@design.estate/dees-element';
+import * as plugins from './wcctools.plugins.js';
+import type { WccCatalog, TWccCatalogTarget } from './catalog.js';
+import { WccElementProperties } from './elementproperties.js';
+import { findElementInstance, resolveTemplateFactory, type ICatalogElementConstructor } from './elements/wcctools.helpers.js';
+import type { WccPreview } from './elements/wcc-preview.js';
+import { waitForRenderedTree } from './renderedtree.js';
+
+type TPreviewEvent = plugins.interfaces.TWccPreviewEvent;
+
+/** What the last render put on screen. */
+interface IRenderedState {
+  selection: plugins.interfaces.IWccSelection | null;
+  elementClass: ICatalogElementConstructor | null;
+  outcome: plugins.interfaces.TWccRenderOutcome;
+}
+
+/**
+ * The preview document's side of the shell bridge: renders the catalog's demos and pages into
+ * the preview surface, switches its theme and reads and edits the rendered element's properties.
+ */
+export class WccPreviewBridge implements plugins.interfaces.IWccPreviewBridge {
+  private readonly listeners = new Set<(eventArg: TPreviewEvent) => void>();
+  private theme: plugins.interfaces.TWccTheme = 'dark';
+  private rendered: IRenderedState | null = null;
+  private renderGeneration = 0;
+  /** Settles when the latest render, including its elements' first updates, has finished. */
+  private renderPromise: Promise<unknown> = Promise.resolve();
+
+  constructor(
+    private readonly catalog: WccCatalog,
+    private readonly preview: WccPreview,
+  ) {}
+
+  public getManifest(): plugins.interfaces.IWccCatalogManifest {
+    return this.catalog.getManifest();
+  }
+
+  public getSelection(): plugins.interfaces.IWccSelection | null {
+    return this.rendered?.selection ? { ...this.rendered.selection } : null;
+  }
+
+  public getTheme(): plugins.interfaces.TWccTheme {
+    return this.theme;
+  }
+
+  /** Render the preview route the document was loaded with. */
+  public async renderRoute(routeArg: plugins.shared.IWccPreviewRoute): Promise<void> {
+    await this.setTheme(routeArg.theme);
+    await this.renderSelection(routeArg.selection);
+  }
+
+  public async render(selectionArg: plugins.interfaces.IWccSelection): Promise<plugins.interfaces.TWccRenderOutcome> {
+    const { sectionName, itemName, demoIndex } = selectionArg;
+    return this.renderSelection({ sectionName, itemName, demoIndex });
+  }
+
+  public async setTheme(themeArg: plugins.interfaces.TWccTheme): Promise<void> {
+    this.theme = themeArg === 'bright' ? 'bright' : 'dark';
+    const domtools = await plugins.deesDomtools.elementBasic.setup();
+    this.theme === 'bright' ? domtools.themeManager.goBright() : domtools.themeManager.goDark();
+    this.writeRoute();
+  }
+
+  public async getProperties(): Promise<plugins.interfaces.TWccPropertyListing> {
+    await this.renderPromise;
+    const rendered = this.rendered;
+    if (!rendered?.selection || rendered.outcome.kind !== 'rendered') {
+      return { kind: 'unavailable', reason: 'Nothing is rendered.' };
+    }
+    if (rendered.outcome.type === 'page') {
+      return { kind: 'unavailable', reason: 'You selected a page.' };
+    }
+    const instance = this.findRenderedInstance();
+    if (!instance) {
+      return { kind: 'unavailable', reason: `The demo of ${rendered.selection.itemName} renders no <${customElements.getName(rendered.elementClass) ?? rendered.selection.itemName}> instance.` };
+    }
+    const properties = new WccElementProperties(rendered.elementClass, instance).describe();
+    if (!properties) {
+      return { kind: 'unavailable', reason: `${rendered.selection.itemName} does not expose element properties.` };
+    }
+    return { kind: 'properties', elementName: rendered.selection.itemName, properties };
+  }
+
+  public setProperty(nameArg: string, valueArg: plugins.interfaces.TWccPropertyScalar): plugins.interfaces.TWccPropertyEditResult {
+    const properties = this.getRenderedProperties();
+    return properties ? properties.set(nameArg, valueArg) : { ok: false, error: 'No element is rendered.' };
+  }
+
+  public setPropertyJson(nameArg: string, jsonArg: string): plugins.interfaces.TWccPropertyEditResult {
+    const properties = this.getRenderedProperties();
+    return properties ? properties.setJson(nameArg, jsonArg) : { ok: false, error: 'No element is rendered.' };
+  }
+
+  public findRenderedInstance(): HTMLElement | null {
+    const elementClass = this.rendered?.elementClass;
+    const viewport = this.preview.shadowRoot?.querySelector('.viewport');
+    if (!elementClass || !viewport) {
+      return null;
+    }
+    return findElementInstance(viewport, elementClass as unknown as new () => HTMLElement);
+  }
+
+  public subscribe(listenerArg: (eventArg: TPreviewEvent) => void): () => void {
+    this.listeners.add(listenerArg);
+    return () => {
+      this.listeners.delete(listenerArg);
+    };
+  }
+
+  private getRenderedProperties(): WccElementProperties | null {
+    const instance = this.findRenderedInstance();
+    return instance ? new WccElementProperties(this.rendered.elementClass, instance) : null;
+  }
+
+  private async renderSelection(
+    selectionArg: plugins.interfaces.IWccSelection | null,
+  ): Promise<plugins.interfaces.TWccRenderOutcome> {
+    const generation = ++this.renderGeneration;
+    const target = this.catalog.resolve(selectionArg);
+    const renderPromise = this.renderTarget(target, selectionArg?.itemName ?? '', generation);
+    this.renderPromise = renderPromise.catch(() => undefined);
+    const outcome = await renderPromise;
+    if (generation === this.renderGeneration) {
+      this.rendered = {
+        selection: selectionArg ? { ...selectionArg } : null,
+        elementClass: target.kind === 'element' ? target.elementClass : null,
+        outcome,
+      };
+      this.writeRoute();
+      this.emit({ type: 'rendered', selection: this.getSelection(), outcome });
+    }
+    return outcome;
+  }
+
+  private async renderTarget(
+    targetArg: TWccCatalogTarget,
+    itemNameArg: string,
+    generationArg: number,
+  ): Promise<plugins.interfaces.TWccRenderOutcome> {
+    const viewport = await this.preview.getViewportElement();
+    if (targetArg.kind === 'empty') {
+      this.showEmptyState(viewport, targetArg.emptyState, generationArg);
+      return { kind: 'empty', reason: targetArg.reason, emptyState: targetArg.emptyState };
+    }
+    try {
+      const template = await resolveTemplateFactory(targetArg.factory);
+      if (generationArg !== this.renderGeneration) {
+        return { kind: 'rendered', type: targetArg.kind };
+      }
+      render(template, viewport);
+      this.preview.emptyState = null;
+      await waitForRenderedTree(viewport);
+      return { kind: 'rendered', type: targetArg.kind };
+    } catch (error) {
+      console.error(`wcctools: rendering "${itemNameArg}" failed`, error);
+      const emptyState = {
+        title: `${itemNameArg} failed to render`,
+        detail: error instanceof Error ? error.message : String(error),
+      };
+      this.showEmptyState(viewport, emptyState, generationArg);
+      return { kind: 'empty', reason: 'failed', emptyState };
+    }
+  }
+
+  private showEmptyState(
+    viewportArg: HTMLElement,
+    emptyStateArg: plugins.interfaces.IWccEmptyState,
+    generationArg: number,
+  ) {
+    if (generationArg !== this.renderGeneration) {
+      return;
+    }
+    render(html``, viewportArg);
+    this.preview.emptyState = emptyStateArg;
+  }
+
+  /** Keep the document's URL on what it shows, so a live reload comes back to it. */
+  private writeRoute() {
+    const query = plugins.shared.formatPreviewQuery({ selection: this.rendered?.selection ?? null, theme: this.theme });
+    window.history.replaceState(window.history.state, '', `${window.location.pathname}${query}`);
+  }
+
+  private emit(eventArg: TPreviewEvent) {
+    for (const listener of this.listeners) {
+      listener(eventArg);
+    }
+  }
+}

package/ts_web/readme.md

@@ -4,7 +4,7 @@
 
 ## Overview
 
-This is the main module of `@design.estate/wcctools`, providing the complete dashboard experience for developing, testing, and documenting web components.
+This is the main module (`.`) of `@design.estate/wcctools`: the **preview runtime** that runs inside a catalogue's own bundle. `setupWccTools()` classifies the catalogue, renders demos and pages into the preview document and installs the bridge (`window.wccPreview`) the wcctools shell drives it through. The shell itself (sidebar, properties panel, recorder) is prebuilt into the package and served by `wcctools dev`.
 
 ## Installation
 
@@ -60,20 +60,13 @@ In an `elements` section, only classes extending `HTMLElement` with a static `de
 
 | Export | Description |
 |--------|-------------|
-| `setupWccTools` | Initialize the component catalogue dashboard |
+| `setupWccTools` | Set up the catalogue's preview document |
 | `IWccConfig` | TypeScript interface for sections configuration |
 | `IWccSection` | TypeScript interface for individual section |
 
-### Recording Components
+### `@design.estate/wcctools/interfaces`
 
-| Export | Description |
-|--------|-------------|
-| `RecorderService` | Service class for screen/viewport recording and MP4 conversion |
-| `WccRecordButton` | Record button UI component |
-| `WccRecordingPanel` | Recording options and preview panel |
-| `IRecorderEvents` | TypeScript interface for recorder callbacks |
-| `IRecordingOptions` | TypeScript interface for recording options |
-| `TOutputFormat` | Type for output format selection (`'webm' \| 'mp4'`) |
+The data-only contracts: the catalogue manifest, the preview bridge (`IWccPreviewBridge`) and the dev server's typed requests.
 
 ## Section Configuration
 
@@ -87,91 +80,39 @@ In an `elements` section, only classes extending `HTMLElement` with a static `de
 | `icon` | `string` | Material Symbols icon name |
 | `collapsed` | `boolean` | Start section collapsed (default: false) |
 
-## Internal Components
-
-The module includes these internal web components:
-
-| Component | Description |
-|-----------|-------------|
-| `wcc-dashboard` | Main dashboard container with routing |
-| `wcc-sidebar` | Navigation sidebar with collapsible sections and search |
-| `wcc-frame` | Responsive viewport with size controls |
-| `wcc-properties` | Property panel with live editing |
-| `wcc-record-button` | Recording state indicator button |
-| `wcc-recording-panel` | Recording workflow UI with format selection |
-
-## RecorderService API
-
-For programmatic recording and MP4 conversion:
-
-```typescript
-import { RecorderService, type IRecorderEvents } from '@design.estate/wcctools';
-
-const events: IRecorderEvents = {
-  onDurationUpdate: (duration) => console.log(`Recording: ${duration}s`),
-  onRecordingComplete: (blob) => saveBlob(blob),
-  onAudioLevelUpdate: (level) => updateMeter(level),
-  onError: (error) => console.error(error),
-  onStreamEnded: () => console.log('User stopped sharing'),
-};
+## Where the Preview Runs
 
-const recorder = new RecorderService(events);
-
-// Load available microphones
-const mics = await recorder.loadMicrophones(true);
-
-// Start audio level monitoring
-await recorder.startAudioMonitoring(mics[0].deviceId);
-
-// Start recording (always captures as WebM internally at up to 60fps)
-await recorder.startRecording({
-  mode: 'viewport',
-  audioDeviceId: mics[0].deviceId,
-  viewportElement: document.querySelector('.viewport'),
-});
-
-// Stop recording
-recorder.stopRecording();
-
-// Convert to MP4 for universal playback (H.264 + AAC via WebCodecs)
-const mp4Blob = await recorder.convertToMp4(recorder.recordedBlob);
-
-// Or export trimmed video
-const trimmedBlob = await recorder.exportTrimmedVideo(videoElement, startTime, endTime);
-
-// Cleanup
-recorder.dispose();
-```
+| Opened as | Behaviour |
+|-----------|-----------|
+| The shell's preview frame (`wcctools dev`) | Installs the bridge and reports ready to the shell; renders what the shell selects |
+| `/wcctools-preview?section=…&item=…&demo=…&theme=…` | Renders that one demo alone; the bridge is available for headless tools |
+| Anywhere else (for example plain `tswatch`) | Shows a notice naming `wcctools dev` |
 
 ## Architecture
 
 ```
-ts_web/
-├── index.ts                    # Main exports
-├── wcctools.interfaces.ts      # Type definitions
-├── types/
-│   ├── dom-webcodecs-stub/     # TS6 compatibility shim
-│   └── dom-mediacapture-stub/  # MediaCapture Transform types
-├── elements/
-│   ├── wcc-dashboard.ts        # Root dashboard component
-│   ├── wcc-sidebar.ts          # Navigation sidebar
-│   ├── wcc-frame.ts            # Responsive viewport
-│   ├── wcc-properties.ts       # Property editing panel
-│   ├── wcc-record-button.ts    # Recording button
-│   ├── wcc-recording-panel.ts  # Recording options/preview
-│   └── wcctools.helpers.ts     # Shared utilities
-├── services/
-│   └── recorder.service.ts     # MediaRecorder + mediabunny MP4 conversion
-└── pages/
-    └── index.ts                # Built-in pages
+ts_web/                         # preview runtime, exported as "."
+├── index.ts                    # setupWccTools
+├── catalog.ts                  # classification, manifest, selection resolution
+├── previewbridge.ts            # IWccPreviewBridge implementation
+├── elementproperties.ts        # editable properties of a rendered element
+├── renderedtree.ts             # waits for a rendered tree's Lit updates
+└── elements/
+    ├── wcc-preview.ts          # render surface (wccToolsViewport container, empty states)
+    ├── wcc-standalone-notice.ts
+    └── wcctools.helpers.ts     # classification and demo helpers
+ts_shell/                       # the shell, bundled to dist_shell/
+ts_interfaces/                  # contracts, exported as "./interfaces"
+ts_shared/                      # the preview route format
+ts/                             # wcctools CLI and dev server
 ```
 
 ## Features
 
-- 🎨 Interactive component preview
+- 🎨 Interactive component preview at the exact viewport width
 - 📂 Section-based sidebar with filtering, sorting & search (by name, tag, or group)
 - 🔧 Real-time property editing with type detection
 - 🌓 Theme switching (light/dark)
-- 📱 Responsive viewport testing
+- 📱 Responsive viewport testing with width media queries
 - 🎬 Screen recording with MP4/WebM export, trimming, and audio
 - 🔗 URL-based deep linking

package/ts_web/renderedtree.ts

@@ -0,0 +1,43 @@
+/** An element with Lit's update lifecycle, identified by shape: catalogs may bundle their own Lit. */
+interface IUpdatingElement extends Element {
+  updateComplete: Promise<unknown>;
+}
+
+const isUpdatingElement = (elementArg: Element): elementArg is IUpdatingElement => {
+  const updateComplete = (elementArg as Partial<IUpdatingElement>).updateComplete;
+  return typeof updateComplete?.then === 'function';
+};
+
+const collectUpdatingElements = (rootArg: Element | ShadowRoot): IUpdatingElement[] => {
+  const result: IUpdatingElement[] = [];
+  const pending = Array.from(rootArg.children);
+  for (let index = 0; index < pending.length; index++) {
+    const element = pending[index];
+    if (isUpdatingElement(element)) {
+      result.push(element);
+    }
+    pending.push(...element.children);
+    if (element.shadowRoot) {
+      pending.push(...element.shadowRoot.children);
+    }
+  }
+  return result;
+};
+
+/**
+ * Resolves once every Lit element below the root, including the ones their updates create,
+ * has completed its pending update.
+ */
+export const waitForRenderedTree = async (rootArg: Element | ShadowRoot): Promise<void> => {
+  const settled = new Set<Element>();
+  for (;;) {
+    const pending = collectUpdatingElements(rootArg).filter((elementArg) => !settled.has(elementArg));
+    if (pending.length === 0) {
+      return;
+    }
+    await Promise.all(pending.map((elementArg) => elementArg.updateComplete));
+    for (const element of pending) {
+      settled.add(element);
+    }
+  }
+};

package/ts_web/wcctools.interfaces.ts

@@ -1,11 +1,13 @@
+import type { TWccSectionType } from '../ts_interfaces/index.js';
+
 /**
- * Configuration for a section in the WCC Tools sidebar
+ * Configuration for a section of the catalog
  */
 export interface IWccSection {
   /** Display name for the section header */
   name: string;
   /** How items in this section are rendered - 'elements' show demos, 'pages' render directly */
-  type: 'elements' | 'pages';
+  type: TWccSectionType;
   /** The items in this section - either element classes or page factory functions */
   items: Record<string, any>;
   /** Optional filter function to include/exclude items */
@@ -24,8 +26,3 @@ export interface IWccSection {
 export interface IWccConfig {
   sections: IWccSection[];
 }
-
-/**
- * Type for element selection types - now section-based
- */
-export type TElementType = 'element' | 'page';

package/ts_web/wcctools.plugins.ts

@@ -1,5 +1,10 @@
 import * as deesDomtools from '@design.estate/dees-domtools';
 
+import * as interfaces from '../ts_interfaces/index.js';
+import * as shared from '../ts_shared/index.js';
+
 export {
-  deesDomtools
+  deesDomtools,
+  interfaces,
+  shared,
 };