@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/components/RootTextEditor.tsx

@@ -0,0 +1,79 @@
+/**
+ * RootTextEditor — spec 27 §6 D3.b double-click-to-edit-text: an inline canonical
+ * multiline text control positioned over the double-clicked node's rect. Escape cancels;
+ * Enter (no shift) or blur commits. Purely a controlled presentational component —
+ * `RootSelectionOverlay` decides WHETHER to render this (via `adapter.text`/`textForId`,
+ * rule zero) and supplies the initial text + the commit/cancel callbacks; this file has
+ * no adapter/DOM reach of its own.
+ */
+
+import { TextArea, zIndex } from '@volter/sdk/widgets';
+import { useEffect, useRef, useState } from 'react';
+
+export interface RootTextEditorProps {
+  rect: { x: number; y: number; width: number; height: number };
+  initialText: string;
+  onCommit: (text: string) => void;
+  onCancel: () => void;
+}
+
+export function RootTextEditor({
+  rect,
+  initialText,
+  onCommit,
+  onCancel,
+}: RootTextEditorProps): React.ReactNode {
+  const [value, setValue] = useState(initialText);
+  const ref = useRef<HTMLTextAreaElement>(null);
+  const committedRef = useRef(false);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    el.focus();
+    el.select();
+  }, []);
+
+  const commit = (): void => {
+    if (committedRef.current) return;
+    committedRef.current = true;
+    onCommit(value);
+  };
+
+  const cancel = (): void => {
+    if (committedRef.current) return;
+    committedRef.current = true;
+    onCancel();
+  };
+
+  return (
+    <TextArea
+      ref={ref}
+      data-testid="world-text-editor"
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+      onBlur={commit}
+      onKeyDown={(e) => {
+        if (e.key === 'Escape') {
+          e.stopPropagation();
+          cancel();
+        } else if (e.key === 'Enter' && !e.shiftKey) {
+          e.preventDefault();
+          commit();
+        }
+      }}
+      data-variant="inline-editor"
+      style={{
+        position: 'absolute',
+        left: rect.x,
+        top: rect.y,
+        width: Math.max(rect.width, 40),
+        height: Math.max(rect.height, 20),
+        boxSizing: 'border-box',
+        zIndex: zIndex.overlayLow,
+        pointerEvents: 'auto',
+        resize: 'none',
+      }}
+    />
+  );
+}

package/src/kit/components/SaveStatus.tsx

@@ -0,0 +1,70 @@
+import { Button } from '@volter/sdk/widgets';
+import { useSyncExternalStore } from 'react';
+import {
+  activeSaveDestination,
+  activeSaveFailure,
+  activeSaveState,
+  saveActiveAuthoring,
+} from '@volter/sdk/kit/authoring/shell-document-ops';
+import { useEditorStore, useOptionalHistoryService } from '@volter/sdk/kit/editor-runtime';
+import { showConsoleUtility } from '../workspace-utility-commands';
+
+const subscribeToNothing = () => () => undefined;
+const noHistorySnapshot = () => null;
+
+/**
+ * Compact save-status affordance for the status bar. Surfaces whether the
+ * ACTIVE authoring adapter has unsaved edits. Click to force a save (also bound
+ * to Cmd/Ctrl+S).
+ */
+export function SaveStatus() {
+  const store = useEditorStore();
+  const history = useOptionalHistoryService();
+  useSyncExternalStore(store.subscribe, store.getShellSnapshot ?? store.getSnapshot);
+  // Source writes clear HistoryService.lastError only after the async commit
+  // succeeds. Subscribe directly so the red failure state clears at that
+  // exact point rather than waiting for an unrelated store/HMR notification.
+  useSyncExternalStore(
+    history?.subscribe ?? subscribeToNothing,
+    history?.getSnapshot ?? noHistorySnapshot,
+    history?.getSnapshot ?? noHistorySnapshot,
+  );
+  const state = activeSaveState(store);
+  // Success is the steady state, not an alert. Keep the status bar quiet
+  // until there is unsaved work or a failure requiring attention.
+  if (state === 'saved') return null;
+  // Destination is the active adapter's own — never a hard-coded path — so
+  // the status honestly reflects where a save (or autosave) would actually go.
+  const destination = activeSaveDestination(store);
+
+  const failed = state === 'failed';
+  const failure = failed ? activeSaveFailure(store) : null;
+  const config = failed
+    ? {
+        label: 'Save failed',
+        title: failure
+          ? `Save failed: ${failure} — click to open Console`
+          : 'Save failed — click to open Console',
+      }
+    : {
+        label: 'Unsaved',
+        title: 'Unsaved changes — click to save (Cmd/Ctrl+S)',
+      };
+  const title = destination ? `${config.title} — ${destination}` : config.title;
+
+  return (
+    <Button
+      type="button"
+      data-testid="save-status"
+      data-save-state={state}
+      variant="ghost"
+      size="compact"
+      className="volter-save-status"
+      onClick={() => (failed ? showConsoleUtility() : void saveActiveAuthoring(store))}
+      title={title}
+    >
+      <span className="volter-save-status-dot" />
+      {config.label}
+    </Button>
+  );
+}

package/src/kit/components/SurfaceCrashBoundary.tsx

@@ -0,0 +1,105 @@
+/**
+ * A CRASH THAT STAYS WHERE IT HAPPENED. One part of the editor's own tree — an
+ * Inspector section, a workspace document such as the UI component board —
+ * that throws while rendering is replaced IN PLACE by its error, with the
+ * message, and nothing above it unmounts.
+ *
+ * Without it the throw climbed to `AppRoot`'s `EditorRuntimeBoundary`, which
+ * swaps the WHOLE editor surface for its startup-error screen. Measured on
+ * raiku-walk (0.5.189, Windows, 2026-10-07): the React inspector's
+ * `ClassesBlock` threw "Invalid hook call" while an agent checked HUD stories
+ * on the UI board, and every panel, the board and the inspector went with it —
+ * to the agent driving the session, the surface simply stopped answering.
+ *
+ * The crash is LOUD as well as contained: an error in the editor console
+ * ledger (what the `console` command and the session log read), with React's
+ * component stack, and a startup failure for the frame's cover, so a crash
+ * drawn under a cover that has not lifted yet is not hidden behind it
+ * (`startup-failure.ts`; `AppRoot`'s boundary publishes the same way). Retry
+ * draws the subtree again; unmounting withdraws the notice.
+ *
+ * Sibling of `ToolHost`'s `ToolErrorBoundary` (a project tool's file, the dock's
+ * wording) and `crash-null-boundary.ts` (a throw that must render nothing).
+ */
+
+import { Button, space, themeVars } from '@volter/sdk/widgets';
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+import { editorConsole } from '@volter/sdk/kit/editor-console';
+import { clearStartupFailure, reportStartupFailure } from '@volter/sdk/kit/startup-failure';
+
+interface SurfaceCrashBoundaryProps {
+  /** Stable id of the part (`inspector-section:<id>`, `document:<id>`): the startup-failure source. */
+  readonly surface: string;
+  /** What crashed, as a person names it ("The Classes inspector section"). */
+  readonly label: string;
+  readonly children?: ReactNode;
+}
+
+interface SurfaceCrashBoundaryState {
+  readonly error: Error | null;
+}
+
+function crashMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export class SurfaceCrashBoundary extends Component<SurfaceCrashBoundaryProps, SurfaceCrashBoundaryState> {
+  override state: SurfaceCrashBoundaryState = { error: null };
+
+  static getDerivedStateFromError(error: unknown): SurfaceCrashBoundaryState {
+    return { error: error instanceof Error ? error : new Error(String(error)) };
+  }
+
+  private get source(): string {
+    return `surface-crash:${this.props.surface}`;
+  }
+
+  override componentDidCatch(error: unknown, info: ErrorInfo): void {
+    const message = crashMessage(error);
+    editorConsole.error(
+      `${this.props.label} crashed while rendering (the rest of the editor is still running): ${message}\n${info.componentStack ?? ''}`,
+      'editor',
+    );
+    reportStartupFailure(this.source, {
+      message: `${this.props.label} crashed: ${message}`,
+      guidance: 'The rest of the editor is still running. Dismiss this; the error is shown in place, with Retry.',
+      command: null,
+    });
+  }
+
+  override componentWillUnmount(): void {
+    clearStartupFailure(this.source);
+  }
+
+  override render(): ReactNode {
+    const { error } = this.state;
+    if (!error) return this.props.children;
+    return (
+      <div
+        role="alert"
+        data-testid="surface-crash"
+        data-surface-crash={this.props.surface}
+        style={{
+          padding: space[4],
+          fontSize: 'var(--volter-font-md)',
+          color: themeVars.semantic.danger,
+          overflow: 'auto',
+        }}
+      >
+        <div style={{ fontWeight: 600, marginBottom: space[2] }}>{this.props.label} crashed</div>
+        <div style={{ whiteSpace: 'pre-wrap', wordBreak: 'break-word' }}>{error.message}</div>
+        <div style={{ color: themeVars.content.muted, marginTop: space[3], marginBottom: space[3] }}>
+          The rest of the editor is still running. The error is in the editor console.
+        </div>
+        <Button
+          onClick={() => {
+            clearStartupFailure(this.source);
+            this.setState({ error: null });
+          }}
+        >
+          Retry
+        </Button>
+      </div>
+    );
+  }
+}

package/src/kit/components/SurfaceStateOverlay.tsx

@@ -0,0 +1,24 @@
+import { StateSurface } from '@volter/sdk/widgets';
+import type { CSSProperties } from 'react';
+import type { SurfaceExplanation } from '@volter/sdk/kit/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/kit/components/ToolContributionSurfaces.tsx

@@ -0,0 +1,49 @@
+import type { ToolAssetDocumentProps, ToolContributionSurfaces } from '@volter/sdk/contributions';
+import { type ComponentType, useCallback, useSyncExternalStore } from 'react';
+import { AssetEditorSubject } from '@volter/sdk/kit/components/AssetEditorShell';
+import { contributionSurface, subscribeContributionSurfaces } from '@volter/sdk/kit/contribution-surfaces';
+
+/**
+ * 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} />;
+}
+
+const forwarders = new Map<string, ComponentType<object>>();
+
+/**
+ * Lightweight contribution boundary: the kit renders the surface a medium's integration
+ * registered under `name` (`kit/contribution-surfaces`) and imports no viewport, so ToolHost
+ * pulls no WebGL or model modules into Node tools and tests.
+ */
+function forwarder(name: string): ComponentType<object> {
+  const existing = forwarders.get(name);
+  if (existing) return existing;
+  function ContributionSurface(props: object) {
+    const read = useCallback(() => contributionSurface(name), []);
+    const Surface = useSyncExternalStore(subscribeContributionSurfaces, read, read) as ComponentType<object> | null;
+    if (!Surface) return <div style={{ minHeight: 240 }}>Loading {name}…</div>;
+    return <Surface {...props} />;
+  }
+  ContributionSurface.displayName = `ContributionSurface(${name})`;
+  forwarders.set(name, ContributionSurface);
+  return ContributionSurface;
+}
+
+/** Stable dependency-injection value shared by every contribution mount: the kit's own surfaces,
+ *  and a forwarder for each name a medium's integration adds. */
+export const toolContributionSurfaces: ToolContributionSurfaces = new Proxy(
+  Object.freeze({ AssetDocument: ToolAssetDocumentSurface }) as ToolContributionSurfaces,
+  {
+    get(target, name, receiver) {
+      // A surface is a component, named like one; `then`, `toJSON` and the rest stay absent.
+      if (typeof name !== 'string' || Reflect.has(target, name) || !/^[A-Z]/.test(name)) {
+        return Reflect.get(target, name, receiver);
+      }
+      return forwarder(name);
+    },
+  },
+);