@volter/editor-ui 0.5.211 → 0.5.212

package/src/react/story-paint-bounds.ts

@@ -0,0 +1,94 @@
+/**
+ * The union of what a mounted DOM story actually PAINTS, in the mount box's
+ * own authored pixels — the measurement half of "mount in the truth, frame the
+ * subject" for the UI board (the capture lane's alpha-bounds scan is the same
+ * decision made on pixels; a live card cannot rasterize per frame, so this
+ * walks the DOM instead).
+ *
+ * The filter matters more than the union: a translated uGUI screen is nested
+ * full-bleed wrapper boxes (anchor stretch, transparent) around a few painted
+ * leaves, so a naive union of ALL element rects is always the whole mount box
+ * and the crop never fires. An element counts only when it paints something a
+ * viewer can see: a non-transparent background, a background image, replaced
+ * content, a visible border/shadow, or its own text.
+ */
+
+/** True when this element itself puts pixels on screen. */
+function elementPaints(element: Element): boolean {
+  const tag = element.tagName;
+  if (
+    tag === 'IMG' ||
+    tag === 'VIDEO' ||
+    tag === 'CANVAS' ||
+    tag === 'svg' ||
+    tag === 'SVG' ||
+    tag === 'PICTURE'
+  ) {
+    return true;
+  }
+  const style = getComputedStyle(element);
+  if (style.visibility === 'hidden' || style.display === 'none') return false;
+  if (backgroundColorPaints(style.backgroundColor)) return true;
+  if (style.backgroundImage && style.backgroundImage !== 'none') return true;
+  if (style.boxShadow && style.boxShadow !== 'none') return true;
+  if (
+    style.borderStyle !== 'none' &&
+    style.borderStyle !== '' &&
+    (parseFloat(style.borderTopWidth) > 0 ||
+      parseFloat(style.borderRightWidth) > 0 ||
+      parseFloat(style.borderBottomWidth) > 0 ||
+      parseFloat(style.borderLeftWidth) > 0)
+  ) {
+    return true;
+  }
+  for (const node of element.childNodes) {
+    if (node.nodeType === Node.TEXT_NODE && (node.textContent ?? '').trim() !== '') return true;
+  }
+  return false;
+}
+
+/** `transparent` serializes as `rgba(0, 0, 0, 0)`; anything with alpha paints. */
+function backgroundColorPaints(color: string): boolean {
+  if (!color || color === 'transparent') return false;
+  const rgba = /^rgba\(\s*[\d.]+\s*,\s*[\d.]+\s*,\s*[\d.]+\s*,\s*([\d.]+)\s*\)$/.exec(color);
+  if (rgba) return parseFloat(rgba[1]!) > 0;
+  return true;
+}
+
+export interface PaintedBounds {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * Union of the painted descendants' boxes in the mount box's authored px, or
+ * `null` when nothing paints. Rects are read through the live client transform
+ * (the board zooms its canvas), so the mount box's own client width supplies
+ * the scale — self-normalizing, no zoom parameter to drift.
+ */
+export function paintedContentBounds(
+  content: HTMLElement,
+  rectOf: (element: Element) => DOMRect = (element) => element.getBoundingClientRect(),
+): PaintedBounds | null {
+  const home = rectOf(content);
+  const authoredWidth = content.offsetWidth;
+  if (home.width <= 0 || authoredWidth <= 0) return null;
+  const scale = home.width / authoredWidth;
+  let left = Number.POSITIVE_INFINITY;
+  let top = Number.POSITIVE_INFINITY;
+  let right = Number.NEGATIVE_INFINITY;
+  let bottom = Number.NEGATIVE_INFINITY;
+  for (const element of content.querySelectorAll('*')) {
+    if (!elementPaints(element)) continue;
+    const rect = rectOf(element);
+    if (rect.width <= 0 || rect.height <= 0) continue;
+    left = Math.min(left, (rect.left - home.left) / scale);
+    top = Math.min(top, (rect.top - home.top) / scale);
+    right = Math.max(right, (rect.right - home.left) / scale);
+    bottom = Math.max(bottom, (rect.bottom - home.top) / scale);
+  }
+  if (right <= left || bottom <= top) return null;
+  return { x: left, y: top, width: right - left, height: bottom - top };
+}

package/src/react/ui-board-document.tsx

@@ -0,0 +1,55 @@
+/** Lazily install the UI board through host document services. A DOM root
+ * supplies its provenance and route; a rootless project presents its component
+ * gallery. Captures remember the selected portable story for restoration. */
+
+import { designTimeRootDescriptors } from '@volter/sdk/authoring/design-time-roots';
+import { projectStoryBoardDescriptor, rememberedPortableStory } from '../host/portable-stories';
+import type { ComponentBoardContext } from '@volter/sdk/component-board-registry';
+import { editorHost } from '@volter/sdk/host';
+import { getCurrentProject } from '@volter/sdk/active-project';
+import { UI_COMPONENTS_DOCUMENT_ID } from '@volter/sdk/workspace-document-ids';
+import type { WorkspaceDocumentContentProps } from '@volter/sdk/workspace-document-registry';
+
+import { UI_COMPONENTS_TITLE } from './ui-board-title';
+
+export function installUiBoard({ store, composite }: ComponentBoardContext): void {
+  const descriptor =
+    designTimeRootDescriptors(composite).find((root) => root.kind === 'dom') ??
+    projectStoryBoardDescriptor();
+  const host = editorHost();
+  const { RootContent } = host.documents;
+  const Content = (props: WorkspaceDocumentContentProps) => (
+    <RootContent {...props} composite={composite} descriptor={descriptor} store={store} />
+  );
+  host.workspace.registerAvailableDocument(
+    {
+      id: UI_COMPONENTS_DOCUMENT_ID,
+      title: UI_COMPONENTS_TITLE,
+      kind: 'world',
+      provenance: {
+        rootId: descriptor.worldId,
+        ...(descriptor.path ? { sourcePath: descriptor.path } : {}),
+      },
+      Content,
+      presentation: () => {
+        // Capture the active story so restoring this view selects the same frame.
+        const projectRoot = getCurrentProject()?.rootPath;
+        const story = projectRoot
+          ? rememberedPortableStory(projectRoot, descriptor.worldId)
+          : undefined;
+        return {
+          kind: 'workspace',
+          id: UI_COMPONENTS_DOCUMENT_ID,
+          ...(story ? { story } : {}),
+        };
+      },
+    },
+    // An asynchronously discovered board opens without taking focus.
+    {
+      category: 'canvas',
+      default: !composite
+        .childAdapters()
+        .some((root) => root.kind === 'stage' || root.kind === 'canvas'),
+    },
+  );
+}

package/src/react/ui-board-title.ts

@@ -0,0 +1,9 @@
+/** The tab reads `UI`, the peer of `Scene` and `3D` in the center strip. The
+ *  document ID is a fixed id, not this label, because persisted layouts address
+ *  panels by id (deriving either from the root would churn the panel identity
+ *  on a rename, stranding the old panel in every layout).
+ *
+ *  Its own module because the registration reads it for the host's absence
+ *  prose while the DOCUMENT reads it for the tab, and the two halves are
+ *  deliberately in different closures. */
+export const UI_COMPONENTS_TITLE = 'UI';

package/src/react/ui-component-board.ts

@@ -0,0 +1,52 @@
+/** Register the UI board for projects with declared DOM stories. The board
+ * document is loaded when story discovery reports that medium present. */
+
+import { editorHost } from '@volter/sdk/host';
+import { commandLine } from '@volter/sdk/product-command';
+import type { ComponentBoard, ComponentBoardContext } from '@volter/sdk/component-board-registry';
+import { editorConsole } from '@volter/sdk/editor-console';
+import {
+  getStoryMediaPresence,
+  subscribeStoryMediaPresence,
+} from '../host/stories/story-media-presence';
+import { UI_COMPONENTS_DOCUMENT_ID } from '@volter/sdk/workspace-document-ids';
+import { UI_COMPONENTS_TITLE } from './ui-board-title';
+
+export const uiComponentBoard: ComponentBoard = {
+  medium: 'dom',
+  owner: '@volter/editor-ui/react/ui-board',
+  documentId: UI_COMPONENTS_DOCUMENT_ID,
+  title: UI_COMPONENTS_TITLE,
+  // Story media determine presence; an unsettled registry has no verdict.
+  presence: () =>
+    !editorHost().stories.ready() ? null : getStoryMediaPresence().dom ? 'present' : 'absent',
+  subscribe: (listener) => {
+    // Two signals, because the verdict is a function of both: the census
+    // (which media the project's stories declare) and the discovery flag that
+    // decides whether the census counts yet.
+    const stopPresence = subscribeStoryMediaPresence(listener);
+    const stopRegistry = editorHost().stories.subscribe(listener);
+    return () => {
+      stopPresence();
+      stopRegistry();
+    };
+  },
+  install: async (context: ComponentBoardContext) => {
+    try {
+      const { installUiBoard } = await import('./ui-board-document');
+      installUiBoard(context);
+    } catch (error: unknown) {
+      editorConsole.error(
+        `Failed to load the ${UI_COMPONENTS_TITLE} board: ${String(error)}`,
+        'scene',
+      );
+      throw error;
+    }
+  },
+  absentReason: () =>
+    `This project has no ${UI_COMPONENTS_TITLE} board (${UI_COMPONENTS_DOCUMENT_ID}): board ` +
+    "presence keys on STORIES, not on roots, and none of this project's stories declares the " +
+    '"dom" medium. Declare it — a manifest root entry naming the story\'s module, or a ' +
+    `\`editor/volter.adapter.ts\` regionInclude that covers it — and the board appears. ${commandLine('console')} ` +
+    'names every story it could not place.',
+};

package/src/runtime/presentation.ts

@@ -0,0 +1,60 @@
+/** Fit a logical story viewport inside its host while preserving aspect. */
+
+/** A width/height pair in whatever unit the caller is working in. */
+export interface PresentationSize {
+  readonly width: number;
+  readonly height: number;
+}
+
+/** Where a logical rect lands inside a container, scaled uniformly and centered. */
+export interface PresentationRect {
+  /** Uniform logical→container scale factor. Always finite and > 0. */
+  readonly scale: number;
+  /** The scaled rect's size in container units. */
+  readonly width: number;
+  readonly height: number;
+  /** The letterbox margins — how far in from the container's top-left the scaled rect starts. */
+  readonly offsetX: number;
+  readonly offsetY: number;
+}
+
+function positiveOrZero(value: number): number {
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+/**
+ * Fit `logical` inside `container`, preserving aspect and centering the result.
+ *
+ * `allowUpscale` is the difference between the two callers this replaces and it is not cosmetic.
+ * A DEVICE PREVIEW must never upscale — the point is to see the device's own pixels, so a phone
+ * frame in a big panel stays phone-sized. A game's DECLARED resolution must upscale, or a 720x540
+ * game sits as a postage stamp in the middle of a maximized panel and the feature reads as broken.
+ *
+ * A degenerate input (zero, negative, NaN — a panel mid-collapse, a manifest with a 0) yields
+ * `scale: 1` and a zero-offset rect rather than an Infinity that would propagate into a CSS
+ * transform.
+ */
+export function fitPresentation(
+  container: PresentationSize,
+  logical: PresentationSize,
+  options: { readonly allowUpscale?: boolean } = {},
+): PresentationRect {
+  const cw = positiveOrZero(container.width);
+  const ch = positiveOrZero(container.height);
+  const lw = positiveOrZero(logical.width);
+  const lh = positiveOrZero(logical.height);
+  if (cw === 0 || ch === 0 || lw === 0 || lh === 0) {
+    return { scale: 1, width: lw, height: lh, offsetX: 0, offsetY: 0 };
+  }
+  const raw = Math.min(cw / lw, ch / lh);
+  const scale = options.allowUpscale === true ? raw : Math.min(raw, 1);
+  const width = lw * scale;
+  const height = lh * scale;
+  return {
+    scale,
+    width,
+    height,
+    offsetX: (cw - width) / 2,
+    offsetY: (ch - height) / 2,
+  };
+}

package/contributions/play-layers.service.ts

@@ -1,31 +0,0 @@
-/** DOM roots offered to playing stages, independent of a product or game loop. */
-import { registerProjectPlayLayers } from '@volter/sdk/kit/project-play-layers';
-import { resolveDomAdapter } from '@volter/editor-game/host/roots/react-root';
-import { activeRealmServices } from '@volter/editor-game/host/realm-services';
-import { fetchGameManifest } from '@volter/sdk/kit/manifest-project';
-export const point = 'workspace.service';
-export function start(): () => void {
-  return registerProjectPlayLayers(async ({ projectRoot, epoch, container, onEntries }) => {
-    const manifest = await fetchGameManifest();
-    const roots = manifest.roots.filter(declaration => declaration.adapter.identity === 'dom');
-    const entries = roots.flatMap(declaration => declaration.entry ? [declaration.entry] : []);
-    onEntries(entries);
-    const realm = await activeRealmServices(projectRoot, epoch);
-    const disposals: (() => void)[] = [];
-    const dispose = () => { for (const end of disposals.splice(0).reverse()) end(); };
-    try {
-      for (const declaration of roots) {
-        const layer = document.createElement('div');
-        Object.assign(layer.style, { position: 'absolute', inset: '0', zIndex: String(declaration.zOrder), pointerEvents: 'none' });
-        layer.dataset.rootId = declaration.id;
-        container.appendChild(layer);
-        disposals.push(() => layer.remove());
-        const adapter = await resolveDomAdapter(declaration, realm);
-        const mounted = await adapter.mount({ container: layer });
-        // Stop can be a parent React commit; unmount the independent root after it.
-        disposals.push(() => queueMicrotask(() => mounted.dispose()));
-      }
-      return { entries, dispose };
-    } catch (error) { dispose(); throw error; }
-  });
-}