@volter/sdk 0.0.0-stage → 0.5.204

package/src/css-numeric-style.ts

@@ -0,0 +1,97 @@
+/**
+ * THE ONE PLACE that knows a CSS numeric style value is not the same thing as
+ * its CSS TEXT.
+ *
+ * React's own rule (`dangerousStyleValue`): a NUMBER style value is emitted
+ * verbatim when it is `0` or the property is unitless, and suffixed with `px`
+ * otherwise. So `style={{ width: 300 }}` paints 300px while
+ * `style={{ width: '300' }}` paints NOTHING — the CSSOM rejects a unitless
+ * length and keeps the previous value.
+ *
+ * That is why the inspector's numeric descriptors must reach source as
+ * NUMBERS: stringifying `300` on the way to the writer produced
+ * `width: '300'`, which React passed through verbatim, which the CSSOM
+ * rejected — a write that changed source, changed nothing on screen, and
+ * acked `persisted: true`.
+ *
+ * The two consumers are the two halves of one write: the SOURCE (a bare `300`
+ * in the JSX style object, which React px-ifies at render) and the LIVE inline
+ * patch / CSS-file declaration (which are CSS TEXT and need the unit spelled).
+ * {@link cssTextForStyleValue} is the second half.
+ */
+
+/**
+ * Properties whose numeric value is unitless in CSS — the exact set the
+ * inspector's numeric widgets already print with no `px` suffix.
+ *
+ * Deliberately the SHIPPED list rather than React's full internal table: this
+ * set covers every `type: 'number'` descriptor the adapters declare
+ * (`STYLE_PROPERTIES`), and a descriptor added outside it would be wrong in
+ * the widget's suffix before it was wrong here.
+ */
+export const UNITLESS_NUMBER_PROPS: ReadonlySet<string> = new Set([
+  'opacity',
+  'zIndex',
+  'flexGrow',
+  'flexShrink',
+  // React's own unitless set includes these two, and px-ifying them writes
+  // INVALID CSS the browser silently drops (blind re-walk: extracting a
+  // class from an element with `fontWeight: 900` emitted
+  // `font-weight: 900px`, losing the weight). A numeric lineHeight is the
+  // unitless multiplier form — px-ifying it changes meaning, not just
+  // validity.
+  'fontWeight',
+  'lineHeight',
+]);
+
+/**
+ * THE READ HALF of the same rule: parse a real `CSSStyleDeclaration`'s
+ * length-property VALUE (always a unit-suffixed STRING, e.g. `"16px"` — CSSOM
+ * never hands back a bare number) into the plain number a `type: 'number'`
+ * `PropertyDescriptor` needs to render/edit correctly (`Inspector.tsx`'s
+ * generic renderer does `typeof v === 'number' ? … : 0` — without this parse,
+ * EVERY numeric style field would silently display `0` against a real browser
+ * DOM, even though plain-object `style: {}` fixtures never caught it, because
+ * a hand-built fixture can hold a bare JS number directly). Strips a trailing
+ * CSS unit (`px`/`em`/`rem`/`%`/`vh`/`vw`, mirroring `ui-source/writer.ts`'s
+ * own `LITERAL_RE` unit set); a value already handed over AS a number (or
+ * `undefined`/unset) passes through unchanged.
+ *
+ * It lived in `react-world-authoring-adapter.ts` until 2026-09-18 and moved
+ * here for the reason this module's header states — this is the one place that
+ * knows CSS numeric value and CSS text are different things — and because one
+ * host module that is NOT the React surface reads it: the overlay gesture bus
+ * (`components/world-overlay-gestures.ts`) parses a computed border width to
+ * place a resize handle. That single edge dragged the whole 3,848-line React
+ * root adapter into every editor boot (phase 1 of the open-source launch).
+ */
+export function numericStyleValue(raw: unknown): number | undefined {
+  if (typeof raw === 'number') return raw;
+  if (typeof raw !== 'string' || raw === '') return undefined;
+  const parsed = Number.parseFloat(raw);
+  return Number.isNaN(parsed) ? undefined : parsed;
+}
+
+/** Numeric inspector edits change the magnitude of an authored CSS dimension.
+ * Keep relative units; ordinary React numbers and px values remain numbers. */
+export function preserveNumericStyleUnit(
+  value: string | number,
+  authored: unknown,
+): string | number {
+  if (typeof value !== 'number' || typeof authored !== 'string') return value;
+  const unit = authored.trim().match(/^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?([a-z]+|%)$/i)?.[1];
+  return unit && unit.toLowerCase() !== 'px' ? `${value}${unit}` : value;
+}
+
+/**
+ * The CSS TEXT for a style value — React's `dangerousStyleValue` rule.
+ *
+ * A string passes through untouched (it is already CSS text — `'12px'`,
+ * `'var(--brand)'`, `'50%'`). A number becomes `${n}px` unless it is `0` or
+ * the property is unitless.
+ */
+export function cssTextForStyleValue(prop: string, value: string | number): string {
+  if (typeof value !== 'number') return value;
+  if (value === 0 || UNITLESS_NUMBER_PROPS.has(prop)) return String(value);
+  return `${value}px`;
+}

package/src/document-probe.ts

@@ -0,0 +1,282 @@
+/**
+ * The wire vocabulary of the EDITOR-SURFACE probe — the scoped editor-chrome
+ * door (`packages/sdk/src/kit/editor-document-probe.ts` implements it,
+ * `@volter/live`'s `editor.document` binds it, and that module's header carries
+ * the design decision and the scope contract).
+ *
+ * Deliberately NOT a page-automation vocabulary: there is no navigation, no
+ * waiting, no frame/window addressing, and no selector rooted anywhere but one
+ * of the NAMED surfaces in {@link DocumentProbeScope}. Eight actions, each one
+ * a gesture or a read an agent cannot otherwise perform through the product.
+ */
+
+/**
+ * WHICH NAMED SURFACE a step runs against — the whole addressing vocabulary of
+ * this door, and the reason it is a vocabulary rather than a free selector.
+ *
+ * Every name here resolves to ONE live element the person is looking at, found
+ * by a stamp that surface's own owner wrote (`data-volter-part` on the element
+ * the workbench handed over for a registered view; the document surface's own
+ * `data-testid`), never by walking the page for a class that looks right. A
+ * name whose surface is not on screen is REFUSED by name — an agent learns the
+ * Properties view is closed instead of reading an empty match list.
+ *
+ *  - `document` — the ACTIVE centre document's whole box: its content, its
+ *    header strip and its shelf rail. The default, and what this door meant
+ *    before there were names.
+ *  - `header` / `shelf` — the active document's toolbar strip and its tool
+ *    rail, each on its own. Both are INSIDE `document`; they exist as names so
+ *    a selector that also matches in the content (`button`, `[role=tab]`) can
+ *    be aimed without an index.
+ *  - `rail` — the Properties view (`volter.properties`): its vertical tab rail,
+ *    the active tab's sections and their fields.
+ *  - `outliner` — the Outliner view (`volter.outliner`): its rows, their
+ *    expand/eye/camera controls, and its header.
+ *  - `content` — the Content view (`volter.content`): its categories and asset
+ *    rows.
+ *
+ *  - `utility` — the utility view showing in the panel (a contribution's
+ *    `*.utility.tsx`, the Profiler, State Watch…).
+ *  - `menubar` — the application menus (Edit, View, Window…) and the menus
+ *    their triggers open: the one place a person chooses Edit › Undo.
+ *  - `area` — the workspace's areas beside the centre document (the Model
+ *    workspace's bottom area: the Timeline, the Action Editor, the NLA editor,
+ *    the Game panel), each a document of its own that the workspace opened.
+ *
+ * `rail`, `outliner`, `content`, `utility`, `menubar` and `area` are EDITOR CHROME and do not belong to the active
+ * document, so they stay reachable while the Game document is active — the
+ * Game refusal is about driving a game through synthetic gestures, and reading
+ * the panel that reports its selection is not that.
+ */
+export type DocumentProbeScope = 'document' | 'header' | 'shelf' | 'rail' | 'outliner' | 'content' | 'utility' | 'menubar' | 'area';
+
+/** Keep an explicit key hold within the SDK's bounded command deadline. */
+export const MAX_DOCUMENT_KEY_HOLD_MS = 120_000;
+
+/** One element as the probe reports it — everything a caller needs to assert
+ *  on, and nothing that requires a second round trip. */
+export interface ProbedElement {
+  /** Position within the match list this element came from. */
+  index: number;
+  tag: string;
+  /** `innerText`, trimmed and capped. */
+  text: string;
+  attributes: Record<string, string>;
+  rect: { x: number; y: number; width: number; height: number };
+  /** Present for form controls. */
+  value?: string;
+  checked?: boolean;
+  disabled?: boolean;
+  /** Resolved style, present only for the names {@link DocumentQueryStep.styles}
+   *  asked for. A standard property carries the browser's own resolved value
+   *  (`backgroundColor` → `rgb(52, 52, 52)`); a custom property carries what it
+   *  PAINTS when it resolves as a colour, and its declared text otherwise. */
+  styles?: Record<string, string>;
+}
+
+export interface DocumentProbeResult {
+  /** The surface the step ran against — echoed so a transcript proves WHICH
+   *  one was read or driven, not merely that something was. `name` is the
+   *  vocabulary word; `id`/`title` are that surface's own identity (a
+   *  document's id and title, or the registered view's). */
+  scope: { name: DocumentProbeScope; id: string; title: string };
+  /** Total matches inside the scope, before any `limit`. */
+  matched: number;
+  elements: ProbedElement[];
+}
+
+/** Which named surface a step runs against; `document` when omitted. */
+interface ScopedStep {
+  scope?: DocumentProbeScope;
+}
+
+/** Read what a surface rendered. */
+export interface DocumentQueryStep extends ScopedStep {
+  action: 'query';
+  selector: string;
+  /** Cap on returned elements (default 25); `matched` still reports the total. */
+  limit?: number;
+  /**
+   * Style property names to resolve on each match — standard
+   * (`backgroundColor`, `borderInlineStartWidth`) or custom (`--volter-…`).
+   *
+   * Ask for the STANDARD property to learn what a surface PAINTS: a theme
+   * token is an expression (`color-mix(…)`), and the element that uses it is
+   * where the browser turns that expression into a colour. A custom property
+   * is resolved here too, through a real paint property, so a token answers
+   * with the rgb it would paint rather than its own algebra — which is the
+   * only way a `:hover` colour can be measured at all, `:hover` being a
+   * browser state no synthetic event can enter. An UNDECLARED custom
+   * property answers `""`, so "does this palette declare this group" is a
+   * question this door can be trusted with.
+   *
+   * The value is the browser's, in the browser's own spelling: a token built
+   * by `color-mix()` answers as `color(srgb …)` with float channels, a plain
+   * one as `rgb(…)`. Both are the paint; multiply a float by 255 to compare
+   * against a reference frame's 8-bit levels.
+   */
+  styles?: string[];
+}
+
+/** A real pointer gesture on one matched element. */
+export interface DocumentClickStep extends ScopedStep {
+  action: 'click';
+  selector: string;
+  /** Which match (default 0). */
+  index?: number;
+  /**
+   * Clicks in the gesture (default 1). `2` is a REAL double click: the second
+   * press carries `detail: 2` and is followed by a `dblclick`, which is the
+   * only event `onDoubleClick` listens for.
+   *
+   * It is on `click` rather than a verb of its own because it is the same
+   * gesture with the same target — and it is here at all because a double
+   * click is the OUTLINER'S OWN rename gesture (`GameHierarchy.tsx`'s
+   * `onDoubleClick` → `onStartEditing`), so without it a rename could only be
+   * driven through `editor.setField`, which is not the control.
+   */
+  clicks?: number;
+  /**
+   * Where in the element the press lands, `[x, y]` as FRACTIONS of its box from its top-left
+   * (the same convention as `drag`'s `from`/`to`); default its centre. A control whose meaning
+   * is its position — a ruler that seeks to the beat under the pointer, a lane whose
+   * double-click adds a point there — can only be driven at a chosen point with it.
+   */
+  at?: [number, number];
+  /** Modifier keys held through the click (a Shift range pick, a Cmd/Ctrl toggle pick). */
+  altKey?: boolean;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  shiftKey?: boolean;
+}
+
+/**
+ * TYPE into a focused field, character by character, and commit with Enter the
+ * way a person does.
+ *
+ * `paste` cannot stand in for this: an untrusted `ClipboardEvent` performs no
+ * default action, so a plain `<input>` with no paste handler keeps its old
+ * value. And a direct `element.value = x` is invisible to React, which caches
+ * the last value it wrote on the node — the same trap `select` documents. So
+ * each character goes through the prototype's own value setter (leaving
+ * React's tracker stale, which is what makes the following `input` read as a
+ * real edit), between a real `keydown`/`keyup` for that character, so a field
+ * that commits on a KEY rather than on `input` sees the keys too.
+ */
+export interface DocumentTypeStep extends ScopedStep {
+  action: 'type';
+  text: string;
+  /** The field; omitted means whatever inside the scope has focus. */
+  selector?: string;
+  index?: number;
+  /** Replace what the field holds first, the way a person selects-all and
+   *  types over it (default true). `false` appends at the end. */
+  replace?: boolean;
+  /** Press Enter after the text (default true) — the commit gesture for the
+   *  Outliner's rename field and every numeric field in the Properties rail. */
+  enter?: boolean;
+}
+
+/**
+ * A real pointer DRAG across one matched element: `pointerdown` at `from`,
+ * `steps` `pointermove`s along the way, `pointerup` at `to` — the sequence a
+ * mouse produces, so a canvas that begins a gesture on press and previews on
+ * move (an Asset Lab document's direct manipulation) sees the whole gesture.
+ * `from`/`to` are FRACTIONS of the element's box (`[0.5, 0.5]` is its
+ * center), so a caller reasons in the element's own space, not the screen's.
+ * A zero-length drag is a click at that fraction.
+ */
+export interface DocumentDragStep extends ScopedStep {
+  action: 'drag';
+  selector: string;
+  /** Which match (default 0). */
+  index?: number;
+  from: [number, number];
+  to: [number, number];
+  /** Waypoints the pointer passes through between `from` and `to`, in
+   *  order — what a lasso or a knife stroke needs, since a straight drag
+   *  encloses nothing. Each leg gets `steps` moves. */
+  via?: [number, number][];
+  /** Intermediate `pointermove`s between consecutive points (default 8). */
+  steps?: number;
+  /** Modifier keys held for the whole gesture (a Shift-extend, an Alt-click). */
+  altKey?: boolean;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  shiftKey?: boolean;
+  /** The button held: 0 primary (default), 1 middle, 2 secondary. A right
+   *  press is what orbits a viewport or, with Shift, places Blender's 3D cursor. */
+  button?: 0 | 1 | 2;
+  /** The pointer may leave the element after the press: `via`/`to` may lie
+   *  outside 0..1 (still fractions of the element's box), the way a person
+   *  drags a 10 px resize handle outward. The press stays inside, and the
+   *  element keeps receiving the moves, as pointer capture delivers them. */
+  leave?: boolean;
+  /** Press and move, and KEEP THE BUTTON DOWN: the gesture stays open for readings taken in the
+   *  middle of it (what another area draws while a gizmo is dragged), until a `release` step
+   *  lets go at `to`. */
+  hold?: boolean;
+}
+
+/** Lets go of the drag a `hold` left pressed, where it was left. */
+export interface DocumentReleaseStep extends ScopedStep {
+  action: 'release';
+}
+
+/** A real key on the explicit target, else whatever inside the document has focus. */
+export interface DocumentKeyStep extends ScopedStep {
+  action: 'key';
+  key: string;
+  code?: string;
+  selector?: string;
+  index?: number;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  shiftKey?: boolean;
+  altKey?: boolean;
+  /** Hold the key this long before releasing it, as a person holding W does;
+   *  omitted, it is pressed and released at once. Must be finite, nonnegative
+   *  and at most MAX_DOCUMENT_KEY_HOLD_MS (120 seconds). */
+  holdMs?: number;
+}
+
+/** A real `ClipboardEvent` carrying `text/plain` — the only way to exercise a
+ *  paste handler, and the gesture the Sheets build could not verify. */
+export interface DocumentPasteStep extends ScopedStep {
+  action: 'paste';
+  text: string;
+  selector?: string;
+  index?: number;
+}
+
+/**
+ * Choose a value on a `<select>` — the gesture `click` cannot make.
+ *
+ * A native dropdown's option list is rendered by the OS, not by the DOM, so
+ * there is nothing inside the document's container for a pointer gesture to
+ * resolve against: `click` on the `<select>` opens a menu no synthetic event
+ * can reach. Assigning `element.value` is equally useless on a React
+ * controlled component — React caches the last value it wrote on the node, so
+ * a direct write is not seen as a change and the next render puts the old
+ * value straight back. The implementation goes through the prototype's own
+ * value setter and then dispatches `input`/`change`, which is the ONE spelling
+ * React's synthetic-event layer honours.
+ */
+export interface DocumentSelectStep extends ScopedStep {
+  action: 'select';
+  selector: string;
+  /** The option's `value` (not its label). */
+  value: string;
+  /** Which match (default 0). */
+  index?: number;
+}
+
+export type DocumentProbeStep =
+  | DocumentQueryStep
+  | DocumentClickStep
+  | DocumentDragStep
+  | DocumentReleaseStep
+  | DocumentKeyStep
+  | DocumentPasteStep
+  | DocumentSelectStep
+  | DocumentTypeStep;

package/src/editor-view.ts

@@ -0,0 +1,225 @@
+import type { AssetKind, EditorCameraState, EditorView, ViewPreset } from './types.js';
+import { EDITOR_VIEW_WORKSPACE_DOCUMENT_IDS, isEditorViewUtility } from './types.js';
+
+const PREFIX = 'view.';
+const MAX_QUERY_LENGTH = 4096;
+const WORKSPACE_DOCUMENT_IDS = new Set<string>(EDITOR_VIEW_WORKSPACE_DOCUMENT_IDS);
+const ASSET_KINDS = new Set<AssetKind>([
+  'model',
+  'image',
+  'audio',
+  'animation',
+  'json',
+  'prefab',
+  'source',
+]);
+const CAMERAS = new Set<ViewPreset | 'isometric'>([
+  'top',
+  'front',
+  'right',
+  'perspective',
+  'isometric',
+]);
+type EditorViewDiagnostic = NonNullable<NonNullable<EditorView['viewport']>['diagnostic']>;
+export const EDITOR_VIEW_DIAGNOSTICS = [
+  'solid',
+  'preview',
+  'rendered',
+  'clay',
+  'unlit',
+  'wireframe',
+  'matcap',
+  'normals',
+  'overdraw',
+  'uv',
+  'vertex-colors',
+  'bounds',
+  'skeleton',
+] as const satisfies readonly EditorViewDiagnostic[];
+const DIAGNOSTICS = new Set<EditorViewDiagnostic>(EDITOR_VIEW_DIAGNOSTICS);
+function nonEmpty(value: string | null): string | null {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function writeDocument(params: URLSearchParams, document: EditorView['document']): void {
+  if (!document) return;
+  params.set(`${PREFIX}docKind`, document.kind);
+  if (document.kind === 'asset' && document.entityId) {
+    params.set(`${PREFIX}doc`, document.entityId);
+    params.set(`${PREFIX}assetSource`, 'entity');
+  } else if (document.kind === 'asset') {
+    params.set(`${PREFIX}doc`, document.path!);
+  } else if (document.kind === 'scene') {
+    params.set(`${PREFIX}doc`, document.path);
+  } else if (document.kind === 'story') {
+    params.set(`${PREFIX}doc`, document.modulePath);
+    params.set(`${PREFIX}story`, document.storyName);
+    if (document.mode === 'docs') params.set(`${PREFIX}storyMode`, 'docs');
+  } else if (document.kind === 'project-tool') {
+    params.set(`${PREFIX}doc`, document.name);
+  } else {
+    params.set(`${PREFIX}doc`, document.id);
+  }
+  if (document.kind === 'asset' && document.assetKind) {
+    params.set(`${PREFIX}assetKind`, document.assetKind);
+  }
+}
+
+function writeViewport(params: URLSearchParams, viewport: EditorView['viewport']): void {
+  if (!viewport) return;
+  if (typeof viewport.camera === 'string') params.set(`${PREFIX}camera`, viewport.camera);
+  else if (viewport.camera) {
+    params.set(`${PREFIX}camera`, 'pose');
+    params.set(
+      `${PREFIX}cameraPosition`,
+      [viewport.camera.position.x, viewport.camera.position.y, viewport.camera.position.z].join(
+        ',',
+      ),
+    );
+    params.set(
+      `${PREFIX}cameraTarget`,
+      [viewport.camera.target.x, viewport.camera.target.y, viewport.camera.target.z].join(','),
+    );
+    if (viewport.camera.fov !== undefined)
+      params.set(`${PREFIX}cameraFov`, String(viewport.camera.fov));
+  }
+  if (viewport.diagnostic) params.set(`${PREFIX}diagnostic`, viewport.diagnostic);
+  if (viewport.frame) params.set(`${PREFIX}frame`, viewport.frame);
+  if (viewport.grid !== undefined) params.set(`${PREFIX}grid`, viewport.grid ? '1' : '0');
+}
+
+function parseVec3(value: string | null): EditorCameraState['position'] | null {
+  if (!value) return null;
+  const parts = value.split(',').map(Number);
+  if (parts.length !== 3 || parts.some((part) => !Number.isFinite(part))) return null;
+  return { x: parts[0]!, y: parts[1]!, z: parts[2]! };
+}
+
+function parseCamera(params: URLSearchParams): NonNullable<EditorView['viewport']>['camera'] {
+  const camera = params.get(`${PREFIX}camera`);
+  if (camera && CAMERAS.has(camera as ViewPreset | 'isometric')) {
+    return camera as ViewPreset | 'isometric';
+  }
+  if (camera !== 'pose') return undefined;
+  const position = parseVec3(params.get(`${PREFIX}cameraPosition`));
+  const target = parseVec3(params.get(`${PREFIX}cameraTarget`));
+  const fovValue = params.get(`${PREFIX}cameraFov`);
+  const fov = fovValue === null ? undefined : Number(fovValue);
+  if (!position || !target || (fov !== undefined && !Number.isFinite(fov))) return undefined;
+  return { position, target, ...(fov !== undefined ? { fov } : {}) };
+}
+
+function parseStoryDocument(params: URLSearchParams, modulePath: string): EditorView['document'] {
+  const storyName = nonEmpty(params.get(`${PREFIX}story`));
+  if (!storyName) return undefined;
+  return {
+    kind: 'story',
+    modulePath,
+    storyName,
+    ...(params.get(`${PREFIX}storyMode`) === 'docs' ? { mode: 'docs' as const } : {}),
+  };
+}
+
+function parseAssetDocument(params: URLSearchParams, value: string): EditorView['document'] {
+  const assetKind = params.get(`${PREFIX}assetKind`);
+  if (params.get(`${PREFIX}assetSource`) === 'entity') {
+    return { kind: 'asset', entityId: value, assetKind: 'model' };
+  }
+  return {
+    kind: 'asset',
+    path: value,
+    ...(assetKind && ASSET_KINDS.has(assetKind as AssetKind)
+      ? { assetKind: assetKind as AssetKind }
+      : {}),
+  };
+}
+
+function parseDocument(params: URLSearchParams): EditorView['document'] {
+  const kind = params.get(`${PREFIX}docKind`);
+  const value = nonEmpty(params.get(`${PREFIX}doc`));
+  if (!value) return undefined;
+  if (kind === 'scene') return { kind, path: value };
+  if (kind === 'tool') return { kind, id: value };
+  if (kind === 'document') return { kind, id: value };
+  if (kind === 'world') return { kind, id: value };
+  if (kind === 'project-tool') return { kind, name: value };
+  if (kind === 'generation') return { kind, id: value };
+  if (kind === 'story') return parseStoryDocument(params, value);
+  if (kind === 'workspace' && WORKSPACE_DOCUMENT_IDS.has(value)) {
+    return {
+      kind,
+      id: value as Extract<NonNullable<EditorView['document']>, { kind: 'workspace' }>['id'],
+    };
+  }
+  return kind === 'asset' ? parseAssetDocument(params, value) : undefined;
+}
+
+function parseViewport(params: URLSearchParams): EditorView['viewport'] {
+  const camera = parseCamera(params);
+  const diagnostic = params.get(`${PREFIX}diagnostic`);
+  const frame = params.get(`${PREFIX}frame`);
+  const grid = params.get(`${PREFIX}grid`);
+  const viewport = {
+    ...(camera ? { camera } : {}),
+    ...(diagnostic && DIAGNOSTICS.has(diagnostic as EditorViewDiagnostic)
+      ? { diagnostic: diagnostic as EditorViewDiagnostic }
+      : {}),
+    ...(frame === 'document' || frame === 'selection'
+      ? { frame: frame as 'document' | 'selection' }
+      : {}),
+    ...(grid === '0' || grid === '1' ? { grid: grid === '1' } : {}),
+  };
+  return Object.keys(viewport).length > 0 ? viewport : undefined;
+}
+
+/** Apply only the view-owned query parameters, preserving project/scene routing params. */
+export function editorViewUrl(view: EditorView, baseUrl: string | URL): string {
+  const url = new URL(baseUrl);
+  for (const key of [...url.searchParams.keys()]) {
+    if (key.startsWith(PREFIX)) url.searchParams.delete(key);
+  }
+  url.searchParams.set(`${PREFIX}v`, '1');
+  writeDocument(url.searchParams, view.document);
+  if (view.selection?.ids.length) {
+    for (const id of view.selection.ids) url.searchParams.append(`${PREFIX}select`, id);
+    if (view.selection.focus) url.searchParams.set(`${PREFIX}focus`, '1');
+  }
+  writeViewport(url.searchParams, view.viewport);
+  if (view.workspace) url.searchParams.set(`${PREFIX}workspace`, view.workspace);
+  if (view.panel) url.searchParams.set(`${PREFIX}panel`, view.panel);
+  if (view.utility) url.searchParams.set(`${PREFIX}utility`, view.utility);
+  if (url.search.length > MAX_QUERY_LENGTH) {
+    throw new Error(`Editor view URL exceeds the ${MAX_QUERY_LENGTH}-character share limit.`);
+  }
+  return url.toString();
+}
+
+/** Parse a shareable editor projection. Malformed projections are ignored at boot. */
+export function editorViewFromUrl(value: string | URL): EditorView | null {
+  const url = value instanceof URL ? value : new URL(value, 'http://editor.invalid');
+  const params = url.searchParams;
+  if (params.get(`${PREFIX}v`) !== '1') return null;
+  const view: EditorView = { version: 1 };
+  const document = parseDocument(params);
+  if (document) view.document = document;
+  const ids = params
+    .getAll(`${PREFIX}select`)
+    .filter((id) => id.length > 0)
+    .slice(0, 32);
+  if (ids.length) view.selection = { ids, focus: params.get(`${PREFIX}focus`) === '1' };
+  const viewport = parseViewport(params);
+  if (viewport) view.viewport = viewport;
+  // Shape check only: a `tool:` id names a utility the OPEN PROJECT
+  // contributes, so the URL cannot know whether it exists. The editor
+  // validates it against its live registry when the view is presented.
+  const workspace = params.get(`${PREFIX}workspace`);
+  if (workspace) view.workspace = workspace;
+  // Shape check only, like `workspace` above: which panels exist is the open
+  // editor's registry, and it answers at present-time.
+  const panel = params.get(`${PREFIX}panel`);
+  if (panel) view.panel = panel;
+  const utility = params.get(`${PREFIX}utility`);
+  if (utility && isEditorViewUtility(utility)) view.utility = utility;
+  return view;
+}

package/src/extension.ts

@@ -0,0 +1,40 @@
+/**
+ * Extension contract (W3a) — the published surface a game project uses to
+ * contribute to the editor, with the degradation ladder made API.
+ *
+ * A project extends the editor through exactly three surfaces:
+ *
+ * (a) **Editor panels** — registered into the workspace as documents
+ *     or utilities via a tool contribution (`package.json#volter.tools` →
+ *     `contributes: [{ point: 'workspace.document' | 'workspace.utility' | 'workspace.analytics' }]`).
+ *     Types: `ToolContributionProps` in `@volter/sdk/contributions`.
+ *     Panels are never a parallel rail — the frame owns all layout.
+ * (b) **Inspector sections** — `point: 'selection.inspector'` /
+ *     `'asset.inspector'` tool contributions with an exported `match`.
+ *     Types: `ToolInspectorContributionProps` and friends, same module.
+ * (c) **System adapters** — runtime capabilities (networking, debug, …)
+ *     registered from game code via `ctx.registerSystemAdapter?.(kind, impl)`
+ *     (`SystemAdapters` in `@volter/project`'s
+ *     `adapter/system-adapter`). Deliberately NOT re-exported here: the
+ *     engine already publishes that seam and every consumer of it also
+ *     imports the engine — an alias would be a dead surface.
+ *
+ * Outcomes (the anti-shim rule, as API): every contribution resolves to an
+ * {@link ExtensionContributionState} —
+ *
+ * - `'active'` — the contribution loaded and produced its surface.
+ * - `'absent'` — nothing was contributed. The editor HIDES the surface
+ *   entirely; it never fabricates placeholder data for a missing
+ *   contribution.
+ * - `'failed'` — the contribution exists but threw / violated the contract.
+ *   The failure is contained per-contribution (the editor never crashes),
+ *   the surface is hidden, and the error is reported LOUDLY (editor
+ *   console) — never silently swallowed into fake output.
+ */
+
+/**
+ * The terminal state of a single extension contribution (see the module doc
+ * above for the exact semantics). Not a grade and not an ordering: `absent`
+ * and `failed` both hide the surface, and `failed` is reported loudly.
+ */
+export type ExtensionContributionState = 'active' | 'absent' | 'failed';