@volter/editor-core 0.5.57

package/src/components/StageOverlays.tsx

@@ -0,0 +1,21 @@
+/**
+ * The lazy boundary for a stage's overlays. The host names them; only a stage
+ * that actually has a shell above it (and therefore something for them to
+ * read) evaluates the module. See `stage-overlay-set.tsx` for what they are
+ * and `world-root-stage.ts`'s header for why the condition gates the LOAD.
+ */
+import { lazy, Suspense } from 'react';
+import type { StageOverlaySetProps } from './stage-overlay-set';
+
+const LazyStageOverlaySet = lazy(async () => {
+  const module = await import('./stage-overlay-set');
+  return { default: module.StageOverlaySet };
+});
+
+export function StageOverlays(props: StageOverlaySetProps) {
+  return (
+    <Suspense fallback={null}>
+      <LazyStageOverlaySet {...props} />
+    </Suspense>
+  );
+}

package/src/components/StartupErrorScreen.tsx

@@ -0,0 +1,76 @@
+import { EDITOR_BRAND } from '@volter/editor-sdk/session/editor-brand';
+/**
+ * StartupErrorScreen — the boot-failure surface.
+ *
+ * `boot-routing.ts` distinguishes `'project' | 'none' | 'unreadable' |
+ * 'unknown'`, and ONLY `'none'` earns the launcher. The measured residual
+ * after that fix was in the rendering: AppRoot's error state handed the
+ * failure to the LAUNCHER, which drew its usual hub — recents, the gallery,
+ * "What do you want to do?" — with a banner on top, and offered a Dismiss
+ * that left the user on a plain launcher. So a server that WAS serving a
+ * project it could not read looked, to a human or to an agent screenshotting
+ * the tab, exactly like a fresh first run.
+ *
+ * This surface is that failure and nothing else: the alert, the two facts a
+ * broken boot must name (the project the server is serving, and the server's
+ * own error string), Retry, and an explicit — never implicit — way to leave
+ * for the launcher. The launcher is a destination you choose here, not the
+ * page you were silently given.
+ *
+ * It keeps `data-testid="project-detection-error"` on the shell root: that
+ * attribute is what `product-shell.css` scopes the red-key-lit stage to, and
+ * it has always been the launcher-vs-failure discriminator. What changed is
+ * that it now selects a page with no launcher in it.
+ */
+
+import type { ServerProjectFailureReport } from '../boot-routing';
+import { BUNDLED_EDITOR_VERSION, BUNDLED_ENGINE_VERSION } from '../build-identity';
+import { ErrorBanner, type ScreenError } from './ErrorBanner';
+import { VgaiLogo } from './VgaiLogo';
+
+export interface StartupErrorScreenProps {
+  error: ScreenError;
+  /** The structured server answer, when the failure came from the boot probe. */
+  report?: ServerProjectFailureReport | undefined;
+  onRetry: () => void;
+}
+
+export function StartupErrorScreen({ error, report, onRetry }: StartupErrorScreenProps) {
+  // Tab accounting is NOT this component's job: AppRoot reports the route for
+  // every surface it renders (this one included), so the tab bijection sees a
+  // live tab that is simply not on the project — visible, never duplicated,
+  // and adoptable the moment the project becomes readable again.
+  return (
+    <div className="vgai-shell" data-testid="project-detection-error">
+      <div className="vgai-shell-container" data-view="startup-error">
+        <header className="vgai-shell-header">
+          <span className="vgai-shell-brand-static">
+            <span className="vgai-shell-brand-mark" aria-hidden="true">
+              <VgaiLogo size={30} animation="static" />
+            </span>
+            <span className="vgai-shell-wordmark">{EDITOR_BRAND.name}</span>
+          </span>
+        </header>
+
+        <ErrorBanner error={error} onRetry={onRetry} startup />
+
+        {report?.projectPath && (
+          <div className="vgai-shell-notice" data-testid="project-startup-serving">
+            <span>
+              This editor server is serving{' '}
+              <code data-testid="project-startup-serving-path">{report.projectPath}</code> — the
+              project exists; the editor could not read it. Fix the file it names above and press
+              Retry.
+            </span>
+          </div>
+        )}
+
+        <footer className="vgai-shell-footer">
+          <span className="vgai-chip" data-variant="tag">
+            Editor v{BUNDLED_EDITOR_VERSION} · Engine v{BUNDLED_ENGINE_VERSION}
+          </span>
+        </footer>
+      </div>
+    </div>
+  );
+}

package/src/components/StartupLoadingScreen.tsx

@@ -0,0 +1,65 @@
+import { EDITOR_BRAND } from '@volter/editor-sdk/session/editor-brand';
+import { VgaiLogo } from './VgaiLogo';
+
+/**
+ * How long the wait has been going on, once it has stopped being instant.
+ *
+ * A boot that is still working is not the same page as a boot that answered in
+ * 200ms, and pretending otherwise is what made the old deadline attractive:
+ * with nothing on screen distinguishing them, "still opening" reads as "hung",
+ * and the fix looked like a timeout. Naming the ask and counting the seconds
+ * makes waiting legible, which is what lets the editor wait as long as it takes.
+ */
+export interface StartupWait {
+  /** Whole seconds since the first detection attempt started. */
+  seconds: number;
+  /** The last attempt's own error, verbatim — never paraphrased. */
+  detail?: string | undefined;
+}
+
+export interface StartupLoadingScreenProps {
+  /** Present once a detection attempt has failed and the editor is re-asking. */
+  wait?: StartupWait | undefined;
+}
+
+/** Lightweight first paint while the local project is being detected and validated. */
+export function StartupLoadingScreen({ wait }: StartupLoadingScreenProps = {}) {
+  return (
+    <main
+      role="status"
+      aria-live="polite"
+      aria-label="Opening project"
+      data-testid="startup-loading-screen"
+      className="vgai-splash"
+    >
+      <div className="vgai-splash-stack">
+        <div aria-hidden="true" className="vgai-splash-logo">
+          {/* §5-R cinematic boot: the mark is the key-lit subject — hub
+           * empty-state scale, blooming in the splash's key light. */}
+          <VgaiLogo size={72} animation="loading" />
+        </div>
+
+        <div className="vgai-splash-title">{EDITOR_BRAND.name}</div>
+
+        <div aria-hidden="true" className="vgai-splash-progress" />
+
+        {wait ? (
+          <>
+            <div className="vgai-splash-status" data-testid="startup-wait-status">
+              {`Asking the server which project it serves — ${wait.seconds}s`}
+            </div>
+            <div className="vgai-splash-note">
+              Still trying. The first boot of a fresh checkout can take a while, so this keeps
+              asking until the server answers.
+            </div>
+            {wait.detail ? (
+              <div className="vgai-splash-note">Last attempt: {wait.detail}</div>
+            ) : null}
+          </>
+        ) : (
+          <div className="vgai-splash-status">Opening project…</div>
+        )}
+      </div>
+    </main>
+  );
+}

package/src/components/StatsOverlay.tsx

@@ -0,0 +1,78 @@
+import { themeVars } from '@volter/editor-sdk/widgets';
+import { useEffect, useState } from 'react';
+import { useEditorStats } from '../editor-runtime';
+import { latestTabCensus } from '../tab-census';
+
+export function StatsOverlay() {
+  const stats = useEditorStats();
+  const [, setTick] = useState(0);
+  // The tab's resource census (tab-census.ts) — the SAME sample the heartbeat
+  // carries and a death line quotes, read here on the tick this overlay
+  // already runs. The author sees the cost while authoring it, which is the
+  // whole reason the census exists: the quality loop grades looks, and a
+  // renderer killed at Chrome's undocumented ceiling grades nothing.
+  const census = latestTabCensus();
+
+  useEffect(() => {
+    const id = setInterval(() => setTick((t) => t + 1), 200);
+    return () => clearInterval(id);
+  }, []);
+
+  return (
+    // V-10 — this was an EIGHTH one-off "dark panel"
+    // value (`rgba(0,0,0,0.7)`, flat black, no border) directly stacked
+    // above-right of ViewportOverlay's cluster and CameraInfo's pill in the
+    // same corner. Given the same border/radius treatment as its siblings so
+    // the whole corner reads as one family.
+    // P6-U6 (owner taste decision 3: HUD overlays → real islands): the paint
+    // moved to `.vgai-hud-overlay` so islands chrome can promote it to the
+    // shared glass-island material (compact tier); bars chrome paints the
+    // exact pre-U6 overlay-whisper recipe from the same class.
+    <div
+      className="vgai-hud-overlay vgai-chrome-island vgai-glass-island"
+      data-island-scale="compact"
+      data-hud-border="strong"
+      style={{
+        position: 'absolute',
+        // U6.5 F1/P2-18 — second HUD tier: below the viewport toolbar row.
+        // The var carries the glass breathing band (54px islands / 102px the
+        // floating header-island clearance, scoped in theme.css); the bare
+        // fallback is the pre-glass 48px so treatment-less chrome ("bars":
+        // graphite/classic/lite/reduced) stays pixel-identical to main.
+        top: 'var(--vgai-viewport-overlay-hud-top, 48px)',
+        right: 8,
+        padding: '6px 10px',
+        pointerEvents: 'auto',
+        fontSize: 'var(--vgai-font-base)',
+        color: themeVars.content.primary,
+        fontFamily: themeVars.typography.mono,
+        lineHeight: '16px',
+      }}
+    >
+      <div>FPS: {stats.fps.toFixed(0)}</div>
+      <div>Draw: {stats.drawCalls}</div>
+      <div>Tris: {stats.triangles.toLocaleString()}</div>
+      <div>Frame: {stats.frameTime.toFixed(1)}ms</div>
+      {census !== null && (
+        <>
+          <div>
+            Heap: {census.heapUsedMB === null ? 'n/a' : `${census.heapUsedMB.toFixed(0)}MB`}
+            {census.heapLimitMB === null ? '' : ` / ${census.heapLimitMB.toFixed(0)}MB`}
+          </div>
+          <div>Mount epochs: {census.mountEpochs}</div>
+          <div>
+            Canvas: {census.canvasMB.toFixed(1)}MB ×{census.canvases}
+          </div>
+          {/* Absent, never zeroed, when no game has registered a render-debug
+              adapter — "no textures" is a different claim from "unmeasured". */}
+          {census.textures !== undefined && (
+            <div>
+              GPU: {census.textures} tex, {census.geometries ?? 0} geo
+              {census.programs === undefined ? '' : `, ${census.programs} prog`}
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  );
+}

package/src/components/SurfaceStateOverlay.tsx

@@ -0,0 +1,24 @@
+import { StateSurface } from '@volter/editor-sdk/widgets';
+import type { CSSProperties } from 'react';
+import type { SurfaceExplanation } from '../surface-state';
+
+export function SurfaceStateOverlay({
+  explanation,
+  testId,
+  style,
+}: {
+  readonly explanation: SurfaceExplanation | null;
+  readonly testId: string;
+  readonly style?: CSSProperties;
+}) {
+  if (!explanation) return null;
+  return (
+    <StateSurface
+      data-testid={testId}
+      tone={explanation.tone}
+      title={explanation.title}
+      description={<span style={{ whiteSpace: 'pre-wrap' }}>{explanation.description}</span>}
+      style={{ position: 'absolute', inset: 0, pointerEvents: 'none', ...style }}
+    />
+  );
+}

package/src/components/ToolContributionSurfaces.tsx

@@ -0,0 +1,65 @@
+import type {
+  ToolAssetDocumentProps,
+  ToolContributionSurfaces,
+  ToolObject3DAuthoringProps,
+  ToolObject3DPreviewProps,
+} from '@volter/editor-sdk/contributions';
+import { lazy, Suspense, useEffect } from 'react';
+import { announceObject3DDocumentStage } from '../authoring/object3d-document-session-registry';
+import { AssetEditorSubject } from './AssetEditorShell';
+
+const LazyToolObject3DPreview = lazy(async () => {
+  const module = await import('./ToolObject3DPreview');
+  return { default: module.ToolObject3DPreview };
+});
+
+const LazyToolObject3DAuthoring = lazy(async () => {
+  const module = await import('./StageHost');
+  return { default: module.ToolObject3DAuthoring };
+});
+
+/**
+ * Lightweight contribution boundary: importing ToolHost must not eagerly pull
+ * WebGL, postprocessing, or browser-only Model Asset modules into Node tools
+ * and tests that never render a 3D preview.
+ */
+export function ToolObject3DPreviewSurface(props: ToolObject3DPreviewProps) {
+  return (
+    <Suspense fallback={<div style={{ minHeight: 240 }}>Loading 3D preview…</div>}>
+      <LazyToolObject3DPreview {...props} />
+    </Suspense>
+  );
+}
+
+export function ToolObject3DAuthoringSurface(props: ToolObject3DAuthoringProps) {
+  // A CONTRIBUTED DOCUMENT'S STAGE ANNOUNCES ITSELF HERE, in the host's own
+  // surface, the moment the contribution renders it — long before the lazy
+  // implementation resolves and registers a session. This is what lets the
+  // `tool` and `document` addresses declare a readiness without the host
+  // knowing which contributions mount a stage: three Builder documents in the
+  // capability catalog do (`builder-document.tsx:66`) and nine other
+  // `workspace.document` contributions do not, and which is which belongs to
+  // the PROJECT, never to a list here.
+  useEffect(() => announceObject3DDocumentStage(props.documentId), [props.documentId]);
+  return (
+    <Suspense fallback={<div style={{ minHeight: 240 }}>Loading 3D authoring surface…</div>}>
+      <LazyToolObject3DAuthoring {...props} />
+    </Suspense>
+  );
+}
+
+/**
+ * Registers the ordinary Asset Lab subject for a project-owned document. The
+ * surface is intentionally childless: it registers a subject and draws nothing
+ * of the document's own, which the document keeps rendering itself.
+ */
+export function ToolAssetDocumentSurface(props: ToolAssetDocumentProps) {
+  return <AssetEditorSubject {...props} />;
+}
+
+/** Stable dependency-injection value shared by every contribution mount. */
+export const toolContributionSurfaces: ToolContributionSurfaces = Object.freeze({
+  AssetDocument: ToolAssetDocumentSurface,
+  Object3DPreview: ToolObject3DPreviewSurface,
+  Object3DAuthoring: ToolObject3DAuthoringSurface,
+});