@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/asset-workflow/pixi-spritesheet.ts

@@ -0,0 +1,197 @@
+/**
+ * Pixi's native spritesheet sidecar — TexturePacker hash/array JSON, the
+ * same document AssetPack writes as `image.png.json`. The game loads THAT
+ * file (`Assets.load('images/game-screen.png.json')`); the PNG is the atlas
+ * page, not the authored unit.
+ */
+
+export interface PixiSpritesheetFrame {
+  readonly name: string;
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly rotated: boolean;
+  /** Untrimmed sprite canvas — Unity/Aseprite's document size. */
+  readonly sourceWidth: number;
+  readonly sourceHeight: number;
+  /** Where the packed pixels sit inside that canvas. */
+  readonly trimX: number;
+  readonly trimY: number;
+}
+
+export interface PixiSpritesheet {
+  readonly image: string;
+  readonly frames: readonly PixiSpritesheetFrame[];
+}
+
+export function spritesheetResolutionRank(name: string): number {
+  if (/@[0-9.]+x\./i.test(name)) return 1;
+  if (/\.webp\.json$/i.test(name)) return 2;
+  if (/\.png\.json$/i.test(name)) return 3;
+  return 0;
+}
+
+export function spritesheetFamilyKey(path: string): string {
+  const slash = path.lastIndexOf('/');
+  const dir = slash < 0 ? '' : path.slice(0, slash);
+  const file = slash < 0 ? path : path.slice(slash + 1);
+  const stem = file
+    .replace(/@[0-9.]+x/i, '')
+    .replace(/\.(png|webp|jpe?g)\.json$/i, '')
+    .replace(/\.json$/i, '');
+  return dir ? `${dir}/${stem}` : stem;
+}
+
+export function parsePixiSpritesheet(source: string): PixiSpritesheet | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(source);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object') return null;
+  const record = parsed as {
+    frames?: unknown;
+    meta?: { image?: unknown };
+  };
+  const image = typeof record.meta?.image === 'string' ? fileName(record.meta.image) : '';
+  const frames = readFrames(record.frames);
+  if (!image || frames.length === 0) return null;
+  return { image, frames };
+}
+
+/** Content/open path: `assets/images/game-screen.png#satellite`. */
+export function splitSpritesheetAssetPath(path: string): {
+  readonly sheetPath: string;
+  readonly frameName: string | null;
+} {
+  const trimmed = path.replace(/^\//, '');
+  const hash = trimmed.lastIndexOf('#');
+  if (hash < 0) return { sheetPath: trimmed, frameName: null };
+  return { sheetPath: trimmed.slice(0, hash), frameName: trimmed.slice(hash + 1) || null };
+}
+
+/** Tab title: the frame name, never `game-screen.png#satellite`. */
+export function spritesheetFrameTitle(path: string): string {
+  const { sheetPath, frameName } = splitSpritesheetAssetPath(path);
+  return frameName ?? sheetPath.split('/').pop() ?? path;
+}
+
+export function sidecarPathForSheet(sheetPath: string): string {
+  return `${sheetPath.replace(/^\//, '')}.json`;
+}
+
+export function sheetVariantsFor(image: string): readonly string[] {
+  const ext = image.match(/\.[a-z0-9]+$/i)?.[0] ?? '';
+  const stem = image.slice(0, image.length - ext.length);
+  return [
+    image,
+    `${stem}.png`,
+    `${stem}.webp`,
+    `${stem}.jpg`,
+    `${stem}@0.5x${ext}`,
+    `${stem}@0.5x.png`,
+    `${stem}@0.5x.webp`,
+    `${stem}@2x${ext}`,
+    `${stem}@2x.png`,
+    `${stem}@2x.webp`,
+  ];
+}
+
+function readFrames(frames: unknown): PixiSpritesheetFrame[] {
+  if (!frames || typeof frames !== 'object') return [];
+  if (Array.isArray(frames)) {
+    return frames.flatMap((entry) => {
+      if (!entry || typeof entry !== 'object') return [];
+      const row = entry as FrameRecord;
+      const name = typeof row.filename === 'string' ? row.filename : '';
+      const parsed = readFrame(row);
+      if (!name || !parsed) return [];
+      return [{ name: stripFrameExt(name), ...parsed }];
+    });
+  }
+  return Object.entries(frames as Record<string, unknown>).flatMap(([name, entry]) => {
+    if (!entry || typeof entry !== 'object') return [];
+    const parsed = readFrame(entry as FrameRecord);
+    if (!parsed) return [];
+    return [{ name: stripFrameExt(name), ...parsed }];
+  });
+}
+
+interface FrameRecord {
+  filename?: unknown;
+  frame?: unknown;
+  rotated?: unknown;
+  sourceSize?: unknown;
+  spriteSourceSize?: unknown;
+}
+
+function readFrame(row: FrameRecord): Omit<PixiSpritesheetFrame, 'name'> | null {
+  const box = readBox(row.frame);
+  if (!box) return null;
+  const source = readSize(row.sourceSize) ?? { width: box.width, height: box.height };
+  const trim = readPoint(row.spriteSourceSize);
+  return {
+    ...box,
+    rotated: row.rotated === true,
+    sourceWidth: source.width,
+    sourceHeight: source.height,
+    trimX: trim?.x ?? 0,
+    trimY: trim?.y ?? 0,
+  };
+}
+
+function readBox(frame: unknown): { x: number; y: number; width: number; height: number } | null {
+  if (!frame || typeof frame !== 'object') return null;
+  const box = frame as { x?: unknown; y?: unknown; w?: unknown; h?: unknown };
+  if (
+    typeof box.x !== 'number' ||
+    typeof box.y !== 'number' ||
+    typeof box.w !== 'number' ||
+    typeof box.h !== 'number'
+  ) {
+    return null;
+  }
+  return { x: box.x, y: box.y, width: box.w, height: box.h };
+}
+
+function readSize(value: unknown): { width: number; height: number } | null {
+  if (!value || typeof value !== 'object') return null;
+  const size = value as { w?: unknown; h?: unknown };
+  if (typeof size.w !== 'number' || typeof size.h !== 'number') return null;
+  return { width: size.w, height: size.h };
+}
+
+function readPoint(value: unknown): { x: number; y: number } | null {
+  if (!value || typeof value !== 'object') return null;
+  const point = value as { x?: unknown; y?: unknown };
+  if (typeof point.x !== 'number' || typeof point.y !== 'number') return null;
+  return { x: point.x, y: point.y };
+}
+
+/**
+ * Packed rect Pixi samples. A rotated TexturePacker frame stores the
+ * unrotated size in `frame` and occupies the swapped rect on the page.
+ */
+export function packedFrameRect(
+  frame: Pick<PixiSpritesheetFrame, 'x' | 'y' | 'width' | 'height' | 'rotated'>,
+): {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+} {
+  return frame.rotated
+    ? { x: frame.x, y: frame.y, width: frame.height, height: frame.width }
+    : { x: frame.x, y: frame.y, width: frame.width, height: frame.height };
+}
+
+function fileName(path: string): string {
+  const slash = path.lastIndexOf('/');
+  return slash < 0 ? path : path.slice(slash + 1);
+}
+
+function stripFrameExt(name: string): string {
+  return name.replace(/\.(png|webp|jpe?g)$/i, '');
+}

package/src/kit/asset-workflow/preview-resource-lifetime.ts

@@ -0,0 +1,44 @@
+export type PreviewResourceKind =
+  | 'webglContext'
+  | 'animationFrame'
+  | 'resizeObserver'
+  | 'objectUrl';
+
+export interface PreviewResourceSnapshot {
+  webglContext: number;
+  animationFrame: number;
+  resizeObserver: number;
+  objectUrl: number;
+  peaks: Record<PreviewResourceKind, number>;
+}
+
+const current: Record<PreviewResourceKind, number> = {
+  webglContext: 0,
+  animationFrame: 0,
+  resizeObserver: 0,
+  objectUrl: 0,
+};
+const peaks = { ...current };
+
+/** Local diagnostic counter used by stress tests and the Debugger; never uploads identifiers. */
+export function registerPreviewResource(kind: PreviewResourceKind): () => void {
+  current[kind]++;
+  peaks[kind] = Math.max(peaks[kind], current[kind]);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    current[kind] = Math.max(0, current[kind] - 1);
+  };
+}
+
+export function previewResourceSnapshot(): PreviewResourceSnapshot {
+  return { ...current, peaks: { ...peaks } };
+}
+
+export function resetPreviewResourceCounters(): void {
+  for (const key of Object.keys(current) as PreviewResourceKind[]) {
+    current[key] = 0;
+    peaks[key] = 0;
+  }
+}

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

@@ -0,0 +1,20 @@
+export const PROJECT_ASSET_COMMANDS = {
+  open: { id: 'project-asset.open', shortcut: 'Enter' },
+  rename: { id: 'project-asset.rename', shortcut: 'F2' },
+  move: { id: 'project-asset.move', shortcut: null },
+  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' },
+} 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);
+}
+

package/src/kit/asset-workflow/project-content.ts

@@ -0,0 +1,288 @@
+/**
+ * WHAT THE CONTENT BROWSER SHOWS: the project's asset rows, their media
+ * facets, spritesheet expansion, and the orderings the gallery sorts by — plus
+ * the shapes the panel and its siblings type against.
+ *
+ * ITS OTHER HALF IS `project-source-index.ts`, and the split is load-bearing:
+ * this module is in the shell's EAGER closure (the Content panel is a static
+ * workspace panel), while indexing a project's own TSX for components and
+ * regions is TypeScript-AST work nothing at boot asks for. Keeping the two
+ * apart is what stops one panel's five presentation helpers from carrying
+ * the source-authoring integration's JSX transform and the five R3F prop-contract bindings into
+ * every editor boot — measured at EIGHT files, 2026-09-18. Add a discovery
+ * function to the index file; add a row-shaping one here.
+ *
+ * The one edge back is `import type { ProjectComponentEntry }`, which is
+ * erased at build and costs no closure. Never make it a value import.
+ */
+
+import type { R3fComponentContract } from '@volter/sdk/source-authoring';
+import { assetCapabilities } from '@volter/sdk/kit/asset-capabilities';
+import {
+  parsePixiSpritesheet,
+  sheetVariantsFor,
+  spritesheetFamilyKey,
+  spritesheetResolutionRank,
+} from './pixi-spritesheet';
+import { ASSET_ROOTS, type AssetRootId } from '@volter/sdk/kit/project-asset-roots';
+
+export interface ProjectComponentEntry {
+  name: string;
+  /** Project-root-relative source file. */
+  path: string;
+  line: number;
+  exported: boolean;
+  defaultExport: boolean;
+  /** Declared in a manifest root's own source module. This is an intent
+   * signal for file-local scene-building components without relying on a
+   * conventional filename or directory layout. */
+  declaredInRootEntry: boolean;
+  /** Static JSX uses of this definition in its own module. Root-entry locals
+   * need repeated/collection use as evidence that they are a reusable scene
+   * building block rather than one-off composition machinery. */
+  sourceUseCount: number;
+  sourceCollectionUse: boolean;
+  surface: 'three' | 'canvas' | 'dom' | 'unknown';
+  /** Inline SVG components are image assets, not general UI components. */
+  contentKind?: 'component' | 'image';
+  contract: R3fComponentContract;
+}
+
+export interface ProjectContentSpritesheetFrame {
+  readonly sheetPath: string;
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly rotated: boolean;
+  readonly sourceWidth: number;
+  readonly sourceHeight: number;
+  readonly trimX: number;
+  readonly trimY: number;
+}
+
+export interface ProjectContentAsset {
+  /** Root-relative asset path (the root is {@link ProjectContentAsset.root}). */
+  path: string;
+  /** Which project asset root this row was listed from. `public` ships with the
+   *  game; `references` is reference material the project keeps and no export
+   *  copies — see `project-asset-roots.ts`. */
+  root: AssetRootId;
+  entry: ProjectContentAssetEntry;
+  /** Present when this row is one frame of a Pixi/TexturePacker sheet. */
+  spritesheet?: ProjectContentSpritesheetFrame;
+}
+
+export interface ProjectContentAssetEntry {
+  name: string;
+  type: 'file' | 'directory';
+  /** Bytes, when the backend reports it. ABSENT means unmeasured — not zero. */
+  size?: number;
+  /** Epoch ms, when the backend reports it. ABSENT means unmeasured — not 1970. */
+  modifiedAt?: number;
+}
+
+/** An asset medium, the component chip, or an OPEN document kind
+ *  (ARCHITECTURE-CORE §The project model) — never a closed list. */
+export type ProjectContentFacet = string;
+
+/**
+ * Flatten every project asset root for the semantic Content view. Browse Files
+ * keeps using shallow listings and folder navigation.
+ *
+ * Both roots are walked the same way and their rows differ only by the `root`
+ * they carry: reference media is ORDINARY FILES in the project, so it is
+ * indexed by listing the directory, never by a side database or an import step.
+ * A project with no `references/` folder simply contributes nothing — an absent
+ * root lists empty (the server route's own rule), it does not fail.
+ *
+ * `failedListings` is returned beside the assets rather than folded into them:
+ * a directory whose listing FAILED contributes nothing, exactly like an empty
+ * one, and without this count the gallery cannot tell "the project has no
+ * content" from "we could not read it".
+ */
+export async function collectProjectContentAssets(
+  list: (
+    root: string,
+    directory: string,
+  ) => Promise<{ ok: true; entries: ProjectContentAssetEntry[] } | { ok: false; reason: string }>,
+  roots: readonly AssetRootId[] = ASSET_ROOTS,
+): Promise<{ assets: ProjectContentAsset[]; failedListings: string[] }> {
+  const walked = await Promise.all(roots.map((root) => collectAssetRoot(list, root)));
+  return {
+    assets: walked.flatMap((result) => result.assets),
+    failedListings: walked.flatMap((result) => result.failedListings),
+  };
+}
+
+async function collectAssetRoot(
+  list: (
+    root: string,
+    directory: string,
+  ) => Promise<{ ok: true; entries: ProjectContentAssetEntry[] } | { ok: false; reason: string }>,
+  root: AssetRootId,
+): Promise<{ assets: ProjectContentAsset[]; failedListings: string[] }> {
+  const pending = [''];
+  const assets: ProjectContentAsset[] = [];
+  const failedListings: string[] = [];
+  let listings = 0;
+  while (pending.length > 0 && listings < 512) {
+    const batch = pending.splice(0, 8);
+    const results = await Promise.all(batch.map((directory) => list(root, directory)));
+    listings += batch.length;
+    results.forEach((result, index) => {
+      const directory = batch[index]!;
+      if (!result.ok) {
+        failedListings.push(`${root}/${directory}: ${result.reason}`);
+        return;
+      }
+      for (const entry of result.entries) {
+        const path = directory ? `${directory}/${entry.name}` : entry.name;
+        if (entry.type === 'directory') pending.push(path);
+        else assets.push({ path, root, entry });
+      }
+    });
+  }
+  return { assets, failedListings };
+}
+
+/**
+ * Replace packed atlas pages with the frames the game actually names.
+ * Sidecars (`image.png.json`) are Pixi's spritesheet document; the PNG is
+ * only the page. Resolution variants (`@0.5x`) of the same family collapse
+ * to the preferred sidecar.
+ *
+ * SHIPPED ASSETS ONLY. An atlas is a thing the game loads, so this reads the
+ * `public` root and leaves every other root's rows exactly as listed — a
+ * reference `.json` beside a reference `.png` is two files someone put there,
+ * not a sheet to unpack, and unpacking it would hide both behind frames that
+ * name a sheet no game reads.
+ */
+export async function expandSpritesheetContentAssets(
+  assets: readonly ProjectContentAsset[],
+  readText: (path: string) => Promise<string | null>,
+): Promise<ProjectContentAsset[]> {
+  const shipped = assets.filter((asset) => asset.root === 'public');
+  const preferred = preferredSpritesheetSidecars(shipped);
+  const sheets = (
+    await Promise.all(
+      preferred.map(async (sidecar) => {
+        const source = await readText(sidecar.path);
+        if (!source) return null;
+        const parsed = parsePixiSpritesheet(source);
+        if (!parsed) return null;
+        return { sidecar, parsed };
+      }),
+    )
+  ).flatMap((entry) => (entry ? [entry] : []));
+
+  const hidden = new Set<string>();
+  for (const { sidecar, parsed } of sheets) {
+    hidden.add(sidecar.path);
+    const dir = parentDir(sidecar.path);
+    for (const variant of sheetVariantsFor(parsed.image)) {
+      hidden.add(dir ? `${dir}/${variant}` : variant);
+    }
+    for (const asset of shipped) {
+      if (spritesheetFamilyKey(asset.path) === spritesheetFamilyKey(sidecar.path)) {
+        hidden.add(asset.path);
+      }
+    }
+  }
+
+  const frames = sheets.flatMap(({ sidecar, parsed }) => {
+    const dir = parentDir(sidecar.path);
+    const sheetPath = dir ? `${dir}/${parsed.image}` : parsed.image;
+    return parsed.frames.map((frame) => ({
+      path: `${sheetPath}#${frame.name}`,
+      root: sidecar.root,
+      entry: {
+        name: `${frame.name}.png`,
+        type: 'file' as const,
+        // The frame inherits the SHEET's measurements; when the sheet was not
+        // measured, neither was the frame — it does not become 0 bytes here.
+        ...(sidecar.entry.size === undefined ? {} : { size: sidecar.entry.size }),
+        ...(sidecar.entry.modifiedAt === undefined ? {} : { modifiedAt: sidecar.entry.modifiedAt }),
+      },
+      spritesheet: {
+        sheetPath,
+        x: frame.x,
+        y: frame.y,
+        width: frame.width,
+        height: frame.height,
+        rotated: frame.rotated,
+        sourceWidth: frame.sourceWidth,
+        sourceHeight: frame.sourceHeight,
+        trimX: frame.trimX,
+        trimY: frame.trimY,
+      },
+    }));
+  });
+
+  // `hidden` holds PUBLIC paths, so the root is part of the test: a reference
+  // file that happens to share a sheet's path is a different file.
+  return [
+    ...assets.filter((asset) => asset.root !== 'public' || !hidden.has(asset.path)),
+    ...frames,
+  ];
+}
+
+function preferredSpritesheetSidecars(
+  assets: readonly ProjectContentAsset[],
+): ProjectContentAsset[] {
+  const best = new Map<string, ProjectContentAsset>();
+  for (const asset of assets) {
+    if (!/\.json$/i.test(asset.path)) continue;
+    const key = spritesheetFamilyKey(asset.path);
+    const current = best.get(key);
+    if (
+      !current ||
+      spritesheetResolutionRank(asset.path) > spritesheetResolutionRank(current.path)
+    ) {
+      best.set(key, asset);
+    }
+  }
+  return [...best.values()];
+}
+
+function parentDir(path: string): string {
+  const slash = path.lastIndexOf('/');
+  return slash < 0 ? '' : path.slice(0, slash);
+}
+
+export function projectContentAssetFacet(name: string): ProjectContentFacet {
+  const kind = assetCapabilities(name).kind;
+  if (kind === 'model' || kind === 'image' || kind === 'video' || kind === 'audio') {
+    return kind;
+  }
+  return 'other';
+}
+
+/** Lower values are more useful in the default gallery. */
+export function projectContentAssetPriority(asset: ProjectContentAsset): number {
+  const capability = assetCapabilities(asset.entry.name);
+  if (capability.placeable && capability.runtimeReady) return 10;
+  if (capability.kind === 'model' && capability.runtimeReady) return 15;
+  if (capability.kind === 'prefab') return 25;
+  if (capability.runtimeReady && (capability.kind === 'image' || capability.kind === 'audio')) {
+    return 30;
+  }
+  if (capability.runtimeReady) return 40;
+  if (capability.importable) return 70;
+  return 90;
+}
+
+/** Lower values are more useful in the default Content gallery — a
+ *  PRESENTATION rule, which is why it sits beside the gallery's other ordering
+ *  helpers rather than with the discovery that produced the row. */
+export function projectComponentPriority(component: ProjectComponentEntry): number {
+  const surface =
+    component.surface === 'three'
+      ? 0
+      : component.surface === 'canvas'
+        ? 10
+        : component.surface === 'dom'
+          ? 20
+          : 30;
+  return surface + (component.exported ? 0 : 4);
+}