@volter/editor-sdk 0.5.57

package/src/selection.tsx

@@ -0,0 +1,108 @@
+/**
+ * W3.1 — `useSelection()`, the third tool-hooks contract member (alongside
+ * `useData`/`writeData` from `use-data.ts`). Where those two hooks are about
+ * DATA ASSETS, this one is about the currently-selected ENTITY.
+ *
+ * Scope, v1:
+ *  - INSPECTOR-placement tools only (`placement: 'inspector'`,
+ *    `define-tool.ts`). `EditorSelectionProvider` is host plumbing —
+ *    `InspectorToolSection` wraps every tool render in it; dock tools
+ *    (`ToolHost`/`BottomPanel`) have no adapter/selection in scope and never
+ *    get a provider. Calling `useSelection()` there throws a teaching error,
+ *    contained by the tool's `ToolErrorBoundary` (the editor survives).
+ *  - READ-only. Write through `InspectorProvider.set` / `writeData` (the
+ *    existing paths), never by mutating what this hook returns. Per-entity
+ *    WRITE-from-tool is deferred with `useTunable` (§10).
+ *
+ * Liveness — two existing paths reused, no new mechanism (§4's "reuse that
+ * path" rule):
+ *  1. Selection changes: `Inspector.tsx`'s own
+ *     `useSyncExternalStore(store.subscribe, store.getSnapshot)` re-renders
+ *     the panel, each matched `Section` gets the new `nodeId` prop, and
+ *     `InspectorToolSection` re-creates this provider's context value.
+ *  2. Edits while the SAME node stays selected: `adapter.subscribe` fires —
+ *     this hook keeps a local version counter bumped per notification
+ *     (exactly `game-state.tsx`'s `useRootObservation` pattern: the adapter
+ *     has no snapshot/version of its own, `subscribe` is fire-only) and
+ *     recomputes.
+ */
+
+import type { AuthoringAdapter, EditorNode } from '@volter/editor-project/adapter';
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+} from 'react';
+
+interface SelectionContextValue {
+  adapter: AuthoringAdapter;
+  nodeId: string | null;
+}
+
+const SelectionContext = createContext<SelectionContextValue | null>(null);
+
+/**
+ * EDITOR-side host plumbing: `InspectorToolSection` wraps a tool's rendered
+ * `<Component/>` in this, passing the adapter + nodeId it already holds.
+ * Project tools never render this themselves — it exists so `useSelection()`
+ * has something to read.
+ */
+export function EditorSelectionProvider({
+  adapter,
+  nodeId,
+  children,
+}: {
+  adapter: AuthoringAdapter;
+  nodeId: string | null;
+  children: ReactNode;
+}) {
+  const value = useMemo(() => ({ adapter, nodeId }), [adapter, nodeId]);
+  return <SelectionContext.Provider value={value}>{children}</SelectionContext.Provider>;
+}
+
+export interface EditorSelection {
+  nodeId: string | null;
+  node: EditorNode | null;
+}
+
+/**
+ * The selected entity, live (read-only — see module doc).
+ *
+ * Throws outside an `EditorSelectionProvider` — inspector tools always render
+ * inside one; a dock tool or game-code caller does not, and the error names
+ * the fix rather than failing silently.
+ */
+export function useSelection(): EditorSelection {
+  const ctx = useContext(SelectionContext);
+  if (!ctx) {
+    throw new Error(
+      'useSelection: no editor selection in context — this hook only works inside an editor-hosted ' +
+        "INSPECTOR tool (placement: 'inspector'). Dock tools and " +
+        'game code have no selection to read.',
+    );
+  }
+  const { adapter, nodeId } = ctx;
+
+  // Local version counter bumped per adapter notification — the adapter has
+  // no snapshot/version of its own, `subscribe` is fire-only (same pattern
+  // as `useRootObservation`'s `versionRef`, game-state.tsx).
+  const versionRef = useRef(0);
+  const version = useSyncExternalStore(
+    (onStoreChange) =>
+      adapter.subscribe?.(() => {
+        versionRef.current++;
+        onStoreChange();
+      }) ?? (() => {}),
+    () => versionRef.current,
+  );
+
+  return useMemo(() => {
+    const node = nodeId ? adapter.hierarchy.node(nodeId) : null;
+    return { nodeId, node };
+    // `version` has no value of its own — only its CHANGE matters, as the
+    // liveness signal described above.
+  }, [adapter, nodeId, version]);
+}

package/src/services.ts

@@ -0,0 +1,18 @@
+/**
+ * THE SERVICE POINT (page side) — code a package RUNS for as long as its
+ * contributions are loaded (WORKBENCH.md §Contribution points, `service`):
+ * a page-wide guard, a worker, a listener. The module declares the point and
+ * exports `start`, which returns the stop; the host starts every service
+ * after a contribution pass and stops it before the next.
+ *
+ *   `audio-unlock.service.ts`
+ *     export const point = 'workspace.service';
+ *     export function start(): () => void { … }
+ *
+ * A service that must run BEFORE a project opens does not belong here — it
+ * is the host's boot. Everything that only matters once a project's own
+ * packages are known does.
+ */
+export interface ServiceContribution {
+  start(): (() => void) | undefined | void;
+}

package/src/session/build-report.ts

@@ -0,0 +1,19 @@
+/**
+ * Transient facts about one native project build. The report crosses the
+ * editor server's existing export SSE response; it is not persisted as a
+ * project document or sidecar. Paths are relative to the project's `dist/`.
+ */
+export const WEB_BUILD_ARTIFACT = 'vgai-web.zip';
+
+export interface BuildReportFile {
+  readonly path: string;
+  readonly bytes: number;
+}
+
+export interface BuildReport {
+  readonly artifact: string;
+  readonly artifactBytes: number;
+  readonly outputBytes: number;
+  readonly fileCount: number;
+  readonly largestFiles: readonly BuildReportFile[];
+}

package/src/session/collaboration-types.ts

@@ -0,0 +1,262 @@
+import type { ShareRole } from '../share';
+
+export type CollaborationCapability =
+  | 'view'
+  | 'comment'
+  | 'test'
+  | 'edit'
+  | 'terminal'
+  | 'maintain';
+/**
+ * A collaboration role is a {@link ShareRole} PLUS the local-only `maintainer`,
+ * and it is spelled that way so the relationship is CHECKED. Written as its own
+ * six-member union — which is what it was — the two lists drift with no
+ * compiler signal: a role added to the share wire is simply a role this session
+ * cannot hold, and the only symptom is a participant the UI refuses to promote.
+ */
+export type CollaborationRole = ShareRole | 'maintainer';
+/**
+ * Least authority first; `maintainer` is local-only and has no share role.
+ *
+ * Declared as a `satisfies Record<CollaborationRole, …>` rather than an array
+ * annotated `readonly CollaborationRole[]`, because the array form accepts an
+ * INCOMPLETE list: adding a role to `CollaborationRole` and forgetting it here
+ * compiles, and the only symptom is that `assignableCollaborationRoles` quietly
+ * offers a participant one fewer role than they can hold. A missing key here is
+ * a compile error.
+ */
+const COLLABORATION_ROLE_RANK = {
+  viewer: 0,
+  commenter: 1,
+  tester: 2,
+  editor: 3,
+  terminal: 4,
+  maintainer: 5,
+} as const satisfies Record<CollaborationRole, number>;
+
+export const COLLABORATION_ROLE_ORDER: readonly CollaborationRole[] = (
+  Object.keys(COLLABORATION_ROLE_RANK) as CollaborationRole[]
+).sort((a, b) => COLLABORATION_ROLE_RANK[a] - COLLABORATION_ROLE_RANK[b]);
+
+/**
+ * Which roles a UI may OFFER for one participant. Enforcement is the server's,
+ * always; this only keeps the editor from presenting an option the session
+ * would refuse. A participant that entered through the share gateway carries a
+ * verified `account` and can never reach `maintainer`, nor exceed the ceiling
+ * its invitation set.
+ */
+export function assignableCollaborationRoles(
+  participant: { account: { id: string } | null },
+  ceiling?: CollaborationRole,
+): CollaborationRole[] {
+  if (!participant.account) return [...COLLABORATION_ROLE_ORDER];
+  const remoteLimit = COLLABORATION_ROLE_ORDER.indexOf('terminal');
+  const ceilingIndex = ceiling ? COLLABORATION_ROLE_ORDER.indexOf(ceiling) : remoteLimit;
+  const limit = Math.min(remoteLimit, ceilingIndex < 0 ? remoteLimit : ceilingIndex);
+  return COLLABORATION_ROLE_ORDER.slice(0, limit + 1);
+}
+
+export type ParticipantKind = 'human' | 'agent';
+export type ParticipantStatus = 'active' | 'idle' | 'needs-input' | 'done';
+
+export interface CollaborationParticipantLocation {
+  repositoryId: string;
+  worktreeId: string;
+  sessionId: string;
+}
+
+export interface CollaborationAgentIdentity {
+  harness: string;
+  conversationId: string;
+}
+
+export interface CollaborationCameraPose {
+  x: number;
+  y: number;
+  z: number;
+  targetX: number;
+  targetY: number;
+  targetZ: number;
+  fov: number;
+}
+
+export function isCollaborationCameraPose(value: unknown): value is CollaborationCameraPose {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const camera = value as Record<string, unknown>;
+  const keys = ['x', 'y', 'z', 'targetX', 'targetY', 'targetZ', 'fov'] as const;
+  return (
+    Object.keys(camera).length === keys.length &&
+    keys.every((key) => typeof camera[key] === 'number' && Number.isFinite(camera[key])) &&
+    (camera['fov'] as number) > 0 &&
+    (camera['fov'] as number) < 180
+  );
+}
+
+/**
+ * THE owner of team-message size limits, read by the HTTP route guard and by
+ * `CollaborationSession`'s own methods alike.
+ *
+ * The two used to carry separate numbers and disagree in both directions — the
+ * route accepted 20k of text the session then refused, and refused 50
+ * references the session would have taken — so which error a caller saw
+ * depended on which layer happened to see the message first. Each value here is
+ * the tighter of the pair that split produced.
+ */
+export const TEAM_MESSAGE_LIMITS = {
+  text: 10_000,
+  mentions: 16,
+  mentionLength: 80,
+  references: 32,
+} as const;
+
+export const COLLABORATION_AGENT_MENTIONS = ['agent', 'claude', 'codex'] as const;
+
+export function isCollaborationAgentMention(value: string): boolean {
+  return (COLLABORATION_AGENT_MENTIONS as readonly string[]).includes(value.toLowerCase());
+}
+
+export interface CollaborationPresence {
+  document: string | null;
+  file: string | null;
+  oid: string | null;
+  selection: readonly string[];
+  camera: Readonly<CollaborationCameraPose> | null;
+  gesture: Readonly<Record<string, unknown>> | null;
+  playtest?: {
+    id: string;
+    play: 'starting' | 'ready' | 'error';
+    networking: 'not-declared' | 'connecting' | 'ready' | 'error';
+    roomName: string | null;
+    problem: string | null;
+  } | null;
+}
+
+export interface CollaborationParticipant {
+  participantId: string;
+  /** Verified VGAI account authority. Null only for local-only host/agent
+   * participants that did not enter through a public share gateway. */
+  account: { id: string; email: string; name?: string } | null;
+  displayName: string;
+  kind: ParticipantKind;
+  color: string;
+  status: ParticipantStatus;
+  location: CollaborationParticipantLocation | null;
+  agent: CollaborationAgentIdentity | null;
+  role: CollaborationRole;
+  capabilities: readonly CollaborationCapability[];
+  connectedAt: string;
+  lastSeenAt: string;
+  presence: CollaborationPresence;
+}
+
+export interface CollaborationAuthorProjection {
+  participantId: string;
+  account: { id: string; email: string; name?: string } | null;
+  displayName: string;
+  kind: ParticipantKind;
+  color: string;
+  location: CollaborationParticipantLocation | null;
+}
+
+const PARTICIPANT_COLORS = [
+  '#4f8cff',
+  '#e45c9d',
+  '#20a87a',
+  '#a46de8',
+  '#d9782d',
+  '#2f9eb8',
+  '#ca4f55',
+  '#6f9f32',
+] as const;
+
+export function collaborationParticipantColor(identity: string): string {
+  let hash = 2_166_136_261;
+  for (const codePoint of identity) {
+    hash ^= codePoint.codePointAt(0) ?? 0;
+    hash = Math.imul(hash, 16_777_619);
+  }
+  return PARTICIPANT_COLORS[(hash >>> 0) % PARTICIPANT_COLORS.length]!;
+}
+
+export type TeamMessageReference =
+  | { type: 'worktree'; worktreeId: string }
+  | { type: 'revision'; revision: number }
+  | { type: 'file'; path: string; revision: number }
+  | { type: 'oid'; oid: string; revision: number }
+  | { type: 'asset'; path: string; revision: number }
+  | { type: 'screenshot'; id: string; revision: number }
+  | { type: 'playtest'; id: string; revision: number }
+  | { type: 'diff'; fromRevision: number; toRevision: number };
+
+export interface TeamMessage {
+  id: string;
+  authorId: string;
+  author: CollaborationAuthorProjection;
+  text: string;
+  mentions: readonly string[];
+  references: readonly TeamMessageReference[];
+  threadId: string | null;
+  editedAt: string | null;
+  deletedAt: string | null;
+  reactions: Readonly<Record<string, readonly string[]>>;
+  revision: number;
+  createdAt: string;
+}
+
+export interface SourceRevision {
+  revision: number;
+  authorId: string;
+  author: CollaborationAuthorProjection;
+  source: 'editor' | 'filesystem';
+  resources: readonly { path: string; sha: string | null }[];
+  createdAt: string;
+}
+
+export interface CollaborationAuditEvent {
+  id: string;
+  type: 'join' | 'leave' | 'role' | 'revision' | 'message' | 'agent' | 'playtest' | 'git';
+  participantId: string;
+  createdAt: string;
+  detail: Readonly<Record<string, unknown>>;
+}
+
+export interface TeamPlaytest {
+  id: string;
+  revision: number;
+  seed: number;
+  roomKey: string;
+  startedBy: string;
+  startedAt: string;
+}
+
+export interface CollaborationSnapshot {
+  sequence: number;
+  revision: number;
+  activePlaytest: TeamPlaytest | null;
+  participants: readonly CollaborationParticipant[];
+  messages: readonly TeamMessage[];
+  revisions: readonly SourceRevision[];
+  audit: readonly CollaborationAuditEvent[];
+}
+
+export type CollaborationEventChannel =
+  | 'participants'
+  | 'presence'
+  | 'messages'
+  | 'revisions'
+  | 'audit'
+  | 'team-test';
+
+export interface CollaborationEvent {
+  sequence: number;
+  channel: CollaborationEventChannel;
+  createdAt: string;
+  payload: unknown;
+}
+
+export interface CollaborationResume {
+  cursor: number;
+  reset: boolean;
+  events: readonly CollaborationEvent[];
+  snapshot?: CollaborationSnapshot;
+}