@volter/editor-core 0.5.57

package/src/chrome-registry.ts

@@ -0,0 +1,159 @@
+/**
+ * CONTRIBUTED CHROME — the registry behind `@volter/editor-sdk/chrome`: the
+ * palette actions, application-menu items and header items a package
+ * contributes.
+ *
+ * WHO READS IT, measured rather than assumed: `palette-action-publisher.tsx`
+ * takes {@link contributedActions} into the table the frame registers as
+ * `MenuId.CommandPalette` items (so ⌘⇧P lists a package's actions with its own
+ * labels); `components/ApplicationMenus.tsx` appends
+ * {@link contributedMenuItems} per menu id; `components/ProjectHeader.tsx` and
+ * `components/Object3DDocumentToolbar.tsx` draw {@link contributedHeaderItems}
+ * in the title bar and the document's own strip; `tool-loader.ts` registers
+ * what a package declares. Ids are namespaced `tool:` so they never collide
+ * with the host's.
+ */
+
+import type {
+  ActionContribution,
+  ContributableMenu,
+  ContributedAction,
+  ContributedMenuItem,
+  DocumentHeaderItemProps,
+  HeaderPlacement,
+  MenuContribution,
+} from '@volter/editor-sdk/chrome';
+import type { ComponentType } from 'react';
+
+const CONTRIBUTABLE_MENUS: readonly ContributableMenu[] = [
+  'asset',
+  'view',
+  'window',
+  'debug',
+  'tools',
+  'help',
+];
+
+export interface ContributedHeaderItem {
+  readonly id: string;
+  readonly order: number;
+  readonly placement: HeaderPlacement;
+  readonly Component: ComponentType<DocumentHeaderItemProps>;
+}
+
+let headerItems: ContributedHeaderItem[] = [];
+let actionRegistrations: readonly ActionContribution[] = [];
+let menuItems: Array<{ menu: ContributableMenu; item: ContributedMenuItem }> = [];
+let version = 0;
+const listeners = new Set<() => void>();
+function notify(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+export function subscribeContributedChrome(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function contributedChromeVersion(): number {
+  return version;
+}
+
+/** Header items in `order`, ties by registration. */
+export function contributedHeaderItems(
+  placement: HeaderPlacement = 'transport',
+): readonly ContributedHeaderItem[] {
+  return headerItems
+    .filter((item) => item.placement === placement)
+    .sort((a, b) => a.order - b.order);
+}
+
+/** Register one header item (`.header.tsx`, `tool:<id>`). Returns the unregister. */
+export function registerContributedHeaderItem(item: ContributedHeaderItem): () => void {
+  if (headerItems.some((existing) => existing.id === item.id))
+    throw new Error(`header item "${item.id}" is already contributed.`);
+  headerItems = [...headerItems, item];
+  notify();
+  return () => {
+    headerItems = headerItems.filter((existing) => existing !== item);
+    notify();
+  };
+}
+
+export function contributedActions(): readonly ContributedAction[] {
+  const seen = new Set<string>();
+  const out: ContributedAction[] = [];
+  for (const registration of actionRegistrations) {
+    const list =
+      typeof registration.actions === 'function' ? registration.actions() : registration.actions;
+    for (const action of list) {
+      const id = `tool:${action.id}`;
+      // A live set may repeat a static id across its own reads; first wins.
+      if (seen.has(id)) continue;
+      seen.add(id);
+      out.push({ ...action, id });
+    }
+  }
+  return out;
+}
+
+export function contributedMenuItems(menu: ContributableMenu): readonly ContributedMenuItem[] {
+  return menuItems.filter((entry) => entry.menu === menu).map((entry) => entry.item);
+}
+
+export function isContributableMenu(value: unknown): value is ContributableMenu {
+  return typeof value === 'string' && (CONTRIBUTABLE_MENUS as readonly string[]).includes(value);
+}
+
+/**
+ * Register a contribution's actions, each under `tool:<id>`. A fixed list is
+ * checked for duplicate ids now; a live one (`actions` as a function) is read
+ * on every listing and re-listed whenever its `subscribe` fires. Returns the
+ * unregister.
+ */
+export function registerContributedActions(contribution: ActionContribution): () => void {
+  if (typeof contribution.actions !== 'function') {
+    const listed = contributedActions();
+    for (const action of contribution.actions)
+      if (listed.some((existing) => existing.id === `tool:${action.id}`))
+        throw new Error(`action "tool:${action.id}" is already contributed.`);
+  }
+  actionRegistrations = [...actionRegistrations, contribution];
+  const stop = contribution.subscribe?.(notify);
+  notify();
+  return () => {
+    stop?.();
+    actionRegistrations = actionRegistrations.filter((existing) => existing !== contribution);
+    notify();
+  };
+}
+
+/** Register a contribution's menu items on one menu. Returns the unregister. */
+export function registerContributedMenu(contribution: MenuContribution): () => void {
+  const added = contribution.items.map((item) => ({
+    menu: contribution.menu,
+    item: { ...item, id: `tool:${item.id}` },
+  }));
+  for (const entry of added)
+    if (menuItems.some((existing) => existing.item.id === entry.item.id))
+      throw new Error(`menu item "${entry.item.id}" is already contributed.`);
+  menuItems = [...menuItems, ...added];
+  notify();
+  return () => {
+    menuItems = menuItems.filter((entry) => !added.includes(entry));
+    notify();
+  };
+}
+
+/**
+ * A fingerprint of every contributed item's CURRENT `disabled` answer, across
+ * every menu. The point (`@volter/editor-sdk/chrome`) promises that `disabled`
+ * is asked at render and may follow session state — which is only true if
+ * something re-renders the bar when that state moves. `ApplicationMenus`
+ * samples this on the shared availability tick while a menu is OPEN, so an
+ * item can go live or dead under the cursor and costs nothing when closed.
+ */
+export function contributedDisabledFingerprint(): string {
+  return menuItems.map((entry) => (entry.item.disabled?.({}) ? '1' : '0')).join('');
+}

package/src/chrome-slot-registry.ts

@@ -0,0 +1,91 @@
+/**
+ * A CHROME SLOT IS A PLACE, NOT A PANEL — the third registry in the same
+ * family as `workspace-document-restore.ts` (a kind owns its persisted state)
+ * and `document-open-registry.ts` (a kind owns how it opens). Here: the host
+ * owns WHERE something sits and how big it is; a package owns WHAT sits there.
+ *
+ * WHY IT EXISTS. The host's chrome had two places whose CONTENT was a product
+ * opinion rather than a workbench concern: the `agent` static panel
+ * (`components/workspace-static-panel-registry.tsx` imported
+ * `ConversationPanel`) and the bottom bar beside the status line
+ * (`components/EditorBottomBar.tsx` imported `HarnessConversationTray`). Both
+ * are an AGENT-HARNESS conversation surface — it talks to coding harnesses, not
+ * to a game, not to a document — so a base library for making IDEs should not
+ * carry it, and neither of the two existing seams fits: it is not a document,
+ * so it neither opens nor persists (WORK.md §The open-source launch, phase 1
+ * unit 6 half A).
+ *
+ * WHAT A SLOT ID IS. A plain string in the host's own vocabulary, spelled at
+ * the ONE host call site that renders the slot. The host declares the place in
+ * its own layout inventory (`workspace-static-panels.ts` still lists the
+ * `agent` panel's title, hotkey scope and placement, because the frame
+ * PERSISTS panel ids and the tab's own chrome is the dock's); what it no
+ * longer holds is the surface.
+ *
+ * NOTHING REGISTERED IS A REAL ANSWER. A build whose package list carries no
+ * filler for a slot renders nothing there — the same honest emptiness a
+ * document kind with no registered opener gives.
+ */
+
+import type { ComponentType } from 'react';
+
+export interface ChromeSlotFiller {
+  /** The place, in the host's vocabulary (`panel:agent`, `bottom-bar`). */
+  readonly slot: string;
+  /** Which module registered it. Re-registering the same owner+slot REPLACES,
+   *  so an HMR re-evaluation leaves one filler, not two. */
+  readonly owner: string;
+  /** Ascending; ties keep registration order. */
+  readonly order?: number;
+  readonly Content: ComponentType;
+}
+
+const _fillers = new Map<string, ChromeSlotFiller[]>();
+const listeners = new Set<() => void>();
+let version = 0;
+
+function publish(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+/** Install a filler. Returns the teardown. */
+export function registerChromeSlot(filler: ChromeSlotFiller): () => void {
+  const existing = _fillers.get(filler.slot) ?? [];
+  const next = existing.filter((item) => item.owner !== filler.owner);
+  next.push(filler);
+  next.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  _fillers.set(filler.slot, next);
+  publish();
+  return () => {
+    const current = _fillers.get(filler.slot);
+    if (!current) return;
+    const remaining = current.filter((item) => item !== filler);
+    if (remaining.length === 0) _fillers.delete(filler.slot);
+    else _fillers.set(filler.slot, remaining);
+    publish();
+  };
+}
+
+/** Everything registered for `slot`, in order. A stable array per version, so
+ *  it is a safe `useSyncExternalStore` snapshot. */
+export function chromeSlotFillers(slot: string): readonly ChromeSlotFiller[] {
+  return _fillers.get(slot) ?? EMPTY;
+}
+
+const EMPTY: readonly ChromeSlotFiller[] = [];
+
+export function subscribeChromeSlots(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function chromeSlotRegistryVersion(): number {
+  return version;
+}
+
+/** Test-only reset (mirrors the restore and open registries' own). */
+export function __resetChromeSlotsForTest(): void {
+  _fillers.clear();
+  publish();
+}

package/src/collaboration-client.ts

@@ -0,0 +1,264 @@
+import type {
+  CollaborationEvent,
+  CollaborationPresence,
+  CollaborationRole,
+  CollaborationSnapshot,
+  TeamMessage,
+  TeamMessageReference,
+  TeamPlaytest,
+} from '@volter/editor-sdk/session/collaboration-types';
+import { connectEvents, EDITOR_PARTICIPANT_ID, type EditorEventSource } from './editor-presence';
+import { assertEditorServerAnswered } from './editor-server-response';
+import { setCollaborationRevision } from './editor-session-attribution';
+
+const BASE = '/__editor/collaboration';
+const EVENT_CHANNELS = [
+  'participants',
+  'presence',
+  'messages',
+  'revisions',
+  'audit',
+  'team-test',
+] as const;
+let current: CollaborationSnapshot | null = null;
+const listeners = new Set<(snapshot: CollaborationSnapshot) => void>();
+const revisionListeners = new Set<(revision: number) => void>();
+// High-water mark of already-published source revisions. Only a SOURCE
+// revision advances `revision`; presence-only publishes reuse it. Tracked on
+// EVERY publish (with or without revision listeners), so a subscriber's
+// baseline is the current revision at subscribe time and it never fires
+// retroactively for a revision already in effect.
+let lastNotifiedRevision = 0;
+
+function publish(snapshot: CollaborationSnapshot): void {
+  current = snapshot;
+  setCollaborationRevision(snapshot.revision);
+  for (const listener of listeners) listener(snapshot);
+  if (snapshot.revision > lastNotifiedRevision) {
+    lastNotifiedRevision = snapshot.revision;
+    for (const listener of revisionListeners) listener(snapshot.revision);
+  }
+}
+
+async function json<T>(path: string, init?: RequestInit): Promise<T> {
+  const response = await fetch(`${BASE}${path}`, init);
+  // 204 carries no body and so no content type; everything else here is JSON,
+  // failures included. A shared session reaches this route through a TUNNEL,
+  // where a page fallback is a live possibility rather than a theoretical one.
+  if (response.status !== 204) {
+    assertEditorServerAnswered(response, `Collaboration request ${path} failed`);
+  }
+  if (!response.ok) {
+    const body = (await response.json().catch(() => null)) as { error?: unknown } | null;
+    throw new Error(typeof body?.error === 'string' ? body.error : `Collaboration request failed.`);
+  }
+  return (response.status === 204 ? undefined : await response.json()) as T;
+}
+
+export function collaborationSnapshot(): CollaborationSnapshot | null {
+  return current;
+}
+
+let streamRelease: (() => void) | null = null;
+let streamRefCount = 0;
+
+/**
+ * Connect ONCE to the shared editor SSE stream and drive `publish` from it,
+ * ref-counted so every consumer — the collaboration panel AND a design
+ * session subscribing for revision advances — shares ONE set of collaboration
+ * listeners over the single page-lifetime `connectEvents()` socket. The last
+ * release removes those listeners and closes its `connectEvents` handle.
+ */
+function acquireCollaborationStream(): () => void {
+  streamRefCount++;
+  if (!streamRelease) {
+    const events: EditorEventSource = connectEvents();
+    const onSnapshot = (event: MessageEvent) => {
+      try {
+        publish(JSON.parse(event.data) as CollaborationSnapshot);
+      } catch {
+        // A malformed event is ignored; the next complete snapshot repairs it.
+      }
+    };
+    let refreshPending = false;
+    const refresh = () => {
+      if (refreshPending) return;
+      refreshPending = true;
+      void json<CollaborationSnapshot>('')
+        .then(publish)
+        .catch(() => {})
+        .finally(() => {
+          refreshPending = false;
+        });
+    };
+    const onTypedEvent = (message: MessageEvent) => {
+      try {
+        const event = JSON.parse(message.data) as CollaborationEvent;
+        if (!current || event.sequence <= current.sequence) return;
+        if (event.channel !== 'presence') {
+          refresh();
+          return;
+        }
+        const payload = event.payload as { participantId?: unknown; presence?: unknown };
+        if (typeof payload.participantId !== 'string' || !payload.presence) return;
+        publish({
+          ...current,
+          sequence: event.sequence,
+          participants: current.participants.map((participant) =>
+            participant.participantId === payload.participantId
+              ? { ...participant, presence: payload.presence as CollaborationPresence }
+              : participant,
+          ),
+        });
+      } catch {
+        // The next snapshot or typed event repairs malformed transient input.
+      }
+    };
+    events.addEventListener('collaboration-snapshot', onSnapshot);
+    for (const channel of EVENT_CHANNELS) {
+      events.addEventListener(`collaboration-${channel}`, onTypedEvent);
+    }
+    void json<CollaborationSnapshot>('')
+      .then(publish)
+      .catch(() => {});
+    streamRelease = () => {
+      events.removeEventListener('collaboration-snapshot', onSnapshot);
+      for (const channel of EVENT_CHANNELS) {
+        events.removeEventListener(`collaboration-${channel}`, onTypedEvent);
+      }
+      events.close();
+    };
+  }
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    streamRefCount--;
+    if (streamRefCount <= 0) {
+      streamRefCount = 0;
+      streamRelease?.();
+      streamRelease = null;
+    }
+  };
+}
+
+export function connectCollaboration(
+  listener: (snapshot: CollaborationSnapshot) => void,
+): () => void {
+  listeners.add(listener);
+  if (current) listener(current);
+  const releaseStream = acquireCollaborationStream();
+  return () => {
+    listeners.delete(listener);
+    releaseStream();
+  };
+}
+
+/**
+ * Fire `listener(revision)` whenever the collaboration snapshot's source
+ * revision strictly ADVANCES — the reliable signal that a collaborator (or
+ * this editor) changed project source, delivered over the same SSE stream
+ * presence rides rather than the fragile HMR websocket. It ensures that
+ * stream is connected, so a subscriber is self-sufficient even if the
+ * collaboration panel never opened, and shares the single ref-counted
+ * connection every other consumer uses (the last unsubscribe closes it). The
+ * current revision is the baseline: a subscriber never fires for a revision
+ * already in effect at subscribe time, only for a strictly greater one after.
+ */
+export function subscribeCollaborationRevision(listener: (revision: number) => void): () => void {
+  revisionListeners.add(listener);
+  const releaseStream = acquireCollaborationStream();
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    revisionListeners.delete(listener);
+    releaseStream();
+  };
+}
+
+export async function updateCollaborationPresence(presence: CollaborationPresence): Promise<void> {
+  await json<void>('/presence', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ participantId: EDITOR_PARTICIPANT_ID, presence }),
+  });
+}
+
+export async function postTeamMessage(
+  text: string,
+  options: {
+    mentions?: readonly string[];
+    references?: readonly TeamMessageReference[];
+    threadId?: string | null;
+  } = {},
+): Promise<TeamMessage> {
+  return json<TeamMessage>('/message', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      authorId: EDITOR_PARTICIPANT_ID,
+      text,
+      mentions: options.mentions ?? [],
+      references: options.references ?? [],
+      threadId: options.threadId ?? null,
+    }),
+  });
+}
+
+export async function editTeamMessage(messageId: string, text: string): Promise<TeamMessage> {
+  return json<TeamMessage>(`/messages/${encodeURIComponent(messageId)}`, {
+    method: 'PATCH',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ actorId: EDITOR_PARTICIPANT_ID, text }),
+  });
+}
+
+export async function deleteTeamMessage(messageId: string): Promise<TeamMessage> {
+  return json<TeamMessage>(`/messages/${encodeURIComponent(messageId)}`, {
+    method: 'DELETE',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ actorId: EDITOR_PARTICIPANT_ID }),
+  });
+}
+
+export async function toggleTeamMessageReaction(
+  messageId: string,
+  reaction: string,
+): Promise<TeamMessage> {
+  return json<TeamMessage>(`/messages/${encodeURIComponent(messageId)}/reactions`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ actorId: EDITOR_PARTICIPANT_ID, reaction }),
+  });
+}
+
+export async function setCollaborationRole(
+  participantId: string,
+  role: CollaborationRole,
+): Promise<void> {
+  await json<void>('/role', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ actorId: EDITOR_PARTICIPANT_ID, participantId, role }),
+  });
+}
+
+export async function startTeamTest(): Promise<TeamPlaytest> {
+  return json('/team-test', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ participantId: EDITOR_PARTICIPANT_ID }),
+  });
+}
+
+export async function stopTeamTest(playtestId: string): Promise<void> {
+  await json<void>('/team-test/stop', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      participantId: EDITOR_PARTICIPANT_ID,
+      playtestId,
+    }),
+  });
+}

package/src/collaboration-presence.ts

@@ -0,0 +1,41 @@
+import type { CollaborationPresence } from '@volter/editor-sdk/session/collaboration-types';
+import { updateCollaborationPresence } from './collaboration-client';
+
+let presence: CollaborationPresence = {
+  document: null,
+  file: null,
+  oid: null,
+  selection: [],
+  camera: null,
+  gesture: null,
+};
+let sent = '';
+let scheduled = false;
+let inFlight = false;
+
+const PRESENCE_INTERVAL_MS = 100;
+
+function schedulePresence(): void {
+  if (scheduled || inFlight) return;
+  scheduled = true;
+  globalThis.setTimeout(() => {
+    scheduled = false;
+    const serialized = JSON.stringify(presence);
+    if (serialized === sent) return;
+    sent = serialized;
+    inFlight = true;
+    void updateCollaborationPresence(presence)
+      .catch(() => {
+        sent = '';
+      })
+      .finally(() => {
+        inFlight = false;
+        if (JSON.stringify(presence) !== sent) schedulePresence();
+      });
+  }, PRESENCE_INTERVAL_MS);
+}
+
+export function reportCollaborationPresence(patch: Partial<CollaborationPresence>): void {
+  presence = { ...presence, ...patch };
+  schedulePresence();
+}

package/src/command-dispatch.ts

@@ -0,0 +1,19 @@
+/**
+ * EVERY RELAYED COMMAND, observed — the host's side of
+ * `host.session.onCommandDispatched`. `command-listener.ts` notes each
+ * command's type at the top of its dispatch; an idle watchdog (Play's
+ * recording: "an agent still driving through `vgai eval` is not idle,
+ * whatever the command was") subscribes rather than being named there.
+ */
+const listeners = new Set<(type: string) => void>();
+
+export function onCommandDispatched(fn: (type: string) => void): () => void {
+  listeners.add(fn);
+  return () => {
+    listeners.delete(fn);
+  };
+}
+
+export function noteCommandDispatched(type: string): void {
+  for (const fn of listeners) fn(type);
+}