@volter/sdk 0.0.0-stage → 0.5.204

package/src/layouts.tsx

@@ -0,0 +1,108 @@
+/** Programmable editor composition. Layouts are React components, not registry keys. */
+import { type ComponentType, type CSSProperties, createElement, type ReactNode } from 'react';
+import { DesignArrangement, type WorkspaceArrangement } from './layout-arrangements';
+import type { EditorView } from './types';
+
+export {
+  DesignArrangement,
+  GameArrangement,
+  type WorkspaceArrangement,
+} from './layout-arrangements';
+
+export interface EditorLayoutProps {
+  readonly playing: boolean;
+  readonly paused: boolean;
+}
+export type EditorLayout = ComponentType<EditorLayoutProps>;
+export interface LayoutFrameProps {
+  readonly children?: ReactNode;
+  readonly style?: CSSProperties;
+  /** Let the enclosing web page scroll when the pointer is over a viewport. */
+  readonly pageScroll?: boolean;
+}
+export interface WorkspaceProps {
+  readonly arrangement?: WorkspaceArrangement;
+  readonly immersivePlay?: boolean;
+  readonly playUtilities?: readonly string[];
+}
+export interface DocumentHandle {
+  /** Select exactly one named native object; ambiguous/missing names refuse. */
+  select(name: string): void;
+  transform(mode: 'combined' | 'translate' | 'rotate' | 'scale'): void;
+  frame(): void;
+}
+export interface DocumentViewProps {
+  readonly document:
+    | Extract<NonNullable<EditorView['document']>, { kind: 'story' | 'workspace' }>
+    | {
+        readonly kind: 'asset';
+        readonly path: string;
+        readonly assetKind?: 'source' | 'model' | 'image' | 'audio' | 'json';
+      };
+  readonly chrome?: boolean;
+  readonly active?: boolean;
+  readonly onReady?: (document: DocumentHandle) => void;
+}
+export interface LayoutHost {
+  readonly Frame: ComponentType<LayoutFrameProps>;
+  readonly Header: ComponentType;
+  readonly Footer: ComponentType;
+  readonly Workspace: ComponentType<WorkspaceProps>;
+  readonly Document: ComponentType<DocumentViewProps>;
+}
+const HOST_KEY = Symbol.for('volter.editor.layout-host');
+const hosts = globalThis as typeof globalThis & { [HOST_KEY]?: LayoutHost };
+/** Installed once by the editor runtime; project modules share this SDK instance. */
+export function registerLayoutHost(value: LayoutHost): void {
+  hosts[HOST_KEY] = value;
+}
+function currentHost(): LayoutHost {
+  const host = hosts[HOST_KEY];
+  if (!host) throw new Error('Editor layouts require an editor host.');
+  return host;
+}
+export function EditorFrame(props: LayoutFrameProps) {
+  return createElement(currentHost().Frame, props);
+}
+export function EditorHeader() {
+  return createElement(currentHost().Header);
+}
+export function EditorFooter() {
+  return createElement(currentHost().Footer);
+}
+export function Workspace(props: WorkspaceProps) {
+  return createElement(currentHost().Workspace, props);
+}
+export function DocumentView(props: DocumentViewProps) {
+  return createElement(currentHost().Document, props);
+}
+
+/** Full game authoring, with the running game taking over the workspace during Play. */
+export function GameLayout() {
+  return (
+    <EditorFrame>
+      <EditorHeader />
+      <Workspace immersivePlay />
+      <EditorFooter />
+    </EditorFrame>
+  );
+}
+/** Studio keeps its authoring panels and opens analytics while the game runs. */
+export function StudioLayout() {
+  return (
+    <EditorFrame>
+      <EditorHeader />
+      <Workspace immersivePlay={false} playUtilities={['tool:analytics.analytics']} />
+      <EditorFooter />
+    </EditorFrame>
+  );
+}
+export function DesignLayout() {
+  return (
+    <EditorFrame>
+      <EditorHeader />
+      <Workspace arrangement={DesignArrangement} immersivePlay={false} />
+      <EditorFooter />
+    </EditorFrame>
+  );
+}

package/src/looks.ts

@@ -0,0 +1,16 @@
+/** Contribution data types are owned by the project adapter contract. */
+export type {
+  EditorKeyActionId,
+  KeyChord,
+  KeymapBindings,
+  KeymapContribution,
+  KeymapNavigation,
+  WorkspaceLayoutRegions,
+  WorkspaceLayoutContribution,
+  MaterialContribution,
+  DensityContribution,
+  StageContribution,
+  IconCategoryTone,
+  IconSetContribution,
+  StyleContribution,
+} from '@volter/project/adapter/editor-looks';

package/src/project/output-roots.ts

@@ -0,0 +1,73 @@
+/**
+ * The project directories a tool may commit generated bytes into, and the one
+ * normalizer every writer validates a path with.
+ *
+ * A project has two of them, and the difference is what SHIPS:
+ *
+ *   - `public/`     — game assets. Exported, served at a root-relative URL,
+ *                     loaded by the game's own source.
+ *   - `references/` — reference material: moodboards, style plates, generated
+ *                     stills and clips an author or an agent looks at while
+ *                     building. Ordinary files, indexed by the editor's Content
+ *                     panel like any other media, and NOT exported — the
+ *                     project's own build copies `publicDir` and nothing else.
+ *
+ * This lives in the SDK rather than beside one writer because the rule has more
+ * than one enforcer: the editor host's atomic project-output writer, and every
+ * registered provider boundary that takes an `outputDirectory` from a caller.
+ * Two copies of "must be under public/" is how a reference output becomes
+ * writable through one door and refused at the next.
+ */
+
+/** The writable output roots, in the order a chooser should offer them. */
+export const PROJECT_OUTPUT_ROOTS = ['public', 'references'] as const;
+
+export type ProjectOutputRoot = (typeof PROJECT_OUTPUT_ROOTS)[number];
+
+/** Human-readable list for an error message: `public/` or `references/`. */
+function rootList(): string {
+  return PROJECT_OUTPUT_ROOTS.map((root) => `${root}/`).join(' or ');
+}
+
+/** POSIX-normalized, `./`-stripped, trailing-slash-stripped. */
+function normalizeSlashes(path: string): string {
+  const slashed = path.replaceAll('\\', '/');
+  const segments: string[] = [];
+  for (const segment of slashed.split('/')) {
+    if (segment === '' || segment === '.') continue;
+    segments.push(segment);
+  }
+  return segments.join('/');
+}
+
+/** The root `path` sits under, or `undefined` when it sits under none. */
+export function projectOutputRootOf(path: string): ProjectOutputRoot | undefined {
+  const normalized = normalizeSlashes(path);
+  return PROJECT_OUTPUT_ROOTS.find(
+    (root) => normalized === root || normalized.startsWith(`${root}/`),
+  );
+}
+
+/**
+ * Validate and normalize a project-relative output path.
+ *
+ * Throws — with a message naming BOTH roots, because the common mistake is
+ * knowing about one of them — for an absolute path, an escape, a bare root
+ * with no file under it, or anything outside the roots above. `subject` names
+ * what is being validated in that message (`Generated output path`, `Fal
+ * outputDirectory`, …).
+ */
+export function normalizeProjectOutputPath(
+  path: string,
+  subject = 'Generated output path',
+): string {
+  const normalized = normalizeSlashes(path);
+  const escapes = normalized.split('/').includes('..');
+  const root = projectOutputRootOf(normalized);
+  if (path.startsWith('/') || escapes || root === undefined || normalized === root) {
+    throw new Error(
+      `${subject} ${JSON.stringify(path)} is invalid; it must be a project-relative path under ${rootList()}.`,
+    );
+  }
+  return normalized;
+}

package/src/project/tab-census.ts

@@ -0,0 +1,155 @@
+/**
+ * THE TAB RESOURCE CENSUS — one declaration of the profile a browser tab
+ * reports about itself, for every compilation unit that speaks it.
+ *
+ * WHAT IT IS. What a game tab is holding: JS heap, canvas backing stores,
+ * renderer resource counts, and how many project mount generations the
+ * document has accumulated. Sampled by the page every five seconds and carried
+ * on the heartbeat, so that a browser-level renderer death — which the presence
+ * system recovers from perfectly and would otherwise leave unexplained — has a
+ * number beside it. MEASUREMENT ONLY: nothing anywhere enforces a budget from
+ * these. The page-side sampler and its `why` are
+ * `packages/sdk/src/kit/tab-census.ts`.
+ *
+ * WHY IT LIVES HERE. This one shape crosses every compilation unit that speaks
+ * it — the page that samples it (`@volter/sdk`'s kit), the editor server
+ * that files it and the session journal that prints it (`@volter/editor-core`'s
+ * node half), and the extension surface that describes the status response
+ * (`@volter/sdk`'s types). `@volter/sdk` is the one package all of
+ * them depend on. It does not belong in `@volter/game-runtime`, whose subject is
+ * a running game, not an editor session's tabs.
+ *
+ * Deliberately import-free so a browser bundle can take it: the census's
+ * journal, `editor-core/server/support/project/session-journal.ts`, reads
+ * `node:fs`.
+ *
+ * WHAT ELSE RIDES IT. The beat is the one channel that still moves when the
+ * page's main thread or a lane's worker is blocked, so `workerCalls` — how long
+ * each lane's worker calls are taking, keyed by the lane's own name — and
+ * `stalls` — how long the main thread has been stalled — are carried here too
+ * (absent until a lane publishes a meter). Same rule as the rest of this file:
+ * measurement only, no budget anywhere.
+ *
+ * ABSENT IS NOT ZERO. `heapUsedMB`/`heapLimitMB` are null off Chromium
+ * (`performance.memory` is non-standard). The renderer counts are ABSENT rather
+ * than zero when no game has registered a render-debug adapter, and `programs`
+ * is absent until a first render: a zero would read as "no textures", which is
+ * a different claim from "nobody measured".
+ */
+
+/**
+ * ONE LANE'S WORKER CALLS, as numbers.
+ *
+ * WHY (measured 2026-09-16): one Blender call held its worker for over 1,800s
+ * and wedged the tab, and a 0.86s-per-call scene stretched into heartbeat
+ * timeouts that read as "tab present, did not respond". The product had no
+ * number for either. Owner ruling: a tab that stops answering is the product's
+ * defect regardless of what the machine is doing, and the product has to
+ * surface it — so these ride the census to the editor's `status` command.
+ *
+ * MEASURED BY THE PAGE, because neither blocked party can report on itself: the
+ * worker's own loop is what is stuck, and a stalled main thread cannot send.
+ * The call half is the lane's meter (`host.session.reportWorkerCallMeter`), and
+ * the stall half is the host's `longtask` observer.
+ *
+ * MEASUREMENT ONLY. No threshold here cancels, kills or budgets a call.
+ */
+export interface WorkerCallTabMetrics {
+  /** Age of the oldest OUTSTANDING worker call, or null when the worker is idle.
+   *  The only field with a number during a wedge. */
+  readonly inFlightMs: number | null;
+  /** Duration of the newest completed call; null before the first one. */
+  readonly lastCallMs: number | null;
+  /** The longest call this page has seen, counting an outstanding one. */
+  readonly maxCallMs: number | null;
+  /** Optional operation/boundary label supplied by the lane, without request payloads. */
+  readonly maxCallLabel?: string | null;
+  /** Current cooperative phase and count of settled wire requests; sampled, not pushed per unit. */
+  readonly currentPhase?: string | null;
+  readonly completedCalls?: number;
+  /** Calls past 5s, and past 30s, since this page loaded. */
+  readonly callsOver5s: number;
+  readonly callsOver30s: number;
+  /** The longest long task that overlapped the newest call's window — what the
+   *  MAIN thread was doing while the worker was busy. Null when there has been
+   *  no call yet, or no long task during it. */
+  readonly lastCallLongestTaskMs: number | null;
+  /**
+   * THE ENGINE'S OWN MEMORY: the lane's wasm module's linear memory in MB, read
+   * in its worker and posted after every call; null when the lane has none.
+   *
+   * It is here because no other number on this census answers the question.
+   * `heapUsedMB` is the PAGE's JS heap — a few tens of MB — while an engine's
+   * memory can be the larger half of the tab by far, and a reader looking at
+   * the heap line alone concludes the tab is cheap. wasm32 memory never
+   * shrinks, so this is simultaneously the current size and the session's
+   * high-water mark.
+   */
+  readonly wasmMemoryMB: number | null;
+}
+
+/** THE MAIN THREAD'S STALLS since page load, from the host's `longtask`
+ *  observer, which starts when the first lane publishes a meter. */
+export interface TabStallMetrics {
+  /** Longest `longtask` entry, in ms; null off Chromium (the Long Tasks API is
+   *  not implemented everywhere) — never 0, which would read as "the main
+   *  thread never stalled". */
+  readonly longestTaskMs: number | null;
+  /** How many long tasks ran past 100ms. */
+  readonly tasksOver100ms: number;
+}
+
+/**
+ * A census as a CURRENT page produces it and the server files it.
+ *
+ * Every field here is guaranteed by a producer that always writes it, and
+ * `packages/editor-core/server/tab-heartbeat.ts`'s `parseCensus` is where that is
+ * checked: a beat frame missing `canvases`, `canvasMB` or `mountEpochs` is
+ * rejected outright rather than filed as a partial profile.
+ */
+export interface TabCensus {
+  /** `performance.memory.usedJSHeapSize` in MB; null off Chromium. */
+  readonly heapUsedMB: number | null;
+  /** `performance.memory.jsHeapSizeLimit` in MB; null off Chromium. */
+  readonly heapLimitMB: number | null;
+  /** Distinct project mount generations fetched by this document. */
+  readonly mountEpochs: number;
+  /** How many `<canvas>` elements the document holds. */
+  readonly canvases: number;
+  /** Their total pixel-buffer footprint: Σ width×height×4 bytes, in MB. */
+  readonly canvasMB: number;
+  /** `renderer.info.memory.textures` — absent with no mounted adapter. */
+  readonly textures?: number;
+  /** `renderer.info.memory.geometries` — absent with no mounted adapter. */
+  readonly geometries?: number;
+  /** Compiled programs — absent with no adapter, or before the first render. */
+  readonly programs?: number;
+  /** Each lane's {@link WorkerCallTabMetrics}, keyed by the name the lane
+   *  published under — absent until a lane publishes a meter. */
+  readonly workerCalls?: Readonly<Record<string, WorkerCallTabMetrics>>;
+  /** {@link TabStallMetrics} — absent until the host is watching its stalls. */
+  readonly stalls?: TabStallMetrics;
+}
+
+/**
+ * A census read back out of a RECORD, where the writer may predate a field.
+ *
+ * Exactly one field varies, and this is the only place that is said: a session
+ * journal line written before the mount census existed has no `mountEpochs`,
+ * and neither does a status response from an older editor server. The
+ * difference is a property of the READER's input, so it is named on the
+ * reader's type rather than by softening {@link TabCensus} — which is what the
+ * four hand-copied declarations did, and how the producers' own guarantee got
+ * lost on the way to the two SDKs.
+ *
+ * There is no runtime narrowing to point at because neither reader has a parse
+ * step to put one in: the journal is `JSON.parse` per line by recorded design
+ * (`session-journal.ts`: "nothing reads a journal back through a validator"),
+ * and the CLI reads the status body as JSON. So the absence is carried in the
+ * type and handled where it is printed — `formatTabCensus` omits the words
+ * rather than printing a fabricated count. Every {@link TabCensus} is a valid
+ * value of this type; the reverse is not.
+ */
+export type RecordedTabCensus = Omit<TabCensus, 'mountEpochs'> & {
+  readonly mountEpochs?: number;
+};

package/src/project-tool-catalog.ts

@@ -0,0 +1,104 @@
+export type ToolContributionPoint =
+  | 'workspace.document'
+  | 'selection.inspector'
+  | 'asset.inspector'
+  | 'generation.result'
+  | 'workspace.utility'
+  | 'workspace.analytics'
+  | 'workspace.status';
+
+/**
+ * One contribution module, FOUND BY SCANNING — never listed anywhere.
+ *
+ * Nothing enumerates these. `editor/tools/` in project source and `src/` in every
+ * `volter`-declaring dependency are walked for the naming convention
+ * (`*.document.tsx`, `*.inspector.tsx`, `*.asset-inspector.tsx`,
+ * `*.result.tsx`, `*.utility.tsx`, `*.analytics.tsx`), and the module itself declares everything
+ * else: `point`, `title` (or `presentations`), and the `tool` it drives, by
+ * name. Its id is derived from this path. A manifest cannot disagree with a
+ * module it does not mention.
+ */
+export interface ProjectToolContribution {
+  /** Project-relative or package-absolute browser module path. */
+  entryPath: string;
+  /** The dependency that declared it (`package.json#volter.contributions`),
+   *  absent for the project's own `editor/contributions/` modules. */
+  package?: string;
+  /** The module's file, for a bundled package's entry (listed by specifier): what the
+   *  page loads when its bundle carries no loader for it, as a checkout's bundle does
+   *  not for a contribution added after it was built. */
+  filePath?: string;
+}
+
+export interface ProjectToolErrorSummary {
+  code: string;
+  summary: string;
+  dataSchema?: unknown;
+}
+
+export interface ProjectToolCatalogEntry {
+  name: string;
+  summary: string;
+  description: string;
+  sourcePath: string;
+  inputSchema: unknown;
+  resultSchema: unknown;
+  errors: ProjectToolErrorSummary[];
+  requires: Record<string, boolean | undefined>;
+  host: 'node' | 'editor-browser' | 'runtime-page';
+  mutates: boolean;
+  supportsDryRun: boolean;
+  longRunning: boolean;
+  permission: { risk: 'read' | 'write' | 'destructive'; summary: string };
+  generation?: { provider: string; role: 'submit' | 'poll' | 'cancel' | 'accept' };
+}
+
+export interface ProjectToolLoadError {
+  sourcePath: string;
+  message: string;
+}
+
+/**
+ * What a host says when it cannot load the project's TypeScript at all.
+ *
+ * ONE owner for the sentence, because two realms reach this state through
+ * different doors and both must say the same true thing rather than fall back
+ * to a fabricated empty catalog:
+ *
+ *  - the NODE side (`packages/editor/server/project-tools.ts`) when a host
+ *    builds the catalog with no `loadModule`; and
+ *  - the PAGE side (`packages/editor/src/project-tools.ts`), whose fetch of
+ *    `/__editor/project-tools` can be answered by an SPA FALLBACK — `200` and
+ *    HTML — when no editor server is in front of the origin, so an unguarded
+ *    fetch that merely checks `response.ok` reads a successful page load as a
+ *    successful catalog, then dies in
+ *    `res.json()`. The panel's empty state ("No project tools registered")
+ *    is a FACT about the project; a host that cannot ask has not learned it.
+ */
+export const NO_PROJECT_MODULE_HOST_MESSAGE =
+  'This editor host cannot RUN registered project tools (package.json#volter.tools): callables ' +
+  'execute on the Node side. Contribution panels still load from project source; to run the ' +
+  'tools themselves, open the project in the Vite-backed dev or packaged editor.';
+
+/** The catalog row that states {@link NO_PROJECT_MODULE_HOST_MESSAGE}. */
+export function noProjectModuleHostError(): ProjectToolLoadError {
+  return { sourcePath: 'package.json#volter.tools', message: NO_PROJECT_MODULE_HOST_MESSAGE };
+}
+
+/**
+ * Callables and contribution modules are SIBLINGS, not parent and child.
+ *
+ * They used to be nested — `tools[].contributions[]` — purely so the browser
+ * loader had a tool to hand the component. A document is not owned by one
+ * callable, and the nesting made project source structurally unable to present
+ * a dependency-provided tool. The module names the tool it drives instead.
+ */
+export interface ProjectToolCatalog {
+  tools: ProjectToolCatalogEntry[];
+  contributions: ProjectToolContribution[];
+  loadErrors: ProjectToolLoadError[];
+  /** The contribution suffixes the serving host scans for
+   *  (`TOOL_CONTRIBUTION_SUFFIXES`), so a page built from another revision can
+   *  say which half is stale. */
+  suffixes?: readonly string[];
+}

package/src/selection.tsx

@@ -0,0 +1,107 @@
+/**
+ * W3.1 — `useSelection()`, the tool-hooks contract member 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` (the
+ *    existing path), 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/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,22 @@
+/**
+ * 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/`.
+ */
+/** The web build's download name: `<project-slug>-web.zip`. */
+export function webBuildArtifactName(projectSlug: string): string {
+  return `${projectSlug}-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[];
+}