@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/asset-workflow/model-inspection.ts

@@ -0,0 +1,185 @@
+import * as THREE from 'three';
+
+export interface ModelInspection {
+  nodes: number;
+  meshes: number;
+  primitives: number;
+  vertices: number;
+  triangles: number;
+  materials: number;
+  textures: number;
+  bones: number;
+  clips: number;
+  morphTargets: number;
+  memoryBytes: number;
+  bounds: { x: number; y: number; z: number } | null;
+  hierarchy: Array<{ id: string; name: string; type: string; depth: number }>;
+  materialNames: string[];
+  textureNames: string[];
+}
+
+const textureKeys = [
+  'map',
+  'alphaMap',
+  'aoMap',
+  'bumpMap',
+  'displacementMap',
+  'emissiveMap',
+  'envMap',
+  'lightMap',
+  'metalnessMap',
+  'normalMap',
+  'roughnessMap',
+  'specularMap',
+] as const;
+
+/** Exact, side-effect-free statistics used by the Asset Editor and import validation. */
+export function inspectModel(root: THREE.Object3D): ModelInspection {
+  const materials = new Set<THREE.Material>();
+  const textures = new Set<THREE.Texture>();
+  const hierarchy: ModelInspection['hierarchy'] = [];
+  let nodes = 0;
+  let meshes = 0;
+  let primitives = 0;
+  let vertices = 0;
+  let triangles = 0;
+  let bones = 0;
+  let morphTargets = 0;
+  let memoryBytes = 0;
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one traversal intentionally reconciles geometry, material, texture, animation, and hierarchy statistics.
+  root.traverse((object) => {
+    nodes++;
+    let depth = 0;
+    for (let parent = object.parent; parent && parent !== root.parent; parent = parent.parent)
+      depth++;
+    hierarchy.push({ id: object.uuid, name: object.name || object.type, type: object.type, depth });
+    if ((object as THREE.Bone).isBone) bones++;
+    const renderable = object as THREE.Mesh;
+    const drawable = object as THREE.Object3D & {
+      isMesh?: boolean;
+      isLine?: boolean;
+      isPoints?: boolean;
+    };
+    if (!drawable.isMesh && !drawable.isLine && !drawable.isPoints) return;
+    meshes++;
+    const geometry = renderable.geometry;
+    if (geometry) {
+      const position = geometry.getAttribute('position');
+      vertices += position?.count ?? 0;
+      triangles += geometry.index
+        ? Math.floor(geometry.index.count / 3)
+        : Math.floor((position?.count ?? 0) / 3);
+      primitives += Math.max(geometry.groups.length, 1);
+      morphTargets += geometry.morphAttributes['position']?.length ?? 0;
+      if (geometry.index) memoryBytes += geometry.index.array.byteLength;
+      for (const attribute of Object.values(geometry.attributes))
+        memoryBytes += attribute.array.byteLength;
+    }
+    const objectMaterials = Array.isArray(renderable.material)
+      ? renderable.material
+      : renderable.material
+        ? [renderable.material]
+        : [];
+    for (const material of objectMaterials) {
+      materials.add(material);
+      for (const key of textureKeys) {
+        const texture = (material as THREE.Material & Record<string, unknown>)[key];
+        if (texture instanceof THREE.Texture) textures.add(texture);
+      }
+    }
+  });
+  for (const texture of textures) {
+    const image = texture.image as { width?: number; height?: number } | undefined;
+    memoryBytes += (image?.width ?? 0) * (image?.height ?? 0) * 4;
+  }
+  const box = new THREE.Box3().setFromObject(root);
+  const size = box.isEmpty() ? null : box.getSize(new THREE.Vector3());
+  return {
+    nodes,
+    meshes,
+    primitives,
+    vertices,
+    triangles,
+    materials: materials.size,
+    textures: textures.size,
+    bones,
+    clips: root.animations.length,
+    morphTargets,
+    memoryBytes,
+    bounds: size ? { x: size.x, y: size.y, z: size.z } : null,
+    hierarchy,
+    materialNames: [...materials].map((material) => material.name || material.type),
+    textureNames: [...textures].map(
+      (texture) => texture.name || texture.source.data?.src || 'Texture',
+    ),
+  };
+}
+
+export type ModelDiagnosticMode =
+  | 'lit'
+  | 'unlit'
+  | 'wireframe'
+  | 'normals'
+  | 'uv'
+  | 'vertex-colors'
+  | 'bounds'
+  | 'skeleton'
+  | 'collision'
+  | 'lod';
+
+export type ModelCameraPreset =
+  | 'front'
+  | 'back'
+  | 'left'
+  | 'right'
+  | 'top'
+  | 'bottom'
+  | 'isometric';
+
+export function cameraPresetDirection(preset: ModelCameraPreset): THREE.Vector3 {
+  const directions: Record<ModelCameraPreset, [number, number, number]> = {
+    front: [0, 0, 1],
+    back: [0, 0, -1],
+    left: [-1, 0, 0],
+    right: [1, 0, 0],
+    top: [0, 1, 0],
+    bottom: [0, -1, 0],
+    isometric: [1, 0.72, 1],
+  };
+  return new THREE.Vector3(...directions[preset]).normalize();
+}
+
+export function supportedModelDiagnosticModes(root: THREE.Object3D): Array<{
+  mode: ModelDiagnosticMode;
+  available: boolean;
+  reason?: string;
+}> {
+  let uv = false;
+  let colors = false;
+  let bones = false;
+  let lod = false;
+  root.traverse((object) => {
+    const mesh = object as THREE.Mesh;
+    uv ||= Boolean(mesh.geometry?.getAttribute('uv'));
+    colors ||= Boolean(mesh.geometry?.getAttribute('color'));
+    bones ||= Boolean((object as THREE.Bone).isBone || (mesh as THREE.SkinnedMesh).isSkinnedMesh);
+    lod ||= (object as THREE.LOD).isLOD === true;
+  });
+  return [
+    { mode: 'lit', available: true },
+    { mode: 'unlit', available: true },
+    { mode: 'wireframe', available: true },
+    { mode: 'normals', available: true },
+    { mode: 'uv', available: uv, ...(!uv ? { reason: 'No UV channel' } : {}) },
+    {
+      mode: 'vertex-colors',
+      available: colors,
+      ...(!colors ? { reason: 'No vertex colors' } : {}),
+    },
+    { mode: 'bounds', available: true },
+    { mode: 'skeleton', available: bones, ...(!bones ? { reason: 'No skeleton' } : {}) },
+    { mode: 'collision', available: false, reason: 'No collision metadata' },
+    { mode: 'lod', available: lod, ...(!lod ? { reason: 'No LOD groups' } : {}) },
+  ];
+}

package/src/asset-workflow/project-asset-commands.ts

@@ -0,0 +1,23 @@
+export const PROJECT_ASSET_COMMANDS = {
+  open: { id: 'project-asset.open', shortcut: 'Enter' },
+  rename: { id: 'project-asset.rename', shortcut: 'F2' },
+  duplicate: { id: 'project-asset.duplicate', shortcut: 'Mod+D' },
+  delete: { id: 'project-asset.delete', shortcut: 'Delete' },
+  copyPath: { id: 'project-asset.copy-path', shortcut: 'Mod+Shift+C' },
+  reveal: { id: 'project-asset.reveal', shortcut: null },
+  refresh: { id: 'project-asset.refresh', shortcut: 'Mod+R' },
+  import: { id: 'project-asset.import', shortcut: null },
+  createFolder: { id: 'project-asset.create-folder', shortcut: 'Mod+Shift+N' },
+  reimport: { id: 'project-asset.reimport', shortcut: null },
+} as const;
+
+export type ProjectAssetCommandId =
+  (typeof PROJECT_ASSET_COMMANDS)[keyof typeof PROJECT_ASSET_COMMANDS]['id'];
+
+export function projectAssetCommandIds(): readonly ProjectAssetCommandId[] {
+  return Object.values(PROJECT_ASSET_COMMANDS).map((command) => command.id);
+}
+
+export function projectAssetBrowserStateKey(projectId: string): string {
+  return `vgai:project-assets:v1:${projectId}`;
+}

package/src/asset-workflow/project-asset-health.ts

@@ -0,0 +1,153 @@
+import type { StorageBackend } from '../storage/types';
+import { assetCapabilities } from './asset-capabilities';
+import type { AssetHealth, AssetHealthCode } from './asset-types';
+
+export interface ProjectAssetFileSnapshot {
+  readonly path: string;
+  readonly text?: string;
+}
+
+export interface ProjectAssetRecipeSnapshot {
+  readonly sourcePath: string;
+  readonly recordedSourceHash: string;
+  readonly currentSourceHash: string;
+}
+
+export interface ProjectAssetReference {
+  readonly ownerPath: string;
+  readonly jsonPath: string;
+  readonly assetPath: string;
+}
+
+export interface ProjectAssetHealthResult {
+  readonly health: AssetHealth;
+  readonly dependencies: readonly string[];
+  readonly references: readonly ProjectAssetReference[];
+}
+
+function collectStringPaths(value: unknown, path = '$'): { path: string; value: string }[] {
+  if (typeof value === 'string') return [{ path, value }];
+  if (Array.isArray(value)) {
+    return value.flatMap((entry, index) => collectStringPaths(entry, `${path}[${index}]`));
+  }
+  if (!value || typeof value !== 'object') return [];
+  return Object.entries(value).flatMap(([key, entry]) =>
+    collectStringPaths(entry, `${path}.${key}`),
+  );
+}
+
+function externalDependencies(assetPath: string, text: string | undefined): string[] {
+  if (!text || !assetPath.toLowerCase().endsWith('.gltf')) return [];
+  try {
+    const json = JSON.parse(text) as { buffers?: { uri?: string }[]; images?: { uri?: string }[] };
+    const base = assetPath.includes('/') ? assetPath.slice(0, assetPath.lastIndexOf('/') + 1) : '';
+    return [...(json.buffers ?? []), ...(json.images ?? [])].flatMap((entry) =>
+      entry.uri && !entry.uri.startsWith('data:') ? [`${base}${entry.uri}`] : [],
+    );
+  } catch {
+    return [];
+  }
+}
+
+export function inspectProjectAssetHealth(input: {
+  readonly assetPath: string;
+  readonly files: readonly ProjectAssetFileSnapshot[];
+  readonly recipe?: ProjectAssetRecipeSnapshot;
+}): ProjectAssetHealthResult {
+  const byPath = new Map(input.files.map((file) => [file.path.replace(/^\//, ''), file]));
+  const assetPath = input.assetPath.replace(/^\//, '');
+  const asset = byPath.get(assetPath);
+  const codes = new Set<AssetHealthCode>();
+  const capability = assetCapabilities(assetPath);
+  if (!asset) codes.add('missing-file');
+  if (!capability.importable) codes.add('unsupported-format');
+  else if (!capability.runtimeReady) codes.add('source-only');
+
+  if (asset?.text && capability.kind === 'json') {
+    try {
+      JSON.parse(asset.text);
+    } catch {
+      codes.add('invalid-metadata');
+    }
+  }
+
+  const dependencies = externalDependencies(assetPath, asset?.text);
+  if (dependencies.some((path) => !byPath.has(path))) codes.add('missing-dependency');
+  if (
+    assetPath.startsWith('asset-library/local/') &&
+    !byPath.has(`${assetPath.slice(0, assetPath.lastIndexOf('/') + 1)}_VGAI_ASSET.json`)
+  ) {
+    codes.add('missing-attribution');
+  }
+  if (input.recipe && input.recipe.recordedSourceHash !== input.recipe.currentSourceHash) {
+    codes.add('stale-import');
+  }
+
+  const references: ProjectAssetReference[] = [];
+  for (const file of input.files) {
+    if (!file.text || !/\.(?:vscn|prefab|mat)\.json$/i.test(file.path)) continue;
+    try {
+      for (const candidate of collectStringPaths(JSON.parse(file.text))) {
+        const normalized = candidate.value.replace(/^\//, '');
+        if (normalized === assetPath) {
+          references.push({ ownerPath: file.path, jsonPath: candidate.path, assetPath });
+        } else if (normalized.startsWith('assets/') && !byPath.has(normalized)) {
+          codes.add('broken-scene-reference');
+        }
+      }
+    } catch {
+      codes.add('invalid-metadata');
+    }
+  }
+
+  if (codes.size === 0) codes.add('healthy');
+  const errorCodes = new Set<AssetHealthCode>([
+    'missing-file',
+    'missing-dependency',
+    'invalid-metadata',
+    'broken-scene-reference',
+  ]);
+  return {
+    health: {
+      status: [...codes].some((code) => errorCodes.has(code))
+        ? 'error'
+        : codes.has('healthy')
+          ? 'healthy'
+          : 'warning',
+      codes: [...codes],
+    },
+    dependencies,
+    references,
+  };
+}
+
+async function snapshotProjectFiles(
+  backend: StorageBackend,
+  dir = '',
+): Promise<ProjectAssetFileSnapshot[]> {
+  const entries = await backend.list(dir);
+  const snapshots: ProjectAssetFileSnapshot[] = [];
+  for (const entry of entries) {
+    const path = dir ? `${dir}/${entry.name}` : entry.name;
+    if (entry.type === 'dir') {
+      snapshots.push(...(await snapshotProjectFiles(backend, path)));
+    } else if (/\.json$|\.gltf$/i.test(path)) {
+      snapshots.push({ path, text: await backend.read(path) });
+    } else {
+      snapshots.push({ path });
+    }
+  }
+  return snapshots;
+}
+
+export async function inspectProjectAssetHealthFromStorage(
+  backend: StorageBackend,
+  assetPath: string,
+  recipe?: ProjectAssetRecipeSnapshot,
+): Promise<ProjectAssetHealthResult> {
+  return inspectProjectAssetHealth({
+    assetPath,
+    files: await snapshotProjectFiles(backend),
+    ...(recipe ? { recipe } : {}),
+  });
+}

package/src/asset-workflow/project-asset-operations.ts

@@ -0,0 +1,119 @@
+import type { HistoryService } from '../history/history-service';
+import { getProjectFileHistory } from '../history/project-file-history';
+import type { StorageBackend } from '../storage/types';
+
+export type ProjectAssetOperation =
+  | { readonly type: 'create-folder'; readonly path: string }
+  | { readonly type: 'duplicate'; readonly source: string; readonly destination: string }
+  | { readonly type: 'move'; readonly source: string; readonly destination: string }
+  | { readonly type: 'delete'; readonly paths: readonly string[] }
+  | { readonly type: 'import'; readonly files: readonly { path: string; bytes: Uint8Array }[] }
+  | { readonly type: 'reimport'; readonly files: readonly { path: string; bytes: Uint8Array }[] };
+
+function emitAssetMutation(detail: {
+  type: 'move' | 'delete' | 'change';
+  oldPath?: string;
+  newPath?: string;
+  paths?: readonly string[];
+}): void {
+  if (typeof window === 'undefined') return;
+  window.dispatchEvent(new CustomEvent('editor:asset-mutation', { detail }));
+  window.dispatchEvent(new CustomEvent('editor:assets-changed'));
+}
+
+function validPath(path: string): string {
+  const normalized = path
+    .replace(/^\/+/, '')
+    .replace(/\\/g, '/')
+    .replace(/\/{2,}/g, '/');
+  if (
+    !normalized ||
+    normalized === '.' ||
+    normalized.split('/').some((part) => !part || part === '..')
+  ) {
+    throw new Error(`Invalid project asset path: ${path}`);
+  }
+  return normalized;
+}
+
+async function assertDestinationsFree(backend: StorageBackend, paths: readonly string[]) {
+  for (const path of paths) {
+    if (await backend.exists(path)) throw new Error(`An asset already exists at ${path}.`);
+  }
+}
+
+/** Executes all writes through exact-byte project history; no UI owns filesystem mutation. */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the tagged operation union is intentionally centralized so every project mutation shares one atomic history boundary.
+export async function executeProjectAssetOperation(
+  operation: ProjectAssetOperation,
+  dependencies: { readonly backend: StorageBackend; readonly history: HistoryService },
+): Promise<boolean> {
+  const files = getProjectFileHistory(dependencies.history, dependencies.backend);
+  switch (operation.type) {
+    case 'create-folder': {
+      const folder = validPath(operation.path);
+      const marker = `${folder}/.vgai-folder`;
+      if (await dependencies.backend.exists(folder))
+        throw new Error(`Folder already exists: ${folder}.`);
+      return files.write(marker, '', { label: `Create folder ${folder}` });
+    }
+    case 'duplicate': {
+      const source = validPath(operation.source);
+      const destination = validPath(operation.destination);
+      await assertDestinationsFree(dependencies.backend, [destination]);
+      const bytes = await dependencies.backend.readBytes(source);
+      return files.write(destination, bytes, { label: `Duplicate ${source}` });
+    }
+    case 'move': {
+      const source = validPath(operation.source);
+      const destination = validPath(operation.destination);
+      await assertDestinationsFree(dependencies.backend, [destination]);
+      const bytes = await dependencies.backend.readBytes(source);
+      const changed = await files.mutate(
+        [
+          { path: destination, data: bytes },
+          { path: source, data: null },
+        ],
+        { label: `Move ${source}` },
+      );
+      if (changed) emitAssetMutation({ type: 'move', oldPath: source, newPath: destination });
+      return changed;
+    }
+    case 'delete': {
+      const paths = [...new Set(operation.paths.map(validPath))];
+      const changed = await files.mutate(
+        paths.map((path) => ({ path, data: null })),
+        { label: `Delete ${paths.length} asset${paths.length === 1 ? '' : 's'}` },
+      );
+      if (changed) emitAssetMutation({ type: 'delete', paths });
+      return changed;
+    }
+    case 'import': {
+      const imported = operation.files.map((file) => ({
+        path: validPath(file.path),
+        data: file.bytes,
+      }));
+      await assertDestinationsFree(
+        dependencies.backend,
+        imported.map((file) => file.path),
+      );
+      const changed = await files.mutate(imported, {
+        label: `Import ${imported.length} asset${imported.length === 1 ? '' : 's'}`,
+      });
+      if (changed) emitAssetMutation({ type: 'change', paths: imported.map((file) => file.path) });
+      return changed;
+    }
+    case 'reimport': {
+      const reimported = operation.files.map((file) => ({
+        path: validPath(file.path),
+        data: file.bytes,
+      }));
+      const changed = await files.mutate(reimported, {
+        label: `Reimport ${reimported.length} asset${reimported.length === 1 ? '' : 's'}`,
+      });
+      if (changed)
+        emitAssetMutation({ type: 'change', paths: reimported.map((file) => file.path) });
+      return changed;
+    }
+  }
+}

package/src/asset-workflow/thumbnail-system.ts

@@ -0,0 +1,172 @@
+import { z } from 'zod';
+import { getStorageBackend } from '../storage';
+import type { AssetCatalog } from './asset-types';
+
+export const THUMBNAIL_PROFILE = {
+  version: 'vgai-thumbnail-v2',
+  width: 256,
+  height: 256,
+  background: 'neutral',
+  framing: 'bounds-isometric-1.3',
+  lighting: 'studio-key-fill-v1',
+  colorManagement: 'srgb-aces-filmic',
+  animationPose: 'representative-35-percent',
+} as const;
+
+export const thumbnailManifestSchema = z.object({
+  version: z.literal(1),
+  profile: z.literal(THUMBNAIL_PROFILE.version),
+  generatedAt: z.string(),
+  entries: z.record(
+    z.string(),
+    z.object({
+      state: z.enum(['generated', 'upstream', 'fallback', 'unsupported', 'failed']),
+      path: z.string().optional(),
+      profileVersion: z.string(),
+      sourceHash: z.string().optional(),
+      resultHash: z.string().optional(),
+      issueCode: z.string().optional(),
+      animation: z.object({ clip: z.string(), time: z.number().nonnegative() }).optional(),
+      framing: z
+        .object({
+          position: z.tuple([z.number(), z.number(), z.number()]),
+          target: z.tuple([z.number(), z.number(), z.number()]),
+        })
+        .optional(),
+    }),
+  ),
+});
+export type ThumbnailManifest = z.infer<typeof thumbnailManifestSchema>;
+
+let manifestPromise: Promise<ThumbnailManifest | null> | null = null;
+export function loadProjectThumbnailManifest(): Promise<ThumbnailManifest | null> {
+  if (!manifestPromise) {
+    const backend = getStorageBackend() as ReturnType<typeof getStorageBackend> | undefined;
+    manifestPromise = backend
+      ? backend.read('.vgai/thumbnails.json').then(
+          (content) => thumbnailManifestSchema.parse(JSON.parse(content)),
+          () => null,
+        )
+      : Promise.resolve(null);
+  }
+  return manifestPromise;
+}
+export function resetProjectThumbnailManifestCache(): void {
+  manifestPromise = null;
+}
+
+interface QueueJob<T> {
+  key: string;
+  priority: number;
+  consumers: number;
+  started: boolean;
+  resolve(value: T): void;
+  reject(error: unknown): void;
+  promise: Promise<T>;
+}
+
+/** Bounded, priority-aware, deduplicating fallback queue shared by all visible cards. */
+export class ThumbnailJobQueue<T> {
+  private active = 0;
+  private readonly jobs = new Map<string, QueueJob<T>>();
+  private pending: QueueJob<T>[] = [];
+  constructor(
+    private readonly execute: (key: string) => Promise<T>,
+    readonly concurrency = 2,
+  ) {}
+  request(key: string, priority = 0): { promise: Promise<T>; cancel(): void } {
+    let job = this.jobs.get(key);
+    if (!job) {
+      let resolve!: (value: T) => void;
+      let reject!: (error: unknown) => void;
+      const promise = new Promise<T>((ok, fail) => {
+        resolve = ok;
+        reject = fail;
+      });
+      job = { key, priority, consumers: 0, started: false, resolve, reject, promise };
+      this.jobs.set(key, job);
+      this.pending.push(job);
+    }
+    job.consumers++;
+    job.priority = Math.max(job.priority, priority);
+    this.pending.sort((a, b) => b.priority - a.priority);
+    this.pump();
+    let cancelled = false;
+    return {
+      promise: job.promise,
+      cancel: () => {
+        if (cancelled) return;
+        cancelled = true;
+        job!.consumers--;
+        if (!job!.started && job!.consumers === 0) {
+          this.pending = this.pending.filter((item) => item !== job);
+          this.jobs.delete(job!.key);
+          job!.reject(new DOMException('Thumbnail request cancelled', 'AbortError'));
+        }
+      },
+    };
+  }
+  snapshot(): { active: number; pending: number; keys: number } {
+    return { active: this.active, pending: this.pending.length, keys: this.jobs.size };
+  }
+  private pump(): void {
+    while (this.active < this.concurrency) {
+      const job = this.pending.shift();
+      if (!job) return;
+      if (job.consumers === 0) continue;
+      job.started = true;
+      this.active++;
+      void this.execute(job.key)
+        .then(job.resolve, job.reject)
+        .finally(() => {
+          this.active--;
+          this.jobs.delete(job.key);
+          this.pump();
+        });
+    }
+  }
+}
+
+export interface ThumbnailQualitySample {
+  alphaCoverage: number;
+  luminanceVariance: number;
+  edgeCoverage: number;
+}
+export function auditThumbnailQuality(sample: ThumbnailQualitySample): string[] {
+  const issues: string[] = [];
+  if (sample.alphaCoverage < 0.01) issues.push('thumbnail.blank-transparent');
+  if (sample.luminanceVariance < 0.0005 && sample.edgeCoverage < 0.01)
+    issues.push('thumbnail.near-uniform');
+  if (sample.edgeCoverage > 0.45) issues.push('thumbnail.possibly-clipped');
+  return issues;
+}
+
+export function catalogThumbnailCoverage(catalog: AssetCatalog): {
+  total: number;
+  generated: number;
+  upstream: number;
+  fallback: number;
+  unsupported: number;
+  failed: number;
+} {
+  const result = { total: 0, generated: 0, upstream: 0, fallback: 0, unsupported: 0, failed: 0 };
+  for (const family of catalog.families) {
+    for (const variant of family.variants) {
+      result.total++;
+      result[variant.thumbnail.state]++;
+    }
+  }
+  return result;
+}
+
+export function representativeAnimationPose(
+  clips: readonly { name: string; duration: number }[],
+): { clip: string; time: number } | null {
+  if (!clips.length) return null;
+  const ranked = [...clips].sort((a, b) => {
+    const score = (name: string) => (/walk|run|idle|action/i.test(name) ? 1 : 0);
+    return score(b.name) - score(a.name) || b.duration - a.duration || a.name.localeCompare(b.name);
+  });
+  const clip = ranked[0]!;
+  return { clip: clip.name, time: Number((clip.duration * 0.35).toFixed(6)) };
+}

package/src/authoring/active-systems.ts

@@ -48,3 +48,18 @@ export function setActiveNetworking(n: SystemAdapters['networking'] | null): voi
 export function getActiveNetworking(): SystemAdapters['networking'] | null {
   return _systems.networking ?? null;
 }
+
+export function setActiveDebug(d: SystemAdapters['debug'] | null): void {
+  const next = { ..._systems };
+  if (d) next.debug = d;
+  else delete next.debug;
+  _systems = next;
+}
+/** The active game's debug seam (`DebugAdapter`, SYNTHETIC-PLAYER-SPEC §3.1) —
+ *  installed with the whole bag by play-mode's `setActiveSystems`, read by
+ *  the Debug Console / State Watch panels and the CLI command relay. Null
+ *  outside play (or for a mount exposing no debug adapter) — the panels'
+ *  hide signal. */
+export function getActiveDebug(): SystemAdapters['debug'] | null {
+  return _systems.debug ?? null;
+}